> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade the Algolia SearchBundle

> Upgrade from SearchBundle 8.0.x to 8.1.x.

Version 8.1 of the Algolia SearchBundle is built on [version 4 of the Algolia PHP API client](/doc/libraries/sdk/upgrade/php).
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:

```sh Command line icon=square-terminal theme={"system"}
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.

```diff PHP icon=code theme={"system"}
- 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:

```diff YAML icon=braces theme={"system"}
  services:
      App\Service\MyService:
          arguments:
-             $client: '@Algolia\AlgoliaSearch\SearchClient'
+             $client: '@Algolia\AlgoliaSearch\Api\SearchClient'
```

Automatically provided constructors need the same change:

```diff PHP icon=code theme={"system"}
- 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`.

```diff PHP icon=code theme={"system"}
  $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`:

| Key               | Type              | Purpose                       |
| ----------------- | ----------------- | ----------------------------- |
| `headers`         | associative array | Custom HTTP headers           |
| `queryParameters` | associative array | Extra URL query parameters    |
| `body`            | associative array | Extra request-body parameters |
| `readTimeout`     | int (seconds)     | Read timeout                  |
| `writeTimeout`    | int (seconds)     | Write timeout                 |
| `connectTimeout`  | int (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.

```diff PHP icon=code theme={"system"}
  $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\`:

| Class                                                  | Returned from                                                                                            |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `Algolia\SearchBundle\Responses\SearchServiceResponse` | `index()` and `remove()` on the live service                                                             |
| `Algolia\SearchBundle\Responses\EngineResponse`        | `clear()` and `delete()` on the live service when the index exists                                       |
| `Algolia\SearchBundle\Responses\NullResponse`          | All 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 YAML icon=braces theme={"system"}
# 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.x                                             | 8.1.x                                           |
| ------------------------------------------------- | ----------------------------------------------- |
| `Algolia\AlgoliaSearch\SearchClient`              | `Algolia\AlgoliaSearch\Api\SearchClient`        |
| `Algolia\AlgoliaSearch\Response\IndexingResponse` | `Algolia\SearchBundle\Responses\EngineResponse` |
| `Algolia\AlgoliaSearch\Response\NullResponse`     | `Algolia\SearchBundle\Responses\NullResponse`   |
| `Algolia\AlgoliaSearch\Support\UserAgent`         | `Algolia\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.