DOCSEARCHbyAlgolia
Submit Docs

Gregwar CaptchaBundle

repository·master·Indexed 43 days ago

https://github.com/gregwar/captchabundle

A Symfony bundle that provides a Form Type for integrating CAPTCHAs into applications. It leverages the gregwar/captcha library to generate images and supports embedded images, file-based storage, and URL-based generation for distributed environments.

Tokens
2.2K
Snippets
7
Records
7
Agent score
6%

What's inside CaptchaBundle

  1. Use Captcha as a URL (for multi-server environments)

    master

    To use a URL to generate a captcha image (via the as_url option), you must register the bundle's routing configuration in your config/routes.yaml. This allows the image tag to point to a route like /generate-captcha/{key}. You can also add a prefix to avoid route conflicts.

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

    With a prefix:

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

  2. Install GregwarCaptchaBundle

    master

    Install the bundle using Composer. If you are using Symfony Flex, the bundle will be automatically registered. If you are not using Flex, you must register the bundle manually in your config/bundles.php file.

    composer require gregwar/captcha-bundle
    // config/bundles.php
return [
    // ...
    Gregwar\CaptchaBundle\GregwarCaptchaBundle::class => ['all' => true]
];

  3. Configure GregwarCaptchaBundle globally

    master

    You can customize global settings for the captcha bundle by creating or modifying /config/packages/gregwar_captcha.yaml. This is useful for setting default dimensions or storage paths for the entire application.

    gregwar_captcha:
  width: 160
  height: 50

  4. Configure CaptchaType options

    master

    You can pass specific options to the CaptchaType when adding it to a form builder to override global settings for that specific instance.

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

  5. Use CaptchaType in Symfony forms

    master

    To add a captcha to a Symfony form, use the Gregwar\CaptchaBundle\Type\CaptchaType class within your form builder. By default, the generated image is embedded directly in the HTML document to avoid extra route/subrequest handling.

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

  6. Customize Captcha Form Theming

    master

    The captcha widget supports standard Symfony form theming. If you need to override the default rendering, the default Twig block structure is as follows:

    {% block captcha_widget %}
{% spaceless %}
    <img src="{{ captcha_code }}" title="captcha" width="{{ captcha_width }}" height="{{ captcha_height }}" />
    {{ form_widget(form) }}
{% endspaceless %}
{% endblock %}

  7. Reference: Global and Type configuration options

    master

    The following options can be set globally in gregwar_captcha configuration or locally on the CaptchaType itself. Note that some options are strictly global.

    ### Global-only options:
* `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.project_dir%/public")
* `gc_freq`: frequency of garbage collection in fractions of 1 (default=100)
* `expiration`: maximum lifetime of captcha image files in minutes (default=60)

### Options available globally OR on CaptchaType:
* `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")
* `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 (default=0)
* `distortion`: enable or disable the distortion on the image (default=true)
* `max_front_lines`: the maximum number of lines to draw on top of the image (default=null)
* `max_behind_lines`: the maximum number of lines to draw behind the image (default=null)
* `background_color`: sets the background color as an array of r,g &b (e.g. [255, 255, 255])
* `background_images`: Sets custom user defined images as the captcha background (array of full paths)
* `interpolation`: enable or disable the interpolation on the captcha
* `ignore_all_effects`: Recommended to use when setting background images, will disable all image effects.
* `session_key`: if you want to host multiple CAPTCHA on the same page, use different session keys to ensure proper storage.