Laravel Blamable Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package extends Eloquent models with "blamable" traits (e.g., created_by, updated_by, deleted_by fields), enabling auditability and ownership tracking without manual middleware or observers. This fits well in:
  • Multi-tenant SaaS (tracking tenant admins vs. end-users).
  • Regulated industries (GDPR, HIPAA compliance via ownership logs).
  • Collaborative platforms (e.g., wikis, docs) where user actions must be attributable.
• Laravel Native: Leverages Laravel’s Eloquent ORM and built-in auth (e.g., Auth::user()), reducing friction in integration.
• Limitation: No built-in soft-deletes or activity logging (e.g., timestamps for changes). Requires pairing with SoftDeletes or third-party packages (e.g., spatie/laravel-activitylog).

Integration Feasibility

• Low-Coupling: Uses traits (Blamable, BlamableSoftDeletes) for opt-in adoption. Existing models require minimal changes (e.g., adding blamable() to boot methods).
• Database Schema: Automatically adds created_by, updated_by, deleted_by (and updated_at, deleted_at if combined with SoftDeletes). Migration risk: Schema changes may require downtime if applied to production tables.
• Auth Dependency: Relies on Laravel’s auth system (e.g., Auth::user()). Edge cases:
  • Anonymous users (e.g., API calls) → Default to null or a system user.
  • Queue jobs/artisans → May need middleware to set auth context.

Technical Risk

Key Questions

1. Ownership Granularity:
   • Do you need role-based blaming (e.g., created_by_role_id) or just user IDs?
   • Should deleted_by track the last editor or the deleter?
2. Anonymous/Service Accounts:
   • How to handle non-authenticated actions (e.g., cron jobs, API webhooks)?
3. Audit Depth:
   • Need change history (e.g., "Field X changed from A to B")? If yes, pair with spatie/laravel-activitylog.
4. Multi-Auth Systems:
   • Using passport/sanctum for APIs + session auth? Ensure Auth::user() resolves correctly.
5. Legacy Models:
   • Existing models without user_id fields? Requires backfilling or a phased migration.

Integration Approach

Stack Fit

• Laravel Ecosystem: Optimized for Laravel 10+ (PHP 8.1+). Compatible with:
  • Eloquent: Core dependency.
  • Auth: Uses Auth::user() (supports laravel/ui, jetstream, or custom auth).
  • Queues/Jobs: Requires auth context injection (see below).
  • Testing: Works with PHPUnit/Pest (mock Auth facade).
• Non-Laravel: Not applicable (hard dependency on Laravel’s auth/Eloquent).

Migration Path

1. Phase 1: New Models

   • Add use \Astalpaert\Blamable\Blamable; to new Eloquent models.
   • Run migration:

     Schema::table('posts', function (Blueprint $table) {
         $table->foreignId('created_by')->constrained('users')->nullable();
         $table->foreignId('updated_by')->constrained('users')->nullable();
         $table->foreignId('deleted_by')->constrained('users')->nullable();
     });
     

   • Call Blamable::blamable() in model boot methods.

2. Phase 2: Legacy Models

   • Backfill created_by from created_at (heuristic: assume first editor is creator).
   • Add fields via zero-downtime migration (if using SoftDeletes).

3. Phase 3: Non-Web Contexts

   • Add middleware to set auth for queues/jobs:

     // app/Http/Middleware/SetAuthForJobs.php
     public function handle($request, Closure $next) {
         if (app()->runningInConsole()) {
             Auth::setUser(User::find(1)); // Default system user
         }
         return $next($request);
     }
     

Compatibility

• Laravel Versions: Tested on Laravel 10 (last release 2026). Check:
  • PHP 8.1+ (required for named arguments in traits).
  • Eloquent 9+ (no breaking changes expected).
• Database: Supports MySQL, PostgreSQL, SQLite (no vendor-specific SQL).
• Conflicts:
  • Avoid naming collisions (e.g., if created_by already exists).
  • Overlap with SoftDeletes is handled via BlamableSoftDeletes trait.

Sequencing

1. Pre-Integration:
   • Audit existing models for user_id fields.
   • Define ownership rules (e.g., "API users default to null").
2. Development:
   • Start with a single model (e.g., Post) to test traits.
   • Implement middleware for non-web contexts.
3. Testing:
   • Unit tests: Mock Auth::user() to verify blaming logic.
   • Integration tests: Simulate queue jobs/artisans.
4. Deployment:
   • Run migrations in a maintenance mode window.
   • Monitor created_by/updated_by fields for null values (indicating auth context issues).

Operational Impact

Maintenance

• Proactive:
  • Schema Changes: Future updates may require new fields (e.g., blamed_at timestamps). Monitor package releases.
  • Auth System: Changes to Auth facade (e.g., switching to Sanctum) may need trait adjustments.
• Reactive:
  • Data Corruption: If Auth::user() fails (e.g., DB connection issues), models may save with null owners. Add retries or fallback users.
  • Performance: Add indexes on created_by, updated_by if querying by owner (e.g., "Show me all posts edited by User X").

Support

• Debugging:
  • Common Issues:
    • null owners → Check auth context in queues/jobs.
    • Missing fields → Verify migrations ran.
  • Logs: Add Blamable events to Laravel’s log channel for auditing.
• Documentation:
  • Internal runbook for:
    • Backfilling legacy data.
    • Handling auth context in non-web layers.
    • Troubleshooting null owner issues.

Scaling

• Database Load:
  • Foreign keys (created_by) add minimal overhead. Index them if filtering by owner.
  • Partitioning: For large tables, partition by created_at (not created_by).
• Concurrency:
  • No locks or race conditions in traits. Safe for high-write environments.
• Sharding:
  • If sharding by tenant, ensure created_by is shard-local or replicated.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Training: 30-minute session on:
    • Adding Blamable to models.
    • Handling auth context in jobs.
  • Checklist:

    - [ ] Added `Blamable` trait to model.
    - [ ] Ran migration for new fields.
    - [ ] Tested `Auth::user()` in queue context.
    - [ ] Verified legacy data backfill (if applicable).
    

• Release Strategy:
  • Canary: Enable on 10% of models first (e.g., Post, Comment).
  • Rollback: Drop