https://github.com/apify/apify-client-php

Apify API client for PHP—Programmatically run Actors, manage and stream data from storages (datasets, key-value stores, request queues), schedule and monitor runs, and access the full Apify platform API. Sync and async interfaces with automatic retries and pagination.
https://github.com/apify/apify-client-php

Last synced: 14 days ago
JSON representation

Apify API client for PHP—Programmatically run Actors, manage and stream data from storages (datasets, key-value stores, request queues), schedule and monitor runs, and access the full Apify platform API. Sync and async interfaces with automatic retries and pagination.

• Host: GitHub
• URL: https://github.com/apify/apify-client-php
• Owner: apify
• License: apache-2.0
• Created: 2026-07-03T06:44:27.000Z (about 1 month ago)
• Default Branch: master
• Last Pushed: 2026-07-11T19:34:33.000Z (27 days ago)
• Last Synced: 2026-07-11T20:06:48.806Z (27 days ago)
• Language: PHP
• Homepage: https://packagist.org/packages/apify/apify-client
• Size: 136 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Apify API client for PHP

> **Official, but experimental — AI-generated and AI-maintained.** This is an official Apify client,

> but it is experimental: it is generated and maintained by AI. Review the code before relying on it

> in production and report issues on the repository.

A resource-oriented PHP client for the [Apify API](https://docs.apify.com/api/v2), mirroring the

official [JavaScript](https://github.com/apify/apify-client-js) reference client: start from an

`ApifyClient`, then drill down into resources (Actors, runs, datasets, key-value stores, request

queues, tasks, schedules, webhooks, the store, users and logs).

## Requirements

- PHP 8.1 or newer, with the `json`, `mbstring` and `hash` extensions.

## Installation

```bash

composer require apify/apify-client

```

## Quick start

All snippets assume the client types are imported from their namespaces, e.g.

`use Apify\Client\ApifyClient;`.

```php

$client = new ApifyClient('my-api-token');

// Start an Actor and wait for it to finish. The last argument is the wait budget in seconds;

// pass a value (e.g. 120) to bound the wait, or null to wait indefinitely (as here).

$run = $client->actor('apify/hello-world')->call(null, null, null);

// Read items from the run's default dataset. getDefaultDatasetId() is ?string, so cast it

// to satisfy dataset(string $id).

$items = $client->dataset((string) $run->getDefaultDatasetId())->listItems();

echo 'Item count: ' . $items->getCount() . PHP_EOL;

```

`new ApifyClient('my-api-token')` takes the token as an explicit argument — it does **not** read

`APIFY_TOKEN` (or any other environment variable) automatically. Read it yourself if you want that,

e.g. `new ApifyClient(getenv('APIFY_TOKEN'))`.

Get your API token from the

[Apify Console → Settings → API & Integrations](https://console.apify.com/settings/integrations).

## Configuration

The constructor accepts named arguments for non-default settings:

```php

$configured = new ApifyClient(

    token: 'my-api-token',

    baseUrl: 'https://api.apify.com',

    maxRetries: 5,

    minDelayBetweenRetriesMillis: 1000,

    timeoutSecs: 120,

    userAgentSuffix: 'my-app/1.2.3',

);

```

| Argument | Default | Meaning |

|---|---|---|

| `token` | `null` | API token, sent as a Bearer token. |

| `baseUrl` | `https://api.apify.com` | API base URL; the `/v2` suffix is appended automatically. |

| `publicBaseUrl` | `baseUrl` | Base URL used when building public, shareable resource URLs. |

| `maxRetries` | `8` | Maximum retries for failed requests. |

| `minDelayBetweenRetriesMillis` | `500` | Minimum delay between retries (exponential backoff). |

| `maxDelayBetweenRetriesMillis` | `timeoutSecs × 1000` (360000) | Upper bound (milliseconds) on the growing inter-retry delay; defaults to the request timeout expressed in milliseconds. |

| `timeoutSecs` | `360` | Overall per-request timeout. |

| `userAgentSuffix` | `null` | Custom suffix appended to the `User-Agent` header. |

| `httpClient` | Guzzle | The replaceable transport (`Apify\Client\Http\HttpClientInterface`). |

Requests are retried on network errors, HTTP 429 (rate limit) and 5xx responses, with exponential

backoff and jitter. Other 4xx responses are thrown immediately as `ApifyApiException`, with one

exception: a resource-not-found 404 (the API's `record-not-found` / `record-or-token-not-found`

error type) on a single-resource fetch is not thrown — `get()` returns `null` and `delete()` is

treated as a successful no-op (see [Error handling](#error-handling)).

### Replaceable HTTP transport

The transport is the `Apify\Client\Http\HttpClientInterface`. The default is `GuzzleHttpClient`; you

can wrap any [PSR-18](https://www.php-fig.org/psr/psr-18/) client with `Psr18HttpClient`, or provide

your own implementation:

```php

// Use the default Guzzle transport explicitly.

$client = new ApifyClient(token: 'my-api-token', httpClient: new GuzzleHttpClient());

// Or wrap any PSR-18 client (configure its proxy/TLS/timeout on the wrapped client, since

// PSR-18 has no per-request timeout and Psr18HttpClient ignores the client's timeoutSecs).

$psr18 = new \GuzzleHttp\Client(['timeout' => 120]); // any Psr\Http\Message ClientInterface

$client = new ApifyClient(token: 'my-api-token', httpClient: new Psr18HttpClient($psr18));

```

## Error handling

Methods that fetch a single resource return `null` when the resource does not exist (rather than

throwing). Other API failures are thrown as `Apify\Client\Exception\ApifyApiException`:

```php

try {

    $client->actor('does/not-exist')->update(['title' => 'x']);

} catch (ApifyApiException $e) {

    echo $e->getStatusCode() . ' ' . $e->getType() . ': ' . $e->getApiMessage() . PHP_EOL;

}

```

`ApifyApiException` extends `RuntimeException` and exposes:

| Accessor | Returns |

|---|---|

| `getStatusCode(): int` | HTTP status code of the error response. |

| `getType(): ?string` | Machine-readable API error type (e.g. `"record-not-found"`). |

| `getApiMessage(): string` | Raw API error message, without the status/type prefix. |

| `getMessage(): string` | Formatted message (`apify API error (status …, type …): …`), from `Throwable`. |

| `getAttempt(): int` | 1-based number of the request attempt that produced the error. |

| `getHttpMethod(): string` | HTTP method of the failed call (e.g. `"GET"`). |

| `getPath(): string` | Path of the API endpoint (URL excluding origin). |

| `getData(): ?array` | Additional structured error data provided by the API, if any. |

Transport-level failures (network errors, timeouts) are retried internally; only if every retry is

exhausted does the underlying error surface, as an `Apify\Client\Exception\TransportException`

(a `RuntimeException`; `isTimeout()` reports whether a request timed out). In short:

`ApifyApiException` means the server returned an error response (a 4xx/5xx with a body), whereas

`TransportException` means the request never produced a usable response (network failure or timeout)

after all retries. Requests are retried on network errors, HTTP 429 and 5xx.

## Versioning

- `Apify\Client\Version::CLIENT_VERSION` — the semantic version of this library.

- `Apify\Client\Version::API_SPEC_VERSION` — the Apify OpenAPI spec version this client was built

  against.

```php

echo Version::CLIENT_VERSION . ' / ' . Version::API_SPEC_VERSION . PHP_EOL;

```

## Documentation

Full documentation lives in [`docs/`](docs/README.md), organized by resource, with runnable

[examples](docs/examples.md).

## License

[Apache-2.0](LICENSE).