Upgrading from 3.4.0 to 4.0.0

The new SearchBundle is now based on our PHP Client v2. In addition to providing you with all the new features our PHP Client v2 has to offer, it has been redesigned to give the most intuitive and easy-to-use experience. For that reason, we tried to make the architecture as clear as possible and we got rid of the Search Engine-agnostic feature. As an example, AlgoliaEngine and IndexManager classes have been merge into one single SearchService class. Also, the Algolia Client is now public. Its methods signatures and return types have however changed from v1 to v2. Please read carefully our PHP Client v2 upgrade guide to get a list of thoses changes.

We attempt to document every possible breaking change. Since some of these breaking changes are in obscure parts of the API Client, only a portion of these changes may affect your application.

Upgrade your algolia/search-bundle dependency from ^3.4 to 4.0.0 in your composer.json file and run composer update algolia/search-bundle algolia/algoliasearch-client-php in your terminal.

Miscellaneous

We strongly encourage you to take a look at the PHP Client v2 upgrade guide to get acquainted with the new features deployed in this version.

Improved DX with our PHP Client v2

Its entire redesign makes it faster and easier to use, but don’t worry about the method signature changes: most of the previous usage stay the same. You will however benefit from its new features, the Algolia Client being now public (it relies on your ALGOLIA_APP_ID and ALGOLIA_API_KEY env variables). For example you have the possibility to copy a whole index, to copy all the rules from an index, to replace all data in one index, creating secured API keys, and more. We also added better Exceptions, made the instantiation of the client easier, and created many more features to help you have the best possible experience with Algolia. Please head over the PHP Client v2 upgrade guide to know more.

Examples:

// Either autowire the SearchClient service...

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class ArticleController extends AbstractController
{
    public function refillAction(SearchClient $client, array $objects)
    {
        // Copy an index
        $client->copyIndex(SRC_INDEX_NAME, DEST_INDEX_NAME);

        // Copy all the rules from an index
        $client->copyRules(SRC_INDEX_NAME, DEST_INDEX_NAME);

        // Replace all objects
        $index = $client->initIndex(DEST_INDEX_NAME);
        $index->replaceAllObjects($objects);
    }
}

// ...Or fetch it directly from the container. Note that however this method is not encouraged.

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class ArticleController extends Controller
{
    public function refillAction(array $objects)
    {
        $client = $this->get('search.client');
        // Copy an index
        $client->copyIndex(SRC_INDEX_NAME, DEST_INDEX_NAME);

        // Copy all the rules from an index
        $client->copyRules(SRC_INDEX_NAME, DEST_INDEX_NAME);

        // Replace all objects
        $index = $client->initIndex(DEST_INDEX_NAME);
        $index->replaceAllObjects($objects);
    }
}

SearchService

IndexManager has been renamed to SearchService. This is the only service you will need to interact with Algolia.

Previously, to get started:

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Algolia\SearchBundle\IndexManagerInterface;

class ExampleController extends Controller
{
    protected $indexManager;

    public function __construct(IndexManagerInterface $indexingManager)
    {
        $this->indexManager = $indexingManager;
    }
}

Now, in 4.0.0 you should update your code to:

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Algolia\SearchBundle\SearchService;

class ExampleController extends Controller
{
    protected $searchService;

    public function __construct(SearchService $searchService)
    {
        $this->searchService = $searchService;
    }
}

List of Method Signature Changes

3.4.0	Breaking Change	4.0.0
`getSearchableEntities(): array<int, string>`	Renamed	`getSearchables(): array<int, string>`
`getFullIndexName($className): string`	Renamed	`searchableAs($className): string`
`index($entities, ObjectManager $objectManager): array<string, int>`	Changed	`index(ObjectManager $objectManager, $searchables, $requestOptions = []): array<int, array<string, \Algolia\AlgoliaSearch\Response\AbstractResponse>>`
`remove($entities, ObjectManager $objectManager): array<string, int>`	Changed	`remove(ObjectManager $objectManager, $searchables, $requestOptions = []): array<int, array<string, \Algolia\AlgoliaSearch\Response\AbstractResponse>>`
`clear($className): boolean`	Changed	`clear($className): \Algolia\AlgoliaSearch\Response\AbstractResponse`
`delete($className): boolean`	Changed	`delete($className): \Algolia\AlgoliaSearch\Response\AbstractResponse`
`search($query, $className, ObjectManager $objectManager, $page = 1, $nbResults = null, array $parameters = []): array<int, object>`	Changed	`search(ObjectManagåer $objectManager, $className, $query = '', $requestOptions = []): array<int, object>`
`rawSearch($query, $className, $page = 1, $nbResults = null, array $parameters = []): array<string, int\|string\|array>`	Changed	`rawSearch($className, $query = '', $requestOptions = []): array<string, int\|string\|array>`
`count($query, $className, array $parameters = []): int`	Changed	`count($className, $query = '', $requestOptions = []): int`

Waitable operations

Methods from the SearchService are now waitable. You can rely on the wait() method to wait for your task to be completely handled by the Engine before moving on, while previously you had to make a separate query with the taskID returned from the operation to achieve the same result.

Examples:

// index objects and wait for the task to finish
$response = $this->searchService->index($entityManager, $objects)->wait();

// clear an index
$response = $this->searchService->clear($className)->wait();

That also means that the return type of those methods has changed. They now all return an Algolia AbstractResponse. Please update your code accordingly.

Add any options to your operations

To have the most consistent, predictable, and future-proof method signature, we followed three rules:

All required parameters have a single argument each
All optional arguments are passed in an array (or RequestOptions object), as the last argument, and is called $requestOptions
The client never sets any default values

So you now have the possibility to pass any optional arguments and options to the engine in the $requestOptions parameter, available in all SearchService methods. You can for example add filters, choose which facets to retrieve, change the number of hits per page, pass new headers, etc.

Here are a few examples:

# v3
$result = $this->indexManager->remove(
    $searchablePosts,
    $this->get('doctrine')->getManager(),
    // you could not pass requestOptions
);

# v4
$result = $this->searchService->remove(
    $this->get('doctrine')->getManager(),
    $searchablePosts,
    // here you can pass any requestOptions, for example 'X-Forwarded-For', 'X-Algolia-UserToken'...
    [
        'X-Forwarded-For' => '0.0.0.0',
    ]
);

# v3
$result = $this->indexManager->search(
    'foo',
    Post::class,
    $this->get('doctrine')->getManager(),
    // the optional page and hitsPerPage parameters were passed separately
    // page argument was starting from 1
    1,
    20,
    'attributesToRetrieve' => [
        'title',
    ],
);

# v4
$result = $this->searchService->search(
    $this->get('doctrine')->getManager(),
    Post::class,
    'foo',
    // all the optional parameters are now sent as once in the $requestOptions
    // be careful as page argument now starts from 0
    [
        'page'                 => 0,
        'hitsPerPage'          => 20,
        'attributesToRetrieve' => [
            'title',
        ],
    ]
);

And also

Better doc blocks to improve the public API and auto-completion.
Better quality tooling, so the bundle is now extra robust and future-proof.

List of changes in fully qualified namespaces

3.4.0	Breaking Change	4.0.0
`Algolia\SearchBundle\Engine\AlgoliaEngine`	Removed	/
`Algolia\SearchBundle\IndexManager`	Renamed	`Algolia\SearchBundle\Services\AlgoliaSearchService`
`Algolia\SearchBundle\IndexManagerInterface`	Renamed	`Algolia\SearchBundle\SearchService`
`Algolia\SearchBundle\Engine\NullEngine`	Changed	`Algolia\SearchBundle\Services\NullSearchService^*`

^*For testing purposes use Algolia\SearchBundle\SearchService by mocking it or extending it and overriding the search.service in your test config (see https://symfony.com/doc/current/configuration.html#configuration-environments). The Algolia\SearchBundle\Services\NullSearchService class is here as an example.

List of classes that became internal

The following classes are now internal and may not respect semantic versioning. Those classes are not meant to be used directly and may be up to changes in minor versions.

Algolia\SearchBundle\Command\SearchClearCommand
Algolia\SearchBundle\Command\SearchImportCommand
Algolia\SearchBundle\Command\SearchSettingsBackupCommand
Algolia\SearchBundle\Command\SearchSettingsCommand
Algolia\SearchBundle\Command\SearchSettingsPushCommand
Algolia\SearchBundle\DependencyInjection\AlgoliaSearchExtension
Algolia\SearchBundle\DependencyInjection\Configuration
Algolia\SearchBundle\EventListener\SearchIndexerSubscriber
Algolia\SearchBundle\SearchableEntity
Algolia\SearchBundle\SettingsManager

List of deleted interfaces and final classes you should use instead

3.4.0	Breaking Change	4.0.0
`Algolia\SearchBundle\Settings\SettingsManagerInterface`	Removed	`Algolia\SearchBundle\Settings\SettingsManager`
`Algolia\SearchBundle\Engine\EngineInterface`	Removed	/

List of updated public services names

3.4.0	Breaking Change	4.0.0
`search.index_manager`	Renamed	`search.service`
`algolia_client` (setup publicly manually, you may not have been using it)	Renamed	`search.client` or `SearchClient` class autowired

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

UPGRADE-4.0.md

UPGRADE-4.0.md

Upgrading from 3.4.0 to 4.0.0

Miscellaneous

Improved DX with our PHP Client v2

SearchService

List of Method Signature Changes

Waitable operations

Add any options to your operations

And also

List of changes in fully qualified namespaces

List of classes that became internal

List of deleted interfaces and final classes you should use instead

List of updated public services names

Files

UPGRADE-4.0.md

Latest commit

History

UPGRADE-4.0.md

File metadata and controls

Upgrading from 3.4.0 to 4.0.0

Miscellaneous

Improved DX with our PHP Client v2

SearchService

List of Method Signature Changes

Waitable operations

Add any options to your operations

And also

List of changes in fully qualified namespaces

List of classes that became internal

List of deleted interfaces and final classes you should use instead

List of updated public services names