IconCaptcha is a self-hosted, customizable, easy-to-implement and user-friendly captcha.

4.0.3 2023-12-19 19:35 UTC

This package is auto-updated.

Last update: 2024-06-20 09:09:03 UTC


A self-hosted, customizable, easy-to-implement and user-friendly captcha.

Version Latest Version on Packagist License Support via PayPal Buy me a coffee

Sonar Quality Sonar Security Sonar Bugs Sonar Vulnerabilities

Introducing IconCaptcha, a self-hosted captcha solution that's designed to be fast, user-friendly, and highly customizable. Unlike other captchas, IconCaptcha spares users the need of deciphering hard-to-read text images, solving complex math problems, or engaging with perplexing puzzle games. Instead, with IconCaptcha it's as straightforward as comparing up to 8 icons and selecting the least common one.

IconCaptcha doesn't just prioritize users; it's also developer-friendly. In just a few steps, you can have IconCaptcha integrated into your website. Even if you're new to PHP and JavaScript, installing IconCaptcha is a straightforward process. The included demo pages in this repository provide all the necessary code to get IconCaptcha up and running. For more in-depth insights, take a moment to explore the information provided on this page and the wiki.

▶ Try the live demo here!

IconCaptcha light and dark theme widget examples.

Using ASP.NET instead? Try IconCaptcha for ASP.NET (not currently maintained - will continue in Q4 of 2023)



composer require fabianwennink/iconcaptcha

Once the package has been installed, continue with the remaining installation instructions, followed by the setup instructions.

Manual Installation

It is recommended to use Composer. However, if you are unable to, follow the manual installation instructions and setup instructions.


  • 🏠 Self-Hosted: As a self-hosted solution, IconCaptcha eliminates reliance on third-party services, keeping things under your control.
  • 🚫 No Data Sharing: Unlike other captchas, IconCaptcha's self-hosted nature ensures no user data is shared with third parties.
  • 🔐 Server-Side Validation: All validation is carried out server-side, boosting security by eliminating exposure of sensitive processes on the client side.
  • 😊 User-Friendly: Replace complex captchas for easily understandable images, delivering a smoother experience for your users.
  • 💾 Database Support: Store and manage challenge data using various popular databases like MySQL, SQL Server, PostgreSQL, and SQLite.
  • 🌐 Cross-Domain Integration: With CORS support, IconCaptcha effortlessly integrates into applications spanning different domains.
  • 🎣 Events and Hooks: Events are triggered throughout the code, allowing you to inject custom code and fine-tune the experience to your needs.
  • 🎨 Contemporary Design: IconCaptcha's modern design seamlessly integrates with a diverse range of styles.
  • 🖌️ Themes: Choose from existing themes, or craft your own unique theme using the provided SASS file.
  • 🔌 jQuery Integration: While written in plain JavaScript, IconCaptcha smoothly integrates with jQuery.

What's New in IconCaptcha 4

Version 4 of IconCaptcha introduces significant enhancements to the architecture and feature set, and offers greater flexibility and customization, alongside improved security. Here are the key updates in this release:

  • 📦 Composer Compatibility: IconCaptcha is now available on Packagist and can be installed using Composer.
  • 🏗️ Restructured Code Base: The entire code base has been restructured, moving away from the previous one-file-does-everything approach. This restructuring makes it easier to maintain the code in the future.
  • 📃 Improved Configuration: IconCaptcha 4 introduces a more comprehensive and polished configuration file, offering more options for customization alongside clearer descriptions for each choice.
  • 💾 Database Support: A notable addition to this version is the inclusion of database support. Challenge data can now be stored using well-known databases like MySQL, SQL Server, PostgreSQL, and SQLite.
  • 🧩 Custom Drivers: Want to handle certain server-side aspects your own way? IconCaptcha 4 allows you to implement custom drivers for critical features such as session management, storage, and timeout handling.
  • 🎣 Server-side Hooks: Hook into server-side events like captcha initialization, challenge generation, and solution processing to customize the processes according to your application's needs.
  • 🌐 CORS Support: Cross-Origin Resource Sharing (CORS) support is now available, allowing IconCaptcha to be integrated into applications spread across different domains while maintaining security standards.


For instructions on installing, setting up, and configuring IconCaptcha, be sure to explore the Wiki pages:

  • Requirements - A list of requirements to get IconCaptcha working properly.
  • Installation - Instructions on how to install/download IconCaptcha.
  • Implementing - Step-by-step instructions on how to implement IconCaptcha.
  • Configuration - Explanation of all available configuration options.
  • Storage - Details about all storage options.
  • Challenge Generator - Information about how to implement a custom challenge generator.
  • Validation - Explanation of the validation process and error handling.
  • Hooks & Events - Overview of events which are triggered at different stages in the captcha process.
  • Token - Information about the usage of the optional widget security token.
  • Themes - Details on creating and setting up custom themes.
  • Localization - Details on how to customize the localization strings.


The icons used in this project are made by BlendIcons.


This project is licensed under the MIT license.