Upgrade guides for the API client

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 upgrade time: 30 minutes.

Please keep in mind while upgrading:

• All deprecated methods and features from v1 have been removed.
• You can’t manage API keys on the Index class. Use the Client 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

1. Download the client from GitHub and unzip it in your project.
2. Inside the client root folder, run ./bin/install-dependencies-without-composer.
3. In your code, require the autoload.php file in the client root folder instead of the algoliasearch.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 relied 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 of forwardToReplicas 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 each getTask 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 each
• 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

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 the Client. 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