Skip to main content

Documentation Index

Fetch the complete documentation index at: https://algolia.com/llms.txt

Use this file to discover all available pages before exploring further.

Version 8.1 of the Algolia SearchBundle is built on version 4 of the Algolia PHP API client. This guide covers the breaking changes between 8.0.x and 8.1.x and how to update your code.

​
Update your dependencies

SearchBundle 8.1 requires:
  • PHP 8.2 or later
  • Symfony 7 or 8
  • algolia/algoliasearch-client-php v4
Bump the bundle constraint in your composer.json and update:
Command line
composer require algolia/search-bundle:^8.1
composer update algolia/search-bundle algolia/algoliasearch-client-php
Composer installs a compatible v4 of the PHP client as a transitive dependency.

​
SearchClient namespace

SearchClient has moved to a new namespace. If you inject or type-hint SearchClient in your own code, update the fully qualified class name.
PHP
- use Algolia\AlgoliaSearch\SearchClient;
+ use Algolia\AlgoliaSearch\Api\SearchClient;
If you wire the client by its fully qualified name in a service definition, update the service ID:
YAML
  services:
      App\Service\MyService:
          arguments:
-             $client: '@Algolia\AlgoliaSearch\SearchClient'
+             $client: '@Algolia\AlgoliaSearch\Api\SearchClient'
Autowired constructors need the same change:
PHP
- public function __construct(\Algolia\AlgoliaSearch\SearchClient $client) {}
+ public function __construct(\Algolia\AlgoliaSearch\Api\SearchClient $client) {}

​
Request options format

In the v3 client, custom HTTP headers could be passed as top-level keys in $requestOptions. The v4 client silently ignores flat top-level keys: headers must be nested under headers.
PHP
  $this->searchService->index($em, $entity, [
-     'X-Forwarded-For' => '0.0.0.0',
+     'headers' => [
+         'X-Forwarded-For' => '0.0.0.0',
+     ],
  ]);
This applies to every SearchService method that accepts $requestOptions: index(), remove(), clear(), delete(), search(), rawSearch(), and count(). These top-level HTTP option keys are the ones the v4 client extracts from $requestOptions:
KeyTypePurpose
headersassociative arrayCustom HTTP headers
queryParametersassociative arrayExtra URL query parameters
bodyassociative arrayExtra request-body parameters
readTimeoutint (seconds)Read timeout
writeTimeoutint (seconds)Write timeout
connectTimeoutint (seconds)Connection timeout
For search(), rawSearch(), and count(), any other top-level keys are forwarded to the engine as search parameters (for example filters, hitsPerPage, attributesToRetrieve). The HTTP option keys above are the ones that change between 8.0 and 8.1.

​
Waitable responses

SearchServiceResponse::wait() no longer accepts parameters. In 8.0, you could pass request options (for example, a custom readTimeout) to wait(). In 8.1, waiting is handled internally by the client’s waitForTask() method, and wait() takes no arguments.
PHP
  $response = $this->searchService->index($em, $entities);
- $response->wait(['readTimeout' => 30]);
+ $response->wait();
The response classes returned by the bundle now live in Algolia\SearchBundle\Responses\:
ClassReturned from
Algolia\SearchBundle\Responses\SearchServiceResponseindex() and remove() on the live service
Algolia\SearchBundle\Responses\EngineResponseclear() and delete() on the live service when the index exists
Algolia\SearchBundle\Responses\NullResponseAll four write methods on the test service; clear() and delete() when the target index doesn’t exist
All three classes expose wait(), so the calling pattern is the same regardless of which one you receive. If you type-hint against response classes from the PHP client, replace them with the bundle’s response classes.

​
Autowiring alias

The bundle’s autowiring alias now targets the new client namespace:
YAML
# src/Resources/config/services.yaml
Algolia\AlgoliaSearch\Api\SearchClient:
    alias: search.client

Algolia\SearchBundle\SearchService:
    alias: search.service
If your own service definitions alias or decorate Algolia\AlgoliaSearch\SearchClient, update them to reference Algolia\AlgoliaSearch\Api\SearchClient.

​
Summary of namespace changes

8.0.x8.1.x
Algolia\AlgoliaSearch\SearchClientAlgolia\AlgoliaSearch\Api\SearchClient
Algolia\AlgoliaSearch\Response\IndexingResponseAlgolia\SearchBundle\Responses\EngineResponse
Algolia\AlgoliaSearch\Response\NullResponseAlgolia\SearchBundle\Responses\NullResponse
Algolia\AlgoliaSearch\Support\UserAgentAlgolia\AlgoliaSearch\Support\AlgoliaAgent
After updating your code, run your test suite and index a few records in a staging environment to confirm that request options and waitable responses behave as expected.
Last modified on April 27, 2026