shevabam/simple-hcaptcha

A simple PHP library to integrate hCaptcha in your PHP applications

Maintainers

Details

github.com/shevabam/simple-hcaptcha

Homepage

Source

Issues

Installs: 3

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

v1.0.0 2025-07-20 19:18 UTC

Requires

MIT 9d4d1c57548f6cfb1aa8b6db5ef3960df68d73cc

captchahcaptcha

This package is auto-updated.

Last update: 2025-07-20 19:22:04 UTC

README

A simple PHP library to integrate hCaptcha in your PHP applications.

Requirements

  • PHP 7.4 or higher
  • cURL extension
  • JSON extension

Installation

Install via Composer:

composer require shevabam/hcaptcha-php

Usage

Basic Usage

<?php
require 'vendor/autoload.php';

use Hcaptcha\Hcaptcha;

// Initialize with your site key and secret key
$hcaptcha = new Hcaptcha('your-site-key', 'your-secret-key');

// Process form submission
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $hcaptchaResponse = $_POST['h-captcha-response'] ?? '';
    
    // Remote IP is optional, but recommended
    if ($hcaptcha->isValid($hcaptchaResponse, $_SERVER['REMOTE_ADDR'])) {
        // CAPTCHA validation passed, process the form
        echo "Form submitted successfully!";
    } else {
        // CAPTCHA validation failed
        echo "CAPTCHA verification failed: " . $hcaptcha->getError();
    }
}
?>

<!-- Your HTML form -->
<html>
<head>
    <?php echo $hcaptcha->getScript(); ?>
</head>
<body>
    <form method="post">
        <!-- Your form fields -->
        
        <!-- Display hCaptcha widget -->
        <?php echo $hcaptcha->display(); ?>
        
        <button type="submit">Submit</button>
    </form>
</body>
</html>

Available Methods

getScript(): string

Generate the HTML code to include the hCaptcha script.

display(): string

Generate the HTML code to display the hCaptcha widget.

isValid(string $response, ?string $remoteIp = null): bool

Verify if the CAPTCHA response is valid.

getError(): string

Get the error message of the last operation.

getErrorCode(): ?string

Get the error code of the last operation.

setTheme(string $theme): self

Set the theme of the hCaptcha widget ('light' or 'dark').

setSize(string $size): self

Set the size of the hCaptcha widget ('normal' or 'compact').

setLanguage(string $language): self

Set the language of the hCaptcha widget.

setOption(string $key, $value): self

Set a custom option.

Configuration

You can configure the hCaptcha widget by passing an array of options to the constructor or using the setter methods:

$hcaptcha = new Hcaptcha('your-site-key', 'your-secret-key', [
    'theme' => 'dark',
    'size' => 'normal',
    'language' => 'fr'
]);

// Or using setter methods
$hcaptcha
    ->setTheme('dark')
    ->setSize('normal')
    ->setLanguage('fr');

Usage

To generate the script tag, use :

$hcaptcha->getScript();

To display the widget in your form, use :

$hcaptcha->display();

To verify the CAPTCHA response, use :

if ($hcaptcha->isValid($_POST['h-captcha-response'], $_SERVER['REMOTE_ADDR'])) {
    // CAPTCHA validation passed, process the form
    echo "Form submitted successfully!";
} else {
    // CAPTCHA validation failed
    echo "CAPTCHA verification failed: " . $hcaptcha->getError();
}

Error Handling

When isValid() returns false, you can get the error message using getError():

if (!$hcaptcha->isValid($response)) {
    $error = $hcaptcha->getError();
    // Handle the error
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Created by @shevabam