README

此扩展包为您的Symfony网站引入了一个新的表单类型，即HCaptchaType，用于显示和验证由https://www.hcaptcha.com提供的CAPTCHA。

此扩展包针对Symfony的主要版本3、4、5和6进行了测试。主要版本2适用于Symfony 3和4，需要PHP 7.2+；主要版本3适用于Symfony 5和6，需要PHP 7.4或8.x；主要版本4适用于Symfony 6.4和7，需要PHP 8.2+。测试依赖项的要求可能更严格。

安装

使用Symfony Flex的应用程序

打开命令行，进入项目目录并执行

$ composer require meteo-concept/hcaptcha-bundle

为了避免让您安装另一个兼容的HTTP客户端，此扩展包依赖于虚拟包，即PSR-18 psr/http-client-interface和PSR-17 psr/http-factory-interface。如果您已经在应用程序中安装了任何提供这些实现的实际包，Composer会抱怨扩展包无法安装。在这种情况下，您必须在安装扩展包的同时提供实际实现。

例如，从Symfony 4开始

$ composer require meteo-concept/hcaptcha-bundle symfony/http-client nyholm/psr7

对于Symfony 3

$ composer require meteo-concept/hcaptcha-bundle guzzlehttp/guzzle nyholm/psr7

不使用Symfony Flex的应用程序

步骤1：下载扩展包

使用上述命令之一安装扩展包。现在您需要启用它并配置它，无需使用配方。

步骤2：启用扩展包

然后，通过将其添加到项目中config/bundles.php文件中注册的扩展包列表中，启用扩展包

// config/bundles.php

return [
    // ...
    MeteoConcept\HCaptchaBundle\MeteoConceptHCaptchaBundle::class => ['all' => true],
];

配置

此CAPTCHA提供有Symfony flex contrib配方，因此如果已启用，则应包含配置。否则，您可以从contrib存储库中复制配置：[https://github.com/symfony/recipes-contrib/tree/master/meteo-concept/hcaptcha-bundle](https://github.com/symfony/recipes-contrib/tree/master/meteo-concept/hcaptcha-bundle)。

配置扩展包，例如在config/packages/meteo_concept_hcaptcha.yml中

parameters:
    hcaptcha_site_key: '%env(resolve:HCAPTCHA_SITE_KEY)%'
    hcaptcha_secret: '%env(resolve:HCAPTCHA_SECRET)%'

meteo_concept_h_captcha:
  hcaptcha:
    site_key: '%hcaptcha_site_key%'
    secret: '%hcaptcha_secret%'
  validation: 'strict' # this is the default

并在.env中进行相应的更改

HCAPTCHA_SITE_KEY="10000000-ffff-ffff-ffff-000000000001"
HCAPTCHA_SECRET="0x0000000000000000000000000000000000000000"

站点密钥和密钥是hCaptcha在https://dashboard.hcaptcha.com提供的值。全局配置使所有CAPTCHA默认使用相同的站点密钥，但在每个表单的定义中可以更改它。

此处显示的值是用于集成测试的示例值（[https://docs.hcaptcha.com/#integrationtest](https://docs.hcaptcha.com/#integrationtest)）。将真实值放入.env.local（至少密钥，站点密钥是公开的）。

验证可以设置为'严格'或'宽松'。如果是'宽松'，则即使hCaptcha端点超时或返回HTTP 500错误等，也将认为CAPTCHA有效（以免过于挫败用户）。如果是严格（默认），则只有当端点返回"success: true"响应时，才认为CAPTCHA有效。

配置Twig以加载hCaptcha小部件的特定模板（或提供您自己的）。

twig:
    ...
    form_themes:
        - '@MeteoConceptHCaptcha/hcaptcha_form.html.twig'
        - ...

如果您使用Guzzle或另一个HTTP库，可能还需要为该库及其服务提供配置。例如，对于Guzzle，您可能需要在services.yaml中添加以下内容

services:
    Psr\Http\Client\ClientInterface:
        class: GuzzleHttp\Client
    Psr\Http\Message\RequestFactoryInterface:
        class: Nyholm\Psr7\Factory\Psr17Factory
    Psr\Http\Message\StreamFactoryInterface:
        class: Nyholm\Psr7\Factory\Psr17Factory

使用方法

在表单中使用验证码

<?php

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;

use MeteoConcept\HCaptchaBundle\Form\HCaptchaType;

class ContactType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('name', TextType::class, [
                'label' => 'Name',
            ])
            ->add('email', TextType::class, [
                'label' => 'Email',
            ])
            ->add('message', TextareaType::class, [
                'label' => 'How can we help you ?',
            ])
            ->add('captcha', HCaptchaType::class, [
                'label' => 'Anti-bot test',
                // optionally: use a different site key than the default one:
                'hcaptcha_site_key' => '10000000-ffff-ffff-ffff-000000000001',
            ])
        ;
    }
}

默认情况下，HCaptchaFormType 类通过约束 NotBlank 和 IsValidCaptcha（此包中安装的新约束，其验证器通过调用 hCaptcha API 来进行 CAPTCHA 检查）验证字段。您可以通过将 constraints 选项传递给表单构建器来覆盖此约束集。此外，由于 CAPTCHA 值通常不需要持久化，所以 HCaptchaFormType 字段默认传递 'mapped' => false。

更新和重大更改

• 在主版本 2 中，已取消对 PHP7.1 的支持，并添加了对 PHP8.0 的支持。
• 在主版本 3 中
  • 已取消对 PHP <7.4 的支持
  • 已取消对 Symfony <5.3 的支持
  • 已添加对 Symfony 6.0 的支持
• 在主版本 4 中
  • 已取消对 PHP <8.2 的支持
  • 已取消对 Symfony <6.4 的支持
  • 已添加对 Symfony 7.0 的支持