Skip to main content
This page documents an earlier version of the API client. For the latest version, see Upgrade.
The PHP API client follows semantic versioning.

​
Upgrade from version 2 to version 3

The architecture of version 3 of the PHP API client stays the same, but it no longer supports PHP < 7.2. Update your PHP version to benefit from the new features.

​
Upgrade from version 1 to version 2

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. We recommended to use at least PHP 7.1. Please keep in mind while updating:
  • All deprecated methods and features from version 1 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.

​
Upgrade 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, 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. 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.
PHP
<?php
// Before
$client = new \AlgoliaSearch\Client("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// After
$client = \Algolia\AlgoliaSearch\SearchClient::create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// Index instantiation doesn't change
$index = $client->initIndex("ALGOLIA_INDEX_NAME");

​
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:
PHP
<?php
// Before
$client = new \AlgoliaSearch\Client("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
$client->setConnectTimeout(10);
$client->setExtraHeader('NAME-OF-HEADER', 'value-of-header');

// After
$config = \Algolia\AlgoliaSearch\Config\SearchConfig::create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
$config->setConnectTimeout(10);
$config->setDefaultHeaders([ 'headerName' => 'headerValue' ]);

$client = \Algolia\AlgoliaSearch\SearchClient::createWithConfig($config);
Other options you can set in the configuration:
  • forwardToReplicas: set the default value of forwardToReplicas to true.
  • setDefaultForwardToReplicas: 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: 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.
PHP
<?php
use Algolia\AlgoliaSearch\Algolia;

$httpClient = new Algolia\AlgoliaSearch\Http\Php53HttpClient([
    // Pass any CurlOption here
    'CURLOPT_PROXY' => $strProxy,
    'CURLOPT_FOLLOWLOCATION' => 1,
]);

Algolia::setHttpClient($httpClient);

​
Analytics instantiation

Similarly, you need to update the way you initialize the AnalyticsClient.
PHP
<?php
// Before
$client = new \AlgoliaSearch\Client("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
$analytics = $client->initAnalytics();

// After
$analytics = \Algolia\AlgoliaSearch\AnalyticsClient::create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

​
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:
PHP
<?php
// 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.
PHP
<?php
// v1
$client->getLogs(0, 10, $type);

// v2
$client->getLogs([
  'type' => $type,
]);

​
List of method signature changes

BeforeAfter
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: copy settings between indices.
  • copySynonyms: copy synonyms between indices.
  • copyRules: copy rules between indices.
  • replaceAllObjects: add new objects to an index and remove all existing ones, atomically.
  • replaceAllSynonyms: add new synonyms to an index and remove all existing ones, atomically.
  • replaceAllRules: add new rules to an index and remove all existing ones, atomically.
  • AccountClient::copyIndex: copy in an index between Algolia applications. Useful when doing client work.

​
Removed methods

  • All deprecated methods and features from version 1 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:
PHP
<?php
// 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. 
php vendor/bin/algolia-doctor
⌘I