Soft Deletable Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Doctrine Alignment: The bundle is tightly coupled with Symfony’s Doctrine ORM, making it a natural fit for Laravel applications using Doctrine (e.g., via doctrine/orm or laravel-doctrine). However, Laravel’s native Eloquent ORM is the primary choice, so integration would require abstraction layers (e.g., a custom Doctrine bridge or hybrid ORM approach).
• Soft Delete Pattern: The bundle implements a standard soft-delete pattern (via deleted_at timestamp), which aligns with Laravel’s built-in SoftDeletes trait. This reduces conceptual friction for teams familiar with Laravel’s approach.
• Configuration Flexibility: The bundle’s optional configuration (e.g., custom column names, per-entity overrides) allows for granular control, which is valuable for large-scale Laravel applications with diverse entity requirements.

Integration Feasibility

• Doctrine Dependency: Laravel’s default stack (Eloquent) is incompatible, but Doctrine integration is possible via:
  • Laravel Doctrine Bridge (e.g., laravel-doctrine/orm).
  • Hybrid ORM Approach: Use Doctrine for specific entities while keeping others in Eloquent (requires careful transaction management).
• Schema Migrations: The bundle adds a deleted_at column, which must be backward-compatible with existing Laravel migrations. Tools like laravel-migrations-generator or custom Doctrine migrations would be needed.
• Query Filtering: The bundle’s Doctrine DQL filter must be replicated in Laravel’s query builder or replaced with Eloquent’s global scopes. This could introduce performance overhead if not optimized.

Technical Risk

• ORM Fragmentation: Mixing Doctrine and Eloquent in Laravel risks inconsistent behavior (e.g., query caching, event listeners, or hydration differences). Mitigation: Isolate Doctrine entities to a single module.
• Legacy Code Impact: If the Laravel app relies on hard deletes or custom delete logic, the bundle’s automatic deleted_at updates may require refactoring.
• Testing Overhead: The bundle’s filter-based approach (vs. Eloquent’s model-level soft deletes) may complicate testing, especially for:
  • Repository tests (mocking the filter).
  • Database snapshots (soft-deleted records persist).
• Performance: The global filter adds a WHERE deleted_at IS NULL clause to all queries, which could impact:
  • Complex joins (filter applied per-table).
  • Bulk operations (e.g., Model::all() becomes slower).

Key Questions

1. ORM Strategy:
   • Will the app use Doctrine exclusively, or hybrid (Doctrine + Eloquent)? If hybrid, how will transactions/queries be managed?
   • Are there existing soft-delete implementations (e.g., custom traits) that could conflict?
2. Migration Path:
   • How will the deleted_at column be added to existing tables without downtime?
   • Will legacy queries (raw SQL, DQL) need updates to handle the filter?
3. Query Performance:
   • Are there high-traffic endpoints where the global filter could cause bottlenecks?
   • Will indexing (e.g., deleted_at) be sufficient, or are partitioning strategies needed for large tables?
4. Feature Parity:
   • Does Laravel need restore functionality (e.g., Model::restore())? The bundle lacks explicit restore methods.
   • Are there custom delete behaviors (e.g., bulk soft deletes) that require extension?
5. Maintenance:
   • Who will support Doctrine-specific issues (e.g., filter bugs, Doctrine version conflicts)?
   • How will the bundle be updated if Laravel’s Doctrine integration evolves?

Integration Approach

Stack Fit

• Primary Use Case: Best suited for Laravel apps already using Doctrine (e.g., legacy Symfony apps migrated to Laravel, or microservices with Doctrine backends).
• Alternatives:
  • Native Laravel: If Doctrine is avoidable, leverage Eloquent’s SoftDeletes trait (lower risk, no integration overhead).
  • Custom Solution: For hybrid apps, build a shared soft-delete trait that works with both Eloquent and Doctrine.
• Compatibility Matrix:

  Component	Compatible?	Notes
  Laravel Eloquent	❌ No	ORM mismatch; requires abstraction.
  Doctrine ORM	✅ Yes	Direct integration possible.
  Laravel Migrations	⚠️ Partial	Manual schema updates needed.
  Query Builder	⚠️ Partial	Filter must be replicated or bypassed.
  API Resources	✅ Yes	Works if entities are Doctrine-based.

Migration Path

1. Assessment Phase:
   • Audit existing delete logic (e.g., Model::destroy(), custom delete methods).
   • Identify entities requiring soft deletes and their current schema.
2. Pilot Integration:
   • Isolate a module: Start with a non-critical feature using Doctrine (e.g., admin panel).
   • Add deleted_at column: Use a Doctrine migration or Laravel’s Schema::table().
   • Implement SoftDeletableInterface: Test with one entity (e.g., Article).
3. Global Rollout:
   • Update migrations: Backfill deleted_at for existing records (if needed).
   • Replace delete logic: Update repositories/services to use entityManager->remove().
   • Query adjustments: Add SoftDeletableFilter to Doctrine’s config/packages/doctrine.yaml (if using Symfony’s config structure).
4. Hybrid Handling (if applicable):
   • Doctrine Entities: Use the bundle’s filter.
   • Eloquent Models: Implement SoftDeletes trait or a shared interface (e.g., SoftDeletable).

Compatibility

• Doctrine Version: The bundle supports Doctrine ORM 2.6.3+, which aligns with Laravel Doctrine bridges (e.g., laravel-doctrine/orm uses Doctrine 2.10+).
• Symfony Dependencies: The bundle requires Symfony FrameworkBundle, which may conflict with Laravel’s service container. Mitigation:
  • Use Symfony’s HttpKernel only for Doctrine-related services.
  • Avoid registering Symfony bundles globally in Laravel.
• PHP Version: Requires PHP 7.4+, which is compatible with Laravel 8+.

Sequencing

1. Infrastructure Setup:
   • Install andanteproject/soft-deletable-bundle via Composer.
   • Configure Doctrine in Laravel (e.g., via laravel-doctrine/orm).
2. Schema Changes:
   • Generate migrations for deleted_at columns (prioritize low-traffic tables).
3. Entity Updates:
   • Implement SoftDeletableInterface and SoftDeletableTrait for target entities.
4. Delete Logic Replacement:
   • Update services/repositories to use entityManager->remove().
5. Query Layer:
   • Enable the SoftDeletableFilter globally (or per-entity).
   • Test API responses to ensure soft-deleted records are excluded.
6. Restore Functionality:
   • Add custom logic to restore records (e.g., setDeletedAt(null) + flush).
7. Monitoring:
   • Track query performance (e.g., EXPLAIN on filtered queries).
   • Log filter-related errors (e.g., missing columns).

Operational Impact

Maintenance

• Dependency Management:
  • The bundle’s last release was in 2021, raising concerns about long-term support. Mitigation:
    • Fork the bundle to fix issues or extend features (e.g., restore functionality).
    • Monitor for Doctrine/Symfony breaking changes (e.g., Symfony 6+ compatibility).
  • Composer Updates: Pin the bundle version to avoid unexpected updates.
• Configuration Drift:
  • The bundle’s optional config may lead to inconsistent setups across environments. Document:
    • Default vs. custom column names.
    • Per-entity overrides.
• Debugging:
  • Filter Issues: Debugging SoftDeletableFilter may require deep knowledge of Doctrine’s event system.
  • Schema Mismatches: Errors like Column 'deleted_at' not found can occur if migrations are out of sync.

Support

• Troubleshooting:
  • Common Issues:
    • Records still appearing after soft delete (filter not enabled).
    • Performance degradation (missing indexes on deleted_at).
    • Conflicts with Doctrine lifecycle callbacks (e.g., preRemove).
  • Tools:
    • Use Doctrine\DBAL\Tools\Dumper to inspect schema.
    • Enable Doctrine’s SQL logging to verify filter queries.
• Team Skills:
  • Requ