Laravel Bannable Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require qirolab/laravel-bannable
   

   (Auto-discovery handles Laravel 5.5+; manually register Qirolab\Laravel\Bannable\BannableServiceProvider for older versions.)

2. Publish Config (Optional):

   php artisan vendor:publish --provider="Qirolab\Laravel\Bannable\BannableServiceProvider"
   

   (Default config is minimal; customize if needed.)

3. Make a Model Bannable: Use the Bannable trait in your Eloquent model:

   use Qirolab\Laravel\Bannable\Traits\Bannable;
   
   class User extends Model
   {
       use Bannable;
   }
   

4. First Use Case: Ban a model instance:

   $user = User::find(1);
   $user->ban(); // Adds `banned_at` timestamp and sets `is_banned` to true
   

Implementation Patterns

Core Workflows

1. Banning/Unbanning:

   // Ban with optional reason
   $model->ban('Spam behavior detected');
   
   // Unban
   $model->unban();
   

2. Query Scoping:

   // Active (non-banned) models
   User::active()->get();
   
   // Banned models
   User::banned()->get();
   

3. Soft-Deletes Integration: If using SoftDeletes, banned models are not automatically soft-deleted. Use:

   $model->ban()->forceDelete(); // Explicitly delete
   

4. Customizing Ban Logic: Override isBanned() in your model to add custom logic:

   public function isBanned()
   {
       return parent::isBanned() || $this->suspiciousActivity > 5;
   }
   

Integration Tips

• Events: Listen for banned/unbanned events:

  event(new Banned($model, 'Reason'));
  

• API Responses: Filter banned models in API responses:

  return User::active()->get()->map(fn ($user) => $user->only(['id', 'name']));
  

• Admin Panels: Use banned_at and ban_reason in admin interfaces for visibility.

Gotchas and Tips

Pitfalls

1. Database Schema:

   • The package adds is_banned (boolean) and banned_at (timestamp) columns automatically on first ban.
   • Fix: Run migrations manually if you need to pre-populate the schema or add indexes:

     Schema::table('users', function (Blueprint $table) {
         $table->boolean('is_banned')->default(false);
         $table->timestamp('banned_at')->nullable();
         $table->string('ban_reason')->nullable();
     });
     

2. Caching:

   • isBanned() checks are not cached by default. For high-traffic apps, cache the result:

     public function isBanned()
     {
         return Cache::remember("user_{$this->id}_is_banned", now()->addHours(1), function () {
             return parent::isBanned();
         });
     }
     

3. Mass Actions:

   • Avoid ban() in bulk operations (e.g., User::all()->ban()). Use query builder:

     User::where('role', 'spammer')->update(['is_banned' => true, 'banned_at' => now()]);
     

Debugging

• Silent Bans: If ban() doesn’t trigger, check for:
  • Missing use Bannable trait.
  • Database transactions rolling back (wrap in DB::transaction() if needed).
• Ban Reason: Always pass a reason for auditing:

  $model->ban('Violated ToS'); // Logs to `ban_reason`
  

Extension Points

1. Custom Ban Fields: Override getBanAttributes() to add custom fields (e.g., banned_by):

   protected function getBanAttributes()
   {
       return array_merge(parent::getBanAttributes(), ['banned_by' => auth()->id()]);
   }
   

2. Ban Expiry: Add unban_at and auto-unban logic:

   public function ban($reason = null)
   {
       parent::ban($reason);
       $this->unban_at = now()->addDays(30);
   }
   

3. Policy Integration: Use the isBanned() check in policies:

   public function viewAny(User $user)
   {
       return !$user->isBanned();
   }
   

Config Quirks

• Default Ban Reason: Set in config/bannable.php:

  'default_reason' => 'Account banned by administrator',
  

• Auto-Unban: Enable with:

  'auto_unban' => true, // Unbans when `unban_at` is reached