README

A package that seamlessly integrates Cloudflare's Turnstile service into your Laravel application.

Installation

To install, use Composer:

composer require teampanfu/laravel-turnstile

Manual setup

As of Laravel 5.5, packages are automatically detected by package discovery. So if you are using a newer version, you can skip these steps.

Add the following to your config/app.php:

'providers' => [
    ...

    /*
     * Package Service Providers...
     */

    Panfu\Laravel\Turnstile\TurnstileServiceProvider::class,

    ...
],

'aliases' => [
    ...

    'Turnstile' => Panfu\Laravel\Turnstile\Facades\Turnstile::class,

    ...
],

Then publish the configuration file:

php artisan vendor:publish --provider="Panfu\Laravel\Turnstile\TurnstileServiceProvider"

Configuration

To get started, log in to the Cloudflare Dashboard, go to "Turnstile" in the side navigation, and add your website.

You will be given a site key and a secret key. You can add both to your .env file as follows:

TURNSTILE_SITEKEY=1x00000000000000000000AA
TURNSTILE_SECRET=1x0000000000000000000000000000000AA

Usage

Display

To display the widget on your website, you can simply add the following HTML code (assuming you are using Blade):

<div class="cf-turnstile" data-sitekey="{{ config('turnstile.sitekey') }}"></div>

A list of available configurations (such as theme or language) can be found in the documentation.

Script

In order for the widget to work, you need to include the JavaScript resource. You can add the following HTML code for this:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

Validation

To validate a request, you can use the following rule:

$request->validate([
    'cf-turnstile-response' => ['turnstile'],
]);

You can leave out the required rule, it is already handled by this package.

Custom validation message

You may want to display an error message in case the validation fails. Add the following to your lang/[lang]/validation.php file:

'custom' => [
    'cf-turnstile-response' => [
        'turnstile' => 'The validation has failed.',
    ],
],

Use without Laravel

Although the package is specifically designed for Laravel, it can still be used without it. Here is an example of how it works:

<?php

require_once 'vendor/autoload.php';

use Panfu\Laravel\Turnstile\Turnstile;

$sitekey = '1x00000000000000000000AA';
$secret = '1x0000000000000000000000000000000AA';
$turnstile = new Turnstile($secret);

if (! empty($_POST)) {
    $responseToken = $_POST['cf-turnstile-response'];
    $remoteip = $_SERVER['REMOTE_ADDR'];

    $isValid = $turnstile->validate($responseToken, $remoteip); // $remoteip is optional

    if ($isValid) {
        echo 'Token is valid.';
    } else {
        echo 'Token is not valid.';
    }
    exit;
}

?>

<form method="POST">
    <div class="cf-turnstile" data-sitekey="<?= $sitekey ?>"></div>
    <button type="submit">Submit</button>
</form>

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

Remote IP helps prevent abuses by ensuring that the current visitor is the one who received the token.

Testing

$ ./vendor/bin/phpunit

Contribute

If you find a bug or have a feature suggestion, feel free to create a new issue or pull request.

We appreciate every contribution!

License

This package is open-source software licensed under the MIT License.

teampanfu / laravel-turnstile

Maintainers

Details