Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cybercog/laravel-ban
Laravel Ban simplify blocking and banning Eloquent models.
https://github.com/cybercog/laravel-ban
access arrest ban block cog eloquent forbid jail justice laravel package php prison restrict sanction security trait user
Last synced: 20 days ago
JSON representation
Laravel Ban simplify blocking and banning Eloquent models.
- Host: GitHub
- URL: https://github.com/cybercog/laravel-ban
- Owner: cybercog
- License: mit
- Created: 2017-03-05T13:14:48.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-03-09T19:22:05.000Z (8 months ago)
- Last Synced: 2024-10-01T19:20:12.286Z (about 1 month ago)
- Topics: access, arrest, ban, block, cog, eloquent, forbid, jail, justice, laravel, package, php, prison, restrict, sanction, security, trait, user
- Language: PHP
- Homepage: https://komarev.com/sources/laravel-ban
- Size: 150 KB
- Stars: 1,062
- Watchers: 15
- Forks: 63
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- laravel-awesome - Laravel Ban - Laravel Ban simplify blocking and banning Eloquent models. (Popular Packages)
- awesome-laravel - Laravel Ban - Simplify blocking and banning Eloquent models (Popular Packages)
README
# 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](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Prepare bannable model](#prepare-bannable-model)
- [Prepare bannable model database table](#prepare-bannable-model-database-table)
- [Available methods](#available-methods)
- [Scopes](#scopes)
- [Events](#events)
- [Middleware](#middleware)
- [Scheduling](#scheduling)
- [Integrations](#integrations)
- [Changelog](#changelog)
- [Upgrading](#upgrading)
- [Contributing](#contributing)
- [Testing](#testing)
- [Security](#security)
- [Contributors](#contributors)
- [Alternatives](#alternatives)
- [License](#license)
- [About CyberCog](#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](https://github.com/cybercog/laravel-nova-ban).
- 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)](http://www.php-fig.org/psr/psr-1/).
- [PSR-2 (Coding Style Guide)](http://www.php-fig.org/psr/psr-2/).
- [PSR-4 (Autoloading Standard)](http://www.php-fig.org/psr/psr-4/).
- Covered with unit tests.
## Installation
First, pull in the package through Composer:
```shell
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`:
```php
'providers' => [
Cog\Laravel\Ban\Providers\BanServiceProvider::class,
],
```
#### Apply database migrations
At last, you need to publish and run database migrations:
```shell
php artisan vendor:publish --provider="Cog\Laravel\Ban\Providers\BanServiceProvider" --tag="migrations"
php artisan migrate
```
## Usage
### Prepare bannable model
```php
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.
#### Create a new migration file
```shell
php artisan make:migration add_banned_at_column_to_users_table
```
Then insert the following code into migration file:
```php
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
```php
$user->ban();
```
#### Apply ban for the entity with reason comment
```php
$user->ban([
'comment' => 'Enjoy your ban!',
]);
```
#### Apply ban for the entity which will be deleted over time
```php
$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:
```php
$user->ban([
'expired_at' => '+1 month',
]);
```
#### Remove ban from entity
```php
$user->unban();
```
On `unban` all related ban models are soft deletes.
#### Check if entity is banned
```php
$user->isBanned();
```
#### Check if entity is not banned
```php
$user->isNotBanned();
```
#### Delete expired bans manually
```php
app(\Cog\Contracts\Ban\BanService::class)->deleteExpiredBans();
```
#### Determine if ban is permanent
```php
$ban = $user->ban();
$ban->isPermanent(); // true
```
Or pass `null` value.
```php
$ban = $user->ban([
'expired_at' => null,
]);
$ban->isPermanent(); // true
```
#### Determine if ban is temporary
```php
$ban = $user->ban([
'expired_at' => '2086-03-28 00:00:00',
]);
$ban->isTemporary(); // true
```
### Scopes
#### Get all models which are not banned
```php
$users = User::withoutBanned()->get();
```
#### Get banned and not banned models
```php
$users = User::withBanned()->get();
```
#### Get only banned models
```php
$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.
```php
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.
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:
```php
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:
```php
Route::get('/', [
'uses' => 'UsersController@profile',
'middleware' => 'forbid-banned-user',
]);
```
If you want force logout banned user on protected routes access, use `LogsOutBannedUser` middleware instead:
```php
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.
```php
// 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
- [Laravel Nova Ban](https://github.com/cybercog/laravel-nova-ban)
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Upgrading
Please see [UPGRADING](UPGRADING.md) for detailed upgrade instructions.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Testing
Run the tests with:
```shell
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 | 
Ilia Lazarev | 
ZeoKnight | |
[Laravel Ban contributors list](../../contributors)
## Alternatives
- https://github.com/imanghafoori1/laravel-temp-tag
## License
- `Laravel Ban` package is open-sourced software licensed under the [MIT License](LICENSE) by [Anton Komarev].
- `Fat Boss In Jail` image licensed under [Creative Commons 3.0](https://creativecommons.org/licenses/by/3.0/us/) by Gan Khoon Lay.
## 🌟 Stargazers over time
[](https://yhype.me?utm_source=github&utm_medium=cybercog-laravel-ban&utm_content=chart-repository-star-cumulative)
## About CyberCog
[CyberCog](https://cybercog.su) is a Social Unity of enthusiasts. Research the best solutions in product & software development is our passion.
- [Follow us on Twitter](https://twitter.com/cybercog)
- [Read our articles on Medium](https://medium.com/cybercog)
[Anton Komarev]: https://komarev.com