CaptchaBundle/README.md

165 lines
6.9 KiB
Markdown
Raw Normal View History

2011-08-25 23:13:27 +02:00
Gregwar's CaptchaBundle
=====================
2016-10-24 12:05:50 +02:00
[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=YUXRLWHQSWS6L)
2015-12-06 23:10:05 +01:00
The `GregwarCaptchaBundle` adds support for a captcha form type for the
Symfony form component.
2016-08-05 20:07:20 +02:00
It uses [gregwar/captcha](https://github.com/Gregwar/Captcha) as captcha generator, which is a separate standalone library that can be used for none-symfony projects.
2015-12-11 10:01:40 +01:00
Compatibility with Symfony
==========================
2020-01-03 01:07:49 +01:00
| CaptchaBundle | Symfony | PHP |
|:---------------:|:---------:|:-------:|
| 3.* | 4.* - 5.* | 7.1 > |
| 2.* | 2.8 - 3.* | 5.3.9 > |
| 1.* | 2.1 - 2.7 | 5.3.0 > |
2015-12-11 10:02:21 +01:00
2015-12-11 10:01:40 +01:00
2011-08-25 23:13:27 +02:00
Installation
============
### Step 1: Download the GregwarCaptchaBundle
2011-08-25 23:13:27 +02:00
2020-01-03 00:43:31 +01:00
Use composer require to download and install the package.
At the end of the installation you can automaticly create the configuration thanks to the Symfony recipe.
2015-12-06 23:10:05 +01:00
``` bash
composer require gregwar/captcha-bundle
```
2011-09-09 14:28:13 +02:00
Configuration
=============
2020-01-03 00:43:31 +01:00
If you made the configuration automaticly trough the Symfony recipe, you should have the following config file `/config/packages/gregwar_captcha.yaml`
2011-08-25 23:13:27 +02:00
2020-01-03 00:43:31 +01:00
Otherwise you can create it manually `/config/packages/gregwar_captcha.yaml` with the following default configuration:
``` yaml
2011-08-25 23:13:27 +02:00
gregwar_captcha: ~
2020-01-03 00:43:31 +01:00
```
2011-08-25 23:13:27 +02:00
Usage
=====
You can use the "captcha" type in your forms this way:
2020-01-03 00:43:31 +01:00
``` php
2011-08-25 23:13:27 +02:00
<?php
use Gregwar\CaptchaBundle\Type\CaptchaType;
2011-08-25 23:13:27 +02:00
// ...
$builder->add('captcha', CaptchaType::class); // That's all !
2011-08-25 23:13:27 +02:00
// ...
```
Note that the generated image will, by default, be embedded in the HTML document
to avoid dealing with route and subrequests.
2011-08-25 23:13:27 +02:00
2011-09-09 20:06:59 +02:00
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")
2020-01-03 00:43:31 +01:00
* **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)
You can define the following configuration options globally or on the CaptchaType itself:
2011-09-09 20:06:17 +02:00
* **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
2011-09-09 20:06:17 +02:00
* **length**: the length of the captcha (number of chars, default 5)
2014-07-10 11:30:57 +02:00
* **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
2012-12-04 12:20:23 +01:00
* **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)
2013-01-21 14:04:53 +01:00
* **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)
2013-04-22 00:41:07 +02:00
* **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.
2013-04-24 18:11:08 +02:00
* **interpolation**: enable or disable the interpolation on the captcha
2015-05-19 20:20:14 +02:00
* **ignore_all_effects**: Recommended to use when setting background images, will disable all image effects.
2011-09-09 20:06:17 +02:00
Example :
2020-01-03 00:43:31 +01:00
``` php
2011-09-09 20:06:17 +02:00
<?php
use Gregwar\CaptchaBundle\Type\CaptchaType;
2011-09-09 20:06:17 +02:00
// ...
$builder->add('captcha', CaptchaType::class, array(
2011-09-09 20:06:17 +02:00
'width' => 200,
'height' => 50,
'length' => 6,
2011-09-09 20:06:17 +02:00
));
```
You can also set these options for your whole application using the `gregwar_captcha`
configuration entry in your `config.yml` file:
2020-01-03 00:43:31 +01:00
``` yaml
2011-09-09 20:06:17 +02:00
gregwar_captcha:
width: 200
height: 50
length: 6
2020-01-03 00:43:31 +01:00
```
2011-09-09 20:06:17 +02:00
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:
2020-01-03 00:43:31 +01:00
``` yaml
gregwar_captcha_routing:
resource: "@GregwarCaptchaBundle/Resources/config/routing/routing.yml"
2020-01-03 00:43:31 +01:00
```
2012-12-03 20:57:38 +01:00
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:
2020-01-03 00:43:31 +01:00
``` yaml
2012-12-03 20:57:38 +01:00
gregwar_captcha_routing:
resource: "@GregwarCaptchaBundle/Resources/config/routing/routing.yml"
prefix: /_gcb
2020-01-03 00:43:31 +01:00
```
2012-12-03 20:57:38 +01:00
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
2012-12-03 21:01:46 +01:00
Form Theming
============
The widget support the standard Symfony theming, see the [documentation](http://symfony.com/doc/current/book/forms.html#form-theming) for details on how to accomplish this.
2011-09-09 14:28:13 +02:00
The default rendering is:
2020-01-03 00:43:31 +01:00
``` twig
{% block captcha_widget %}
2011-09-09 14:28:13 +02:00
{% spaceless %}
<img src="{{ 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.
2011-08-25 23:13:27 +02:00
License
=======
This bundle is under the MIT license. See the complete license in the bundle:
LICENSE
2011-08-25 23:13:27 +02:00