Configuration

This page contains all configuration options for both the PHP and Javascript packages. The configurations are leveled/nested, which means that every dot (.) in the configuration options indicates that it's 1 level deeper in the configuration array/object. Below is a list of all available configuration options.

Configuration options:

PHP
Javascript

PHP

The following options are all specified in the captcha-config.php, found in the examples folder. This config must be loaded before IconCaptcha is initialized.

General

All configuration options which do not specifically fall under any other category.

iconPath

This option specifies the directory path where the icon files are located. This path will vary depending on how you implement IconCaptcha. Make sure this path is correct and points to the assets folder, otherwise the server will be unable to generate a captcha challenge.

If you've installed IconCaptcha using Composer, you may set this option to null. By default, the internal code will attempt to use the included assets located in the package's vendor directory. However, if you've chosen to publish the included assets folder to your own project by using the composer run-script publish-iconcaptcha-assets command during setup, it becomes necessary to update this path to point to the correct folder in your project.

Expected value type	`string`
Default value	`__DIR__ . '/../assets/icons/'`

ipAddress

This option specifies a function that must return the IP address of the visitor by using $_SERVER['REMOTE_ADDR'] or other means.

If you are using Cloudflare to manage your DNS, you should use the HTTP_CF_CONNECTING_IP server variable to retrieve the IP address instead of REMOTE_ADDR, as using REMOTE_ADDR would return the Cloudflare proxy IP address and not the visitor's IP. For more information about this, visit the Cloudflare documentation.

Expected value type	`Closure`
Default value	`static fn() => $_SERVER['REMOTE_ADDR']`
Default value (Cloudflare)	`static fn() => $_SERVER['HTTP_CF_CONNECTING_IP']`

themes

This option contains all additional custom themes. Instructions about how to register custom themes can be found on the Themes wiki page.

token

This option allows you to specify the class responsible for generating and validating challenge CSRF (Cross-Site Request Forgery) tokens. These tokens serve as an additional layer of security by ensuring that each request sent to the server includes a token for validation. If the token is either missing (when configured) or invalid, server requests will be denied.

It's worth noting that if you are unable to execute PHP within your HTML page, this feature will not function and should be disabled. To disable this security measure, simply set the option to null.

For more information about this token option, visit the Token wiki page.

Expected value type	`string`
Default value	`\IconCaptcha\Token\IconCaptchaToken::class`
Disable option	Set to `null`

hooks

This option contains all server-side event hooks. Instructions about how to register hooks can be found on the Hooks-&-Events wiki page.

Storage

All configuration options related to data storage.

storage.driver

This option specifies the driver which should be used for captcha data storage. The following drivers are available available: session, mysql, sqlsrv, pgsql and sqlite. The session driver will simply store data in the PHP session. For the session driver to work, ensure that session_start() is called before initializing IconCaptcha.

In order to use any driver other than session, ensure that the correct PDO driver extensions are installed and enabled in your PHP installation.

Expected value type	`string`
Default value	`'session'`
Available drivers	`'session'`, `'mysql'`, `'sqlsrv'`, `'pgsql'`, `'sqlite'`

storage.connection

This option holds all the necessary information for the storage driver to establish a connection with the storage device. This array will be provided to the driver during its initialization process. By default, IconCaptcha includes database storage drivers that anticipate database connection details or a connection string to be included here.

In the case of a custom storage driver, you can define the required connection details for your specific driver within this configuration.

storage.datetimeFormat

This option specifies the format used to create formatted datetime values to use in database queries. If your database uses a different format from the default value specified below, please change the value accordingly. See the PHP datetime format manual for instructions on how to do so.

Expected value type	`string`
Default value	`'Y-m-d H:i:s'`

Challenge

All configuration options related to challenge generation.

challenge.availableIcons

This option specifies the maximum number of unique icons that are available to be used while generating new captcha challenges. By default, IconCaptcha ships with 180 icons, but you are free to add, remove or change them.

Expected value type	`integer`
Default value	`180`

challenge.iconAmount.min

This option specifies the minimum number of icons to use in each challenge image. The lowest possible amount of icons per challenge is 5.

Expected value type	`integer`
Default value	`5`
Lowest possible value	`5`
Highest possible value	`8`

challenge.iconAmount.max

This option specifies the maximum number of icons to use in each challenge image. The highest possible amount of icons per challenge is 8.

Expected value type	`integer`
Default value	`8`
Lowest possible value	`5`
Highest possible value	`8`

challenge.rotate

This option specifies whether to rotate the icons in a challenge image randomly. The icons will be randomly rotated 0, 90, 180 or 270 degrees.

Expected value type	`boolean`
Default value	`true`

challenge.flip.horizontally

This option specifies whether to randomly flip the icons in a challenge image horizontally. The chance of an icon flipping horizontally when enabled in 50/50 and will be determined per icon.

Expected value type	`boolean`
Default value	`true`

challenge.flip.vertically

This option specifies whether to randomly flip the icons in a challenge image vertically. The chance of an icon flipping vertically when enabled in 50/50 and will be determined per icon.

Expected value type	`boolean`
Default value	`true`

challenge.border

This option specifies whether to render a border between the icons in a challenge image. When disabled, no visible separator line will be generated between the icons.

Expected value type	`boolean`
Default value	`true`

challenge.generator

This option specifies the generator class to use for creating challenge images. Generators for the GD and Imagick extensions are available by default. To use either of these generators, ensure that either the GD extension or ImageMagick is installed and enabled for image processing.

The GD generator is located at \IconCaptcha\Challenge\Generators\GD::class, and the Imagick generator is located at \IconCaptcha\Challenge\Generators\Imagick::class.

If you wish to create your own generator, please refer to the Challenge Generator wiki page for instructions.

Expected value type	`string`
Default value	`\IconCaptcha\Challenge\Generators\GD::class`
Available generators	`\IconCaptcha\Challenge\Generators\GD::class` and `\IconCaptcha\Challenge\Generators\Imagick::class`
Requirements	To use the GD generator, install and enable the GD extension. To use the Imagick generator, install and enable ImageMagick.

Validation

All configuration options related to challenge validation.

validation.inactivityExpiration

This option specifies the duration in seconds before an unsolved challenge is invalidated due to inactivity. The timer will start once the challenge is returned by the server and is tracked both on the server and by the client-side widget. If there is no interaction with the widget for the set amount of seconds, the widget will reset itself, and the visitor will have to request a new challenge.

Expected value type	`integer`
Default value	`120`
Disable option	Set to `0`

validation.completionExpiration

This option specifies the duration in seconds after which a solved challenge will be invalidated. Once the challenge is invalidated, it can no longer be submitted and the visitor has to solve a new challenge. The widget will automatically reset itself once a challenge is invalidated, to let the visitor know their previously solved challenge can no longer be submitted.

If you do not wish to invalidate already solved challenges, simply set the option value to 0. This will keep all solved challenges valid indefinitely until the form is submitted.

Expected value type	`integer`
Default value	`300`
Disable option	Set to `0`

validation.attempts.enabled

This option specifies whether to enable the attempts and timeout feature. It is recommended to keep this feature enabled to counter brute-force attacks.

Expected value type	`boolean`
Default value	`true`

validation.attempts.amount

This option specifies the maximum number of incorrect attempts a visitor can make before they will receive a timeout. The duration of the timeout is determined by the validation.attempts.timeout option.

Expected value type	`integer`
Default value	`3`

validation.attempts.timeout

This option specifies the time in seconds which the visitor has to wait after making too many incorrect attempts before being able to request a new challenge.

Expected value type	`integer`
Default value	`60`

validation.attempts.valid

This option specifies the time in seconds after which an incorrect captcha solving attempt will be forgotten and removed from the visitor's attempts counter.

By automatically reducing the attempts counter, we prevent the issue where a visitor might receive a timeout after 1 try because attempts were remembered indefinitely from a previous session.

Expected value type	`integer`
Default value	`30`

validation.attempts.storage.driver

This option allows you to specify a custom driver class to manage attempts and timeout data. By default, an internal driver that is compatible with the configured storage.driver option will be used automatically. When using the session storage driver, the SessionAttempts driver is utilized. When utilizing any of the provided database storage drivers, the PDOAttempts driver is utilized.

To implement your own custom driver, ensure it extends \IconCaptcha\Attempts\Attempts::class and implements all required functions.

Expected value type	`string`
Default value	`null`

validation.attempts.storage.options

This option holds all the details for the attempts/timeouts driver to function. This array will be provided to the driver during its initialization process. If you use a custom attempts/timeouts driver, the default table and purging options may be deleted from this array, as these are only used by the provided drivers.

validation.attempts.storage.options.table

This option specifies the table name used by the database storage drivers to keep track of attempts and timeouts. The table can be named anything, however it's best to keep the iconcaptcha_ table prefix to keep your database organized.

Expected value type	`string`
Default value	`iconcaptcha_attempts`

validation.attempts.storage.options.purging

This option specifies whether the expired attempts/timeout records should automatically be deleted from storage.

Expected value type	`boolean`
Default value	`true`

Session

All configuration options related to challenge data management.

session.driver

This option allows you to specify a custom driver class to manage challenge data. By default, an internal driver that is compatible with the configured storage.driver option will be used automatically. When using the session storage driver, the ServerSession driver is utilized. When utilizing any of the provided database storage drivers, the PDOSession driver is utilized.

To implement your own custom session driver, ensure it extends \IconCaptcha\Session\Session::class and implements all required functions.

Expected value type	`string`
Default value	`null`

session.options

This option holds all the details for the session driver to function. This array will be provided to the driver during its initialization process. If you use a custom session driver, the default table and purging options may be deleted from this array, as these are only used by the provided drivers. Note that the identifierTries option cannot be deleted and must remain configured.

session.options.table

This option specifies the table name used by the database storage drivers to keep track of challenges. The table can be named anything, however it's best to keep the iconcaptcha_ table prefix to keep your database organized.

Expected value type	`string`
Default value	`iconcaptcha_challenges`

session.options.purging

This option specifies whether the expired challenges should automatically be deleted from storage. It's best to always set this to true regardless of which storage driver is used, as this will prevent possible issues with the captcha identifier generation (see session.options.identifierTries).

Especially when using the session storage driver, it is advised to always set this to true. This will prevent the max. session size from being reached.

Expected value type	`boolean`
Default value	`true`

session.options.identifierTries

This option specifies the maximum amount of attempts that will be made to generate a captcha identifier before failing and throwing an exception. The higher the value, the longer it might take to generate a captcha challenge.

Expected value type	`integer`
Default value	`100`

CORS

All configuration options related to Cross-Origin Resource Sharing (CORS).

cors.enabled

This option specifies whether CORS is enabled. If your application already has CORS support integrated, keep this option set to false. When you enable CORS support, ensure that you properly configure the cors.origins option as well.

Note that if you try the provided example captchas on localhost, CORS might not function as expected and it's best to keep it disabled.

Expected value type	`boolean`
Default value	`false`

cors.origins

This option specifies the list of origins which are allowed to make CORS requests. Each string entry in the array is a new origin. Wildcard origins, such as *.example.com, are also supported. Use the global wildcard * to allow all origins to make requests, but be aware of the security implications this brings. It is not advised to use the global wildcard in production environments.

Expected value type	`array`
Default value	`[]`

cors.credentials

This option specifies whether to include credentials (cookies, headers, etc.) in CORS requests. In most cases, this should be left set to true or you might experience unexpected behaviour.

Expected value type	`boolean`
Default value	`true`

cors.cache

This option specifies the maximum time in seconds to cache CORS preflight requests. Caching preflight requests improves the latency of the captcha requests. This is because once a preflight request has been cached, it will not be repeated until after the cache has expired.

Expected value type	`integer`
Default value	`86400`

Javascript

general.endpoint

This option specifies the URL to the server endpoint responsible for captcha challenges. Ensure it is correctly configured to enable challenge requests from the server.

Expected value type	`string`
Default value	`null`

general.fontFamily

This option allows you to set the font family used by the widget. Leaving it blank will result in the widget using the default font family of the webpage where it is embedded.

Expected value type	`string`
Default value	`'inherit'`

general.showCredits

Control the visibility of the widget's credits element. The credits section, displayed at the bottom of the widget, includes the text 'IconCaptcha' with a hyperlink leading to either this wiki or the demo page. Hiding the credits retains the HTML, but makes it visible only to web crawlers, hiding it from regular website visitors.

I respectfully request that you keep the credits visible.

Expected value type	`boolean`
Default value	`true`

security.interactionDelay

This option specifies the duration, in milliseconds, during which user interaction with the captcha challenge is disabled. This delay is implemented to counteract bots that attempt to interact with the captcha immediately after it appears. To disable this click delay, set the option to 0.

Expected value type	`number`
Default value	`1500`
Disable option	Set to `0`

security.hoverProtection

This option determines whether hover-click protection should be activated. When enabled, clicking events on the captcha challenge will be disregarded until the cursor hovers over the challenge area, helping to prevent automated interactions.

Expected value type	`boolean`
Default value	`true`

security.displayInitialMessage

This option specifies whether to display the initial 'verify that you are human' screen to the visitor, requiring them to initialize the captcha. Enabling this feature enhances security by ensuring that a user interacts with the captcha, and also helps reduce server load. To immediately load a challenge from the server upon page load, set this option to false. Note that disabling this feature is not recommended.

Please also note that, when setting the option to false, you may want to disable the PHP validation.inactivityExpiration feature. Leaving it enabled will automatically reset the widget/fetch a new challenge after a set amount of time of inactivity. However, the benefits of this option - resetting to the initial widget state - is mostly lost due to the initial widget screen being skipped.

Expected value type	`boolean`
Default value	`true`

security.initializationDelay

This option specifies the delay in milliseconds between the visitor initializing the widget and the captcha requesting a challenge from the server. During this period, a loading indicator will be displayed in the widget. To disable this delay and load the challenge immediately, set this option to 0. Please note that this option is disregarded when security.displayInitialMessage is configured as false.

Expected value type	`number`
Default value	`500`
Disable option	Set to `0`

security.incorrectSelectionResetDelay

This option specifies the time, in milliseconds, that the widget will wait before resetting itself after an incorrect icon has been selected. To disable this delay and allow immediate retries, set the option to 0.

Expected value type	`number`
Default value	`3000`
Disable option	Set to `0`

security.loadingAnimationDuration

This option specifies the duration, in milliseconds, for displaying a loading animation after a visitor selects an icon but before their answer is sent to the server for validation. To disable this delay, set the option to 0.

Expected value type	`number`
Default value	`1000`
Disable option	Set to `0`

locale

The locale options and strings can be found on the Localization wiki page.

IconCaptcha 4

Getting Started
- Requirements
- Installation
Implementation
- PHP
- HTML
- Javascript
Configuration
- PHP
- Javascript
Storage
- Database Storage
Session
Challenge Generator
Validation
Hooks & Events
Token
Themes
Localization

IconCaptcha 3 (outdated)