Ezplatform Search Laravel Package

Technical Evaluation

Architecture Fit

• Search-Centric Alignment: The ezsystems/ezplatform-search package remains tailored for Elasticsearch integration, offering scalable full-text search, filtering, and faceting. Its alignment with decoupled architectures (microservices/modular monoliths) persists, though Laravel-specific adaptations are still required.
• Decoupled Design: The package’s abstraction of Elasticsearch interactions remains valuable, but the reusable generator workflow (IBX-5569) may simplify index mapping generation for Laravel models, reducing boilerplate.
• Legacy System Constraints: Non-eZ Platform systems (e.g., Laravel) still require adapters or proxy layers, though the new workflow could streamline schema definitions.

Integration Feasibility

• PHP/Ecosystem Compatibility: Continues to work with Laravel (PHP 8.0+) and Elasticsearch (v7.x/8.x). The reusable generator workflow may reduce manual mapping efforts, easing adoption.
• ORM/Query Builder Synergy:
  • Laravel Eloquent: Still requires custom repositories or query translators, but the generator workflow could automate index field definitions from Eloquent models.
  • Raw Elasticsearch Queries: Feasible for complex searches, with the new workflow potentially simplifying DSL generation.
• Caching Layer: Laravel’s cache (Redis/Memcached) remains viable for mitigating Elasticsearch latency.

Technical Risk

• Schema Mismatch: Risk persists if Laravel models evolve post-integration, but the reusable generator workflow may reduce drift by automating schema updates.
• Performance Overhead:
  • Index population and real-time sync remain CPU/memory-intensive, though the generator could optimize initial setup.
  • Write latency persists but may be mitigated via queues or event-driven updates.
• Vendor Lock-in: eZ Platform-specific abstractions still pose a risk, though the generator workflow is a neutral improvement (not lock-in).
• Elasticsearch Expertise: Debugging remains complex, but the workflow may lower the barrier for basic integrations.

Key Questions

1. Use Case Clarity:
   • Does the reusable generator workflow align with your model-to-index mapping needs? (e.g., complex nested objects vs. simple fields)
2. Existing Infrastructure:
   • Will the workflow reduce manual schema management effort in your Laravel project?
3. Laravel Integration Depth:
   • Can the generator fully replace custom mappings, or will manual overrides still be needed?
4. Fallback Strategy:
   • Does the workflow support fallback-friendly index designs (e.g., minimal required fields)?
5. Maintenance:
   • How will the workflow impact schema updates during Laravel model migrations?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Elasticsearch Client: Still recommend elasticsearch/elasticsearch (v8+) alongside the package.
  • Service Container: Register package components as Laravel bindings/facades; the generator workflow can pre-generate index mappings during deployment.
  • Query Builder: For Eloquent, use the generator to auto-create base mappings, then extend manually for complex cases.
• Alternatives Considered:
  • Laravel Scout: If search is secondary, Scout (with Elasticsearch driver) may still suffice with less boilerplate.
  • Direct Elasticsearch: For full control, bypass the package and use the PHP client directly (higher maintenance).

Migration Path

1. Phase 1: Proof of Concept (Updated)
   • Use the reusable generator workflow to auto-generate Elasticsearch mappings from Laravel models.
   • Validate generated mappings against realistic data (e.g., nested relationships, polymorphic associations).
   • Test basic queries with the auto-generated index.
2. Phase 2: Hybrid Integration
   • Implement dual-write (sync Laravel DB changes to Elasticsearch via observers or model events).
   • Use the generator to update mappings during Laravel model migrations.
3. Phase 3: Full Replacement
   • Replace SQL searches with Elasticsearch where applicable, leveraging the generator for consistent schema management.

Compatibility

• Elasticsearch Version: Ensure compatibility with the package’s supported version (v7.10+).
• Laravel Version: Test with Laravel 9/10 (PHP 8.0+).
• Data Model Alignment:
  • The generator workflow simplifies mapping alignment but may still require manual adjustments for complex Laravel features (e.g., polymorphic relations).

Sequencing

1. Infrastructure Setup:
   • Deploy Elasticsearch cluster (or use managed service).
   • Configure index templates and aliases, leveraging the generator for initial mappings.
2. Laravel Configuration:
   • Publish package configs and extend with Laravel-specific settings (e.g., cache adapters).
   • Set up queue workers for async indexing, using the generator to validate mappings before bulk indexing.
3. Feature Development:
   • Build search endpoints with Laravel’s HTTP layer, using the generator’s auto-generated fields.
   • Implement fallback logic (e.g., SQL queries if Elasticsearch is down).
4. Testing:
   • Unit tests: Mock Elasticsearch responses for query logic, focusing on generator-output mappings.
   • Integration tests: Validate sync between Laravel and Elasticsearch, including mapping updates.
   • Load tests: Simulate peak traffic with auto-generated indices.

Operational Impact

Maintenance

• Elasticsearch Management:
  • Schema Drifts: The generator workflow reduces manual mapping errors but requires testing updates during Laravel model migrations.
  • Cluster Health: Monitor as before; the generator does not affect runtime performance.
• Laravel-Specific:
  • Package Updates: Monitor for breaking changes; the workflow is an internal improvement.
  • Custom Code: Maintain adapters for Laravel-specific features (e.g., Scout integration).
• Documentation:
  • Runbooks: Update to include generator workflow in schema recovery procedures.
  • Troubleshooting: Log generator output validation and mapping conflicts.

Support

• Debugging Complexity:
  • Elasticsearch queries remain hard to debug, but the generator may reduce mapping-related issues.
  • Laravel Logs: Instrument sync jobs and search queries with structured logging, including generator metadata.
• Vendor Support:
  • Limited community support persists; rely on Elasticsearch docs and PHP client issues.
  • Consider commercial support for Elasticsearch if SLAs are required.
• User Training:
  • Developers: Train on the generator workflow and Elasticsearch DSL.
  • Operations: Ensure team understands cluster scaling and security, with generator outputs as part of CI/CD.

Scaling

• Horizontal Scaling:
  • Elasticsearch: Add nodes as before; the generator does not impact scaling.
  • Laravel: Scale search endpoints independently (e.g., queue-based processing).
• Performance Tuning:
  • Indexing: Batch writes, use bulk API, or async queues to avoid blocking Laravel requests.
  • Query Optimization:
    • Use index sorting and filter caching for faceted searches.
    • Avoid script_score or function_score in high-volume queries.
  • Cost Optimization: Right-size nodes; the generator may reduce over-provisioning by ensuring efficient mappings.
• Generator Workflow:
  • CI/CD Integration: Run the generator in pre-deployment to validate mappings.
  • Dynamic Updates: Use the workflow to regenerate mappings during Laravel migrations.

Failure Modes