Doctrine Footprint Extension Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Aligns with Laravel’s Doctrine ORM (if using doctrine/dbal or doctrine/orm alongside Laravel) for audit logging without reinventing the wheel.
  • Lightweight trait-based approach minimizes entity boilerplate (avoids manual created_at, updated_at, etc. fields).
  • Soft-deletes via Doctrine filters integrate with Laravel’s Eloquent soft-delete conventions if adapted.
• Cons:
  • Not native to Laravel: Requires Doctrine ORM (not Eloquent), which is uncommon in Laravel monoliths. May conflict with Laravel’s built-in timestamps() and softDeletes().
  • Stale codebase: Last release in 2019 raises concerns about compatibility with modern PHP (8.1+) and Doctrine (3.x).
  • No Laravel-specific integrations: No out-of-the-box support for Laravel’s auth system (e.g., Auth::user()), requiring manual mapping of security.token_storage to Laravel’s auth.

Integration Feasibility

• Doable but non-trivial:
  • Requires Doctrine ORM setup (uncommon in Laravel; typically uses Eloquent).
  • Conflict risk: Overrides Laravel’s default timestamps() if entities use both systems.
  • Auth integration: security.token_storage must be bridged to Laravel’s Auth facade or a custom service.
• Workarounds:
  • Use Doctrine alongside Eloquent (hybrid approach) with a custom listener to sync metadata.
  • Replace with Laravel-native solutions (e.g., laravel-auditlog, spatie/laravel-activitylog) if Doctrine is not a hard requirement.

Technical Risk

• High:
  • Deprecation risk: Doctrine 2.x (used here) is end-of-life; modern Laravel apps use Doctrine 3.x or Eloquent.
  • Maintenance burden: Stale package may break with PHP/Doctrine updates.
  • Testing overhead: Manual validation needed for auth/user resolution and edge cases (e.g., bulk operations).
• Mitigations:
  • Fork and modernize: Update the package for PHP 8.1+ and Doctrine 3.x.
  • Isolate scope: Restrict to non-critical entities or use as a prototype for a custom solution.

Key Questions

1. Why Doctrine ORM?
   • Is this a legacy system or a strategic shift to Doctrine? If Laravel/Eloquent is the primary ORM, this may not be worth the effort.
2. Auth System Compatibility
   • How will security.token_storage map to Laravel’s Auth? Requires custom glue code.
3. Performance Impact
   • Does the Doctrine filter add significant overhead to queries? Benchmark against alternatives.
4. Alternatives
   • Compare with Laravel packages like:
     • spatie/laravel-activitylog (Eloquent-focused, modern).
     • owen-it/laravel-auditlogs (supports soft deletes, timestamps).
5. Long-Term Viability
   • Is the team willing to maintain a fork, or should this be a short-term solution?

Integration Approach

Stack Fit

• Target Stack:
  • Laravel + Doctrine ORM (not Eloquent).
  • Symfony Security Bundle (for security.token_storage compatibility).
  • PHP 8.1+ (requires package updates).
• Mismatches:
  • Laravel’s default stack (Eloquent, Illuminate/Auth) is not natively supported.
  • Doctrine 2.x is outdated; modern Laravel apps may use Doctrine 3.x or avoid it entirely.

Migration Path

1. Assess Doctrine Adoption:
   • If Doctrine is already in use, proceed with integration.
   • If not, evaluate cost vs. benefit of adopting Doctrine for this feature.
2. Auth Bridge:
   • Create a custom service to translate security.token_storage to Laravel’s Auth::user().
   • Example:

     // src/Service/DoctrineAuthBridge.php
     class DoctrineAuthBridge {
         public function getUser(): ?User {
             return Auth::user(); // Map Symfony token to Laravel user
         }
     }
     

3. Configuration:
   • Add Doctrine filter to config/packages/doctrine.yaml.
   • Register the listener in config/services.yaml with the auth bridge as an argument.
4. Entity Adoption:
   • Use the trait in Doctrine entities:

     use Glazer\DoctrineFootprintExtension\Traits\FootprintTrait;
     
     class Product {
         use FootprintTrait;
         // ...
     }
     

Compatibility

• Doctrine Version:
  • Test with Doctrine ORM 3.x (if possible) or fork the package for compatibility.
• Laravel Auth:
  • Ensure security.token_storage can resolve the current user (may require middleware or a custom guard).
• Soft Deletes:
  • If using Laravel’s softDeletes(), conflicts may arise with Doctrine’s soft-delete filter. Decide on a single source of truth.

Sequencing

1. Phase 1: Proof of Concept
   • Integrate into one non-critical entity to validate auth/user resolution and performance.
2. Phase 2: Full Rollout
   • Gradually apply to other entities; monitor query performance.
3. Phase 3: Monitoring
   • Set up logs for failed user resolutions or timestamp updates.

Operational Impact

Maintenance

• High Effort:
  • Forking required: Stale package needs updates for PHP 8.1+ and Doctrine 3.x.
  • Dependency management: Doctrine ORM is a heavy dependency for a simple feature.
  • Auth system coupling: Custom bridge may break if Laravel’s auth system changes.
• Alternatives:
  • Use a Laravel-native package (lower maintenance risk).
  • Build a custom trait for Eloquent (recommended if not using Doctrine).

Support

• Limited Community:
  • No stars/issues suggest low adoption; troubleshooting will be self-reliant.
• Debugging:
  • Complexity arises from:
    • Doctrine event listeners.
    • Auth token resolution.
    • Potential conflicts with Laravel’s built-in features.
• Documentation:
  • README is minimal; expect to document internal setup (e.g., auth bridging).

Scaling

• Performance:
  • Filter overhead: Doctrine filters can impact query performance if not indexed properly.
  • Bulk operations: Test with mass updates/deletes to ensure timestamps/users are set correctly.
• Database:
  • Additional indexes may be needed on created_by, updated_by for query optimization.

Failure Modes

Ramp-Up

• Learning Curve:
  • Moderate: Requires familiarity with Doctrine ORM and Symfony’s security.token_storage.
  • High for Laravel teams: Uncommon stack combination.
• Onboarding:
  • Document:
    • Auth bridging process.
    • Entity setup steps.
    • Troubleshooting for common failures (e.g., missing user).
• Training:
  • Focus on Doctrine event listeners and custom service integration.
• Alternatives:
  • If ramp-up is too steep, consider spatie/laravel-activitylog (Laravel-native, lower barrier).