Algolia Bundle Laravel Package

Getting Started

Read this first: this is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no facade, no config/algolia.php, and Composer auto-discovery will not wire anything up for you. If you are in a Laravel codebase, the honest answer is that you almost certainly want laravel/scout plus the Algolia driver, or the algolia/algolia-php-client directly — not this bundle. Everything below assumes you are either (a) working in a Symfony app that happens to sit next to your Laravel work, or (b) evaluating whether to port the bundle's conventions into a Laravel integration.

Minimal steps in a Symfony host:

composer require goldenline/algolia-bundle

Register the bundle (config/bundles.php on Symfony 4+, AppKernel::registerBundles() on 2/3):

GoldenLine\AlgoliaBundle\AlgoliaBundle::class => ['all' => true],

Then configure credentials. Expect a tree roughly like:

# config/packages/algolia.yaml
algolia:
    application_id: "%env(ALGOLIA_APP_ID)%"
    api_key: "%env(ALGOLIA_API_KEY)%"
    indexes:
        products: App\Entity\Product

Where to look first, in order:

1. DependencyInjection/Configuration.php — the authoritative list of config keys. Do not trust the README; bundles like this drift.
2. Resources/config/services.yml (or config/services.xml) — the service IDs and aliases you will actually inject.
3. DependencyInjection/*Extension.php — how index definitions are turned into service arguments.
4. Any Command/ directory — the indexer/console commands are usually the fastest way to see the intended workflow end to end.

First use case: define one index in config, run the bundle's reindex command (bin/console algolia:reindex or similar — check Command/), then inject the client into a controller and call search(). Get that loop working before touching Doctrine listeners or event subscribers.

Implementation Patterns

Inject the client, not a static call. The bundle's value is a configured Algolia\AlgoliaSearch\Client (or SearchClient in v3) plus named index handles. Type-hint against the client interface or use the per-index service alias rather than constructing clients inline:

public function __construct(private Client $algolia) {}

public function search(string $q): array
{
    return $this->algolia->initIndex('products')->search($q);
}

Index naming with environment prefixes. The usual pattern in these bundles is to derive the index name from config plus an environment suffix, so products becomes products_dev / products_prod. Confirm how the extension builds names before you write anything that hardcodes an index string — mismatches here are the #1 source of "my data isn't there" confusion.

Index-time vs. query-time separation. The clean split that works in both Symfony and Laravel:

• Indexing — Doctrine lifecycle listeners / Eloquent observers that push a saveObjects/deleteObject call, or a nightly full reindex command. Prefer the command for the initial backfill and observers for incremental updates.
• Querying — a thin repository/service wrapping the index handle, exposing typed results. Never let controllers touch initIndex() directly; you lose the ability to swap index names per environment.

Batch and throttle. Full reindexes should use saveObjects in chunks (Algolia's own guidance is batches of ~1k–10k records, and it returns per-object errors you must inspect). Do not loop saveObject per row — you will hit rate limits and take hours.

If you are porting to Laravel: skip the bundle and mirror its shape by hand.

// config/services.php
'algolia' => [
    'id' => env('ALGOLIA_APP_ID'),
    'key' => env('ALGOLIA_API_KEY'),
],

// AppServiceProvider::register()
$this->app->singleton(Client::class, fn () => new Client(
    config('services.algolia.id'),
    config('services.algolia.key'),
));

Then bind a ProductIndex class that owns the index name and the saveObjects/search calls. That gives you the bundle's ergonomics without dragging Symfony's DI, bundle registration, and Configuration.php into a Laravel app.

Replicas and sorting. If you need sort orders, create replica indexes (products_price_asc) and search those — Algolia will not sort on arbitrary attributes in the primary index. This is configured outside the bundle; the bundle only cares about the primary index name.

Gotchas and Tips

The Symfony/Laravel mismatch is the big one. No register()/boot(), no package discovery, no config/*.php publish. You cannot composer require this in Laravel and expect a working service. If a teammate added it to composer.json by mistake, expect zero effect and a very slow autoload classmap scan.

Unmaintained and low-signal. Zero dependents and no stars is a real signal. Check composer.json for the pinned algolia/algolia-php-client version against what you have installed. The Algolia PHP client went through a significant v2→v3 rename (Client → SearchClient, initIndex semantics, search signature). If the bundle pins ^1.0, you are on an API that Algolia's current docs no longer describe — budget time for a compatibility shim or a rewrite.

Key type mistakes are silent until they are not. api_key in these configs is usually the admin key (needed for indexing). Never let it reach the browser. For frontend search you want a separate search-only key; most bundles do not manage that for you, so keep the two config values distinct and pass the search key to the frontend explicitly.

Index name drift between environments. Confirm the suffixing rule before seeding. A common failure: staging and production write to the same index because the env var wasn't set, and you spend a day debugging why staging edits appear in prod search.

Errors from saveObjects do not throw. Algolia returns 200 with a body listing failed object IDs. Wrap your reindex command to assert on $response['objectIDs'] / error counts and exit non-zero, otherwise CI will happily pass a broken index.

Debugging checklist when search returns nothing:

1. bin/console debug:container | grep -i algolia — confirm the service exists and which ID.
2. bin/console debug:config algolia (Symfony 4+) — confirm the config actually merged; YAML keys under the wrong bundle alias are silently ignored.
3. Query the index directly with curl against the Algolia REST API using your app ID — isolates bundle issues from credential/index issues.
4. Check whether the record has the attributesForFaceting / searchableAttributes settings you assume; defaults are permissive but replicas and facets are not.

Extension points. The DI extension is the place to hook in: override the index-name service, decorate the client with a logging wrapper, or add a compiler pass to auto-tag indexer services. Adding a ->decorate() for the client is the cleanest way to add retry/backoff without forking the bundle.

Config quirks. Watch for application_id vs app_id and api_key vs admin_api_key naming differences between the bundle's Configuration.php and Algolia's own docs — copy-pasting from Algolia's README into the bundle's YAML is a classic source of "invalid credentials" errors that look like bad keys but are ignored config keys.