README

Laravel ReCAPTCHA 是一个非常简单易用的 Laravel 5 包，用于在您的应用程序中嵌入 Google reCAPTCHA。

什么是 reCAPTCHA？

谷歌开发者说：“reCAPTCHA 可以保护您免受垃圾邮件和其他类型的自动化滥用。在这里，我们解释如何将 reCAPTCHA 添加到您的网站或应用程序。”

您可以在 Google reCAPTCHA 开发者指南 中找到更多信息

reCAPTCHA 可用版本

目前有 3 个版本可用（适用于 Web 应用程序）

• v3，最新版本（reCAPTCHA v3）
• v2 检查框 或简单称为 reCAPTCHA v2（reCAPTCHA v2）
• v2 无痕（无痕 reCAPTCHA）

首先获取您的密钥！

首先，您需要在 这里 创建自己的 API 密钥

按照说明操作，并在过程结束时，您将找到 网站密钥 和 密钥密钥。请妥善保管它们，您很快就会用到！

系统要求

(*) 版本 3.6.1 适用于 Laravel 6

Composer

您可以通过 composer 安装此包

$ composer require biscolab/laravel-recaptcha

Laravel 5.5（或更高版本）使用包自动发现，因此不需要您手动添加 Service Provider，但如果您不使用自动发现，则必须在 config/app.php 中注册 ReCaptchaServiceProvider

'providers' => [
    ...
    Biscolab\ReCaptcha\ReCaptchaServiceProvider::class,
];

您可以使用 facade 以缩短代码。将 ReCaptcha 添加到您的别名

'aliases' => [
    ...
    'ReCaptcha' => Biscolab\ReCaptcha\Facades\ReCaptcha::class,
];

发布包

使用以下 artisan 命令创建 config/recaptcha.php 配置文件

$ php artisan vendor:publish --provider="Biscolab\ReCaptcha\ReCaptchaServiceProvider"

设置环境变量

添加您的 API 密钥

打开 .env 文件并设置 RECAPTCHA_SITE_KEY 和 RECAPTCHA_SECRET_KEY

# in your .env file
RECAPTCHA_SITE_KEY=<YOUR_API_SITE_KEY>
RECAPTCHA_SECRET_KEY=<YOUR_API_SECRET_KEY>
RECAPTCHA_SKIP_IP=<YOUR_IP_LIST>

RECAPTCHA_SKIP_IP（自 v5.2.0 起不再需要，CSV 格式）允许您添加 IP/CIDR（包括子网掩码）列表。它将是 skip_ip 的值

以下环境变量已被删除！！！ 现在，只有敏感信息（如 API 密钥）才允许作为环境变量，这意味着您必须在 config/recaptcha.php 中设置配置值

• RECAPTCHA_DEFAULT_VERSION
• RECAPTCHA_CURL_TIMEOUT
• RECAPTCHA_DEFAULT_VALIDATION_ROUTE
• RECAPTCHA_DEFAULT_TOKEN_PARAMETER_NAME
• RECAPTCHA_DEFAULT_LANGUAGE

完整配置

打开 config/recaptcha.php 配置文件并设置 version

return [
    'api_site_key'                  => env('RECAPTCHA_SITE_KEY', ''),
    'api_secret_key'                => env('RECAPTCHA_SECRET_KEY', ''),
    // changed in v4.0.0
    'version'                       => 'v2', // supported: "v3"|"v2"|"invisible"
    // @since v3.4.3 changed in v4.0.0
    'curl_timeout'                  => 10,
    'skip_ip'                       => env('RECAPTCHA_SKIP_IP', []), // array of IP addresses - String: dotted quad format e.g.: "127.0.0.1", IP/CIDR netmask eg. 127.0.0.0/24, also 127.0.0.1 is accepted and /32 assumed
    // @since v3.2.0 changed in v4.0.0
    'default_validation_route'      => 'biscolab-recaptcha/validate',
    // @since v3.2.0 changed in v4.0.0
    'default_token_parameter_name' => 'token',
    // @since v3.6.0 changed in v4.0.0
    'default_language'             => null,
    // @since v4.0.0
    'default_form_id'              => 'biscolab-recaptcha-invisible-form', // Only for "invisible" reCAPTCHA
    // @since v4.0.0
    'explicit'                     => false, // true|false
    // @since v4.3.0
    'api_domain'                   => "www.google.com", // default value is "www.google.com"
    // @since v5.1.0
    'empty_message'                => false,
    // @since v5.1.0
    'error_message_key'            => 'validation.recaptcha',
    // @since v4.0.0
    'tag_attributes'               => [
        'theme'                    => 'light', // "light"|"dark"
        'size'                     => 'normal', // "normal"|"compact"
        'tabindex'                 => 0,
        'callback'                 => null, // DO NOT SET "biscolabOnloadCallback"
        'expired-callback'         => null, // DO NOT SET "biscolabOnloadCallback"
        'error-callback'           => null, // DO NOT SET "biscolabOnloadCallback"
    ]
];

(array) tag_attributes

不要将 tag_attributes.callback、tag_attributes.expired-callback 和 tag_attributes.error-callback 设置为 biscolabOnloadCallback。 biscolabOnloadCallback 是当 显式 设置为 true 并且小部件 onload 事件触发时调用的默认 JavaScript 回调函数。

您可以在以下位置找到有关 tag_attributes.* 的更多详细信息 https://developers.google.com/recaptcha/docs/display#render_param

重新加载配置缓存文件

!!! 重要 !!! 每次更改某些配置时，请运行以下 shell 命令

$ php artisan config:cache

您已更新了吗？

如果您正在从旧版本迁移，请检查您的 config/recaptcha.php 配置文件，并将其与 https://github.com/biscolab/laravel-recaptcha/blob/master/config/recaptcha.php 进行比较。

确保 config/recaptcha.php 已更新

自定义错误信息

仅适用于 v2 和隐形用户。

在开始之前，请将验证信息添加到 resources/lang/[LANG]/validation.php 文件中

return [
    ...
    'recaptcha' => 'Hey!!! :attribute is wrong!',
];

嵌入 Blade

在关闭 </head> 标签之前插入 htmlScriptTagJsApi() 辅助函数。

您还可以使用 ReCaptcha::htmlScriptTagJsApi()。

<!DOCTYPE html>
<html>
    <head>
        ...
        {!! htmlScriptTagJsApi($configuration) !!}
    </head>

htmlScriptTagJsApi

htmlScriptTagJsApi 函数接受 $configuration 参数。根据您使用的 ReCAPTCHA 类型，$configuration 包含不同的键。

• 复选框
• 隐形

ReCAPTCHA v2 复选框

htmlScriptTagJsApi($configuration)

$configuration 参数可以包含以下键

• lang 设置 reCAPTCHA 语言。这将覆盖 config/recaptcha.php 中的 default_language。在此处您可以找到可用的完整语言列表 https://developers.google.com/recaptcha/docs/language

表单设置

在您插入 htmlFormSnippet() 辅助函数到您想要使用字段 g-recaptcha-response 的表单中之后。

您还可以使用 ReCaptcha::htmlFormSnippet() .

<form>
    @csrf

    ...
    {!! htmlFormSnippet() !!}
    <!-- OR -->
    {!! htmlFormSnippet($attributes) !!}
    <input type="submit">
</form>

不要忘记 @csrf blade 指令

htmlFormSnippet([, array $attributes = [] ])

htmlFormSnippet 函数不需要属性，但您可以覆盖默认的 data- 属性

{!! htmlFormSnippet([
    "theme" => "light",
    "size" => "normal",
    "tabindex" => "3",
    "callback" => "callbackFunction",
    "expired-callback" => "expiredCallbackFunction",
    "error-callback" => "errorCallbackFunction",
]) !!}

htmlFormSnippet 方法允许以下属性名称

• theme
• size
• tabindex
• callback
• expired-callback
• error-callback

任何不同的属性名称都将被拒绝

自定义

在 config/recaptcha.php 中，您可以自定义 reCAPTCHA 小部件设置 tag_attributes 数组值。请参阅 完整配置 中的 tag_attributes 部分

ReCAPTCHA v2 隐形

htmlScriptTagJsApi($configuration)

$configuration 参数可以包含以下键

• form_id 设置 reCAPTCHA 表单 ID。这将覆盖 config/recaptcha.php 中的 default_form_id。此值将由 getFormId() 函数返回，以便设置表单标签的 id 属性。

表单设置

在您插入 htmlFormButton($button_label, $properties) 辅助函数到您想要使用 reCAPTCHA 的表单中之后。

此函数创建提交按钮，因此您不需要插入 <input type="submit"> 或类似的。

您还可以使用 ReCaptcha::htmlFormButton($button_label, $properties) .

$button_label 是您想要在提交按钮上写入的内容

<form id="{{ getFormId() }}">
  @csrf ... {!! htmlFormButton($button_label, $properties) !!}
</form>

不要忘记 @csrf blade 指令

getFormId()

getFormId 函数返回默认表单 ID 值。这是 config/recaptcha.php 中的 default_form_id 的值或之前作为 htmlScriptTagJsApi 辅助函数参数设置的 $configuration['form_id']。

$configuration['form_id'] 覆盖默认设置。

htmlFormButton()

htmlFormButton 函数接受 2 个参数

• $button_label: (字符串：可选) 按钮标签。例如：订阅！;
• $properties: (数组：可选) HTML 按钮属性。例如

// $properties =
[
    'class' => 'btn btn-info',
    'data-foo' => 'bar'
]

如果设置了 data-sitekey 和 data-callback 属性，它们将被覆盖

如果设置了 class 属性，则将附加值 g-recaptcha

验证提交数据

将 recaptcha 添加到您的规则中

$validator = Validator::make(request()->all(), [
    ...
    'g-recaptcha-response' => 'recaptcha',
    // OR since v4.0.0
    recaptchaFieldName() => recaptchaRuleName()
]);

// check if validator fails
if($validator->fails()) {
    ...
    $errors = $validator->errors();
}

嵌入 Blade

在关闭 </head> 标签之前插入 htmlScriptTagJsApi($config) 辅助函数。

<!DOCTYPE html>
<html>
    <head>
        ...
        {!! htmlScriptTagJsApi([
            'action' => 'homepage',
            'callback_then' => 'callbackThen',
            'callback_catch' => 'callbackCatch'
        ]) !!}

        <!-- OR! -->
        
        {!! htmlScriptTagJsApi([
            'action' => 'homepage',
            'custom_validation' => 'myCustomValidation'
        ]) !!}
    </head>

$config 是必需的，是一个关联数组，包含用于 JavaScript 验证处理的所需配置参数。

键是

内置JavaScript验证系统

grecaptcha.execute的回调中，将使用fetch函数执行到config('recaptcha.default_validation_route')的ajax调用。如果响应成功，将接收到一个Promise对象，并将其作为参数传递给您设置的callback_then函数。如果没有设置，则不会执行任何操作。

与callback_catch相同。在响应错误事件中调用callback_catch，错误将作为参数传递给该函数。如果没有设置，则不会执行任何操作。

请访问使用Fetch以获取有关fetch JavaScript函数的更多信息。

警告!!! 检查浏览器兼容性 fetch函数与一些浏览器（如IE）存在兼容性问题。请创建一个自定义验证函数，并将custom_validation设置为该函数的名称。该函数必须接受从Google reCAPTCHA API收到的token作为参数。

Fetch浏览器兼容性

验证Laravel路由

默认验证路由是config('recaptcha.default_validation_route', 'biscolab-recaptcha/validate')。
路由和相对控制器都是内置在包中的。该路由通过Laravel web中间件进行过滤和保护，这就是为什么重要，您需要嵌入csrf-token HTML元标签，并发送X-Requested-With和X-CSRF-TOKEN头。

您还可以通过在recaptcha.php配置文件中更改default_validation_route值来更改验证端点。

<head>
    ...
    <!-- IMPORTANT!!! remember CSRF token -->
    <meta name="csrf-token" content="{{ csrf_token() }}">
</head>

验证响应对象

输出将是一个包含以下数据的JSON

• 默认输出（无错误）

{
    "action":"homepage",
    "challenge_ts":"2019-01-29T00:42:08Z",
    "hostname":"www.yourdomain.ext",
    "score":0.9,
    "success":true
}

• 当调用IP包含在"skip_ip"配置白名单中时的输出

{
    "skip_by_ip":true,
    "score":0.9,
    "success":true
}

如果您使用htmlScriptTagJsApiV3助手在blade文件中嵌入代码，则不会执行验证调用！

更多信息请参阅配置页面

• 来自Google reCAPTCHA API的空响应输出

{
    "error":"cURL response empty",
    "score":0.1,
    "success":false
}

在下一段中，您可以学习如何处理验证promise对象

"callback_then"和"callback_catch"

在内置验证之后，您应该做一些事情。如何？使用callback_then和callback_catch函数。

您需要做的是只是创建函数，并设置它们的参数。

• callback_then必须接收一个类型为Promise的参数。

• callback_catch必须接收一个类型为string的参数

结果应该是这样的

<head>
    ...
    <!-- IMPORTANT!!! remember CSRF token -->
    <meta name="csrf-token" content="{{ csrf_token() }}">
    ...
    <script type="text/javascript">
        function callbackThen(response){
        	// read HTTP status
            console.log(response.status);
            
            // read Promise object
            response.json().then(function(data){
                console.log(data);
            });
        }
        function callbackCatch(error){
            console.error('Error:', error)
        }   
    </script>    
    ...
    {!! htmlScriptTagJsApiV3([
        'action' => 'homepage',
        'callback_then' => 'callbackThen',
        'callback_catch' => 'callbackCatch'
    ]) !!}    
</head>

“custom_validation”函数

如前所述，您可以使用自己的函数处理验证。为此，您必须编写自己的函数，并将custom_validation参数设置为该函数的名称。

结果应该是这样的

<head>
    ...
    <!-- IMPORTANT!!! remember CSRF token --> 
    <meta name="csrf-token" content="{{ csrf_token() }}">
    ...
    <script type="text/javascript">
        function myCustomValidation(token) {
            // do something with token 
        }
    </script>    
    ...
    {!! htmlScriptTagJsApiV3([
        'action' => 'homepage',
        'custom_validation' => 'myCustomValidation'
    ]) !!}    
</head>