Plastic Laravel Package

Technical Evaluation

Architecture Fit

• Elasticsearch Synergy: Plastic bridges Laravel Eloquent models with Elasticsearch, enabling seamless full-text search, aggregations, and complex queries without manual index management. This aligns well with modern Laravel applications requiring scalable search capabilities (e.g., e-commerce, content platforms, or analytics dashboards).
• ODM Pattern: The Object-Document Mapper (ODM) abstraction reduces boilerplate for Elasticsearch operations, making it a strong fit for teams already using Eloquent. It abstracts away low-level Elasticsearch client interactions while preserving Laravel’s query builder familiarity.
• Hybrid Data Layer: Plastic enables a dual-write pattern (database + Elasticsearch) with minimal overhead, which is critical for applications where search relevance outweighs real-time consistency needs (e.g., product catalogs, logs, or user-generated content).

Integration Feasibility

• Laravel Ecosystem Compatibility: Leverages Laravel’s service container, Eloquent events, and query builder, reducing friction for existing Laravel projects. The package’s reliance on illuminate/support and illuminate/database ensures high compatibility with Laravel 8+.
• Elasticsearch Version Support: Explicitly supports Elasticsearch 7.x/8.x, which is critical for avoiding version-specific pitfalls (e.g., breaking changes in the _source field or pagination APIs). However, the lack of explicit support for Elasticsearch 6.x may limit legacy system adoption.
• Customization Flexibility: Supports custom mappings, analyzers, and query DSL via fluent methods, allowing teams to tailor Elasticsearch behavior without forking the package. This is ideal for domain-specific search requirements (e.g., fuzzy matching for typos or geospatial queries).

Technical Risk

• Performance Overhead: Dual-writing to both SQL and Elasticsearch introduces latency and eventual consistency risks. Teams must design idempotent write paths and handle retry logic for failed Elasticsearch operations (e.g., using Laravel’s queue:failed table).
• Schema Drift: Elasticsearch indices may diverge from database schemas over time, especially if Plastic’s auto-mapping isn’t configured strictly. Teams must implement validation (e.g., via Laravel migrations or custom events) to sync schemas.
• Dependency Bloat: Adds Elasticsearch PHP client (elasticsearch/elasticsearch) as a dependency, increasing deployment complexity (e.g., Docker configurations, connection pooling). For serverless or edge deployments, this may require additional infrastructure (e.g., managed Elasticsearch like AWS OpenSearch).
• Learning Curve: While Plastic abstracts Elasticsearch complexity, teams unfamiliar with Elasticsearch concepts (e.g., analyzers, tokenizers, or aggregations) may struggle with advanced use cases. Documentation gaps (e.g., lack of examples for nested objects or parent-child relationships) could slow adoption.

Key Questions

1. Use Case Alignment:
   • Is Elasticsearch a core feature (e.g., search-driven UI) or a nice-to-have? If the latter, consider lighter alternatives like Laravel Scout with Algolia.
   • Are there real-time consistency requirements (e.g., inventory systems)? If so, Plastic’s eventual consistency model may need augmentation (e.g., with Laravel events or webhooks).
2. Infrastructure Readiness:
   • Is Elasticsearch already deployed, or will this require new infrastructure? If the latter, factor in costs (e.g., managed vs. self-hosted) and operational overhead.
   • How will connection pooling or circuit breakers be handled in high-traffic scenarios?
3. Migration Strategy:
   • How will existing Elasticsearch indices (if any) be migrated to Plastic’s schema? Will manual mapping overrides be needed?
   • Are there legacy queries or dashboards (e.g., Kibana) that must remain compatible with the new schema?
4. Team Expertise:
   • Does the team have Elasticsearch experience, or will training be required? If the latter, budget for ramp-up time.
   • Are there existing Laravel packages (e.g., spatie/laravel-searchable) that could be deprecated in favor of Plastic?
5. Monitoring and Observability:
   • How will Elasticsearch performance (e.g., query latency, cluster health) be monitored? Will custom Laravel metrics (e.g., via laravel-debugbar) be needed?
   • Are there plans for alerting on Elasticsearch failures (e.g., connection drops, index corruption)?

Integration Approach

Stack Fit

• Laravel-Centric: Plastic is designed for Laravel, with deep integration into Eloquent, migrations, and service providers. It replaces or augments Laravel Scout, making it ideal for projects already using Eloquent models.
• Elasticsearch Stack Compatibility:
  • Works with any Elasticsearch-compatible deployment (self-hosted, AWS OpenSearch, Bonsai, etc.).
  • Supports Elasticsearch’s security features (e.g., API keys, TLS) via standard client configurations.
• Tooling Synergy:
  • Compatible with Laravel Forge/Senv for deployment automation.
  • Integrates with Laravel Horizon for background index updates or bulk operations.
  • Works with Laravel Telescope for debugging Elasticsearch queries.

Migration Path

1. Assessment Phase:
   • Audit existing Elasticsearch usage (if any) to identify schema, queries, or dependencies that may conflict with Plastic.
   • Document current search workflows (e.g., manual _search API calls) to map them to Plastic’s fluent syntax.
2. Proof of Concept (PoC):
   • Start with a single Eloquent model (e.g., Product or Article) and Plastic’s basic CRUD operations.
   • Test auto-mapping vs. custom mappings to validate schema alignment.
   • Benchmark performance against existing solutions (e.g., raw Elasticsearch client or Scout).
3. Incremental Rollout:
   • Phase 1: Replace simple search queries (e.g., where('name', 'like', '%term%')) with Plastic’s search() method.
   • Phase 2: Migrate aggregations, facets, and sorting to Plastic’s fluent DSL.
   • Phase 3: Implement dual-write logic for critical models (e.g., using Laravel events or observers).
   • Phase 4: Deprecate legacy Elasticsearch queries in favor of Plastic’s syntax.
4. Schema Migration:
   • Use Plastic’s migrate command to sync existing indices with Laravel models.
   • For custom indices, manually define mappings in config/plastic.php or via model events (booted).

Compatibility

• Laravel Versions: Officially supports Laravel 8/9/10. Test thoroughly for breaking changes in newer Laravel versions (e.g., dependency injection updates).
• PHP Versions: Requires PHP 8.0+. Ensure your environment meets this requirement.
• Elasticsearch Versions: Test against your target Elasticsearch version (7.x vs. 8.x) for compatibility with features like:
  • Eager loading (_source vs. stored_fields).
  • Deprecated APIs (e.g., type field in 8.x).
• Third-Party Packages:
  • Conflict risk with other Elasticsearch packages (e.g., elasticsearch/elasticsearch may be loaded twice). Use Laravel’s PackageServiceProvider to resolve bindings.
  • Scout users: Plastic is not a drop-in replacement; Scout integrations (e.g., scout:import) will need rewriting.

Sequencing

1. Pre-Integration:
   • Set up Elasticsearch and configure Laravel’s config/plastic.php (e.g., host, port, index prefix).
   • Install the package: composer require sleimanx2/plastic.
   • Publish and customize the config: php artisan vendor:publish --tag=plastic-config.
2. Model Integration:
   • Extend Eloquent models with use Sleimanx2\Plastic\Traits\Searchable;.
   • Define mappings in getPlasticMapping() or use auto-mapping.
   • Example:

     class Product extends Model
     {
         use Searchable;
     
         public function getPlasticMapping()
         {
             return [
                 'properties' => [
                     'name' => ['type' => 'text', 'analyzer' => 'english'],
                     'price' => ['type' => 'float'],
                     'tags' => ['type' => 'keyword'],
                 ],
             ];
         }
     }
     

3. Query Migration:
   • Replace raw Elasticsearch queries with Plastic’s fluent methods:

     // Before (raw client)
     $results = $client->search(['index' => 'products', 'body' => [...]]);
     
     // After (Plastic)
     $results = Product::search('term')->paginate(10);
     

4. Post-Integration:
   • Implement monitoring for Elasticsearch health and query performance.
   • Set up backup/recovery procedures for indices (e.g., using Elasticsearch snapshots).
   • Document Plastic-specific queries for the team.

Operational Impact

Maintenance

• Package Updates:
  • Monitor sleimanx2/plastic for breaking changes (e.g., Elasticsearch 8.x compatibility).
  • Test updates in staging before production deployment.
• Dependency Management:
  • Elasticsearch PHP client updates may require adjustments (e.g., deprecated methods).
  • Laravel version upgrades may necessitate Plastic compatibility checks.
• Schema Maintenance:
  • Use Plastic’s migrate command to update indices when models