cybercog/laravel-ban

Laravel Ban simplify blocking and banning Eloquent models.

Laravel Ban

, _(*1)

, _(*2)

Introduction

Laravel Ban simplify management of Eloquent model's ban. Make any model bannable in a minutes!, _(*3)

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

Contents

• Features
• Installation
• Usage
  • Prepare bannable model
  • Prepare bannable model database table
  • Available methods
  • Scopes
  • Events
  • Middleware
  • Scheduling
• Integrations
• Changelog
• Upgrading
• Contributing
• Testing
• Security
• Contributors
• Alternatives
• License
• About CyberCog

Features

• Model can have many bans.
• Removed bans kept in history as soft deleted records.
• Most parts of 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.
• Designed to work with Laravel Eloquent models.
• Has Laravel Nova support.
• Using contracts to keep high customization capabilities.
• Using traits to get functionality out of the box.
• Following PHP Standard Recommendations:
  • PSR-1 (Basic Coding Standard).
  • PSR-2 (Coding Style Guide).
  • PSR-4 (Autoloading Standard).
• Covered with unit tests.

Installation

First, pull in the package through Composer:, _(*5)

composer require cybercog/laravel-ban

Registering package

The package will automatically register itself. This step required for Laravel 5.4 or earlier releases only., _(*6)

Include the service provider within app/config/app.php:, _(*7)

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

Apply database migrations

At last, you need to publish and run database migrations:, _(*8)

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

Usage

Prepare bannable model

use Cog\Contracts\Ban\Bannable as BannableInterface;
use Cog\Laravel\Ban\Traits\Bannable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements BannableInterface
{
    use Bannable;
}

Prepare bannable model database table

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

Create a new migration file

php artisan make:migration add_banned_at_column_to_users_table

Then insert the following code into migration file:, _(*10)

<?php

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

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

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('banned_at');
        });
    }
};

Available methods

Apply ban for the entity

$user->ban();

Apply ban for the entity with reason comment

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

Apply ban for the entity which will be deleted over time

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

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

Remove ban from entity

$user->unban();

On unban all related ban models are soft deletes., _(*12)

Check if entity is banned

$user->isBanned();

Check if entity is not banned

$user->isNotBanned();

Delete expired bans manually

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

Determine if ban is permanent

$ban = $user->ban();

$ban->isPermanent(); // true

Or pass null value., _(*13)

$ban = $user->ban([
   'expired_at' => null,
]);

$ban->isPermanent(); // true

Determine if ban is temporary

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

$ban->isTemporary(); // true

Scopes

Get all models which are not banned

$users = User::withoutBanned()->get();

Get banned and not banned models

$users = User::withBanned()->get();

Get only banned models

$users = User::onlyBanned()->get();

Scope auto-apply

To apply query scopes all the time you can define shouldApplyBannedAtScope method in bannable model. If method returns true all banned models will be hidden by default., _(*14)

use Cog\Contracts\Ban\Bannable as BannableInterface;
use Cog\Laravel\Ban\Traits\Bannable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements BannableInterface
{
    use Bannable;

    /**
     * Determine if BannedAtScope should be applied by default.
     *
     * @return bool
     */
    public function shouldApplyBannedAtScope()
    {
        return true;
    }
}

Events

If entity is banned \Cog\Laravel\Ban\Events\ModelWasBanned event is fired., _(*15)

Is entity is unbanned \Cog\Laravel\Ban\Events\ModelWasUnbanned event is fired., _(*16)

Middleware

This package has route middleware designed to prevent banned users to go to protected routes., _(*17)

To use it define new middleware in $routeMiddleware array of app/Http/Kernel.php file:, _(*18)

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

Then use it in any routes and route groups you need to protect:, _(*19)

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

If you want force logout banned user on protected routes access, use LogsOutBannedUser middleware instead:, _(*20)

protected $routeMiddleware = [
    'logs-out-banned-user' => \Cog\Laravel\Ban\Http\Middleware\LogsOutBannedUser::class,
]

Scheduling

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

The command can be scheduled in Laravel's console kernel, just like any other command., _(*22)

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

Integrations

• Laravel Nova Ban

Changelog

Please see CHANGELOG for more information on what has changed recently., _(*24)

Upgrading

Please see UPGRADING for detailed upgrade instructions., _(*25)

Contributing

Please see CONTRIBUTING for details., _(*26)

Testing

Run the tests with:, _(*27)

vendor/bin/phpunit

Security

If you discover any security related issues, please email open@cybercog.su instead of using the issue tracker., _(*28)

Contributors

Anton Komarev	badr aldeen shek salim	Rick Mac Gillis	AnsellC	Joe Archer
Francisco Solis	Jakub Adamec	Ilia Lazarev	ZeoKnight

Laravel Ban contributors list, _(*29)

Alternatives

• https://github.com/imanghafoori1/laravel-temp-tag

License

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

🌟 Stargazers over time

, _(*30)

About CyberCog

CyberCog is a Social Unity of enthusiasts. Research the best solutions in product & software development is our passion., _(*31)

• Follow us on Twitter
• Read our articles on Medium

, _(*32)