sameer-shelavale/multi-captcha

Multiple(7) types of CAPTCHA in one package. Supports Gif captcha( Animated Gif captcha), Image Captcha( User has to type SOME OR ALL part of code displayed in the image), HoneyPot captcha(It simply adds an empty field asking users to leave it blank. Bots fill it up.), ASCII captcha(It displays the CAPTCHA text as ASCII Art. User has to type SOME OR ALL part of the code.), Math captcha( It asks user to solve simple mathematical expressions.), Recaptcha(Google Recaptcha) and NoCaptcha(Google ReCaptcha v2.0). This package also has captcha refresh feature.

multi-captcha

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., _(*1)

Key Features

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

Supported types of CAPTCHA

Captcha Type	Screenshot	Description	Protection	Difficulty for humans
image		Asks user to identify all or some characters from the jpg image. Live demo	High	Average
gif		Asks user to identify all or some characters from the animated image. Live demo	High	Average
ascii		Asks user to identify all or some characters from code displayed in ASCII art. Live demo	Moderate	Average
math		Asks user to solve simple mathematical expression. Live demo	Below Average	Easy
honeypot		Asks user to leave the captcha field blank. Live demo	Low	Very Easy
recaptcha	(image is resized)	Google ReCaptcha. Asks user to identify all characters displayed in the jpg image. Live demo	High	Average
nocaptcha	(image is resized)	Google NoCaptcha(Recaptcha v2.0). Live demo	Moderate	Average

Installation:

Using Composer

Command Line

You can install MultiCaptcha using Composer by doing, _(*2)

composer require sameer-shelavale/multi-captcha

composer.json

Alternatively, you can add it directly in your composer.json file in require block, _(*3)

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

and then run, _(*4)

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, _(*5)

Note: Make sure the cache directory is writable., _(*6)

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

Usage:

Initialize:

The minimal code required to initialize the captcha looks like:, _(*7)

$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., _(*8)

And more customized code looks like:, _(*9)

$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,, _(*10)

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., _(*11)

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., _(*12)

Example of ASCII captcha configuration:, _(*13)

$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., _(*14)

Math Captcha(Simple Mathematical expression)

Honeypot Captcha

Recaptcha

Note: You can register and get your recaptcha keys at http://www.google.com/recaptcha, _(*15)

Nocaptcha

| Configuration Param | Default Value | Required | Description | | ------------------- | ------------- | -------- | ---------- | | siteKey | null | Required | You Recaptcha Site key given to you by Google | | secretKey | null | Required | You Recaptcha Secret key given to you by Google | | lang | en | Optional | language code as on https://developers.google.com/recaptcha/docs/language | Note: You can register and get your recaptcha keys at http://www.google.com/recaptcha, _(*16)

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

For example You can do:, _(*17)

$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, _(*18)

Render

You can use the following one liner to render the captcha, _(*19)

echo $captcha->render() ;

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

Refresh

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

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., _(*22)

Validate

You can validate your form data simply by doing, _(*23)

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, _(*24)

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

or, _(*25)

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, _(*26)

$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, _(*27)

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., _(*28)

Extending the DefaultTheme

1. The render() and refresh() functions are crucial for rendering the captcha, your theme must have it.
2. 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., _(*29)

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., _(*30)

Features under progress

1. Multi-language support

Planned Features

1. 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., _(*31)