Upgrade guides for the API client
Upgrade from v1
We entirely rewrote The PHP client but we chose to keep a similar design to make it as easy as possible to upgrade.
There is still a client and an index classes but they have been renamed to
SearchIndex with similar method names.
This new version is compatible with the same PHP versions, from 5.3 to the latest. Note that we highly recommend to use at least PHP 7.1.
Estimated upgrade time: 30 minutes.
- All deprecated methods and features from v1 have been removed.
- Api keys cannot be managed on the Index but only on the Client. Add index restriction to get the same limitations. Delete existing keys on index from the Dashboard.
Upgrading the Library
- Update your
- If your PHP version is >= 5.5, require the dependency
- Download the client from GitHub and unzip it in your project
- Inside the client root folder, execute
- In your code, require the
autoload.phpfile in the client root folder instead of the
Namespace and Class Names
The namespace was changed from
Algolia\AlgoliaSearch, to be more standard.
Index classes were renamed
This clarifies which client accesses the Search API and which one access the others (Analytics and Monitoring APIs).
Replace the instantiation of the client as shown below.
1 2 3 4 5 6 7 8 // Before $client = new \AlgoliaSearch\Client($appId, $apiKey); // After $client = \Algolia\AlgoliaSearch\SearchClient::create($appId, $apiKey); // Index instantiation doesn't change $index = $client->initIndex("indexName");
All clients can be instantiated via configuration objects. This is useful to affect the way a client behaves. All setters have been removed. If, for instance, you relied on
setConnectTimeout, you need to change your code to use a configuration object.
1 2 3 4 5 6 7 8 9 10 11 // Before $client = new \AlgoliaSearch\Client($appId, $apiKey); $client->setConnectTimeout(10); $client->setExtraHeader('NAME-OF-HEADER', 'value-of-header'); // After $config = new \Algolia\AlgoliaSearch\Config\SearchConfig(); $config->setConnectTimeout(10); $config->setDefaultHeaders(['NAME-OF-HEADER', 'value-of-header']); $client = \Algolia\AlgoliaSearch\SearchClient::createWithConfig($config);
Here is some other options that you can set in the configuration:
forwardToReplicas: Allows to set the default value of
setDefaultForwardToReplicas: Allows to modify the default value of forwardToReplicas (
setBatchSize: All write operations create batch automatically, you can change the batch size (1000 by default)
setWaitTaskTimeBeforeRetry: Allows to set a different interval time before each getTask call when waiting
If you were passing curl options in the Client, you you’ll have to pass these options, to the HttpClient. This is done only once and will be used for all new client instantiated.
1 2 3 4 5 6 7 8 9 use Algolia\AlgoliaSearch\Algolia; $httpClient = new Algolia\AlgoliaSearch\Http\Php53HttpClient([ // Pass any CurlOption here 'CURLOPT_PROXY' => $strProxy, 'CURLOPT_FOLLOWLOCATION' => 1, ]); Algolia::setHttpClient($httpClient);
Places Index Instantiation
If you were using Places, you now need to use the new Places client.
1 2 3 4 5 // Before $places = new \AlgoliaSearch\Client::initPlaces($appId, $apiKey); // After $places = \Algolia\AlgoliaSearch\PlacesClient::create($appId, $apiKey);
Similarly, you need to update the way you initialize the Analytics client.
1 2 3 4 5 6 // Before $client = new \AlgoliaSearch\Client($appId, $apiKey); $analytics = $client->initAnalytics(); // After $analytics = \Algolia\AlgoliaSearch\AnalyticsClient::create($appId, $apiKey);
Optional Methods Parameters
To have the most consistant, predictable and future-proof method signature, we’re following three rules:
- All required parameters have a single argument each
- All optional arguments are passed in an array, as the last argument, and is called
- The client never sets any default values
Most method names remain the same, only the arguments changed. Typically, optional parameters were removed and passed in the
We recommend to go through all methods and check if you are using optional parameters. The full list of changes is available here.
Here are a few examples:
1 2 3 4 5 6 7 8 9 // v1 $client->getLogs($offset, $length, $type); // v2 $client->getLogs([ 'offset' => $offset, 'length' => $length, 'type' => $type, ]);
This lets you use the default values without having to pass them explicitly.
1 2 3 4 5 6 7 // v1 $client->getLogs(0, 10, $type); // v2 $client->getLogs([ 'type' => $type, ]);
List of Method Signature Changes
Some new methods were added, most of them are helpers as the feature was already available but required either deeper understanding or more custom code.
copySettings: Allows you to copy settings between indices.
copySynonyms: Allows you to copy synonyms between indices.
copyRules: Allows you to copy rules between indices.
replaceAllObjects: Allows you to add new objects to an index and remove all existing ones, atomically.
replaceAllSynonyms: Allows you to add new synonyms to an index and remove all existing ones, atomically.
replaceAllRules: Allows you to add new rules to an index and remove all existing ones, atomically.
AccountClient::copyIndex: Allows to copy in an index between Algolia applications. Very handy when doing client work.
- All deprecated methods and features from v1 have been removed. Most of the time, the feature is still available and was only renamed.
- API keys can’t be managed on the
Index, only on the
Client. Add index restrictions to get the same limitations, and delete existing index keys from the Dashboard.
The namespace of the class
AlgoliaException exception has changed:
1 2 3 4 5 // v1 use AlgoliaSearch\AlgoliaException; // v2 use Algolia\AlgoliaSearch\Exceptions\AlgoliaException;
We introduced a new command line tool to help you debug your Algolia implementation. It will test your environment and configuration to display useful information like installing other libraries or updating some PHP ini settings.
1 php vendor/bin/algolia-doctor