README

As the name says, this is one package to render them all! Multiple types of CAPTCHA in one package. Sometimes we just need to avoid spambots still want to keep the forms user-friendly and sometimes we need complete protection even if becomes a bit complex for users. MultiCaptcha helps you have uniform Captcha validation code over your projects.

Key Features

7 types of captcha supported with multitude of configuration options for each of them.
Shows refresh button (you need to provide refresh url).
Each Captcha challenge can be submitted only once.
Customizable error messages
You can customize the look and feel using themeOptions Or you can write your own theme/s.

Supported types of CAPTCHA

Installation:

Using Composer

Command Line

You can install MultiCaptcha using Composer by doing

composer require sameer-shelavale/multi-captcha

composer.json

Alternatively, you can add it directly in your composer.json file in require block

{
    "require": {
        "sameer-shelavale/multi-captcha": "1.3.*"
    }
}

and then run

composer update

PHP Include

Or you can download the zip/rar archive and extract it and copy the /src folder to appropriate location in your project folder. And then include the captcha.php

Note: Make sure the cache directory is writable.

include_once( 'PATH-TO-MULTI-CAPTCHA-FOLDER/src/Captcha.php' );

Usage:

Initialize:

The minimal code required to initialize the captcha looks like:

$captcha = new \MultiCaptcha\Captcha([
    'secret'=>    "your-secret-key",
] );

The above code will initialize the captcha object to output "image" captcha which is default. Note: Its important to set your own secret key, as its used to encrypt and decrypt the captcha fields.

And more customized code looks like:

$captcha = new \MultiCaptcha\Captcha([
    'secret'=>    "your-secret-key",
    'life' => 2, //number of hours the generated captcha will be valid
    'customFieldName' => 'my_captcha', //this becomes the name of captcha answer field
    'options' =>  [
        'image' => [
            'maxCodeLength' => 8,
            'font'=>'../src/types/image/comic.ttf',
            'width'=>180
        ]
    ]
] );

Now, that we have basic knowledge of how to initialize it, lets look at the supported parameters in details,

Supported Parameters

Options

Right now we can render 7 types of captcha namely image, gif, ascii, math, honeypot, recaptcha and nocaptcha. Now lets look in details at the supported configuration parameters for each of them.

Image Captcha

Gif Captcha(GIF Animated captcha)

ASCII Captcha

ASCII font names: You can find the currently supported ASCII figlet fonts in src/types/ascii/fonts/ folder and use the name of the font without the .flf extension.

Example of ASCII captcha configuration:

$captcha = new \MultiCaptcha\Captcha([
    'secret'=>    "your-secret-key",
    'options' =>  [
        'ascii' => [
            'maxCodeLength' => 8,
            'fonts'=>array(
                'banner' => 4, //render with font size 4px or it becomes too big
                'doom' => 8, //render with font size 8px
                'small' =>'8' //render with font size 8px, "small" font is at src/types/ascii/fonts/small.flf
            )
        ]
    ]
] );

Note, the fonts parameter, it has the font name without extension as key. and the size in pixels as the value. Unless you provide a fontPath parameter, it will look in src/types/ascii/fonts/ folder for that font.

Math Captcha(Simple Mathematical expression)

Honeypot Captcha

Recaptcha

Note: You can register and get your recaptcha keys at http://www.google.com/recaptcha

Nocaptcha

You can generate random type of captcha from multiple configured types.

For example You can do:

$captcha = new \MultiCaptcha\Captcha([
    'secret'=>    "your-secret-key",
    'options' =>  [
        'math' => array(
            'description'=> "Answer following question if you are human",
            'level' => 4
        ),
        'image' => array(
            'maxCodeLength' => 8,
            'font'=>'../src/types/image/comic.ttf',
            'width'=>180
        ),
        'ascii' => array(
            'maxCodeLength' => 8,
            'fonts'=>array(
                'banner'=> 4,
                'doom'=> 8,
                'small'=>'8'
            )
        ),
        'gif' => array(
            'maxCodeLength' => 8,
            'font'=>'../src/types/image/comic.ttf',
            'width'=>180,
            'height'=>60,
            'totalFrames'=>50,
            'delay'=>20
        )
    ]
] );

And then it will generate a random type of captcha from the 4 types which are configured

Render

You can use the following one liner to render the captcha

echo $captcha->render() ;

That will do it.(note that $captcha is the name of object you initialized)

Refresh

To display the refresh button, its necessary to provide the refreshUrl. Then in script of that url you can do.

echo $captcha->refresh() ;
exit; //this is important to ensure no html is trailing the captcha

Note: make sure no html is displayed before or after the captcha->refresh(); You can also render and refresh at same page, please refer to the gif, ascii, image and math captcha examples.

Validate

You can validate your form data simply by doing

if( $captcha->validate( $_POST ){
    //do further processing, validate individual form fields
}

Note: We need to pass all the submitted data to the validate function because the name of captcha field is encrypted & random. If you specify the customFieldName parameter it will require that field and the challenge field for validation. E.g. if customFieldName = my_captcha, then you need to pass an array

if( $captcha->validate( [ 'my_captcha'=>$_POST['my_captcha'], 'my_captcha_challenge'=>$_POST['my_captcha_challenge'] ] ){
    //do further processing, validate individual form fields
}

if( $captcha->validate( array_intersect_key($_POST, array_flip(['my_captcha', 'my_captcha_challenge']) ) ) ){
    //do further processing, validate individual form fields
}

Themes/customization

MultiCaptcha ships with a default theme named DefaultTheme. This theme supports customization of its color/style through various parameters nested under themeOptions. e.g. you can change the background color to blue

$captcha = new \MultiCaptcha\Captcha([
    'secret'=>    "form1-secret-key",
    'options' =>  [
        'image' => array(
            'maxCodeLength' => 8,
            'font'=>'../src/types/image/comic.ttf',
            'width'=>180,
            'themeOptions' => [
                'containerStyle' => 'border:1px solid #0f702d; border-radius: 5px; padding: 5px; display: table; margin: 2px; background-color: #29713f; font-family: Helvetica; font-size: 14px; max-width: 180px;position:relative;',
                'fieldStyle' => 'background-color:#52785e; border:2px solid #fff; color:#fff; font-size:120%; font-weight:bold; border-radius:3px;width:144px;',
                'labelStyle' => 'font-size:80%; line-height:100%; color: #fff;',
            ]
        ),
        'ascii' => array(
            'maxCodeLength' => 8,
            'fonts'=>array(
                'banner'=> 4,
                'doom'=> 8,
                'small'=>'8'
            ),
            'themeOptions' => [
                'containerStyle' => 'border:1px solid #1e2a37; border-radius: 5px; padding: 10px; display: table; margin: 2px; background-color: #374c63; font-family: Helvetica; font-size: 14px; max-width: 180px;position:relative;',
                'fieldStyle' => 'background-color:#4d5d6f; border:2px solid #fff; color:#fff; font-size:120%; font-weight:bold; border-radius:3px;width:144px;',
                'labelStyle' => 'font-size:80%; line-height:100%; color: #fff;'
            ]
        ),
    ],
    'refreshUrl'=>'random.php?captcha=refresh',
    'helpUrl'=>'http://github.com/sameer-shelavale/multi-captcha',

] );

Note: each captcha type can have its own theme and themeOptions

themeOptions for DefaultTheme

With the above themeOptions you will be able to change the look and feel of the default theme. However if you need to change the placements of the elements you will have to write your own theme by extending the DefaultTheme Please refer example/theming.php for working example of themeOptions.

Extending the DefaultTheme

The render() and refresh() functions are crucial for rendering the captcha, your theme must have it.
When you extend the DefaultTheme you can use that theme by setting the theme e.g.

$captcha = new \MultiCaptcha\Captcha([
    'secret'=>    "form1-secret-key",
    'options' =>  [
        'image' => array(
            'maxCodeLength' => 8,
            'font'=>'../src/types/image/comic.ttf',
            'width'=>180,
            'theme' => 'CustomTheme1'
        ),
        'ascii' => array(
            'maxCodeLength' => 8,
            'fonts'=>array(
                'banner'=> 4,
                'doom'=> 8,
                'small'=>'8'
            ),
            'theme' => 'CustomTheme2'
        ),
    ],
] );

Note: you can have your own themeOptions when you make your own theme. Also remember to update javascipt refresh function, it needs updating whenever you change the structure/layout.

Cache

Multicaptcha uses file cache to record the answered captcha and uses it to block brute-force attack using single captcha and multiple answers. It stores the unique id of captcha and expiration time in the record, and that record is kept till the captcha expires. It uses file cache to store these records. To avoid the cache becoming too big the records are dispersed over multiple files. The number of files to be used for caching is specified by a variable $cacheSize and the directory in which the files should be stored is specified by $cacheDir, you can pass both of these variables as params to the constructor. Default cache size is 10, but you can increase it for busy websites. Note: The cache directory MUST be writable if you are using the default file cache implementation.

Features under progress

Multi-language support

Planned Features

Custom background image for image and gif captcha

License

AGPL3.0, Free for non-commercial use. Email me at samiirds@gmail.com for other type of licensing.

sameer-shelavale / multi-captcha

Maintainers

Details