Getting Started

Requirements

For IconCaptcha to function correctly, the following requirements must be met before proceeding with the installation.

• PHP 7.4 or newer (tested up to 8.2)
• Have the JSON extension installed and enabled.
• Have the GD extension or ImageMagick installed and enabled.

Database support

Optional: If you wish to use one of the provided database storage drivers, ensure these requirements are met.

• Have the PDO extension installed.
• Have the PDO driver for your database type installed and enabled.
  • For MySQL: Driver
  • For PostgreSQL: Driver
  • For SQLite: Driver
  • For SQL Server: Driver or ODBC driver

Installation

To install IconCaptcha in your application, follow the steps below. You can install IconCaptcha using Composer or opt for a manual installation process.

Composer

To install IconCaptcha using Composer, execute the following command:

composer require fabianwennink/iconcaptcha

Once the installation is complete, you'll need to add the client-side assets (stylesheet and script) to your project. These are bundled with this package and can be included in your project by executing the command below from your project root. The assets will be published to the /iconcaptcha directory.

php vendor/fabianwennink/iconcaptcha/scripts/publish-client-assets.php

After publishing the assets to your project, you can now use them during the implementation steps. If needed, you may relocate these files to a directory of your preference.

Publishing server assets

If you wish to make modifications to the icons that are included in the package, you can publish them to your project as well. To do so, run the command below from your project root. The icons will be published to the /iconcaptcha/icons directory. If needed, you may relocate them to a directory of your preference.

php vendor/fabianwennink/iconcaptcha/scripts/publish-server-assets.php

Important

Please note that when you publish the icons to your project, it's important to update the path specified in the iconPath option accordingly during the implementation step.

---

Manual Installation

If you're unable to use Composer or prefer a manual installation, follow these steps.

1. Download the latest release of IconCaptcha for PHP.

   • Ensure you download the zip file named IconCaptcha-x.x.x.manual-install.zip from the release, rather than cloning the source code.

2. Unpack the content of the downloaded archive to a location on your computer or server.

   • Verify that the unpacked IconCaptcha for PHP folder contains the /vendor folder. We will utilize the pre-optimized autoloader generated with Composer to load IconCaptcha into your application. The classes in the project are structured according to the PSR-4 standard, so you can also use your own autoloader or include the files directly in your code.

3. In your application, create a folder where you will place the IconCaptcha source and assets.

   • For this example, we will utilize /iconcaptcha as the name for this folder.

4. Move the contents of the PHP package into the /iconcaptcha folder.

   • Verify that this folder now contains at least the following items: /vendor, /src and /assets.
   • Optionally, you may include the /examples and /sql folders if you wish to use these during the implementation step.

While the PHP package includes all the necessary client-side assets, it's possible that these assets may not always be the most up-to-date version. To guarantee that your project uses the latest version, proceed with steps 5 to 8.

5. Download the latest compatible release (same major version) of the IconCaptcha client-side package.

6. Move the /dist/js and /dist/css folders from the client-side package into the /iconcaptcha/assets/client folder.

7. Move the icons inside of the /dist/icons folder from the client-side package into the /iconcaptcha/icons folder.

8. Verify that the /assets folder now contains the following items: /client/css/iconcaptcha.min.css, /client/js/iconcaptcha.min.js, /icons and placeholder.png.

As a last check, verify that the /iconcaptcha folder contains the following items:

/assets/client/css/iconcaptcha.min.css
/assets/client/js/iconcaptcha.min.js
/assets/icons/light/
/assets/icons/dark/
/assets/placeholder.png
/src/
/vendor/

Important

The included vendor folder expects the source files to be located in the /src folder. Renaming or moving the folder around will break the included vendor folder.

All required files should now be available in your application and you can proceed with the the implementation step below.

Implementation

After completing the installation, continue with the implementation guide for detailed instructions on how to integrate IconCaptcha into your application and start protecting your forms.