Php Document Store Laravel Package

Technical Evaluation

Architecture Fit

• Hexagonal/Onion Architecture Alignment: The DocumentStore interface fits perfectly as a port in Laravel’s layered architecture, enabling clean separation between domain logic and persistence. This complements Laravel’s repository pattern and service layer, reducing direct database access in business logic.
• Event-Driven Synergy: Ideal for event sourcing and CQRS patterns, where documents represent state snapshots or read models. The replaceDoc/replaceMany methods prevent accidental merges, critical for consistency in event-sourced systems.
• Laravel-Specific Advantages:
  • Service Container Integration: Laravel’s DI system can bind the interface to implementations (e.g., PostgresDocumentStore in production, InMemoryDocumentStore in tests) with zero boilerplate.
  • Migration Support: Leverages Laravel’s migration system to manage schema changes (e.g., indices) via Schema::create/drop methods.
  • Task Scheduling: Async operations (e.g., bulk updates) can use Laravel’s queues (Illuminate\Queue) for background processing.
• Testing Facilitation: The in-memory store eliminates the need for mocks or test databases, accelerating TDD in Laravel’s Pest/PHPUnit workflows.

Integration Feasibility

• Minimal Surface Area: The interface requires only 15 methods (CRUD + indexing), making it easy to adapt to Laravel’s existing abstractions (e.g., Illuminate\Database\Eloquent\Model).
• Database Agnosticism:
  • PostgreSQL: Native support via event-engine/postgres-document-store.
  • MySQL: Requires a custom adapter (e.g., using Laravel’s DB facade).
  • NoSQL: Can wrap MongoDB (jenssegers/mongodb) or Elasticsearch with minimal effort.
• Dependency Risks:
  • Circular Dependency: Mitigated by:
    • Using composer’s replace for local dev:

      "repositories": [
        { "type": "path", "url": "../event-engine/persistence" }
      ],
      "replace": {
        "event-engine/persistence": "*"
      }
      

    • Monorepo Setup: If using Laravel Sail or Docker, mount the persistence package as a volume.
  • PHP 8.4 Deprecations: Already patched in v0.8.2; no action required for Laravel 10+.

Technical Risk

Key Questions

1. Storage Backend:
   • Should we prioritize PostgreSQL (native support) or build a Laravel-specific adapter (e.g., for MySQL/NoSQL)?
2. Testing Strategy:
   • Will we use the in-memory store for all tests, or supplement with database snapshots (e.g., Laravel’s RefreshDatabase)?
3. Event Integration:
   • How will document changes trigger Laravel events (e.g., DocumentUpdated) or domain events (e.g., EventEngine\Event)?
4. Concurrency:
   • Are optimistic/pessimistic locks needed for high-contention scenarios? (Not natively supported; may require custom logic.)
5. Monitoring:
   • How will we track document store latency and failure rates? (Integrate with Laravel’s Sentry or Prometheus.)

Integration Approach

Stack Fit

• Laravel Service Container:
  • Bind the interface in AppServiceProvider with environment-based implementations:

    $this->app->bind(DocumentStore::class, function ($app) {
        return config('app.env') === 'testing'
            ? new InMemoryDocumentStore()
            : new PostgresDocumentStore($app['db']->connection());
    });
    

  • Use Laravel’s config to toggle features (e.g., document_store.enable_indexing).
• Eloquent Integration:
  • Accessors/Mutators: Sync document data with Eloquent models:

    class User extends Model {
        public function getDocumentAttribute() {
            return $this->documentStore->findDoc($this->id);
        }
    }
    

  • Observers: Trigger document updates on Eloquent events:

    User::observe(function ($model) {
        $model->documentStore->replaceDoc($model->toArray());
    });
    

• Queue Integration:
  • Offload heavy operations (e.g., replaceMany) to Laravel’s queues:

    ReplaceManyDocuments::dispatch($collectionId, $docs)->onQueue('document-store');
    

• Caching Layer:
  • Cache documents using Laravel’s Cache facade with tags for invalidation:

    Cache::tags(['documents'])->remember("doc:{$id}", now()->addMinutes(5), fn() =>
        $this->documentStore->findDoc($id)
    );
    

Migration Path

1. Phase 1: Contract Setup (1–2 days)
   • Add the interface to Laravel’s app/Contracts/DocumentStore.php.
   • Publish a config file (config/document_store.php) for backend selection.
2. Phase 2: Implementation (3–5 days)
   • Option A: Use PostgresDocumentStore with Laravel’s DB facade.
   • Option B: Build a custom adapter (e.g., EloquentDocumentStore) for ORM integration.
   • Example adapter skeleton:

     class EloquentDocumentStore implements DocumentStore {
         public function findDoc(string $id): ?array {
             return Model::find($id)?->toArray();
         }
         // ... other methods
     }
     

3. Phase 3: Testing (2–3 days)
   • Replace production store with InMemoryDocumentStore in tests:

     use function Pest\Laravel\actingAs;
     actingAs()->withDocumentStore(InMemoryDocumentStore::class);
     

   • Test edge cases (e.g., unique index violations, partial updates).
4. Phase 4: Deployment (1–2 sprints)
   • Gradually migrate document-heavy services to use the new store.
   • Use Laravel’s feature flags (e.g., spatie/laravel-feature-flags) to toggle implementations.

Compatibility

Sequencing

1. Start with Non-Critical Paths:
   • Begin with read-heavy use cases (e.g., CQRS read models) before write-heavy ones (e.g., event sourcing).
2. Leverage Existing Abstractions:
   • Use Laravel’s repositories or services to wrap DocumentStore calls.
3. Incremental Testing:
   • Test unit → feature → integration layers, using the in-memory store for fast feedback.
4. Performance Tuning:
   • Profile with Laravel Debugbar or Blackfire to identify bottlenecks (e.g., indexing overhead).
5. Rollback Plan:
   • Maintain a feature flag to revert to the old implementation if issues arise.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor event-engine/php-document-store for BC breaks (e.g., dropIndex changes).
  • Use Laravel’s upgrade command to handle schema migrations.
• Schema Management: