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 SearchClient and 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.

Notes

• 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

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"

Without Composer

1. Download the client from GitHub and unzip it in your project
2. Inside the client root folder, execute ./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 was changed from AlgoliaSearch to Algolia\AlgoliaSearch, to be more standard.

The main Client and Index classes were renamed 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");

Using configuration

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 setExtraHeaders or setConnectTimeout, you need to change your code to use a configuration object.

Example:

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(['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 forwardToReplicas to true.
• setDefaultForwardToReplicas: Allows to modify 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

Curl options

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);

Analytics Instantiation

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 requestOptions
• 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 requestOptions array.

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

New methods

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.

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

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