Update the PHP API client
This is documentation for v3 of the PHP API clients, which is not the latest version. To see the documentation for the latest version, see PHP v4.
You should keep your PHP API client up to date to benefit from improvements and bug fixes.
The PHP API client follows Semantic Versioning.
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 SearchClient
and 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
Index
class. Use theClient
class 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
In your composer.json
file:
- Update your
algolia/algoliasearch-client-php
dependency to^2.0
- If your PHP version is >= 5.5, require the dependency
guzzlehttp/guzzle: "^6.0"
Projects without Composer
- Download the client from GitHub and unzip it in your project.
- Inside the client root folder, run
./bin/install-dependencies-without-composer
. - In your code, require the
autoload.php
file in the client root folder instead of thealgoliasearch.php
file.
Namespace and class names
The namespace changed from AlgoliaSearch
to Algolia\AlgoliaSearch
, to be more standard.
The main Client
and Index
classes are named SearchClient
and SearchIndex
.
This clarifies which client accesses the Search API and which one access the others (Analytics and Monitoring APIs).
Client instantiation
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 rely on setExtraHeaders
or 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 offorwardToReplicas
to true.setDefaultForwardToReplicas
: allows to change the default value of forwardToReplicas (false
by default)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 eachgetTask
call when waiting
Using curl options
If you were passing curl options to the Client
, pass them to the HttpClient
instead.
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 PlacesClient
.
1
2
3
4
5
// Before
$places = new \AlgoliaSearch\Client::initPlaces($appId, $apiKey);
// After
$places = \Algolia\AlgoliaSearch\PlacesClient::create($appId, $apiKey);
Analytics instantiation
Similarly, you need to update the way you initialize the AnalyticsClient
.
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
- All optional arguments are passed in a
requestOptions
array 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 requestOptions
array.
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.
For example:
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
Before | After |
---|---|
setSettings($settings, true) |
setSettings($settings, ['forwardToReplicas' => true]) |
copyIndex('source', 'dest') |
copyIndex('source', 'dest') |
scopedCopyIndex('source', 'dest', ['settings', 'synonyms']) |
copyIndex('source', 'dest', ['scope' => ['settings', 'synonyms']]) |
batchSynonyms($objects, true, false) |
saveSynonyms($objects, ['forwardToReplicas' => true]) |
batchSynonyms($objects, true, true) |
replaceAllSynonyms($objects, ['forwardToReplicas' => true]) |
batchSynonyms($objects, false, false) |
saveSynonyms($objects) |
batchSynonyms($objects, false, true) |
replaceAllSynonyms($objects) |
saveObjects($objects) |
saveObjects($objects) |
saveObjects($objects, 'id') |
saveObjects($objects, ['objectIDKey' => 'id]) |
addObjects($objectsWithObjectId) |
saveObjects($objectsWithObjectId) |
addObjects($objectsWithoutObjectId) |
saveObjects($objectsWithoutObjectId, ['autoGenerateObjectIDIfNotExist' => 'id]) |
$client->setExtraHeader('header-name', 'header-value') |
$config->setDefaultHeaders(['header-name', 'header-value']) and pass the configuration to the client |
New methods
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.
Removed methods
- 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 theClient
. Add index restrictions to get the same limitations, and delete existing index keys from the Dashboard.
Exceptions
The namespace of the class AlgoliaException
exception has changed:
1
2
3
4
5
// v1
use AlgoliaSearch\AlgoliaException;
// v2
use Algolia\AlgoliaSearch\Exceptions\AlgoliaException;
Doctor
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