A important part of the integration is verifying whether a captcha has been successfully completed. To achieve this, you need to handle the submitted form and allow IconCaptcha to validate the request. Chances are, you already have code in place for processing your form, so the next step is to incorporate the captcha validation process into your existing workflow.

You can validate the captcha by using $captcha->validate($_POST);. This function returns an object that contains the success() function. When you call this function, it returns a boolean value, indicating whether the captcha was completed or not. If the captcha was successfully completed (returns true), you can proceed with the form submission. However, if it returns false, it means the captcha was not completed, and you should handle this situation accordingly.

To determine the reason for why the captcha was not completed, you can check the error code by using getErrorCode() on the same variable. This error code will correspond with one of the error codes listed below.

The following code snippet is taken from the form submission demo and shows how to integrate this process into your application.

<?php

// Load the Composer autoloader.
require_once __DIR__ . '/path/to/vendor/autoload.php';

use IconCaptcha\IconCaptcha;

// Start a session.
// Only required when using any 'session' driver in the configuration.
session_start();

// If the form has been submitted, validate the captcha.
if(!empty($_POST)) {

    // Load the IconCaptcha options.
    $options = require 'captcha-config.php';

    // Create an instance of IconCaptcha.
    $captcha = new IconCaptcha($options);

    // Validate the captcha.
    $validation = $captcha->validate($_POST);

    // Confirm the captcha was validated.
    if($validation->success()) {
        // The captcha is valid. Execute your form processing code here.
    } else {
        // The captcha is invalid. To see the reason, use $validation->getErrorCode()
    }
}

You can manually reset either all captcha widgets on a webpage or reset a specific widget. Refreshing a widget will invalidate the challenge and rebuild the widget.

To reset all rendered widgets on the page, simply call the IconCaptcha.reset() function from your JavaScript code. This action will restore all widgets to their initial state.

If you wish to reset a specific widget, provide the widget's unique identifier as an argument to the reset function, like this: IconCaptcha.reset('5fd3c68181999b447d4c89df5818e8e3ed9142dc'). This will reset only the specified widget while leaving others unchanged.

If the validation process fails, you can determine the cause by examining the error code within the response. You can retrieve this error code by using the getErrorCode function of the validation object, like this: $validation->getErrorCode(). Below, you'll find a list of possible error codes that you may encounter. It's important to implement your own error handling mechanisms for these events.