zyuzka / laravel-ban Goto Github PK

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

Use case is not limited to User model, any Eloquent model could be banned: Organizations, Teams, Groups and others.

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

• Designed to work with Laravel Eloquent models.
• Using contracts to keep high customization capabilities.
• Using traits to get functionality out of the box.
• Model can has many bans.
• Removed bans keeps in history as Soft deleted record.
• 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.

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

use Cog\Ban\Contracts\HasBans as HasBansContract;
use Cog\Ban\Traits\HasBans;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements HasBansContract
{
    use HasBans;
}

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

Bannable model must have nullable timestamp column named banned_at. This value used as flag and simplify checks if user was banned. If you are trying to make default Laravel User model to be bannable you can use example below.

$ php artisan make:migration add_banned_at_column_to_users_table

Then insert the following code into migration file:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class AddBannedAtColumnToUsersTable extends Migration
{
    public function up()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->timestamp('banned_at')->nullable();
        });
    }
    
    public function down()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('banned_at');
        });
    }
}

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

$user->ban();

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

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

$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.

$user->unban();

On unban all related ban models are soft deletes.

$user->isBanned();

$user->isNotBanned();

app(\Cog\Ban\Services\BanService::class)->deleteExpiredBans();

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

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

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',
]);

After you have performed the basic installation you can start using the ban: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 command can be scheduled in Laravel's console kernel, just like any other command.

// app/Console/Kernel.php

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

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

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

Please see CONTRIBUTING for details.

Run the tests with:

$ composer test

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

• Anton Komarev
• All Contributors

Feel free to add more alternatives as Pull Request.

• 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.

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