Audit Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require moox/audit
   php artisan mooxaudit:install
   

   This runs migrations and publishes config/views automatically.

2. Prerequisites: Ensure spatie/laravel-activitylog is installed (this package builds on it). If not, install it first:

   composer require spatie/laravel-activitylog
   

3. First Use Case:

   • Log an activity (via Spatie’s Activity::log()).
   • Access the Filament-based UI at /audit (default route) to view logs.
   • Example:

     use Moox\Audit\Facades\Audit;
     use Spatie\Activitylog\Models\Activity;
     
     Activity::log('user.created', $user);
     Audit::view(); // Redirects to the UI (if using Filament)
     

Implementation Patterns

Core Workflows

1. Logging Activities:

   • Use Spatie’s Activity::log() as usual. Moox Audit extends this with a Filament UI for visualization.
   • Example for model events:

     use Spatie\Activitylog\LogOptions;
     use Spatie\Activitylog\Traits\LogsActivity;
     
     class User extends Model
     {
         use LogsActivity;
     
         protected static $logAttributes = ['*'];
         protected static $logOnlyDirty = true;
         protected static $logName = 'user';
     }
     

2. Integrating with Filament:

   • Moox Audit provides a pre-built Filament panel for auditing. Register it in AppServiceProvider:

     use Moox\Audit\AuditPanel;
     
     public function boot()
     {
         Filament::registerPanel(
             AuditPanel::make()
                 ->id('audit')
                 ->path('audit')
         );
     }
     

   • Customize the panel via config (config/audit.php):

     'panel' => [
         'visible' => env('AUDIT_PANEL_VISIBLE', true),
         'permissions' => ['view-audit-logs'],
     ],
     

3. Filtering and Search:

   • Leverage Filament’s built-in filters (e.g., date ranges, log types) in the UI.
   • Extend filters via custom Filament widgets:

     use Moox\Audit\Widgets\AuditFilters;
     
     AuditFilters::make()
         ->addFilter(
             Filament\Forms\Components\Select::make('log_type')
                 ->options(['user.created', 'post.updated'])
         );
     

4. Real-Time Updates:

   • Use Laravel Echo/Pusher to notify admins of critical log events:

     use Moox\Audit\Facades\Audit;
     
     Audit::log('user.suspended', $user)
          ->notifyAdmins(); // Hypothetical method (extend via events)
     

Gotchas and Tips

Pitfalls

1. Missing Spatie Activity Log:

   • If spatie/laravel-activitylog isn’t installed, the package won’t work. Install it first:

     composer require spatie/laravel-activitylog
     

2. Filament Dependency:

   • Moox Audit requires Filament for the UI. If Filament isn’t installed, the /audit route will fail. Install Filament first:

     composer require filament/filament
     

3. Migration Conflicts:

   • If you’ve customized Spatie’s activity_log table, the mooxaudit:install command may fail. Run migrations manually:

     php artisan vendor:publish --tag="audit-migrations"
     php artisan migrate --path=/vendor/moox/audit/database/migrations
     

4. Permission Denied:

   • The Filament panel respects Laravel’s gates/policies. Ensure users have the view-audit-logs permission (or adjust in config/audit.php).

Debugging

1. Logs Not Appearing:

   • Verify Spatie’s Activity model is logging correctly:

     Activity::query()->latest()->take(5)->get(); // Check raw logs
     

   • Clear cached views if the UI is blank:

     php artisan view:clear
     

2. UI Styling Issues:

   • Moox Audit uses Filament’s default styles. Override via Filament’s resources or widgets:

     Filament::serving(function () {
         Filament::registerResourceViewModifications(
             \Moox\Audit\Resources\AuditResource::class,
             fn (Blueprint $blueprint) => $blueprint->modifyForm(fn (Form $form) => $form->schema([]))
         );
     });
     

Extension Points

1. Custom Log Types:

   • Extend Spatie’s log types by creating a custom trait:

     use Spatie\Activitylog\Traits\LogsActivity;
     
     trait LogsCustomActivity
     {
         use LogsActivity;
     
         protected static $logOnlyDirty = false;
         protected static $logAttributes = ['custom_field'];
     }
     

2. Adding Custom Columns:

   • Extend the Filament table via a custom resource:

     use Moox\Audit\Resources\AuditResource;
     
     class CustomAuditResource extends AuditResource
     {
         public static function table(Table $table): Table
         {
             parent::table($table);
             $table->addColumns([
                 Tables\Columns\TextColumn::make('custom_field')
                     ->label('Custom Data'),
             ]);
         }
     }
     

3. Exporting Logs:

   • Use Filament’s export actions to download logs as CSV/Excel:

     use Filament\Tables\Actions\ExportAction;
     
     AuditResource::table(function (Table $table) {
         $table->actions([
             ExportAction::make()
                 ->label('Export Logs')
                 ->filename('audit-logs-' . now()->format('Y-m-d')),
         ]);
     });
     

4. Webhooks for Logs:

   • Trigger external actions (e.g., Slack notifications) via Laravel events:

     use Spatie\Activitylog\Events\Logged;
     
     Logged::listen(function (Logged $event) {
         if ($event->properties['log'] === 'user.suspended') {
             // Send Slack alert
         }
     });