qirolab/laravel-bannable

Laravel bannable package is for blocking and banning Eloquent models.

3.1.0 2024-03-07 16:42 UTC

Requires

• php: >=7.3
• illuminate/database: ^8.0|^9.0|^10.0|^11.0
• illuminate/events: ^8.0|^9.0|^10.0|^11.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
• phpunit/phpunit: ^8.5|^9.0|^10.5
• vimeo/psalm: ^4.0|^5.22

MIT

• Harish Kumar

• user
• block
• laravel
• eloquent
• ban
• restrict
• forbid

README

Laravel bannable package for blocking and banning Eloquent models. Using this package any model can be made bannable such as Organizations, Teams, Groups, and others.

Installation

Download package into the project using Composer.

composer require qirolab/laravel-bannable

Registering package

Laravel 5.5 (or higher) uses Package Auto-Discovery, so doesn't require you to manually add the ServiceProvider.

For Laravel 5.4 or earlier releases version include the service provider within app/config/app.php:

'providers' => [
    Qirolab\Laravel\Bannable\BannableServiceProvider::class,
],

Prepare Migration

Now need to add nullable banned_at timestamp column to model. So, create a new migration file.

php artisan make:migration add_banned_at_column_to_users_table

Add $table->timestamp('banned_at')->nullable(); in this new migration file as in below example.

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

Now run migration.

php artisan migrate

Prepare bannable model

Use Bannable trait in the Model as in below example.

use Qirolab\Laravel\Bannable\Traits\Bannable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Bannable;
}

Available methods

Ban model entity.

$user->ban();

Ban model entity with reason comment

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

Ban model entity with expire time

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

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

or

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

or

$date = Carbon::now()->addWeeks(2);

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

Remove ban model

On unban all related ban models are soft deletes.

$user->unban();

Check if entity is banned

$user->isBanned();

Check if entity is not banned

$user->isNotBanned();

Delete expired bans manually

Qirolab\Laravel\Bannable\Models\Ban::deleteExpired();

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

Disable scope that hides banned models entity by default

By default all banned models will be hidden. To disable query scopes all the time you can define disableBannedAtScope method in bannable model.

/**
 * Determine which BannedAtScope should be applied or not.
 *
 * @return bool
 */
public function disableBannedAtScope()
{
    return true;
}

Events

On model entity ban \Qirolab\Laravel\Bannable\Events\ModelWasBanned event is fired.

On model entity unban \Qirolab\Laravel\Bannable\Events\ModelWasUnbanned event is fired.

Middleware

To prevent banned users to go to protected routes Qirolab\Laravel\Bannable\Middleware\ForbidBannedUser middleware is created.

Register it in $routeMiddleware array of app/Http/Kernel.php file:

protected $routeMiddleware = [ 'isBannedUser' => \Qirolab\Laravel\Bannable\Middleware\ForbidBannedUser::class, ]