> ## 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 Scout Extended

> How to upgrade Algolia Scout Extended from version 3 to version 4 or 5.

To upgrade to the latest version of [Scout Extended](/doc/framework-integration/laravel/getting-started/introduction-to-scout-extended), run:

```sh Command line icon=square-terminal theme={"system"}
composer require "algolia/scout-extended:^5.0"
```

If you're upgrading from version 3, review the breaking changes of both version 4 and version 5.

## Upgrade from version 4 to version 5

Version 5 requires Laravel Scout 11,
which [replaces the `numericFilters` search parameter with `filters`](https://github.com/laravel/scout/pull/839).

Version 5 includes these **breaking changes**:

* **The engine sends the `filters` search parameter instead of `numericFilters`**

  Scout Extended computes `filters` from your `where`, `whereIn`, and `whereNotIn` clauses
  and overwrites any value you pass manually.
  If you combined `with(['filters' => ...])` with `where` clauses,
  move all filter conditions into the builder methods:

  ```php PHP icon=code theme={"system"}
  $articles = Article::search('Star Trek')
      ->where('views', '>', 100)
      ->with(['filters' => 'id:1 OR id:2']) // [!code --]
      ->whereIn('id', [1, 2]) // [!code ++]
      ->get();
  ```

* **`filters()` returns a string instead of an array**

  If you subclass `Algolia\ScoutExtended\Engines\AlgoliaEngine` and override the `filters()` method,
  update it to return a boolean filter expression string,
  such as `views > 100 AND (id=1 OR id=2)`,
  instead of an array.

Version 5 also expands the query builder:
the `where` method now supports the `<`, `<=`, `=`, `!=`, `>=`, and `>` operators,
and the new `whereNotIn` method excludes matching values.
For more information, see [Server-side search](/doc/framework-integration/laravel/searching/server-side-search).

## Upgrade from version 3 to version 4

Version 4 increases the required minimal versions to PHP 8.1, Laravel 10, and Laravel Scout 10.11.6.

Version 4 includes these **breaking changes**:

* **Upgrade the PHP API client to version 4**

  The version 4 client uses a flat API:
  the `SearchIndex` class no longer exists,
  and all index operations take the index name as their first argument directly on the client.
  If you [access the API directly](/doc/framework-integration/laravel/advanced-use-cases/access-api-directly),
  [upgrade your code](/doc/libraries/sdk/upgrade/php).

  The `Algolia::index` facade method now returns the index name as a string
  instead of a `SearchIndex` instance:

  ```php PHP icon=code theme={"system"}
  use Algolia\ScoutExtended\Facades\Algolia;

  $index = Algolia::index(App\Models\Article::class); // [!code --]
  $synonym = $index->getSynonym('a-unique-identifier'); // [!code --]
  $client = Algolia::client(); // [!code ++]
  $indexName = Algolia::index(App\Models\Article::class); // [!code ++]
  $synonym = $client->getSynonym($indexName, 'a-unique-identifier'); // [!code ++]
  ```

* **Search callbacks receive the search client instead of an index**

  The first argument passed to `search` callbacks is now the `SearchClient`.
  Update any callback that used the index object's methods:

  ```php PHP icon=code theme={"system"}
  $articles = Article::search('Star Trek', function ($algolia, $query, $options) {
      return $algolia->search($query, $options); // [!code --]
      return $algolia->searchSingleIndex( // [!code ++]
          (new Article)->searchableAs(), // [!code ++]
          array_merge(['query' => $query], $options), // [!code ++]
      ); // [!code ++]
  })->get();
  ```

* **Record deletion no longer uses `deleteBy` by default**

  Deleting records now uses the `browseObjects` and `deleteObjects` operations,
  so your API key needs the `browse` permission.
  To restore the previous behavior,
  set `use_deprecated_delete_by` to `true` in the `algolia` section of your `config/scout.php` file:

  ```php PHP icon=code theme={"system"}
  'algolia' => [
      'id' => env('ALGOLIA_APP_ID', ''),
      'secret' => env('ALGOLIA_SECRET', ''),
      'use_deprecated_delete_by' => true,
  ],
  ```