Laravel Nova Ban Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require cybercog/laravel-nova-ban
   

   Publish the migration (if needed) and run it:

   php artisan vendor:publish --provider="CyberCog\NovaBan\NovaBanServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Prepare a Bannable Model Add the CyberCog\Ban\Traits\Bannable trait to your Eloquent model (e.g., User):

   use CyberCog\Ban\Traits\Bannable;
   
   class User extends Authenticatable
   {
       use Bannable;
       // ...
   }
   

3. Register Ban Actions in Nova Resource Extend your Nova resource to include ban actions:

   use CyberCog\NovaBan\Actions\Ban;
   use CyberCog\NovaBan\Actions\Unban;
   
   class UserResource extends Resource
   {
       public static $actions = [
           Ban::make(),
           Unban::make(),
       ];
       // ...
   }
   

4. First Use Case Visit your Nova dashboard, locate a user, and click the "Ban" action to test the functionality.

Implementation Patterns

Core Workflows

1. Banning Users

   • Trigger via Nova UI: Click the "Ban" action in the resource table or detail view.
   • Customize ban reason via a modal (default or overridden in resource):

     Ban::make()->withReasonField('ban_reason');
     

   • Automate bans programmatically:

     $user->ban('Spam behavior', $adminId);
     

2. Unbanning Users

   • Use the "Unban" action in Nova or programmatically:

     $user->unban($adminId);
     

3. Integration with Nova Tools

   • Filters: Add a ban status filter to your Nova resource:

     use CyberCog\NovaBan\Filters\Banned;
     
     class UserResource extends Resource
     {
         public static $filters = [
             new Banned,
         ];
     }
     

   • Index Columns: Display ban status in the table:

     use CyberCog\NovaBan\Fields\BanStatus;
     
     class UserResource extends Resource
     {
         public function fields(Request $request)
         {
             return [
                 // ...
                 BanStatus::make(),
             ];
         }
     }
     

4. Event Listeners

   • Listen for ban/unban events to trigger side effects (e.g., notifications):

     use CyberCog\Ban\Events\UserBanned;
     use CyberCog\Ban\Events\UserUnbanned;
     
     event(new UserBanned($user, $admin, 'Reason'));
     

Advanced Patterns

• Custom Ban Logic Override the isBannable() method in your model to enforce rules:

  public function isBannable(): bool
  {
      return $this->isActive() && !$this->isAdmin();
  }
  

• Ban Expiry Set temporary bans by extending the Ban action:

  Ban::make()->temporary(30); // 30-day ban
  

• Multi-Model Support Reuse the trait across multiple models (e.g., User, Vendor) with shared ban logic.

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If the bans table already exists, the package’s migration may fail. Manually adjust the schema or drop the table first.
   • Fix: Check for existing bans table in database/migrations/ before publishing.

2. Permission Issues

   • Nova actions require proper authorization. Ensure the ban and unban actions are guarded in your Nova policy:

     public function authorizeBanAction(User $user, $model)
     {
         return $user->isAdmin();
     }
     

3. Soft Deletes vs. Bans

   • The package assumes bans are separate from soft deletes. If your model uses SoftDeletes, ensure the deleted_at column doesn’t interfere with ban logic.

4. Caching Quirks

   • Ban status may not update in real-time if Nova caches resources. Clear the cache or use nova:cache-clear after testing.

Debugging Tips

• Log Ban Events Add logging to debug ban/unban triggers:

  \CyberCog\Ban\Events\UserBanned::dispatch($user, $admin, 'Reason');
  

  Check Laravel logs (storage/logs/laravel.log) for entries.

• Verify Database Inspect the bans table directly to confirm ban records:

  SELECT * FROM bans WHERE bannable_id = [user_id];
  

• Nova Toolbar Errors If actions fail silently, enable Nova’s debug mode:

  NOVA_DEBUG=true
  

Extension Points

1. Custom Ban Fields Extend the ban modal by publishing and overriding views:

   php artisan vendor:publish --provider="CyberCog\NovaBan\NovaBanServiceProvider" --tag="views"
   

   Modify resources/views/vendor/nova-ban/....

2. API Integration Expose ban logic via API routes:

   Route::post('/users/{user}/ban', function (User $user) {
       $user->ban(request('reason'), auth()->id());
       return response()->json(['status' => 'banned']);
   });
   

3. Localization Translate ban messages by publishing language files:

   php artisan vendor:publish --provider="CyberCog\NovaBan\NovaBanServiceProvider" --tag="lang"
   

   Update resources/lang/en/nova-ban.php.

4. Testing Use the package’s test helpers to assert ban status:

   $this->assertTrue($user->isBanned());
   $this->assertEquals('Reason', $user->ban->reason);