README

Callable 包装器、Slim3 中间件和 Pimple 风格的服务提供者，用于 Google 的 ReCaptcha。

使用 Composer 安装

$ composer require germania-kg/googlerecaptcha

或者，直接将此包添加到您的 composer.json：

"require": {
    "germania-kg/googlerecaptcha": "^1.0"
}

使用方法

以下示例假设您正在使用 Pimple 或 Slim 框架，并且您的依赖注入容器已准备就绪

$app = new Slim\App;
$dic = $app->getContainer();
$dic = new Slim\Container;
$dic = new Pimple\Container;

服务提供者

请参阅服务详细信息，了解提供哪些服务和资源。有关公共和秘密测试密钥，请参阅官方 reCAPTCHA v2 FAQ。

<?php
use Germania\GoogleRecaptcha\GoogleRecaptchaServiceProvider;

// See FAQ for test keys
$public_key = "lots_of_characters_here";
$secret_key = "secret_bunch_of_characters_here";

// Pass keys to ServiceProvider
$recaptcha_services = new GoogleRecaptchaServiceProvider( $public_key, $secret_key );
// ... and optionally a PSR-3 Logger
$recaptcha_services = new GoogleRecaptchaServiceProvider( $public_key, $secret_key, $logger );

// Now register; all services will transparently be added to the $dic
$dic->register( $recaptcha_services );

Slim3 风格中间件

在路由控制器执行之前，此中间件会检查

是否有 recaptcha 用户输入在 $_POST['g-recaptcha-response']
是否与 Google 的 ReCaptcha 客户端验证成功。

根据结果，此中间件会

将验证结果存储在名为 GoogleRecaptcha 的 Request 属性中。
当验证失败时，将 400 Bad Request 状态码添加到 Response 对象。

此处使用的字符串标识符可以在Google.Recaptcha.Config 服务中进行修改，请参阅下文。

<?php
use Germania\GoogleRecaptcha\GoogleRecaptchaMiddleware;

// 1. Add Service provider first
// 2. Create route
$route = $app->post('/new', function() { ...} );

// 2. Add route middleware
$route->add( 'Google.Recaptcha.Middleware' );

重要提示：无论验证状态如何，中间件都将调用 $next 中间件。任何路由控制器都应该自行检查 HTTP 状态并相应地作出反应。GoogleRecaptcha 请求属性数组将有所帮助——只需请求 failed、success 或 status 元素即可。

$route = $app->post('/new', function(Request $request, Response $response) { ...

	// Grab
	$recaptcha_status = $request->getAttribute("GoogleRecaptcha");

	// All these are boolean
	if ($recaptcha_status['failed']) { ... }
	if ($recaptcha_status['success']) { ... }
	if ($recaptcha_status['status'] == true) { ... }
});

Callable 验证包装器

ReCaptcha 验证客户端会自动实例化。Callable 包装器使用与 ServiceProvider 相同的日志实例。有关如何设置自己的验证器实例，请参阅Google.Recaptcha.Validator 部分。

<?php
// 1. Add Service provider first
// 2. Grab service. 
$callable_recaptcha = $dic['Google.Recaptcha.Validator.Callable'];

// TRUE or FALSE
$valid = $callable_recaptcha( $_POST['g_recaptcha_response'], $_SERVER['REMOTE_ADDR'] );

服务详细信息

Google.Recaptcha.PublicKey

这可能是您最需要的服务。

<?php
$public_key = $dic['Google.Recaptcha.PublicKey'];

echo $twig->render('form.tpl', [
	'recaptcha_key' => $public_key
]);

Google.Recaptcha.Logger

默认日志已传递给实例化。可以像这样覆盖或自定义

<?php
$dic->extend('Google.Recaptcha.Logger', function($default_logger, $dic) {
	$custom_logger = $dic['CustomLogger'];
    return $custom_logger->withName( "CustomLogger" );
});

Google.Recaptcha.ClientIP

客户端 API 用于请求 Google 的 Web API；其默认值为 $_SERVER['REMOTE_ADDR']。您通常不需要覆盖此值

<?php
$dic->extend('Google.Recaptcha.ClientIP', function($server_remote_addr, $dic) {
	$ip = 'whatever'
    return $ip;
});

Google.Recaptcha.Validator

这会创建 Google 的服务器端验证客户端，它包含官方 ReCaptcha\ReCaptcha 库。它将与此 GoogleRecaptcha 包自动安装并自动实例化。如果您希望创建自己的，可以这样做

<?php
use ReCaptcha\ReCaptcha;

$dic->extend('Google.Recaptcha.Validator', function($default, $dic) {
	$secret = $dic['Google.Recaptcha.SecretKey'];
	$my_recaptcha = new Recaptcha( $secret );
    return $my_recaptcha;
});

Google.Recaptcha.Validator.Callable

Google.Recaptcha.Validator.Callable 是一个可调用的包装器，即一个可调用的类，围绕 Google.Recaptcha.Validator 服务。此可执行程序将返回确切的 true 或 false。 它使用上述 Google.Recaptcha.Logger 实例，在成功时记录 info，在失败时记录 notice。

<?php
// Most simple:
$callable_recaptcha = $dic['Google.Recaptcha.Validator.Callable'];

// Validate a form:
$recaptcha_input = $_POST['g-recaptcha-response'];
$remote_ip = $dic['Google.Recaptcha.ClientIP'];

$valid = $callable_recaptcha( $recaptcha_input, $remote_ip);

手动实例化时，它接受可选的日志记录器。

<?php>
use Germania\GoogleRecaptcha\GoogleRecaptchaCallable;

$validator = $dic['Google.Recaptcha.Validator'];
$callable_recaptcha = new GoogleRecaptchaCallable( $validator );
// Optionally with custom Logger
$callable_recaptcha = new GoogleRecaptchaCallable( $validator, $logger );

Google.Recaptcha.Config

此配置数组由GoogleRecaptchaMiddleware使用，并提供以下值

<?php
$dic->extend('Google.Recaptcha.Config', function($default, $dic) {
    return array_merge($default, [
        'request_attribute' => 'custom_attr_name'
    ]);
});

开发

$ git clone https://github.com/GermaniaKG/GoogleRecaptcha.git
$ cd GoogleRecaptcha
$ composer install

单元测试

可以将phpunit.xml.dist复制到phpunit.xml并根据需要修改，或者保持原样。运行PhpUnit测试或composer脚本如下

$ composer test
# or
$ vendor/bin/phpunit

germania-kg / googlerecaptcha

维护者

详细信息