> ## Documentation Index
> Fetch the complete documentation index at: https://www.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.

## Responses you can wait for

`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()` doesn't take any 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 responses you can wait for behave as expected.