prefeituravitoria/captcha-bundle

Captcha bundle

Gregwar's CaptchaBundle

, _(*1)

The GregwarCaptchaBundle adds support for a captcha form type for the Symfony form component., _(*2)

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

Compatibility with Symfony

If you are using Symfony < 2.8, you should use version 1.*, _(*4)

If you are using SYmfony >= 2.8, you should use version 2.*, _(*5)

Installation

Step 1: Download the GregwarCaptchaBundle

Ultimately, the GregwarCaptchaBundle files should be downloaded to the 'vendor/bundles/Gregwar/CaptchaBundle' directory., _(*6)

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

Using Composer, _(*8)

Use composer require to download and install the package., _(*9)

``` bash composer require gregwar/captcha-bundle, <sub>(*10)</sub>

***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:

``` bash
$ php bin/vendors install

Using submodules, <sub>(*11)</sub>

If you prefer instead to use git submodules, then run the following:, <sub>(*12)</sub>

``` bash $ git submodule add git://github.com/Gregwar/CaptchaBundle.git vendor/bundles/Gregwar/CaptchaBundle $ git submodule update --init, <sub>(*13)</sub>

### 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
<?php
// app/autoload.php

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

Step 3: Enable the bundle

Finally, enable the bundle in the kernel:, <sub>(*14)</sub>

<?php
// app/appKernel.php

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

Configuration

Add the following configuration to your app/config/config.yml:, <sub>(*15)</sub>

gregwar_captcha: ~

Usage

You can use the "captcha" type in your forms this way:, <sub>(*16)</sub>

<?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., <sub>(*17)</sub>

Options

You can define the following configuration options globally:, <sub>(*18)</sub>

• 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:, <sub>(*19)</sub>

• 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 :, <sub>(*20)</sub>

<?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:, <sub>(*21)</sub>

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 !, <sub>(*22)</sub>

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:, <sub>(*23)</sub>

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:, <sub>(*24)</sub>

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, <sub>(*25)</sub>

Form Theming

The widget support the standard Symfony theming, see the documentation for details on how to accomplish this., <sub>(*26)</sub>

The default rendering is:, <sub>(*27)</sub>

{%- 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., <sub>(*28)</sub>

License

This bundle is under the MIT license. See the complete license in the bundle: LICENSE, <sub>(*29)</sub>