CaptchaBundle/README.md

201 lines
5.9 KiB
Markdown
Raw Normal View History

2011-08-25 23:13:27 +02:00
Gregwar's CaptchaBundle
=====================
The `GregwarCaptchaBundle` adds support for a "captcha" form type for the
Symfony2 form component.
2011-08-25 23:13:27 +02:00
Important note: the master of this repository is containing current development
in order to work with Symfony 2.1. If you are using Symfony 2.0 please checkout
the 2.0 branch.
2011-08-25 23:13:27 +02:00
Installation
============
### Step 1: Download the GregwarCaptchaBundle
2011-08-25 23:13:27 +02:00
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 Symfony2 method.
2011-09-09 14:28:13 +02:00
***Using the vendors script***
Add the following lines to your `deps` file:
```
2011-08-25 23:13:27 +02:00
[GregwarCaptchaBundle]
git=http://github.com/Gregwar/CaptchaBundle.git
2011-08-25 23:13:27 +02:00
target=/bundles/Gregwar/CaptchaBundle
2012-06-29 19:21:02 +02:00
version=origin/2.0 <- add this if you are using Symfony 2.0
```
2011-08-25 23:13:27 +02:00
Now, run the vendors script to download the bundle:
2011-08-25 23:13:27 +02:00
``` bash
$ php bin/vendors install
```
***Using submodules***
2011-09-09 14:28:13 +02:00
If you prefer instead to use git submodules, then run the following:
``` bash
$ git submodule add git://github.com/Gregwar/CaptchaBundle.git vendor/bundles/Gregwar/CaptchaBundle
$ git submodule update --init
```
2012-06-22 19:04:05 +02:00
***Using Composer***
Add the following to the "require" section of your `composer.json` file:
```
2012-08-21 13:20:32 +02:00
"gregwar/captcha-bundle": "dev-master"
2012-06-22 19:04:05 +02:00
```
And update your dependencies
### Step 2: Configure the Autoloader
2012-06-22 19:04:05 +02:00
If you use composer, you can skip this step.
Now you will need to add the `Gregwar` namespace to your autoloader:
``` php
2011-08-25 23:13:27 +02:00
<?php
// app/autoload.php
2012-08-11 11:24:15 +02:00
$loader->registerNamespaces(array(
// ...
'Gregwar' => __DIR__.'/../vendor/bundles',
));
2011-08-25 23:13:27 +02:00
```
### Step 3: Enable the bundle
2011-08-25 23:13:27 +02:00
Finally, enable the bundle in the kernel:
2011-08-25 23:13:27 +02:00
```php
<?php
// app/appKernel.php
2011-08-25 23:13:27 +02:00
public function registerBundles()
{
$bundles = array(
// ...
2011-08-25 23:13:27 +02:00
new Gregwar\CaptchaBundle\GregwarCaptchaBundle(),
);
}
2011-08-25 23:13:27 +02:00
```
2011-09-09 14:28:13 +02:00
Configuration
=============
Add the following configuration to your `app/config/config.yml`:
2011-08-25 23:13:27 +02:00
gregwar_captcha: ~
Usage
=====
You can use the "captcha" type in your forms this way:
```php
<?php
// ...
$builder->add('captcha', 'captcha'); // That's all !
// ...
```
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")
* **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:
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)
* **length**: the length of the captcha (number of chars, default 5)
* **quality**: jpeg quality of captchas (default=15)
* **charset**: the charset used for code generation (default=abcdefhjkmnprstuvwxyz23456789)
2011-12-02 19:07:28 +01:00
* **font**: the font to use (default=Generator/Font/captcha.ttf)
* **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)
2012-12-03 21:01:46 +01:00
* **valid_keys**: names that are able to be used for a captcha form type (default=[captcha])
2011-09-09 20:06:17 +02:00
Example :
```php
<?php
// ...
$builder->add('captcha', 'captcha', array(
'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:
gregwar_captcha:
width: 200
height: 50
length: 6
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"
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:
gregwar_captcha_routing:
resource: "@GregwarCaptchaBundle/Resources/config/routing/routing.yml"
prefix: /_gcb
2012-12-03 21:01:46 +01:00
If you are using multiple captchas or assigning names other than the default "captcha", you will need to whitelist your captcha names in the "valid_keys" configuration:
gregwar_captcha:
valid_keys: [registration_captcha, confirmation_captcha]
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:
```html
{% 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