Demo & Documentation for SOLVEX CAPTCHA

SOLVEX CAPTCHA is a PHP image CAPTCHA widget with server-side validation, token checks, refresh cooldowns, and rate limiting. This page follows the same documentation format as the provided template, while documenting the actual SOLVEX integration available at https://localhost/SOLVEX/.

To see the SOLVEX CAPTCHA in action right now, use the live demo below. This is the real form handler from index.php, so submissions are validated by captcha_validate_submission() on the server.

You need only one widget container inside your form and one script include. Code sample:

<form method="post" autocomplete="off">
    <div data-solvex-captcha data-refresh-url="captcha_refresh.php"></div>
    <button type="submit">Submit</button>
</form>

<script src="solvex-captcha.js"></script>

Server-side validation is handled in PHP by reading the posted token and answer, then calling captcha_validate_submission(). Code sample:

<?php
require_once __DIR__ . '/captcha_lib.php';

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $token = isset($_POST['captcha_token']) ? strtolower(trim((string) $_POST['captcha_token'])) : '';
    $answer = isset($_POST['captcha_answer']) ? (string) $_POST['captcha_answer'] : '';

    $result = captcha_validate_submission($answer, $token);
    if ($result['ok']) {
        // Continue normal processing
    } else {
        $errorMessage = $result['message'];
    }
}

The refresh endpoint returns JSON that includes the token, image URL, expiry, and image dimensions. The widget uses this payload automatically. Example payload:

{
  "ok": true,
  "token": "7e6f...",
  "image_url": "captcha.php?token=7e6f...",
  "expires_in": 180,
  "size": "300x100",
  "width": 300,
  "height": 100
}

The widget container supports the data attributes below. These control which endpoint is used, how the fields are named, and what text is shown in the interface:

attribute	default	description
data-refresh-url	captcha_refresh.php	POST endpoint used to load or refresh the current challenge.
data-refresh-cooldown	8	Seconds before the refresh button becomes active again.
data-token-field	captcha_token	Hidden field name used for the generated challenge token.
data-answer-field	captcha_answer	Visible input field name used for the typed answer.
data-answer-label	CAPTCHA Answer	Label text shown above the answer input.
data-answer-placeholder	Enter the CAPTCHA text	Placeholder text shown inside the answer field.
data-refresh-text	Refresh CAPTCHA	Button text for requesting a new challenge.

Only these project files are needed for the SOLVEX CAPTCHA demo and embed flow:

file	purpose
index.php	Demo and documentation page using the template layout.
solvex-captcha.js	Frontend widget that renders the CAPTCHA block and fetches challenges.
captcha_refresh.php	JSON endpoint that returns the active or refreshed challenge payload.
captcha.php	PNG image endpoint protected by token, session, and rate-limit checks.
captcha_lib.php	Shared challenge generation, validation, rendering, and rate-limit logic.

Important response codes and behaviors are listed below. These are the responses the browser or your form handler may see while working with the CAPTCHA endpoints:

code	meaning
200	Challenge loaded successfully, or form validation passed.
400	Bad request, such as an invalid token format.
403	Request token does not match the active session challenge.
405	Invalid HTTP method on the refresh endpoint.
410	Challenge expired and must be refreshed.
422	Wrong answer; the server rotates to a new challenge.
429	Cooldown, lock window, or rate limit reached.
503	Image generation capacity is temporarily busy.

Production notes:

• Replace CAPTCHA_SECRET in captcha_lib.php with a long random value before production use.
• Ensure the PHP GD extension is enabled in XAMPP.
• Keep storage/ writable by the web server user.
• Keep usable font files inside fonts/ for CAPTCHA rendering.
• Wrong answers rotate to a new challenge, successful answers clear the session challenge, and expired challenges must be refreshed.