Update the PHP API client
You should keep your PHP API client up to date to benefit from improvements and bug fixes. Algolia’s Service Level Agreement only applies to the latest version of the API client.
We released a new version of the PHP API client in public beta. Read the beta documentation for more information.
We released a new version of the Java API client in public beta. Read the beta documentation for more information.
Upgrade from v2 to v3
The architecture of the v3 of the PHP API client stay the same, but it no longer supports PHP < 7.2. Please update your PHP version to benefit from the new features.
Upgrade from v1 to v2
The design of the latest version of the PHP client is almost the same as the earlier version to make upgrading as smooth as possible.
The names of the client and index classes changed to
SearchIndex with similar method names.
This new version is compatible with the same PHP versions, from 5.3 to the latest. It’s highly recommended to use at least PHP 7.1.
Estimated time: 30 minutes.
Please keep in mind while updating:
- All deprecated methods and features from v1 have been removed.
- You can’t manage API keys on the
Indexclass. Use the
Clientclass instead. You can add index restrictions to get the same limitations. Delete existing keys on the index from the dashboard.
Upgrading the library
Projects with Composer
- Update your
- If your PHP version is >= 5.5, require the dependency
Projects without Composer
- Download the client from GitHub and unzip it in your project.
- Inside the client root folder, run
- In your code, require the
autoload.phpfile in the client root folder instead of the
Namespace and class names
The namespace changed from
Algolia\AlgoliaSearch, to be more standard.
Index classes are named
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");
Instantiating with configuration
You can instantiate all clients with configuration objects. This is useful to change 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 = \Algolia\AlgoliaSearch\Config\SearchConfig::create($appId, $apiKey); $config->setConnectTimeout(10); $config->setDefaultHeaders([ 'headerName' => 'headerValue' ]); $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 change the default value of forwardToReplicas (
setBatchSize: all write operations create batch automatically, you can change the batch size (
setWaitTaskTimeBeforeRetry: allows to set a different interval time before each
getTaskcall when waiting
Using cURL options
If you were passing cURL options to the
Client, pass them to the
You have to do this once, the library uses this
HttpClient for new clients you instantiate.
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’re using Algolia Places, you now need to use the new
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
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 consistent, predictable, and future-proof method signature, the API client follows three rules:
- All required parameters have a single argument each
- All optional arguments are passed in a
requestOptionsarray as the last argument
- The client never sets any default values
Most method names remain the same, just the arguments changed. Typically, optional parameters are now part of the
You should go through all methods you use to check if you’re using optional parameters. You can compare your code to the full list of method signature changes.
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
The new version introduces some new methods. Most of these are helpers for which 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. Useful 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;
Algolia Doctor is a command-line tool that helps you debug your Algolia implementation.
It tests your environment and configuration to display useful information, like libraries to install or
php.ini settings to update.
1 php vendor/bin/algolia-doctor