CloudConvert PHP SDK

https://github.com/cloudconvert/cloudconvert-php
Admin
The official PHP SDK for the CloudConvert API v2, enabling developers to integrate file conversion...
Tokens:91,954
Snippets:739
Trust Score:8.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### get() example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/jobs-resource.md

Fetches a job by its UUID and prints its status.

```php
$job = $cloudconvert->jobs()->get('cd82535b-0614-4b23-bbba-b24ab0e892f7');
echo $job->getStatus(); // e.g. 'error'
```

--------------------------------

### Example: basic call with cache key

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/signed-url-builder.md

Example from README 'Signed URLs': creates a job with import/convert/export tasks, then generates a signed URL with a cache key.

```php
$job = (new Job())
    ->addTask((new Task('import/url', 'import-my-file'))->set('url', 'https://my.url/file.docx'))
    ->addTask((new Task('convert', 'convert-my-file'))
        ->set('input', 'import-my-file')
        ->set('output_format', 'pdf'))
    ->addTask((new Task('export/url', 'export-my-file'))
        ->set('input', 'convert-my-file'));

$signedUrlBase = 'SIGNED_URL_BASE';
$signingSecret = 'SIGNED_URL_SIGNING_SECRET';
$url = $cloudconvert->signedUrlBuilder()
    ->createFromJob($signedUrlBase, $signingSecret, $job, 'CACHE_KEY');
```

--------------------------------

### Install CloudConvert PHP SDK with Composer

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Install the SDK alongside Guzzle using Composer. The package requires PSR-7, PSR-17, PSR-18, and HTTPlug implementations, so you must also install packages providing psr/http-client-implementation and psr/http-factory-implementation (e.g., Guzzle).

```bash
composer require cloudconvert/cloudconvert-php guzzlehttp/guzzle
```

--------------------------------

### get() with query and error handling

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/jobs-resource.md

Passes an 'include' query parameter and catches a 404 HttpClientException.

```php
try {
    $job = $cloudconvert->jobs()->get($id, ['include' => 'tasks']);
} catch (\CloudConvert\Exceptions\HttpClientException $e) {
    if ($e->getResponseCode() === 404) { /* job not found */ }
}
```

--------------------------------

### users() example: fetch current user

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Calls users()->me() and prints the username.

```php
$user = $cloudconvert->users()->me();
echo $user->getUsername();
```

--------------------------------

### all() usage example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Calls all() with per_page=100 and counts the returned tasks.

```php
$tasks = $cloudconvert->tasks()->all(['per_page' => 100]);
echo count($tasks); // number of tasks returned
```

--------------------------------

### Run unit tests with PHPUnit

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Executes the unit test suite using PHPUnit. Requires vendor/bin/phpunit to be available.

```bash
vendor/bin/phpunit --testsuite unit
```

--------------------------------

### Example: custom hydrator implementation

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/hydrator.md

Shows the required methods to implement HydratorInterface. Each method body is left as a placeholder for custom logic.

```php
class MyHydrator implements \CloudConvert\Hydrator\HydratorInterface
{
    public function hydrateObject($object, $data)            { /* ... */ }
    public function hydrateArray($array, string $objectClass, $data) { /* ... */ }
    public function createObjectByResponse(string $class, ResponseInterface $response) { /* ... */ }
    public function hydrateObjectByResponse($object, ResponseInterface $response) { /* ... */ }
    public function hydrateArrayByResponse($array, string $objectClass, ResponseInterface $response) { /* ... */ }
}
```

--------------------------------

### Basic Task construction example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Creates a Task for importing a file from a URL with the operation 'import/url' and name 'import-my-file'.

```php
$task = new Task('import/url', 'import-my-file');
```

--------------------------------

### jobs() example: create a job

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Builds a Job with an import/url task and a convert task, then creates it via jobs()->create().

```php
$job = (new Job())
    ->addTask((new Task('import/url', 'import-my-file'))->set('url', 'https://my-url'))
    ->addTask((new Task('convert', 'convert-my-file'))
        ->set('input', 'import-my-file')
        ->set('output_format', 'pdf'));

$cloudconvert->jobs()->create($job);
```

--------------------------------

### constructEvent usage example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/webhook-handler.md

Reads the raw request body and CloudConvert-Signature header, then constructs a WebhookEvent.

```php
$signingSecret = '...'; // from your webhook settings
$payload   = @file_get_contents('php://input');
$signature = $_SERVER['HTTP_CLOUDCONVERT_SIGNATURE'];

$webhookEvent = $cloudconvert->webhookHandler()->constructEvent($payload, $signature, $signingSecret);
$job = $webhookEvent->getJob();
```

--------------------------------

### Example: hydrator in action through the facade

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/hydrator.md

Typical usage: get the cached JsonMapperHydrator from the facade, then create a User object from a response and hydrate a JobCollection from another response.

```php
$hydrator = $cloudconvert->getHydrator(); // JsonMapperHydrator, cached

$user = $hydrator->createObjectByResponse(User::class, $response);
$jobs = $hydrator->hydrateArrayByResponse(new JobCollection(), Job::class, $response);
```

--------------------------------

### Get processing start time with getStartedAt()

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Returns the processing start timestamp as ?\DateTimeImmutable, or null while waiting. Hydrated by tasks()->create()/get()/refresh()/wait() or via a parent job.

```php
public function getStartedAt(): ?\DateTimeImmutable
```

--------------------------------

### Example: get task by ID

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Fetches a task using its ID and prints the operation and code. The code may be 'INPUT_TASK_FAILED' on failure.

```php
$task = $cloudconvert->tasks()->get('4c80f1ae-5b3a-43d5-bb58-1a5c4eb4e46b');
echo $task->getOperation();  // e.g. 'export/url'
echo $task->getCode();       // e.g. 'INPUT_TASK_FAILED' on failure
```

--------------------------------

### upload() usage example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/http-transport.md

Example of calling upload() with form values from an import/upload task result. The form URL, file handle, filename, and additional parameters are passed to the transport.

```php
$form  = $uploadTask->getResult()->form;
$response = $transport->upload(
    $form->url,
    fopen('./file.pdf', 'r'),
    'file.pdf',
    (array)$form->parameters ?? []
);
```

--------------------------------

### create() upload task example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Creates an import/upload task and accesses the resulting upload form parameters.

```php
$task = new Task('import/upload', 'upload-test');
$cloudconvert->tasks()->create($task);

// $task->getResult()->form now contains the upload URL + parameters
$form = $task->getResult()->form;
```

--------------------------------

### Example: guard the preconditions

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Wraps the upload call in a try-catch to handle \BadMethodCallException when the task is not an import/upload task or the upload form is not ready.

```php
try {
    $cloudconvert->tasks()->upload($uploadTask, $content, 'file.pdf');
} catch (\BadMethodCallException $e) {
    // Task is not an import/upload task yet, or the upload form is not ready
}
```

--------------------------------

### signedUrlBuilder() example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Creates a signed URL from a job using the provided base URL, signing secret, and cache key.

```php
$url = $cloudconvert->signedUrlBuilder()
    ->createFromJob($signedUrlBase, $signingSecret, $job, 'CACHE_KEY');
```

--------------------------------

### Run integration tests with PHPUnit

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Runs the integration test suite against the Sandbox API by default. Set the CLOUDCONVERT_API_KEY environment variable to use your own account; then whitelist the listed MD5 hashes for Sandbox API.

```bash
vendor/bin/phpunit --testsuite integration
```

--------------------------------

### Basic CloudConvert initialization with API key

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Initializes the SDK with an API key and sandbox mode disabled. This is the basic setup for using the CloudConvert API.

```php
use CloudConvert\CloudConvert;

$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);
```

--------------------------------

### Example: download every export of a finished job

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/http-transport.md

Uses download() to fetch each export URL, detaches the stream to a PHP resource, and copies it to a local file.

```php
foreach ($job->getExportUrls() as $file) {
    $source = $cloudconvert->getHttpTransport()->download($file->url)->detach();
    $dest = fopen('output/' . $file->filename, 'w');
    stream_copy_to_stream($source, $dest);
}
```

--------------------------------

### Example: without cache key and redirect

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/signed-url-builder.md

Generates a signed URL without a cache key, then redirects the client to that URL.

```php
$url = $cloudconvert->signedUrlBuilder()
    ->createFromJob($signedUrlBase, $signingSecret, $job); // no &cache_key=
header('Location: ' . $url);
```

--------------------------------

### get() method signature

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/jobs-resource.md

Retrieves a job by ID. Returns a Job object.

```php
public function get(string $id, $query = null): Job
```

--------------------------------

### get(string $path, array $query = []): ResponseInterface

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/http-transport.md

Issues a GET request with an accept-encoding header of 'application/json' and authenticates. Returns the PSR-7 response.

```APIDOC
## get(string $path, array $query = []): ResponseInterface

### Description
Issues a GET request with an accept-encoding header of 'application/json' and authenticates. Returns the PSR-7 response.

### Method
`get`

### Signature
```php
public function get(string $path, array $query = []): ResponseInterface
```

### Parameters
- **$path** (string) - Required - Full URL (typically `getBaseUri()` + resource path)
- **$query** (array) - Optional - Query parameters; added with `?` + `http_build_query($query)` when non-empty

### Returns
- **ResponseInterface** - The PSR-7 response.

### Throws
- `CloudConvert\Exceptions\Exception` subclasses via `sendRequest()`
- `HttpServerException::networkError()` on client-level transport failures
```

--------------------------------

### Payload after set() example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Shows the payload structure after setting URL and filename options on an import task.

```php
$task = (new Task('import/url', 'import-it'))
    ->set('url', 'https://example.com/a.docx')
    ->set('filename', 'a.docx');
// (array)$task->getPayload() == ['url' => ..., 'filename' => ...]
```

--------------------------------

### Create a CloudConvert Job with PHP SDK

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Create a job with import/url, convert, and export/url tasks. Configure the CloudConvert client with an API key and sandbox flag. Use the Job Builder to see available options for task types.

```php
use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;


$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);


$job = (new Job())
    ->setTag('myjob-1')
    ->addTask(
        (new Task('import/url', 'import-my-file'))
            ->set('url','https://my-url')
    )
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'import-my-file')
            ->set('output_format', 'pdf')
            ->set('some_other_option', 'value')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$cloudconvert->jobs()->create($job)
```

--------------------------------

### constructEventFromRequest usage example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/webhook-handler.md

Uses a framework request object to construct the event, then retrieves the job and a finished export task.

```php
$webhookEvent = $cloudconvert->webhookHandler()
    ->constructEventFromRequest($request, $signingSecret);

$job = $webhookEvent->getJob();
$job->getTag(); // correlate with your internal ID

$exportTask = $job->getTasks()
    ->whereStatus(Task::STATUS_FINISHED)
    ->whereName('export-it')[0];
```

--------------------------------

### Get credits

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/user.md

Returns the remaining conversion credits/minutes as an integer.

```php
public function getCredits(): int
```

--------------------------------

### Find upload task by name and upload file

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/collections.md

Example from the README pattern: retrieves the upload task by name, then uploads a file using that task.

```php
$uploadTask = $job->getTasks()->whereName('upload-my-file')[0];
$cloudconvert->tasks()->upload($uploadTask, fopen('./file.pdf', 'r'), 'file.pdf');
```

--------------------------------

### Example: create and upload a file

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Creates a job with an import/upload task and a convert task, then uploads a file to the upload task. The upload uses the task's pre-signed form URL with no bearer token.

```php
$job = (new Job())
    ->addTask(new Task('import/upload', 'upload-my-file'))
    ->addTask((new Task('convert', 'convert-my-file'))
        ->set('input', 'upload-my-file')
        ->set('output_format', 'pdf'));

$job = $cloudconvert->jobs()->create($job);
$uploadTask = $job->getTasks()->whereName('upload-my-file')[0];

$cloudconvert->tasks()->upload($uploadTask, fopen('./file.pdf', 'r'), 'file.pdf');
```

--------------------------------

### getStartedAt(): ?\DateTimeImmutable

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Returns the processing start timestamp, or null while waiting.

```APIDOC
## getStartedAt(): ?\DateTimeImmutable

### Description
Returns the processing start timestamp, or null while waiting.

### Method
`getStartedAt`

### Signature
```php
public function getStartedAt(): ?\DateTimeImmutable
```

### Returns
- **?\DateTimeImmutable** - Processing start timestamp, or null while waiting.

### Source
`src/Models/Task.php:118`
```

--------------------------------

### me() method signature

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/users-resource.md

Public method that returns a User object. Executes GET /users/me with bearer authentication.

```php
public function me(): User
```

--------------------------------

### webhookHandler() example with error handling

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Constructs a webhook event from payload, signature, and signing secret. Catches UnexpectedDataException for invalid payload and SignatureVerificationException for invalid signature, responding with HTTP 400 and exiting.

```php
try {
    $webhookEvent = $cloudconvert->webhookHandler()
        ->constructEvent($payload, $signature, $signingSecret);
} catch (\CloudConvert\Exceptions\UnexpectedDataException $e) {
    // Invalid payload
    http_response_code(400);
    exit();
} catch (\CloudConvert\Exceptions\SignatureVerificationException $e) {
    // Invalid signature
    http_response_code(400);
    exit();
}
```

--------------------------------

### Download All Exports Example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/job.md

Waits for job completion, then downloads each export file to the output directory. Uses the HTTP transport's download method.

```php
$cloudconvert->jobs()->wait($job); // Wait for job completion

foreach ($job->getExportUrls() as $file) {
    $source = $cloudconvert->getHttpTransport()->download($file->url)->detach();
    $dest = fopen('output/' . $file->filename, 'w');
    stream_copy_to_stream($source, $dest);
}
```

--------------------------------

### Get created_at timestamp

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/user.md

Returns the account creation timestamp as a \DateTimeImmutable object.

```php
public function getCreatedAt(): \DateTimeImmutable
```

--------------------------------

### addTask chained task building example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/job.md

Builds a job with a tag and three chained tasks: import from URL, convert to PDF, and export to URL. Each task is created with its operation, name, and payload, and the tasks are linked via input references.

```php
$job = (new Job())
    ->setTag('myjob-1')
    ->addTask((new Task('import/url', 'import-my-file'))->set('url', 'https://my-url'))
    ->addTask((new Task('convert', 'convert-my-file'))
        ->set('input', 'import-my-file')
        ->set('output_format', 'pdf'))
    ->addTask((new Task('export/url', 'export-my-file'))
        ->set('input', 'convert-my-file'));
```

--------------------------------

### GET /v2/jobs

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/endpoints.md

Lists jobs. Supports optional query parameters for pagination and filtering.

```APIDOC
## GET /v2/jobs

### Description
Lists jobs. Supports optional query parameters for pagination and filtering.

### Method
GET

### Endpoint
/v2/jobs

### Parameters
#### Query Parameters
- **query** (object) - Optional - Query parameters for pagination/filtering, passed through verbatim.

### Response
#### Success Response (200)
- **data** (array of Job) - List of jobs.
- **links** (object) - Pagination links.
- **meta** (object) - Pagination metadata.

#### Response Example
{
  "data": [
    {
      "id": "string",
      "status": "string",
      "created_at": "string",
      "tasks": []
    }
  ],
  "links": {},
  "meta": {}
}

### Error Codes
- **401** - Unauthorized
- **5xx** - Server error
```

--------------------------------

### Download file using raw transport

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Example showing how to reach the raw transport for a file download. Calls getHttpTransport()->download($file->url) and detaches the stream.

```php
$source = $cloudconvert->getHttpTransport()->download($file->url)->detach();
```

--------------------------------

### GET /v2/jobs/{id}

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/endpoints.md

Retrieves a job by ID. Optionally accepts query parameters.

```APIDOC
## GET /v2/jobs/{id}

### Description
Retrieves a job by ID. Optionally accepts query parameters.

### Method
GET

### Endpoint
/v2/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID.

#### Query Parameters
- **query** (object) - Optional - Query parameters passed through verbatim.

### Response
#### Success Response (200)
- **data** (Job) - The job object.

#### Response Example
{
  "data": {
    "id": "string",
    "status": "string",
    "created_at": "string",
    "tasks": []
  }
}

### Error Codes
- **404** - Not found
```

--------------------------------

### Download Output Files with CloudConvert PHP SDK

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Wait for job completion, then download all export URLs. The download() method returns a PSR-7 StreamInterface, which can be used as a PHP resource via detach().

```php
$cloudconvert->jobs()->wait($job); // Wait for job completion

foreach ($job->getExportUrls() as $file) {

    $source = $cloudconvert->getHttpTransport()->download($file->url)->detach();
    $dest = fopen('output/' . $file->filename, 'w');
    
    stream_copy_to_stream($source, $dest);

}
```

--------------------------------

### getPayload() Usage Example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/job.md

Demonstrates calling getPayload() and accessing a specific task's payload. The comment shows the expected structure for a convert task.

```php
$payload = $job->getPayload();
// $payload['tasks']['convert-my-file'] == ['operation' => 'convert', 'input' => ..., 'output_format' => ...]
```

--------------------------------

### Upload a File with CloudConvert PHP SDK

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Create a job with an import/upload task, then upload a file using the tasks()->upload() method. The upload method accepts a string, PHP resource, or PSR-7 StreamInterface as the second parameter.

```php
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;


$job = (new Job())
    ->addTask(new Task('import/upload','upload-my-file'))
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'upload-my-file')
            ->set('output_format', 'pdf')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$job = $cloudconvert->jobs()->create($job);

$uploadTask = $job->getTasks()->whereName('upload-my-file')[0];

$cloudconvert->tasks()->upload($uploadTask, fopen('./file.pdf', 'r'), 'file.pdf');
```

--------------------------------

### GET /v2/tasks

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/endpoints.md

Retrieves a list of tasks. Supports optional query parameters for pagination and filtering.

```APIDOC
## [GET] /v2/tasks

### Description
Retrieves a list of tasks. Supports optional query parameters for pagination and filtering.

### Method
GET

### Endpoint
/v2/tasks

### Parameters
#### Query Parameters
- **query** (object) - Optional - Pagination/filter parameters passed through to the API.

### Response
#### Success Response (200)
- **data** (array of Task) - List of tasks.
- **links** (object) - Pagination links.
- **meta** (object) - Pagination metadata.

#### Response Example
{
  "data": [
    {
      "id": "string",
      "operation": "string",
      "status": "string"
    }
  ],
  "links": {},
  "meta": {}
}

### Authentication
Bearer token required.
```

--------------------------------

### Construct WebhookEvent from PSR-7 request

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Alternative way to construct a WebhookEvent using a PSR-7 RequestInterface instead of raw payload and signature. Requires a signing secret from webhook settings.

```php
$webhookEvent = $cloudconvert->webhookHandler()->constructEventFromRequest($request, $signingSecret);
```

--------------------------------

### constructEvent error handling example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/webhook-handler.md

Catches both failure modes: UnexpectedDataException for invalid payload and SignatureVerificationException for invalid signature, returning HTTP 400.

```php
try {
    $webhookEvent = $cloudconvert->webhookHandler()
        ->constructEvent($payload, $signature, $signingSecret);
} catch (\CloudConvert\Exceptions\UnexpectedDataException $e) {
    http_response_code(400);   // Invalid payload — reject
    exit();
} catch (\CloudConvert\Exceptions\SignatureVerificationException $e) {
    http_response_code(400);   // Invalid signature — reject
    exit();
}
```

--------------------------------

### Filter convert tasks with error handling

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/collections.md

Example showing how to check for the absence of convert tasks and handle the no-match case by inspecting the job status or task codes.

```php
$convertTasks = $job->getTasks()->whereOperation('convert');
if (count($convertTasks) === 0) {
    // job has no convert task — inspect $job->getStatus() / task codes
}
```

--------------------------------

### all($query = null): TaskCollection

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Retrieves a list of tasks from the CloudConvert API. This method corresponds to a GET request to the /tasks endpoint and returns a TaskCollection.

```APIDOC
## all($query = null): TaskCollection

### Description
Retrieves a list of tasks from the CloudConvert API. This method corresponds to a GET request to the /tasks endpoint and returns a TaskCollection.

### Method
GET

### Endpoint
GET {baseUri}/tasks

### Parameters
#### Query Parameters
- **$query** (array|null) - Optional - Query parameters (pagination/filters passed through)

### Returns
TaskCollection

### Example
```php
$tasks = $cloudconvert->tasks()->all(['per_page' => 100]);
echo count($tasks); // number of tasks returned
```
```

--------------------------------

### me(): User

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/users-resource.md

Retrieves the authenticated account information for the configured API key. This method hits the GET /users/me endpoint and returns a User object with account details.

```APIDOC
## [GET] /users/me

### Description
Retrieves the authenticated account information for the configured API key. This method hits the GET /users/me endpoint and returns a User object with account details.

### Method
GET

### Endpoint
{baseUri}/users/me

### Parameters
#### Path Parameters
- **none** - No path parameters required.

#### Query Parameters
- **none** - No query parameters required.

#### Request Body
- **none** - No request body required.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the user.
- **username** (string) - The username of the authenticated account.
- **email** (string) - The email address associated with the account.
- **credits** (number) - The remaining credits for the account.
- **created_at** (string) - The timestamp when the account was created.
- **links** (object) - Related links for the user resource.

#### Response Example
{
  "id": "user-id",
  "username": "johndoe",
  "email": "john@example.com",
  "credits": 100,
  "created_at": "2023-01-01T00:00:00Z",
  "links": {}
}

### Error Handling
- **401 Unauthorized** - Invalid or expired API key.
- **403 Forbidden** - API key lacks permission for this endpoint.
- **404 Not Found** - Resource not found.
- **500 Internal Server Error** - Server error.
- **Network Error** - Network unreachable or unknown status code.
- **Unexpected Data** - Response body cannot be mapped onto User.
```

--------------------------------

### Filter finished jobs with whereStatus()

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/collections.md

Example usage of whereStatus() to retrieve only finished jobs from the jobs collection returned by JobsResource::all().

```php
$finished = $cloudconvert->jobs()->all()->whereStatus(Job::STATUS_FINISHED);
```

--------------------------------

### get method signature

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Retrieves a task by ID, hydrates response data into a Task. Throws HttpClientException on 404, HttpServerException, or UnexpectedDataException.

```php
public function get(string $id, $query = null): Task
```

--------------------------------

### List all jobs with pagination (all method)

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/jobs-resource.md

Retrieves a paginated list of jobs via GET /jobs. The $query parameter accepts pagination options like 'page' and 'per_page'. Returns a JobCollection of Job objects; pagination links/meta are not exposed on the collection.

```php
public function all($query = null): JobCollection
```

```php
$jobs = $cloudconvert->jobs()->all(['per_page' => 25]);
foreach ($jobs as $job) {
    echo $job->getId() . ': ' . $job->getStatus() . "\n";
}
```

--------------------------------

### Chained filters for finished export tasks

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/collections.md

Example showing chained whereStatus() and whereName() filters to find finished export tasks, then accessing the first result's file URL.

```php
$exports = $job->getTasks()
    ->whereStatus(Task::STATUS_FINISHED)
    ->whereName('export-it');

if (count($exports) > 0) {
    echo $exports[0]->getResult()->files[0]->url;
}
```

--------------------------------

### all($query = null): JobCollection

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/jobs-resource.md

Retrieves a list of jobs from the CloudConvert API. This method sends a GET request to the /jobs endpoint and hydrates the response into a JobCollection of Job objects.

```APIDOC
## GET /jobs

### Description
Retrieves a list of jobs from the CloudConvert API. This method sends a GET request to the /jobs endpoint and hydrates the response into a JobCollection of Job objects.

### Method
GET

### Endpoint
{baseUri}/jobs

### Parameters
#### Query Parameters
- `$query` (array|null) - Optional - Query parameters, e.g. pagination (`page`, `per_page`) or filters

### Request Example
```php
$jobs = $cloudconvert->jobs()->all(['per_page' => 25]);
```

### Response
#### Success Response (200)
- `JobCollection` - List of jobs (see collections)

#### Response Example
```php
foreach ($jobs as $job) {
    echo $job->getId() . ': ' . $job->getStatus() . "\n";
}
```
```

--------------------------------

### Get HAL links with getLinks()

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Returns the HAL links object. Hydrated by tasks()->create()/get()/refresh()/wait() or via a parent job.

```php
public function getLinks()
```

--------------------------------

### getStartedAt(): ?\DateTimeImmutable

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/job.md

Returns the processing start timestamp; null while the job is waiting. This getter is read-only and returns null until the job is hydrated.

```APIDOC
## GETTER getStartedAt

### Description
Returns the processing start timestamp; null while the job is waiting.

### Method
Getter

### Signature
```php
public function getStartedAt(): ?\DateTimeImmutable
```

### Source
`src/Models/Job.php:116`

### Return Value
- **?\DateTimeImmutable** - The start timestamp, or null if not started.
```

--------------------------------

### get(string $id, $query = null): Job

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/jobs-resource.md

Retrieves a job by its ID. Sends a GET request to the jobs endpoint and hydrates the response into a new Job object.

```APIDOC
## GET /v2/jobs/{id}

### Description
Retrieves a job by its ID. Sends a GET request to the jobs endpoint and hydrates the response into a new Job object.

### Method
GET

### Endpoint
/v2/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Job ID (UUID returned by the API)

#### Query Parameters
- **query** (array) - Optional - Extra query parameters (e.g., `['include' => 'tasks']`), serialized with `http_build_query`

### Request Example
```php
$job = $cloudconvert->jobs()->get('cd82535b-0614-4b23-bbba-b24ab0e892f7');
```

### Response
#### Success Response (200)
- **data** (object) - Job data, hydrated into a `Job` object

#### Response Example
```json
{
  "data": {
    "id": "cd82535b-0614-4b23-bbba-b24ab0e892f7",
    "status": "error"
  }
}
```

### Error Handling
- **404** - `HttpClientException` with `notFound` if the job does not exist
- **5xx** - `HttpServerException`
- **UnexpectedDataException** - if response data cannot be hydrated
```

--------------------------------

### HTML Form for Direct Client Upload to CloudConvert

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Generate an HTML form that allows clients to upload files directly to CloudConvert. The form action and hidden parameters come from the upload task's result.

```html
<form action="<?=$uploadTask->getResult()->form->url?>"
      method="POST"
      enctype="multipart/form-data">
    <? foreach ((array)$uploadTask->getResult()->form->parameters as $parameter => $value) { ?>
        <input type="hidden" name="<?=$parameter?>" value="<?=$value?>">
    <? } ?>
    <input type="file" name="file">
    <input type="submit">
</form>
```

--------------------------------

### Generate signed URL for on-demand conversion

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Builds a signed URL from a job with import/url, convert, and export/url tasks. Requires a signed URL base and signing secret from the CloudConvert Dashboard. The URL is created with a cache key for on-demand conversion.

```php
$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);

$job = (new Job())
    ->addTask(
        (new Task('import/url', 'import-my-file'))
            ->set('url', 'https://my.url/file.docx')
    )
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'import-my-file')
            ->set('output_format', 'pdf')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$signedUrlBase = 'SIGNED_URL_BASE';
$signingSecret = 'SIGNED_URL_SIGNING_SECRET';
$url = $cloudConvert->signedUrlBuilder()->createFromJob($signedUrlBase, $signingSecret, $job, 'CACHE_KEY');
```

--------------------------------

### get(string $id, $query = null): Task

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Retrieves a task by its ID. This method sends a GET request to the /tasks/{id} endpoint and hydrates the response into a Task object.

```APIDOC
## GET /tasks/{id}

### Description
Retrieves a task by its ID. This method sends a GET request to the /tasks/{id} endpoint and hydrates the response into a Task object.

### Method
GET

### Endpoint
/tasks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Task ID

#### Query Parameters
- **query** (array|null) - Optional - Extra query parameters (null → [])

### Request Example
```php
$task = $cloudconvert->tasks()->get('4c80f1ae-5b3a-43d5-bb58-1a5c4eb4e46b');
```

### Response
#### Success Response (200)
- **data** (object) - Task data

#### Response Example
```json
{
  "data": {
    "id": "4c80f1ae-5b3a-43d5-bb58-1a5c4eb4e46b",
    "operation": "export/url",
    "code": "INPUT_TASK_FAILED"
  }
}
```

### Error Handling
- **404** - notFound (HttpClientException)
- **500** - HttpServerException
- **UnexpectedDataException** - when response data cannot be hydrated
```

--------------------------------

### Handle webhook event with signature verification

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/README.md

Constructs a WebhookEvent from raw PHP input and verifies the signature using the signing secret from webhook settings. Catches UnexpectedDataException for invalid payload and SignatureVerificationException for invalid signature, returning HTTP 400. The job tag can store an ID and tasks can be filtered by status and name.

```php
$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);

$signingSecret = '...'; // You can find it in your webhook settings

$payload = @file_get_contents('php://input');
$signature = $_SERVER['HTTP_CLOUDCONVERT_SIGNATURE'];

try {
    $webhookEvent = $cloudconvert->webhookHandler()->constructEvent($payload, $signature, $signingSecret);
} catch(\CloudConvert\Exceptions\UnexpectedDataException $e) {
    // Invalid payload
    http_response_code(400);
    exit();
} catch(\CloudConvert\Exceptions\SignatureVerificationException $e) {
    // Invalid signature
    http_response_code(400);
    exit();
}

$job = $webhookEvent->getJob();

$job->getTag(); // can be used to store an ID

$exportTask = $job->getTasks()
            ->whereStatus(Task::STATUS_FINISHED) // get the task with 'finished' status ...
            ->whereName('export-it')[0];        // ... and with the name 'export-it'
// ...
```

--------------------------------

### Get creation timestamp with getCreatedAt()

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Returns the creation timestamp as ?\DateTimeImmutable. Hydrated by tasks()->create()/get()/refresh()/wait() or via a parent job.

```php
public function getCreatedAt(): ?\DateTimeImmutable
```

--------------------------------

### Handle validation and credit errors on job creation

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/jobs-resource.md

Catches HttpClientException when creating a job and switches on the error code to handle 'CREDITS_EXCEEDED' (402) or 'INVALID_DATA' (400) cases. This example shows the recommended error-handling pattern for the create method.

```php
try {
    $cloudconvert->jobs()->create($job);
} catch (\CloudConvert\Exceptions\HttpClientException $e) {
    switch ($e->getErrorCode()) {
        case 'CREDITS_EXCEEDED': /* 402 - buy credits */ break;
        case 'INVALID_DATA':     /* 400 - fix payload */  break;
    }
}
```

--------------------------------

### Get email

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/user.md

Returns the account email as a string.

```php
public function getEmail(): string
```

--------------------------------

### setTag usage example

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/job.md

Creates a new Job, sets the tag 'myjob-1', and passes it to the jobs create method. The tag is used to identify the job.

```php
$job = (new Job())->setTag('myjob-1');
$cloudconvert->jobs()->create($job);
```

--------------------------------

### Catch patterns for CloudConvert exceptions

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/exceptions.md

Consumer code example showing how to catch HttpClientException (4xx), HttpServerException (5xx/network), and the base Exception (e.g., UnexpectedDataException) when creating a job. Uses getResponseCode(), getErrorCode(), and getResponseBody() on the client exception.

```php
use CloudConvert\Exceptions\Exception;
use CloudConvert\Exceptions\HttpClientException;
use CloudConvert\Exceptions\HttpServerException;

try {
    $cloudconvert->jobs()->create($job);
} catch (HttpClientException $e) {
    // 4xx: the API rejected the request
    echo $e->getResponseCode() . ' ' . $e->getErrorCode();
    var_dump($e->getResponseBody());
} catch (HttpServerException $e) {
    // 5xx / network unreachable
} catch (Exception $e) {
    // any other CloudConvert failure (e.g. UnexpectedDataException)
}
```

--------------------------------

### Get username

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/user.md

Returns the account username as a string.

```php
public function getUsername(): string
```

--------------------------------

### Get operation name with getOperation()

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Returns the operation as string, e.g. 'convert'. Hydrated by tasks()->create()/get()/refresh()/wait() or via a parent job.

```php
public function getOperation(): string
```

--------------------------------

### Get user ID

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/user.md

Returns the numeric user ID as an integer.

```php
public function getId(): int
```

--------------------------------

### configureOptions option constraints

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Sets required, allowed types, defaults, and defined options for the resolver. Accepted keys are api_key (required string), sandbox (boolean, default false), http_client (optional ClientInterface), and region (optional string). Note that request_factory, uri_factory, and stream_factory are not declared here.

```php
$resolver->setRequired('api_key');
$resolver->setAllowedTypes('api_key', 'string');

$resolver->setDefault('sandbox', false);
$resolver->setAllowedTypes('sandbox', 'boolean');

$resolver->setDefined('http_client');
$resolver->setAllowedTypes('http_client', [ClientInterface::class]);

$resolver->setDefined('region');
$resolver->setAllowedTypes('region', 'string');
```

--------------------------------

### GET /v2/sync/jobs/{id}

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/endpoints.md

Synchronously waits for a job to complete. Blocks until the job is done.

```APIDOC
## GET /v2/sync/jobs/{id}

### Description
Synchronously waits for a job to complete. Blocks until the job is done.

### Method
GET

### Endpoint
/v2/sync/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID.

### Response
#### Success Response (200)
- **data** (Job) - The job in terminal state.

#### Response Example
{
  "data": {
    "id": "string",
    "status": "finished",
    "created_at": "string",
    "tasks": []
  }
}
```

--------------------------------

### Basic call to me()

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/users-resource.md

Retrieves the authenticated user and prints username, email, and credits.

```php
$user = $cloudconvert->users()->me();
echo $user->getUsername() . ' (' . $user->getEmail() . ')';
echo 'Credits: ' . $user->getCredits();
```

--------------------------------

### CloudConvert initialization with sandbox and region

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Initializes the SDK with sandbox mode disabled and a fixed region set to 'us-east'. This follows the README 'Setting a Region' guidance.

```php
$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false,
    'region'  => 'us-east'
]);
```

--------------------------------

### Instantiate CloudConvert with options

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Creates a new CloudConvert SDK instance. The constructor validates options against the keys declared in configureOptions() and lazily builds an HttpTransport and JsonMapperHydrator. Unset required options cause option validation to fail.

```php
use CloudConvert\CloudConvert;

$cloudconvert = new CloudConvert([...]);
```

--------------------------------

### Get HAL links

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/user.md

Returns the HAL links array, e.g., the self link.

```php
public function getLinks(): array
```

--------------------------------

### Build a task chain with set()

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/task.md

Chains set() calls to configure a conversion task, specifying input, output format, and other options.

```php
$task = (new Task('convert', 'convert-my-file'))
    ->set('input', 'import-my-file')
    ->set('output_format', 'pdf')
    ->set('some_other_option', 'value');
```

--------------------------------

### getResponseCode accessor

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/exceptions.md

Returns the HTTP status code of the response, for example 400.

```php
public function getResponseCode(): int
```

--------------------------------

### GET /v2/sync/tasks/{id}

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/endpoints.md

Synchronously waits for a task to reach a terminal state using long-polling.

```APIDOC
## [GET] /v2/sync/tasks/{id}

### Description
Synchronously waits for a task to reach a terminal state using long-polling.

### Method
GET

### Endpoint
/v2/sync/tasks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The task ID.

### Response
#### Success Response (200)
- **data** (object) - The task object with updated status.

#### Response Example
{
  "data": {
    "id": "string",
    "operation": "string",
    "status": "finished"
  }
}

### Authentication
Bearer token required.
```

--------------------------------

### create() method signature

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/tasks-resource.md

Method signature for TasksResource::create(). Accepts a Task instance.

```php
public function create(Task $task): Task
```

--------------------------------

### GET /v2/tasks/{id}

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/endpoints.md

Retrieves a single task by its ID. Supports optional query parameters.

```APIDOC
## [GET] /v2/tasks/{id}

### Description
Retrieves a single task by its ID. Supports optional query parameters.

### Method
GET

### Endpoint
/v2/tasks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The task ID.

#### Query Parameters
- **query** (object) - Optional - Additional query parameters.

### Response
#### Success Response (200)
- **data** (object) - The task object.

#### Response Example
{
  "data": {
    "id": "string",
    "operation": "string",
    "status": "string"
  }
}

### Error Responses
- **404** - Task not found.

### Authentication
Bearer token required.
```

--------------------------------

### Get base URI method signature

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/http-transport.md

Returns the API base URI based on sandbox and region options.

```php
public function getBaseUri(): string
```

--------------------------------

### download() method signature

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/http-transport.md

Signature of the download method in HttpTransport. It issues an unauthenticated GET request and returns a PSR-7 StreamInterface.

```php
public function download(string $url)
```

--------------------------------

### new CloudConvert(array $options = [])

Source: https://github.com/cloudconvert/cloudconvert-php/blob/master/_autodocs/api-reference/cloudconvert.md

Constructor for the CloudConvert SDK entry point. Validates and stores the constructor options, lazily builds an HttpTransport and a JsonMapperHydrator, and exposes factories for the API resource classes, webhook handler, and signed-URL builder.

```APIDOC
## new CloudConvert(array $options = [])

### Description
Constructor for the CloudConvert SDK entry point. Validates and stores the constructor options, lazily builds an HttpTransport and a JsonMapperHydrator, and exposes factories for the API resource classes, webhook handler, and signed-URL builder.

### Method
Constructor

### Signature
```php
public function __construct(array $options = [])
```

### Parameters
- **$options** (array) - Optional - Option map validated against the keys declared in `configureOptions()`. Default: `[]`.

### Throws
None directly; option validation failures are reported by the symfony/options-resolver package.

### Example
```php
use CloudConvert\CloudConvert;

$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);
```

### Example - Sandbox plus fixed region
```php
$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false,
    'region'  => 'us-east'
]);
```
```
Tokens:
Raw