Introduction

Laravel Ban simplify management of eloquent model's ban. Make any model bannable in a minutes!

Contents

• Features
• Installation
• Usage
  • Prepare bannable model
  • Available methods
  • Events
  • Middleware
  • Scheduling
• Change log
• Contributing
• Testing
• Security
• Credits
• Alternatives
• License
• About CyberCog

Features

• Designed to work with Laravel Eloquent models.
• Using contracts to keep high customization capabilities.
• Using traits to get functionality out of the box.
• Most part of the the logic is handled by the BanService.
• Has middleware to prevent banned user route access.
• Use case is not limited to User model, any Eloquent model could be banned.
• Events firing on models ban and unban.
• Covered with unit tests.

Installation

First, pull in the package through Composer.

composer require cybercog/laravel-ban

And then include the service provider within app/config/app.php.

'providers' => [
    Cog\Ban\Providers\BanServiceProvider::class,
],

At last you need to publish and run database migrations.

php artisan vendor:publish --provider="Cog\Ban\Providers\BanServiceProvider" --tag="migrations"
php artisan migrate

Usage

Prepare bannable model

use Cog\Ban\Contracts\CanBeBanned as CanBeBannedContract;
use Cog\Ban\Traits\CanBeBanned;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements CanBeBannedContract
{
    use CanBeBanned;
}

Note: CanBeBanned contract using CanBeOwner contract under the hood. If you are using cybercog/laravel-ownership package CanBeOwner contract could be omitted from bannable model.

Available methods

Apply ban for the entity

$user->bans()->create();

$user->ban();

Apply ban for the entity with reason comment

$user->bans()->create([
    'comment' => 'Enjoy your ban!',
]);

$user->ban([
    'comment' => 'Enjoy your ban!',
]);

Apply ban for the entity which will be deleted over time

$user->bans()->create([
    'expired_at' => '+1 month',
]);

$user->ban([
    'expired_at' => '2086-03-28 00:00:00',
]);

expired_at attribute could be \Carbon\Carbon instance or any string which could be parsed by \Carbon\Carbon::parse($string) method.

Remove ban from entity

$user->unban();

On unban all related ban models are soft deletes.

Check if entity is banned

$user->isBanned();

Check if entity is not banned

$user->isNotBanned();

Events

If entity is banned \Cog\Ban\Events\ModelWasBanned event is fired.

Is entity is unbanned \Cog\Ban\Events\ModelWasUnbanned event is fired.

Middleware

This package has route middleware designed to prevent banned users to go to protected routes.

To use it define new middleware in $routeMiddleware array of app/Http/Kernel.php file:

protected $routeMiddleware = [
    'forbid-banned-user' => \Cog\Ban\Http\Middleware\ForbidBannedUser::class,
]

Then use it in any routes and route groups you need to protect:

Route::get('/', [
    'uses' => 'UsersController@profile',
    'middleware' => 'forbid-banned-user',
]);

Scheduling

After you have performed the basic installation you can start using the backup:delete-expired command. In most cases you'll want to schedule these command so you don't have to manually run it everytime you need to delete expired bans and unban models.

The commands can be scheduled in Laravel's console kernel, just like any other command.

// app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
    $schedule->command('backup:delete-expired')->everyMinute();
}

Of course, the time used in the code above is just example. Adjust it to suit your own preferences.

Change log

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Testing

Run the tests with:

composer test

Security

If you discover any security related issues, please email a.komarev@cybercog.su instead of using the issue tracker.

Credits

• Anton Komarev
• All Contributors

Alternatives

Feel free to add more alternatives as Pull Request.

License

• Laravel Ban package is open-sourced software licensed under the MIT License.
• Fat Boss In Jail image licensed under Creative Commons 3.0 by Gan Khoon Lay.

About CyberCog

CyberCog is a Social Unity of enthusiasts. Research best solutions in product & software development is our passion.