包简介

Laravel package for Google reCAPTCHA v3 integration with form validation and spam protection

README 文档

README

A Laravel package that provides a simple and elegant integration of Google reCAPTCHA v3 for your Laravel applications. This package includes a Blade directive for easy frontend integration and a validation rule for backend verification with customizable score thresholds.

Installation

You can install the package via composer:

composer require maize-tech/laravel-google-recaptcha-v3

You can install and configure the package with:

php artisan google-recaptcha-v3:install

This command will publish the configuration file.

This is the contents of the published config file:

return [
    /*
    |--------------------------------------------------------------------------
    | Enabled
    |--------------------------------------------------------------------------
    |
    | This option controls whether Google reCAPTCHA v3 is enabled.
    | When disabled, the validation will be skipped.
    |
    */
    'enabled' => env('GOOGLE_RECAPTCHA_V3_ENABLED', true),

    /*
    |--------------------------------------------------------------------------
    | Site Key
    |--------------------------------------------------------------------------
    |
    | Your Google reCAPTCHA v3 site key.
    | You can get this from https://www.google.com/recaptcha/admin
    |
    */
    'site_key' => env('GOOGLE_RECAPTCHA_V3_SITE_KEY'),

    /*
    |--------------------------------------------------------------------------
    | Secret Key
    |--------------------------------------------------------------------------
    |
    | Your Google reCAPTCHA v3 secret key.
    | You can get this from https://www.google.com/recaptcha/admin
    |
    */
    'secret_key' => env('GOOGLE_RECAPTCHA_V3_SECRET_KEY'),

    /*
    |--------------------------------------------------------------------------
    | Score Threshold
    |--------------------------------------------------------------------------
    |
    | The minimum score threshold for the reCAPTCHA validation.
    | Google reCAPTCHA v3 returns a score (1.0 is very likely a good interaction,
    | 0.0 is very likely a bot). Default is 0.5.
    |
    */
    'score_threshold' => env('GOOGLE_RECAPTCHA_V3_SCORE_THRESHOLD', 0.5),

    /*
    |--------------------------------------------------------------------------
    | Badge
    |--------------------------------------------------------------------------
    |
    | The default badge position for the reCAPTCHA badge.
    | Available options: 'bottomright', 'bottomleft', 'inline', 'hidden'.
    | Default is 'bottomright'.
    |
    */
    'badge' => env('GOOGLE_RECAPTCHA_V3_BADGE', 'bottomright'),
];

Configuration

After installing the package, add the following environment variables to your .env file:

GOOGLE_RECAPTCHA_V3_ENABLED=true
GOOGLE_RECAPTCHA_V3_SITE_KEY=your-site-key-here
GOOGLE_RECAPTCHA_V3_SECRET_KEY=your-secret-key-here
GOOGLE_RECAPTCHA_V3_SCORE_THRESHOLD=0.5
GOOGLE_RECAPTCHA_V3_BADGE=bottomright

You can obtain your site key and secret key from the Google reCAPTCHA Admin Console.

Usage

Frontend Integration

Add the reCAPTCHA script to your Blade templates using the @recaptcha directive:

@recaptcha

You can also customize the badge position by passing one of the available badge positions:

<!DOCTYPE html>
<html>
<head>
    <title>My Form</title>
</head>
<body>
    <form id="myForm" method="POST" action="/submit">
        @csrf
        <!-- Your form fields -->
        <input type="hidden" name="g-recaptcha-response" id="g-recaptcha-response">
        <button type="submit">Submit</button>
    </form>

    @recaptcha(\Maize\GoogleRecaptchaV3\Enums\Badge::BOTTOMRIGHT)

    <script>
        document.getElementById('myForm').addEventListener('submit', async function(e) {
            e.preventDefault();

            const token = await window.recaptcha('submit');
            document.getElementById('g-recaptcha-response').value = token;

            this.submit();
        });
    </script>
</body>
</html>

Available Badge Positions

Badge::INLINE - Displays the badge inline
Badge::BOTTOMLEFT - Displays the badge at the bottom left
Badge::BOTTOMRIGHT - Displays the badge at the bottom right (recommended)
Badge::HIDDEN - Hides the badge completely

Important Note about Hidden Badge: When using Badge::HIDDEN, you must display the reCAPTCHA branding visibly in your user flow. According to Google's guidelines, you need to include the following text:

This site is protected by reCAPTCHA and the Google
<a href="https://policies.google.com/privacy">Privacy Policy</a> and
<a href="https://policies.google.com/terms">Terms of Service</a> apply.

Backend Validation

Use the googleRecaptchaV3 validation rule in your form requests or controllers:

use Illuminate\Support\Facades\Validator;

$validator = Validator::make($request->all(), [
    'name' => 'required|string',
    'email' => 'required|email',
    'g-recaptcha-response' => ['required', 'string', Rule::googleRecaptchaV3()],
]);

Custom Score Threshold

You can override the default score threshold (configured in config/google-recaptcha-v3.php) by passing a custom threshold to the validation rule:

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

$validator = Validator::make($request->all(), [
    'g-recaptcha-response' => ['required', 'string', Rule::googleRecaptchaV3(0.7)],
]);

A higher threshold (e.g., 0.7 or 0.8) means stricter validation, while a lower threshold (e.g., 0.3 or 0.4) is more permissive.

Form Request Example

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

class ContactFormRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'max:255'],
            'message' => ['required', 'string', 'max:1000'],
            'g-recaptcha-response' => ['required', 'string', Rule::googleRecaptchaV3()],
        ];
    }
}

JavaScript Helper

The package automatically provides a global window.recaptcha() function that you can use to get the reCAPTCHA token:

// Get token with default action 'submit'
const token = await window.recaptcha();

// Get token with custom action
const token = await window.recaptcha('login');

This function returns a Promise that resolves to the reCAPTCHA token, or null if reCAPTCHA is not available or fails.

Disabling reCAPTCHA

You can disable reCAPTCHA validation by setting the enabled configuration to false or by setting the GOOGLE_RECAPTCHA_V3_ENABLED environment variable to false. This is useful for local development or testing environments.

When disabled:

The @recaptcha directive will not render any scripts
The validation rule will pass without making any API calls to Google

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

maize-tech/laravel-google-recaptcha-v3 适用场景与选型建议

maize-tech/laravel-google-recaptcha-v3 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 90 次下载、GitHub Stars 达 3，最近一次更新时间为 2025 年 10 月 17 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「security」「laravel」「form-validation」「spam-protection」「recaptcha-v3」「google-recaptcha」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 maize-tech/laravel-google-recaptcha-v3 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 maize-tech/laravel-google-recaptcha-v3 我们能提供哪些服务？

定制开发 / 二次开发

基于 maize-tech/laravel-google-recaptcha-v3 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 maize-tech/laravel-google-recaptcha-v3 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

bitapps/wp-validator 12

WordPress Validation and Sanitization Library

sil/route-security-bundle 7

Provide a way to secure accesses to all routes of an symfony application.

emailsherlock/email-guard-core 0

Email-Guard core library for PHP: local email checks (syntax, reserved TLDs, disposable domains) plus optional escalation to the EmailSherlock Verify API.

vuillaume-agency/symfony-turnstile 4

Symfony bundle for Cloudflare Turnstile - a privacy-friendly, GDPR-compliant CAPTCHA alternative. Drop-in reCAPTCHA replacement with zero user friction.

caspermascot/forms 0

A fast PHP7 implementation of Html forms

eftec/securityonemysql 6

It's a barebone security class written on PHP

maize-tech/laravel-google-recaptcha-v3

包简介

关键字：