search

Gregwar / CaptchaBundle

Symfony bundle implementing a "captcha" form type
MIT License
346 stars 126 forks source link

readme

Gregwar's CaptchaBundle

paypal

The GregwarCaptchaBundle adds support for a captcha form type for the Symfony form component.

It uses gregwar/captcha as captcha generator, which is a separate standalone library that can be used for none-symfony projects.

Compatibility with Symfony

CaptchaBundle Symfony PHP
2.3.* 6. - 7. >= 8.0.2
2.2.* 5. - 6. >= 7.1
2.1.* 4. - 5. >= 7.1
2.0.* 2.8 - 3.* >= 5.3.9
1.* 2.1 - 2.7 >= 5.3.0

Installation

Step 1: Download the GregwarCaptchaBundle

Use composer require to download and install the package. At the end of the installation, the bundle is automatically registered thanks to the Symfony recipe.

    composer require gregwar/captcha-bundle

If you don't use flex, register it manually:

<?php
// config/bundles.php
return [
    // ...
    Gregwar\CaptchaBundle\GregwarCaptchaBundle::class => ['all' => true]
];

Configuration

If you need to customize the global bundle configuration, you can create a /config/packages/gregwar_captcha.yaml file with your configuration:

gregwar_captcha:
  width: 160
  height: 50

Usage

You can use the "captcha" type in your forms this way:

<?php
use Gregwar\CaptchaBundle\Type\CaptchaType;
// ...
$builder->add('captcha', CaptchaType::class); // That's all !
// ...

Note that the generated image will, by default, be embedded in the HTML document to avoid dealing with route and subrequests.

Options

You can define the following configuration options globally:

You can define the following configuration options globally or on the CaptchaType itself:

Example :

<?php
use Gregwar\CaptchaBundle\Type\CaptchaType;
// ...
$builder->add('captcha', CaptchaType::class, array(
    'width' => 200,
    'height' => 50,
    'length' => 6,
));

You can also set these options for your whole application using the gregwar_captcha configuration entry in your config.yml file:

gregwar_captcha:
    width: 200
    height: 50
    length: 6

Translation

The messages are using the translator, you can either change the invalid_message option or translate it. Any contribution about the language is welcome !

As URL

To use a URL to generate a captcha image, you must add the bundle's routing configuration to your config/routes.yaml file:

gregwar_captcha_routing:
    resource: "@GregwarCaptchaBundle/Resources/config/routing/routing.yml"

This will use the bundle's route of /generate-captcha/{key} to handle the generation. If this route conflicts with an application route, you can prefix the bundle's routes when you import:

gregwar_captcha_routing:
    resource: "@GregwarCaptchaBundle/Resources/config/routing/routing.yml"
    prefix: /_gcb

Since the session key is transported in the URL, it's also added in another session array, under the whitelist_key key, for security reasons

Form Theming

The widget support the standard Symfony theming, see the documentation for details on how to accomplish this.

The default rendering is:

{% block captcha_widget %}
{% spaceless %}
    <img src="https://github.com/Gregwar/CaptchaBundle/raw/master/{{ captcha_code }}" title="captcha" width="{{ captcha_width }}" height="{{ captcha_height }}" />
    {{ form_widget(form) }}
{% endspaceless %}
{% endblock %}

Image creation

If you choose to use image files instead of embedding the widget will execute a garbage collection randomly and delete images that exceed the configured lifetime.

Use internal Quality-Tools

vendor/bin/phpstan analyse
vendor/bin/ecs check .

License

This bundle is under the MIT license. See the complete license in the bundle: LICENSE