README

Protect your website against automated scripts using the botscout.com API.

Installation

You can install the package via composer:

composer require nicolasbeauvais/laravel-botscout

Next, you must install the service provider:

// config/app.php
'providers' => [
    ...
    NicolasBeauvais\LaravelBotScout\BotScoutServiceProvider::class,
];

Add your botscout.com api key to the .env file:

BOTSCOUT_SECRET=your-api-key

If needed you can also publish the config file:

php artisan vendor:publish --provider="NicolasBeauvais\LaravelBotScout\BotScoutServiceProvider" --tag="config"

If you want to make use of the facade you must install it as well:

// config/app.php
'aliases' => [
    ...
    'BotScout' => NicolasBeauvais\LaravelBotScout\BotScoutFacade::class,
];

Usage

You are highly advised to read the BotScout.com API guide to understand the meaning of each method.

Validator

You can easily use botscout in your existing validators:

// Validate name
$validator = Validator::make(['name' => 'John Doe'], [
  'name' => 'required|botscout_name'
]);

// Validate email
$validator = Validator::make(['email' => 'toto@gmail.com'], [
  'email' => 'required|botscout_mail'
]);

// Validate ip
$validator = Validator::make(['ip' => '127.0.0.1'], [
  'ip' => 'required|botscout_ip'
]);

Note that you will need to create the validation message by yourself, as described in the Laravel documentation.

Facade

You can use the BotScout facade anywhere in your app:

BotScout::multi('John Doe', 'email@test.com', '127.0.0.1')->isValid();

BotScout::all('John Doe')->isValid();

BotScout::name('John Doe')->isValid();

BotScout::mail('email@test.com')->isValid();

BotScout::ip('127.0.0.1')->isValid();

// We also include a quick way of testing a user with integrated exception catch
BotScout::check('John Doe', 'email@test.com', '127.0.0.1'); // true or false

Real life example using the check method

The check method is the recommended way to validate a register form:

The check method is a wrapper to the multimethod that catch any http error / timeout. If the botscout api is not responding, the method will return false.

// Create a classic validation 
$validator = Validator::make($request->all(), [
    'email' => 'required|email|unique:users',
    'name' => 'required|max:20',
]);

$validator->after(function ($validator) {
    if (!BotScout::check($request->get('name'), $request->get('email'), $request->ip())) {
        $validator->errors()->add('email', 'Sorry, it looks like your a bot!');
    }
});

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email nicolasbeauvais1@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

nicolasbeauvais / laravel-botscout

Maintainers

Details