Elasticsearch Bundle Laravel Package

Getting Started

• Requirements: PHP 5.6/7.x, Symfony 2.x, and an elasticsearch/elasticsearch client version that matches your cluster’s major version. Confirm the server version first (curl localhost:9200) — mismatched client/server majors are the most common failure mode with bundles of this vintage.
• Install: composer require openclassrooms/elasticsearch-bundle. If the repo has no tagged release, pin a specific commit hash rather than a branch.
• Register: add the bundle to app/AppKernel.php in the bundles array (new OpenClassrooms\Bundle\ElasticsearchBundle\OpenClassroomsElasticsearchBundle()).
• Configure: add an openclassrooms_elasticsearch: block in app/config/config.yml (or config/packages/ if you’re back-porting). Typical keys are hosts, index_prefix, and logging options — verify actual key names in DependencyInjection/Configuration.php, since bundle config shapes drift between commits.
• Where to look first: Resources/config/services.xml (or .yml) for the real service IDs, and the DependencyInjection/ folder for how the client is constructed. Don’t trust README examples for service IDs — they go stale fastest.
• First use case: inject the client service into a controller or command, index a single document, then run a match query and dump the hit count. This confirms config, auth, and mapping in one pass before you build anything on top.

Implementation Patterns

• Client as a shared service: never instantiate Elasticsearch\Client manually — inject the bundle-provided service so connection settings and logging stay centralized. Wrap it in your own SearchService/Indexer so controllers never touch raw DSL.
• Index naming with prefixes: use the configured prefix plus environment (myapp_dev, myapp_prod) so dev/test traffic never collides with production.
• Domain repositories: create a ProductIndexRepository per document type, encapsulating mapping, indexing, and query construction. This gives you a clean seam to swap to Elastica or the official Symfony integration later.
• Bulk indexing for backfills and imports: build NDJSON bodies and send in batches of ~500–1000. Call bulk() in a loop over array_chunk(), and check per-item results (see Gotchas).
• Reindex-with-alias pattern: create a new versioned index (products_v2), bulk-load, run a _count sanity check, then atomically swap the read alias in a single _aliases call. Never mutate a live index in place.
• Doctrine lifecycle hooks: index on postPersist/postUpdate via a listener. Be aware this runs inside the transaction — prefer queuing into a message/table and draining asynchronously so a failed index doesn’t roll back a legitimate DB write.
• Console commands: implement app:search:reindex and app:search:health commands. They become the operational interface for ops and CI.
• Testing: use a dedicated test index prefix, truncate/delete between tests, and abstract the client behind an interface so you can stub it in unit tests that don’t need a live cluster.

Gotchas and Tips

• Maintenance status: this is a Symfony2-era bundle with zero dependents — treat it as frozen. Pin exact versions (composer.lock committed), and budget for a migration to FOSElasticaBundle or direct elasticsearch/elasticsearch usage on your next Symfony major upgrade.
• Client/server major mismatch: elasticsearch-php 5.x talks to a 5.x/6.x cluster; 7.x dropped mapping types. If you see “type is deprecated” warnings or No handler found for uri, this is why. The bundle does not abstract API differences.
• Mapping types removal: any bundle example using index/type/id will break on ES 7+. Your wrappers should speak index/_doc/id.
• Bulk is not all-or-nothing: bulk() returns HTTP 200 even when individual items fail. Always check $response['errors'] and iterate $response['items'] for non-2xx status per item — otherwise silent data loss.
• refresh: true is a trap in production: it forces an immediate segment refresh and will crater indexing throughput. Only use it in tests or right before an assertion; in prod rely on the default refresh interval.
• Config key drift: older commits use elasticsearch: as the root key, newer ones openclassrooms_elasticsearch:. If config is silently ignored, run app/console config:dump-reference <bundle> to see what the installed version actually expects.
• Alias swaps must be one request: separate add/remove calls leave a window where reads hit the wrong index. Use the actions array form of _aliases.
• Scroll memory leaks: large scroll scans hold server-side context. Always call clearScroll in a finally block and size batches (~1000 docs) to your heap.
• Debugging: if the bundle registers a data collector, use the Symfony profiler’s Elasticsearch panel to inspect raw queries and timings. If not, enable the client’s logger (Monolog handler at debug) — logging the full request body is the single most useful debugging lever.
• Extension points: override service definitions in your app’s services.yml (Symfony lets app-level definitions win) rather than editing vendor. If the bundle exposes parameters for hosts/prefix, use those; otherwise a compiler pass is the cleanest injection point.