Laravel Elastica Bridge Laravel Package

Getting Started

elastica-bridge wraps the Elastica client for Elasticsearch in a Laravel service provider, exposing configuration, a container binding/facade, and optional Sentry breadcrumb integration.

1. Install and publish the config:

   composer require <vendor>/elastica-bridge
   php artisan vendor:publish --tag=elastica-bridge-config
   

2. Set the connection details in .env (hosts, index prefix, credentials) and, on v2.2.0+, optionally the log level:

   ELASTICSEARCH_LOG_LEVEL=warning
   

3. Resolve the client from the container rather than constructing Elastica\Client yourself, so config and logging hooks apply consistently.

Look here first: config/elastica-bridge.php. It is the single source of truth for hosts, index naming, and the logging block. Confirm the published file exists and is not stale — an old published config will silently ignore newer keys such as logging.level.

First use case: index a document and read it back in a Tinker session or a feature test to validate connectivity and index/alias naming before wiring it into a repository or job.

$client = app(\Elastica\Client::class); // or the package's bound service/facade
$index  = $client->getIndex(config('elastica-bridge.index'));
$index->addDocument(new \Elastica\Document(1, ['title' => 'hello']));

Implementation Patterns

Wrap the client, don't sprinkle it. Bind your own repository/search service around the package client and inject that. Business code should not know about Elastica\Query unless it is genuinely a search concern. This keeps the eventual upgrade path (Elastica major versions, OpenSearch forks) contained.

Per-connection configuration. Keep connection profiles in config keyed by name rather than branching on env inside services; resolve the profile at boot from env. Tests then override config() instead of mutating globals.

Log level as an environment concern (v2.2.0). Treat elastica-bridge.logging.level as a per-environment dial:

// config/elastica-bridge.php
'logging' => [
    'level' => env('ELASTICSEARCH_LOG_LEVEL', 'debug'),
],

• Local/staging with Sentry enabled: debug is useful — full request/response bodies in breadcrumbs make query debugging fast.
• Production with Sentry enabled: warning or error. Debug bodies are huge, and dumping them as breadcrumbs on every query inflates memory and flushes PII to a third party.
• If sentry_breadcrumbs is disabled entirely, this setting is inert — no need to tune it.

Index lifecycle as artisan commands/jobs. Put create/alias-swap/reindex logic in dedicated commands rather than ad-hoc scripts, so index naming from config stays authoritative and reindexes are repeatable in CI and on deploy.

Bulk operations. Use Elastica's bulk API for writes; a loop of addDocument calls is the most common performance mistake. Wrap bulk responses in a check — Elastica does not throw on per-item failures.

Testing. Bind a fake or an in-memory stub for your repository in unit tests; reserve integration tests hitting a real (containerised) Elasticsearch for the narrow set of query-shape assertions. Assert on the generated query array rather than round-tripping documents where possible.

Gotchas and Tips

• Naming mismatch: the config key is elastica-bridge.logging.level but the env var is ELASTICSEARCH_LOG_LEVEL — not the package-prefixed name you'd guess. Copy it exactly; a typo yields a silent fallback to debug and a production memory surprise.
• This is not a Monolog channel. The setting filters what reaches Sentry breadcrumbs, not what hits storage/logs. Lowering Monolog's LOG_LEVEL does not reduce breadcrumb payloads, and vice versa.
• Breadcrumbs are captured eagerly. Filtering happens at capture time, so you cannot recover debug breadcrumbs after the fact by lowering the level. If you need query detail for an intermittent failure, you must raise the level before reproducing it.
• Bodies are logged in full at debug. Elasticsearch responses echo documents back; anything sensitive in an indexed document (emails, tokens, free text) can end up attached to Sentry events. Use Sentry's before_breadcrumb / before_send hooks to scrub, or keep production at warning.
• Sentry caps breadcrumbs (max_breadcrumbs, typically 100). High-volume debug queries will evict more useful application breadcrumbs from the ring buffer — another reason to run production above debug.
• Config caching: after changing ELASTICSEARCH_LOG_LEVEL, run php artisan config:clear in local or php artisan config:cache in deploy. A cached config makes env changes appear to do nothing.
• The default is deliberately non-breaking. debug preserves pre-2.2.0 behaviour exactly, so upgrading changes nothing until you set the variable — don't assume the release "fixed" your memory issue.
• Check the published config is current. After upgrading, diff the package's config stub against yours; new keys like logging.level only apply if present. vendor:publish --force overwrites — diff first.
• Debugging connection issues: log at the transport level rather than raising breadcrumb verbosity first; debug bodies are noisy and bury the actual connection error. Verify host/port and cluster health with a direct curl before blaming the bridge.