Doctrine Audit Log Bundle Laravel Package

Getting Started

Install via Composer:

composer require vendor/package-name

Ensure your project meets the minimum PHP 8.4 requirement (check via php -v). Register the package in config/app.php under providers and publish its config with:

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

Start by leveraging the LogEntry model for structured logging. Example:

use Vendor\PackageName\Models\LogEntry;

// Log a system event
LogEntry::create([
    'tag' => 'System', // Updated from 'OpenAPI' (breaking change)
    'level' => 'info',
    'message' => 'User authenticated',
    'context' => ['user_id' => 123],
]);

Implementation Patterns

Core Workflows

1. Structured Logging Use LogEntry for audit trails or system events. Tag entries with 'System' (replaces deprecated 'OpenAPI').

   LogEntry::query()
       ->where('tag', 'System')
       ->where('level', '>', 'warning')
       ->get();
   

2. Middleware Integration Attach logging to middleware for request tracking:

   namespace App\Http\Middleware;
   
   use Vendor\PackageName\Models\LogEntry;
   
   class LogRequests
   {
       public function handle($request, Closure $next)
       {
           $response = $next($request);
           LogEntry::create([
               'tag' => 'System',
               'level' => 'debug',
               'message' => 'Request processed',
               'context' => ['path' => $request->path()],
           ]);
           return $response;
       }
   }
   

3. Event Listeners Trigger logs via Laravel events (e.g., Illuminate\Auth\Events\Authenticated):

   namespace App\Listeners;
   
   use Vendor\PackageName\Models\LogEntry;
   
   class LogAuthentication
   {
       public function handle($event)
       {
           LogEntry::create([
               'tag' => 'System',
               'level' => 'info',
               'message' => 'User logged in',
               'context' => ['email' => $event->user->email],
           ]);
       }
   }
   

Testing

Unit tests for LogEntry are now included. Extend them in your test suite:

use Vendor\PackageName\Tests\Unit\LogEntryTest;

class CustomLogEntryTest extends LogEntryTest
{
    public function testCustomScenario()
    {
        // Override or extend existing tests
    }
}

Gotchas and Tips

Breaking Changes

• PHP 8.4 Requirement: Update your project or use a version manager (e.g., phpbrew) to avoid runtime errors. Check compatibility with other packages.
• Tag Renaming: Replace 'OpenAPI' with 'System' in all existing logs/configurations. Run a database search for 'OpenAPI' to catch missed instances.

Debugging

• Missing Logs: Verify the LogEntry table exists (run migrations if needed). Check config/package-name.php for storage paths.
• Performance: Batch inserts for bulk logs:

  LogEntry::insert([
      ['tag' => 'System', 'level' => 'info', 'message' => 'Batch log 1'],
      ['tag' => 'System', 'level' => 'info', 'message' => 'Batch log 2'],
  ]);
  

Extension Points

• Custom Tags: Extend the tag field for domain-specific logging (e.g., 'Payment', 'Inventory').
• Webhooks: Use LogEntry events to trigger external actions (e.g., Slack alerts for 'error' logs):

  LogEntry::created(function ($log) {
      if ($log->level === 'error') {
          // Send alert
      }
  });
  

Configuration

• CI/CD: The new CLAUDE.md (likely a contributor license agreement) may require updates to your workflow. Review if you accept external contributions.
• OpenAPI Docs: If using Swagger/OpenAPI, update annotations to reflect the 'System' tag change.

Pro Tips

• Query Scopes: Add custom scopes to LogEntry for reusable queries:

  namespace Vendor\PackageName\Models;
  
  class LogEntry extends Model
  {
      public function scopeForUser($query, $userId)
      {
          return $query->where('context->user_id', $userId);
      }
  }
  

• Retention Policy: Implement a scheduled job to purge old logs (e.g., via LogEntry::where('created_at', '<=', now()->subDays(30))->delete()).