README

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

If you are using Symfony < 2.8, you should use version 1.*

If you are using SYmfony >= 2.8, you should use version 2.*

Installation

Step 1: Download the GregwarCaptchaBundle

Ultimately, the GregwarCaptchaBundle files should be downloaded to the 'vendor/bundles/Gregwar/CaptchaBundle' directory.

You can accomplish this several ways, depending on your personal preference. The first method is the standard Symfony method.

Using Composer

Use composer require to download and install the package.

    composer require gregwar/captcha-bundle

Using the vendors script

Add the following lines to your deps file:

    [GregwarCaptchaBundle]
        git=http://github.com/Gregwar/CaptchaBundle.git
        target=/bundles/Gregwar/CaptchaBundle
        version=origin/2.0 <- add this if you are using Symfony 2.0

Now, run the vendors script to download the bundle:

$ php bin/vendors install

Using submodules

If you prefer instead to use git submodules, then run the following:

$ git submodule add git://github.com/Gregwar/CaptchaBundle.git vendor/bundles/Gregwar/CaptchaBundle
$ git submodule update --init

Step 2: Configure the Autoloader

If you use composer, you can skip this step.

Now you will need to add the Gregwar namespace to your autoloader:

<?php
// app/autoload.php

$loader->registerNamespaces(array(
    // ...
    'Gregwar' => __DIR__.'/../vendor/bundles',
));

Step 3: Enable the bundle

Finally, enable the bundle in the kernel:

<?php
// app/appKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Gregwar\CaptchaBundle\GregwarCaptchaBundle(),
    );
}

Configuration

Add the following configuration to your app/config/config.yml:

gregwar_captcha: ~

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 !
    // If you're using php<5.5, you can use instead:
    $builder->add('captcha', 'Gregwar\CaptchaBundle\Type\CaptchaType');
    // ...

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:

image_folder: name of folder for captcha images relative to public web folder in case as_file is set to true (default="captcha")
web_path: absolute path to public web folder (default="%kernel.root_dir%/../web")
gc_freq: frequency of garbage collection in fractions of 1 (default=100)
expiration: maximum lifetime of captcha image files in minutes (default=60)

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

width: the width of the captcha image (default=120)
height: the height of the captcha image (default=40)
disabled: disable globally the CAPTCHAs (can be useful in dev environment), it will still appear but won't be editable and won't be checked
length: the length of the captcha (number of chars, default 5)
quality: jpeg quality of captchas (default=30)
charset: the charset used for code generation (default=abcdefhjkmnprstuvwxyz23456789)
font: the font to use (default is random among some pre-provided fonts), this should be an absolute path
keep_value: the value will be the same until the form is posted, even if the page is refreshed (default=true)
as_file: if set to true an image file will be created instead of embedding to please IE6/7 (default=false)
as_url: if set to true, a URL will be used in the image tag and will handle captcha generation. This can be used in a multiple-server environment and support IE6/7 (default=false)
invalid_message: error message displayed when an non-matching code is submitted (default="Bad code value", see the translation section for more information)
bypass_code: code that will always validate the captcha (default=null)
whitelist_key: the session key to use for keep the session keys that can be used for captcha storage, when using as_url (default=captcha_whitelist_key)
reload: adds a link to reload the code
humanity: number of extra forms that the user can submit after a correct validation, if set to a value different of 0, only 1 over (1+humanity) forms will contain a CAPTCHA (default=0, i.e each form will contain the CAPTCHA)
distortion: enable or disable the distortion on the image (default=true, enabled)
max_front_lines, max_behind_lines: the maximum number of lines to draw on top/behind the image. 0 will draw no lines; null will use the default algorithm (the number of lines depends on the size of the image). (default=null)
background_color: sets the background color, if you want to force it, this should be an array of r,g &b, for instance [255, 255, 255] will force the background to be white
background_images: Sets custom user defined images as the captcha background (1 image is selected randomly). It is recommended to turn off all the effects on the image (ignore_all_effects). The full paths to the images must be passed.
interpolation: enable or disable the interpolation on the captcha
ignore_all_effects: Recommended to use when setting background images, will disable all image effects.

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 app/routing.yml 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 -%}
    <img src="{{ captcha_code }}" title="captcha" width="{{ captcha_width }}" height="{{ captcha_height }}" />
    {{ form_widget(form) }}
{%- 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.

License

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

prefeituravitoria / captcha-bundle

Maintainers

Details