Laravel Ban
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
- Installation
- Usage
- 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
Usermodel, any Eloquent model could be banned. - Events firing on models
banandunban. - 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:
$ 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:
$ 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
$ 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');
});
}
}
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' => 'UsersController@profile',
'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:
$ vendor/bin/phpunit
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Contributors
 Anton Komarev |
 badr aldeen shek salim |
 Rick Mac Gillis |
 AnsellC |
 Joe Archer |
|---|---|---|---|---|
 Francisco Solis |
 Jakub Adamec |
Alternatives
License
Laravel Banpackage is open-sourced software licensed under the MIT License by Anton Komarev.Fat Boss In Jailimage 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.
720 Jan 3, 2023
317 Dec 22, 2022
1.5k Jan 7, 2023
996 Dec 28, 2022
111 Nov 4, 2022
3 Feb 10, 2022
5 Nov 17, 2022
2 Aug 5, 2022
25 Dec 14, 2022
3 Jun 13, 2022
55 Jan 4, 2023
3.6k Dec 30, 2022
955 Dec 25, 2022
859 Dec 11, 2022
32 Oct 30, 2022
845 Jan 1, 2023
25 Jul 17, 2022
327 Dec 29, 2022