> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade the PHP API client to version 3

> Keep your PHP API client up to date to benefit from improvements and bug fixes.

export const Legacy = ({title, href}) => {
  return <Note>

    This page documents an earlier version of the API client.
    For the latest version, see <a href={href}>{title}</a>.

    </Note>;
};

<Legacy title="Upgrade" href="/doc/libraries/sdk/upgrade/php" />

The PHP API client follows [semantic versioning](http://semver.org).

## 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](#client-instantiation) 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 recommend using at least PHP 7.1.

Keep this 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](/doc/libraries/sdk/v1/methods/generate-secured-api-key#param-restrict-indices)
  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](https://www.github.com/algolia/algoliasearch-client-php) 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 icon=code theme={"system"}
<?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("INDEX_NAME");
```

### Instantiate 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 icon=code theme={"system"}
<?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

### Use 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 icon=code theme={"system"}
<?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 icon=code theme={"system"}
<?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`](/doc/libraries/sdk/v1/request-options) 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](#list-of-method-signature-changes).

For example:

```php PHP icon=code theme={"system"}
<?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 icon=code theme={"system"}
<?php
// 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`: 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 icon=code theme={"system"}
<?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.

```sh Command line icon=square-terminal theme={"system"}
php vendor/bin/algolia-doctor
```