Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hendurhance/laracaptcha

A Laravel package to seamlessly use hCapthca or reCaptcha v2 or v3 on your forms or RESTful APIs
https://github.com/hendurhance/laracaptcha

captcha data-validation form-validation google-recaptcha google-recaptcha-v2 google-recaptcha-v3 hcaptcha hcaptcha-api laravel laravel-captcha laravel-package laravel10 laravel8 laravel9 php php8 recaptcha recaptcha-api recaptcha-v2 recaptcha-v3

Last synced: 3 months ago
JSON representation

A Laravel package to seamlessly use hCapthca or reCaptcha v2 or v3 on your forms or RESTful APIs

Host: GitHub
URL: https://github.com/hendurhance/laracaptcha
Owner: hendurhance
License: mit
Created: 2023-07-08T19:22:21.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2023-12-04T21:33:02.000Z (about 1 year ago)
Last Synced: 2024-09-28T19:41:25.739Z (3 months ago)
Topics: captcha, data-validation, form-validation, google-recaptcha, google-recaptcha-v2, google-recaptcha-v3, hcaptcha, hcaptcha-api, laravel, laravel-captcha, laravel-package, laravel10, laravel8, laravel9, php, php8, recaptcha, recaptcha-api, recaptcha-v2, recaptcha-v3
Language: PHP
Homepage:
Size: 73.2 KB
Stars: 14
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md

Awesome Lists containing this project

README

        # LaraCaptcha

[![Latest Version on Packagist](https://img.shields.io/packagist/v/martian/laracaptcha.svg?style=flat-square)](https://packagist.org/packages/martian/laracaptcha)

[![Total Downloads](https://img.shields.io/packagist/dt/martian/laracaptcha.svg?style=flat-square)](https://packagist.org/packages/martian/laracaptcha)

![GitHub Actions](https://github.com/hendurhance/laracaptcha/actions/workflows/main.yml/badge.svg)

A Laravel package to seamlessly integrate Google [reCAPTCHA](https://developers.google.com/recaptcha/intro) v3, v2 or [hCAPTCHA](https://www.hcaptcha.com/) into your application forms or Restful API.



  

    

    hCaptcha

  

  

    

    reCaptcha

  



## Supported Captcha Services

| Service | Version | Type | Supported |

| --- | --- | --- | --- |

| [Google reCAPTCHA](https://developers.google.com/recaptcha/docs/v3) | v3 | - | ✅ Yes |

| [Google reCAPTCHA](https://developers.google.com/recaptcha/docs/display) | v2 | Checkbox | ✅ Yes |

| [Google reCAPTCHA](https://developers.google.com/recaptcha/docs/invisible) | v2 | Invisible | ✅ Yes |

| [hCAPTCHA](https://docs.hcaptcha.com/) | - | Checkbox | ✅ Yes |

| [hCAPTCHA](https://docs.hcaptcha.com/invisible) | - | Invisible | ✅ Yes |

## Installation

> **Note:** This package requires PHP 7.4 or higher.

You can install the package via composer:

```bash

composer require martian/laracaptcha

```

## Register Service Provider

Add the following to the `providers` array in `config/app.php`:

```php

Martian\LaraCaptcha\Providers\LaraCaptchaServiceProvider::class,

```

## Publish Configuration File

Publish the configuration file using the following command:

```bash

php artisan vendor:publish --provider="Martian\LaraCaptcha\Providers\LaraCaptchaServiceProvider"

```

## Configuration

The configuration file is located at `config/laracaptcha.php`. The following options are available:

### reCAPTCHA v2 Configuration

- In order to use reCAPTCHA you need to [register your site](https://www.google.com/recaptcha/admin/create) for an API key pair. To use reCaptcha v2 Checkbox, select **Challenge (v2)** **>** **I'm not a robot Checkbox**. To use the invisible reCAPTCHA, select **Challenge (v2)** **>** **Invisible reCAPTCHA badge**. The API key pair consists of a site key and secret key. Set the `default` option to `recaptcha` in `config/laracaptcha.php`:

    ```php

    'default' => 'recaptcha',

    ```

- Change the `version` option to `v2` to use reCAPTCHA v2:

    ```php

    'drivers' => [

        'recaptcha' => [

            ...

            'version' => 'v2',

            ...

        ],

    ],

    ```

- Add `RECAPTCHA_SITE_KEY` and `RECAPTCHA_SECRET_KEY` to your `.env` file:

    ```env

    RECAPTCHA_SITE_KEY=your-site-key

    RECAPTCHA_SECRET_KEY=your-secret-key

    ```

### reCAPTCHA v3 Configuration

- In order to use reCAPTCHA you need to [register your site](https://www.google.com/recaptcha/admin/create) for an API key pair. To use reCaptcha v3, select **reCAPTCHA v3**. The API key pair consists of a site key and secret key. Set the `default` option to `recaptcha` in `config/laracaptcha.php`:

    ```php

    'default' => 'recaptcha',

    ```

- Change the `version` option to `v3` to use reCAPTCHA v3:

    ```php

    'drivers' => [

        'recaptcha' => [

            ...

            'version' => 'v3',

            ...

        ],

    ],

    ```

- Add `RECAPTCHA_SITE_KEY`, `RECAPTCHA_SECRET_KEY` and `RECAPTCHA_SITE_URL` to your `.env` file:

    ```env

    RECAPTCHA_SITE_KEY=your-site-key

    RECAPTCHA_SECRET_KEY=your-secret-key

    RECAPTCHA_SITE_URL=${APP_URL}

    ```

### hCAPTCHA Configuration

- In order to use hCAPTCHA you need to [register your site](https://dashboard.hcaptcha.com/signup) for an API key pair. The API key pair consists of a site key and secret key. Set the `default` option to `hcaptcha` in `config/laracaptcha.php`:

    ```php

    'default' => 'hcaptcha',

    ```

- Add `HCAPTCHA_SITE_KEY` and `HCAPTCHA_SECRET_KEY` to your `.env` file:

    ```env

    HCAPTCHA_SITE_KEY=10000000-ffff-ffff-ffff-000000000001

    HCAPTCHA_SECRET_KEY=0x0000000000000000000000000000000000000000

    ```

*These are the test keys we use by default. You should not use them in production!*

## Usage

To display captcha in your form, follow the steps below according to the captcha configuration you are using.

### reCAPTCHA v2 Checkbox & Invisible

#### Initializing JavaScript

Add the following to the `` section of your page:

```php

{!! LaraCaptcha::script() !!}

```

With other options in [Google reCaptcha v2 Checkbox dox](https://developers.google.com/recaptcha/docs/display#config)

```php

{!! LaraCaptcha::script('yourCallbackFunction', 'explicit', 'en') !!}

```

*Note: The first parameter is the callback function name, the second is the rendering mode (explicit or onload), and the third is the language code from [doc](https://developers.google.com/recaptcha/docs/language)*

#### Displaying Captcha Widget - Checkbox

Add the following to your form:

```php

{!! LaraCaptcha::display() !!}

```

With other options in [Google reCaptcha v2 Checkbox dox](https://developers.google.com/recaptcha/docs/display#render_param)

```php

{!! LaraCaptcha::display(['data-theme' => 'dark']) !!}

```

*Note: The parameter is an array of attributes for the widget*

#### Displaying Captcha Widget - Invisible

Add the following to your form:

```php

{!! LaraCaptcha::displayInvisibleButton('formIdentifier', 'Submit Button',['data-size' => 'invisible']) !!}

```

*Note: The first parameter is the form identifier, the second is the button label (Submit Button), and the third is an array of attributes for the widget, see [doc](https://developers.google.com/recaptcha/docs/invisible#render_param). Add the **formIdentifier** value as the id in the form element* 

#### Validating Captcha

Add the following to your validation rules:

```php

'g-recaptcha-response' => 'recaptcha',

```

You can also use the rule in the Validator facade:

```php

$validator = Validator::make($request->all(), [

    'g-recaptcha-response' => 'recaptcha',

]);

```

#### Add Custom Validation Message

Add the following to your validation messages:

```php

'g-recaptcha-response.recaptcha' => 'Captcha verification failed.',

```

Or you can change the default message in `config/laracaptcha.php`:

```php

'error_message' => 'Captcha verification failed.',

```

### reCAPTCHA v3

#### Initializing JavaScript

Add the following to the `` section of your page:

```php

{!! LaraCaptcha::script() !!}

```

With other options in [Google reCaptcha v3 dox](https://developers.google.com/recaptcha/docs/v3#config)

```php

{!! LaraCaptcha::script('yourCallbackFunction', 'explicit', 'en') !!}

```

#### Displaying Captcha Widget

Add the following to your form:

```php

{!! LaraCaptcha::display() !!}

```

With other options in [Google reCaptcha v3 dox](https://developers.google.com/recaptcha/docs/v3#render_param)

```php

{!! LaraCaptcha::display(['action' => 'homepage', 'custom_validation' => 'yourCustomFunction', 'recaptcha_input_identifier' => 'yourReCaptchaInputId']) !!}

```

*Note: The parameter is an array of attributes for the widget, see [doc](https://developers.google.com/recaptcha/docs/v3#interpreting_the_score) for actions type*

### hCAPTCHA v2 Checkbox & Invisible

#### Initializing JavaScript

Add the following to the `` section of your page:

```php

{!! LaraCaptcha::script() !!}

```

With other options in [hCAPTCHA dox](https://docs.hcaptcha.com/configuration)

```php

{!! LaraCaptcha::script('yourCallbackFunction', 'onload' 'en', 'on') !!}

```

*Note: The first parameter is the callback function name, the second is the rendering mode (onload or explicit), the third is the language code from [doc](https://docs.hcaptcha.com/languages), and the fourth is the recaptchacompat option*

#### Displaying Captcha Widget - Checkbox

Add the following to your form:

```php

{!! LaraCaptcha::display() !!}

```

With other options in [hCAPTCHA dox](https://docs.hcaptcha.com/configuration/#hcaptcha-container-configuration)

```php

{!! LaraCaptcha::display(['data-theme' => 'dark']) !!}

```

*Note: The parameter is an array of attributes for the widget*

#### Displaying Captcha Widget - Invisible

Add the following to your form, see documentation for [invisible hcaptcha](https://docs.hcaptcha.com/invisible):

```php

{!! LaraCaptcha::displayInvisibleButton('formIdentifier', 'Submit Button',['data-size' => 'invisible']) !!}

```

*Note: The first parameter is the form identifier, the second is the button label (Submit Button), and the third is an array of attributes for the widget, see [doc](https://docs.hcaptcha.com/configuration/#hcaptcha-container-configuration)*

#### Validating Captcha

Add the following to your validation rules:

```php

'h-captcha-response' => 'hcaptcha',

```

You can also use the rule in the Validator facade:

```php

$validator = Validator::make($request->all(), [

    'h-captcha-response' => 'hcaptcha',

]);

```

#### Add Custom Validation Message

Add the following to your validation messages:

```php

'h-captcha-response.hcaptcha' => 'Captcha verification failed.',

```

Or you can change the default message in `config/laracaptcha.php`:

```php

'error_message' => 'Captcha verification failed.',

```

For other configuration go through the `config/laracaptcha.php` file.

### Testing

```bash

./vendor/bin/phpunit

```

### Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

## Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

### Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

## Credits

-   [Josiah Endurance](https://github.com/hendurhance)

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.