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
  • General
    • iconPath
    • ipAddress
    • themes
    • token
    • hooks
  • Storage
    • storage.driver
    • storage.connection
    • storage.datetimeFormat
  • Challenge
    • challenge.availableIcons
    • challenge.iconAmount.min
    • challenge.iconAmount.max
    • challenge.rotate
    • challenge.flip.horizontally
    • challenge.flip.vertically
    • challenge.border
    • challenge.generator
  • Validation
    • validation.inactivityExpiration
    • validation.completionExpiration
    • validation.attempts.enabled
    • validation.attempts.amount
    • validation.attempts.timeout
    • validation.attempts.valid
    • validation.attempts.storage.driver
    • validation.attempts.storage.options
    • validation.attempts.storage.options.table
    • validation.attempts.storage.options.purging
  • Session
    • session.driver
    • session.options
    • session.options.table
    • session.options.purging
    • session.options.identifierTries
  • Cors
    • cors.enabled
    • cors.origins
    • cors.credentials
    • cors.cache
• Javascript
  • general.validationPath
  • general.fontFamily
  • general.credits
  • security.clickDelay
  • security.hoverDetection
  • security.enableInitialMessage
  • security.initializeDelay
  • security.selectionResetDelay
  • security.loadingAnimationDelay
  • locale.*

---

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 icon folder, otherwise the server will be unable to generate a captcha challenge.

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

TODO

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

TODO

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, ensure that your custom generator class extends the AbstractImageGenerator class and implements all required functions.

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

TODO

Expected value type	string
Default value	null

validation.attempts.storage.options

TODO

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

TODO

Expected value type	string
Default value	null

session.options

TODO

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.validationPath

This option specifies the route/URL to captcha-request.php. Make sure you use the correct URL, otherwise no challenge can be requested from the server.

Expected value type	string
Default value	null

general.fontFamily

This option specifies the font family used by the captcha. Leaving this blank will default the captcha to using the page font family.

Expected value type	string
Default value	'inherit'

general.credits

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. Disabling the credits removes both the display and the HTML.

I respectfully request that you keep the credits visible.

Expected value type	string
Default value	'show'
Available values	'show', 'hide' or 'disabled'

security.clickDelay

This option specifies the duration, in milliseconds, during which the visitor cannot interact with the challenge. This delay is implemented to counteract bots that instantly click on the captcha widget. To disable this click delay, set the option to 0.

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

security.hoverDetection

This option specifies whether hover-click protection should be activated. When enabled, clicking events on the challenge will be disregarded until the cursor hovers over the captcha challenge area.

Expected value type	boolean
Default value	true

security.enableInitialMessage

This option specifies whether to display the initial 'verify that you are human' screen, requiring the visitor to initiate the captcha. Enabling this feature enhances security and prevents additional server load. To immediately load a new challenge from the server upon page load, set this option to false. Note that this is not recommended.

Expected value type	boolean
Default value	true

security.initializeDelay

This option specifies the delay in milliseconds between the visitor initializing the widget and the captcha requesting a challenge from the server. A loading indicator will be displayed in the widget during this period. To disable this delay, set this option to 0. It's important to note that this option is disregarded when security.enableInitialMessage is configured as false.

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

security.selectionResetDelay

This option specifies the reset time in milliseconds for the widget after an incorrect icon has been selected. To disable this delay, set the option to 0.

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

security.loadingAnimationDelay

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.