laravel-ban

by cybercog

cybercog / laravel-ban

Laravel Ban simplify blocking and banning Eloquent models.

490 Stars 39 Forks Last release: 24 days ago (4.4.0) MIT License 107 Commits 18 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Laravel Ban

cog-laravel-ban

Discord Releases Build Status StyleCI Code Quality License

Introduction

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.

Contents

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:
  • Covered with unit tests.

Installation

First, pull in the package through Composer:

shell script
$ composer require cybercog/laravel-ban

Registering package

The package will automatically register itself. This step required for Laravel 5.4 or earlier releases only.

Include the service provider within

app/config/app.php
:
'providers' => [
    Cog\Laravel\Ban\Providers\BanServiceProvider::class,
],

Apply database migrations

At last you need to publish and run database migrations:

shell script
$ 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 BannableContract;
use Cog\Laravel\Ban\Traits\Bannable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements BannableContract { 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.

Create a new migration file

shell script
$ php artisan make:migration add_banned_at_column_to_users_table

Then insert the following code into migration file:

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');
    });
}

}

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:
$user->ban([
    'expired_at' => '+1 month',
]);

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();

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.
$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.
use Cog\Contracts\Ban\Bannable as BannableContract;
use Cog\Laravel\Ban\Traits\Bannable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements BannableContract { 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.

Is entity is unbanned

\Cog\Laravel\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\Laravel\Ban\Http\Middleware\ForbidBannedUser::class,
]

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

Route::get('/', [
    'uses' => '[email protected]',
    'middleware' => 'forbid-banned-user',
]);

If you want force logout banned user on protected routes access, use

LogsOutBannedUser
middleware instead:
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.

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.

Integrations

Changelog

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

Upgrading

Please see UPGRADING for detailed upgrade instructions.

Contributing

Please see CONTRIBUTING for details.

Testing

Run the tests with:

shell script
$ vendor/bin/phpunit

Security

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

Contributors

| @antonkomarev
Anton Komarev
| @badrshs
badr aldeen shek salim
| @rickmacgillis
Rick Mac Gillis
| @AnsellC
AnsellC
| @joearcher
Joe Archer
| | :---: | :---: | :---: | :---: | :---: |

Laravel Ban contributors list

Alternatives

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

License

About CyberCog

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

CyberCog

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.