API client / Getting started / Customize

Customize your PHP client

To change individual requests made with an API client, pass individual request options. To change all requests, create a custom configuration. This lets you change timeouts, add HTTP headers, and so on.

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

Use a custom host

You can change the default hosts to which the API client connects:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
require __DIR__ . '/vendor/autoload.php';

use Algolia\AlgoliaSearch\SearchClient;
use Algolia\AlgoliaSearch\Config\SearchConfig;

$config = [
    'appId' => 'YourApplicationID',
    'apiKey' => 'YourWriteAPIKey',
    'hosts' => ['yourapplication.example.net']
];

$client = SearchClient::createWithConfig(
    new SearchConfig($config)
);

$index = $client->initIndex('your_index_name');

Changing the hosts can be useful if you want to proxy the search requests through another server, for example, to process the request or response, or to perform custom analytics.

Add HTTP headers to every request

Adding HTTP headers to your requests lets you set parameters such as a user identifier or an IP address. This can be useful for analytics, geographical search, or applying API key rate limits.

1
2
3
4
5
6
7
8
9
use Algolia\AlgoliaSearch\Config\SearchConfig;
use Algolia\AlgoliaSearch\SearchClient;

$config = SearchConfig::create('YourApplicationID', 'YourWriteAPIKey');
$config->setDefaultHeaders([
  'headerName' => 'headerValue'
]);

$client = SearchClient::createWithConfig($config);

You can add these headers to your requests:

Header Use case
X-Algolia-UserToken Use API key rate limits
X-Algolia-UserToken The Analytics API uses the value of this header to distinguish between users. It takes priority over any value in X-Forwarded-For. Use the X-Algolia-UserToken header to forward the user’s identity without relying on IP addresses.
X-Forwarded-For Use for analytics in backend implementations. If your server sends the user’s IP address with every search, analytics can distinguish between users. Otherwise, the analytics uses the server’s IP address and considers all your users as a single user.
X-Forwarded-For Use for geolocation, when you perform searches from your backend. This ensures that the geolocation for a search uses your user’s IP address and not that of your server.
1
2
3
4
5
$index = $client->initIndex('indexName');

$res = $index->search('query string', [
  'X-Algolia-UserToken' => 'user123'
]);

Make sure to use the same user token for your events (Insights API) and search requests (Search API).

  • If you send the authenticatedUserToken with your events, send the same value with your search requests.
  • If you send the userToken with your events, send the same value with your search requests.

Change timeouts for all requests

Network connections and DNS resolution can be slow. That’s why the API clients come with default timeouts.

1
2
3
4
5
6
$config = SearchConfig::create('YourApplicationID', 'YourWriteAPIKey');
$config->setConnectTimeout(2); // connection timeout in seconds
$config->setReadTimeout(30); // read timeout in seconds
$config->setWriteTimeout(30); // write timeout in seconds

SearchClient::createWithConfig($config);

Don’t change the default timeouts without a good reason.

1
2
3
4
5
6
$index = $client->initIndex('indexName');

$res = $index->search('query string', [
  // Set the readTimeout to 20 seconds
  'readTimeout' => 20
]);

Pass options to the HTTP client

The PHP API client lets you override what HTTP layer will be used by the search client. You can pass custom options to the underlying HTTP client, for example, to configure a proxy. Choose between these two HTTP clients:

  • Guzzle, a popular HTTP client for PHP (recommended)
  • A custom HTTP client built on top of curl

Passing options to the Guzzle HTTP client

You can pass any guzzle option.

1
2
3
4
5
6
7
8
9
10
use Algolia\AlgoliaSearch\Algolia;
use GuzzleHttp\Client as GuzzleClient;

$httpClient = new Algolia\AlgoliaSearch\Http\Guzzle6HttpClient(
  new GuzzleClient([
    'proxy' => $proxyAddress,
  ])
);

Algolia::setHttpClient($httpClient);

Passing options to the default PHP client

You can pass any curl option.

1
2
3
4
5
6
7
8
use Algolia\AlgoliaSearch\Algolia;

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

Algolia::setHttpClient($httpClient);
Did you find this page helpful?