### Install Composer

Source: https://github.com/opencoconut/coconutphp/blob/master/README.md

Installs Composer, a dependency manager for PHP. This is a prerequisite for installing the Coconut PHP library.

```console
curl -sS https://getcomposer.org/installer | php
```

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

### Create a Video Processing Job

Source: https://github.com/opencoconut/coconutphp/blob/master/README.md

Creates a new job for video processing. This example demonstrates setting input files and defining multiple output formats, including JPG thumbnails, 1080p MP4, and HLS HTTP streaming.

```php
<?php

try {
  $job = $coconut->job->create([
    'input' => [ 'url' => 'https://mysite/path/file.mp4' ],
    'outputs' => [
      'jpg:300x' => [ 'path' => '/image.jpg' ],
      'mp4:1080p' => [ 'path' => '/1080p.mp4' ],
      'httpstream' => [
        'hls' => [ 'path' => 'hls/' ]
      ]
    ]
  ]);

  print_r($job);

} cacth(Exception $e) {
  echo $e->getMessage();
}

?>
```

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

### Install Composer Dependencies

Source: https://github.com/opencoconut/coconutphp/blob/master/README.md

Executes Composer to install the project dependencies, including the Coconut PHP library, after updating composer.json.

```console
php composer.phar install
```

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

### Install Coconut PHP Library via Composer

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Install the Coconut PHP library using Composer by requiring the opencoconut/coconut package.

```bash
curl -sS https://getcomposer.org/installer | php

php composer.phar require opencoconut/coconut:3.*
```

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

### Configure Composer Dependencies

Source: https://github.com/opencoconut/coconutphp/blob/master/README.md

Specifies the Coconut PHP library version to be included in your project's dependencies. Ensure you have Composer installed before running this.

```javascript
{
    "require": {
        "opencoconut/coconut": "3.*"
    }
}
```

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

### `$coconut->job->retrieve($jid)` — Get job status and details

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Fetches the current state of an existing encoding job by its ID. Returns a decoded JSON object with status, progress, output URLs, and error details if applicable. Poll this endpoint or rely on the webhook notification to know when processing is complete.

```APIDOC
## `GET /jobs/{jid}`

### Description
Fetches the current state of an existing encoding job by its ID. Returns a decoded JSON object with status, progress, output URLs, and error details if applicable. Poll this endpoint or rely on the webhook notification to know when processing is complete.

### Method
GET

### Endpoint
`/jobs/{jid}`

### Parameters
#### Path Parameters
- **jid** (string) - Required - The ID of the job to retrieve.

### Response
#### Success Response (200)
- **status** (string) - The current status of the job (e.g., "job.completed", "job.starting", "job.processing", "job.failed").
- **id** (string) - The ID of the job.
- **outputs** (array) - An array of output objects, each with a `key` and `status`.

### Request Example
```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut
Client('k-api-key');

try {
    $job = $coconut->job->retrieve('OolQXaiU86NFki');

    echo $job->status;
    echo $job->id;

    foreach ($job->outputs as $output) {
        echo $output->key . ': ' . $output->status . PHP_EOL;
    }

} catch (Coconut\Error $e) {
    echo 'Error: ' . $e->getMessage();
}
?>
```
```

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

### Create a client instance

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Instantiates the API client with your API key. Optional configuration can be provided for region, endpoint, storage, and notification defaults.

```APIDOC
## `new Coconut\Client($api_key, $config = [])`

### Description
Instantiates the API client. The `$api_key` is required. The optional `$config` array accepts `region`, `endpoint`, `storage`, and `notification` keys to set defaults reused across all jobs created with this client.

### Parameters
#### Path Parameters
- **api_key** (string) - Required - Your Coconut API key.
- **config** (array) - Optional - Configuration options for region, endpoint, storage, and notification.
  - **region** (string) - Optional - Specifies the AWS region to route API requests.
  - **endpoint** (string) - Optional - Allows setting a custom endpoint, useful for local testing.
  - **storage** (array) - Optional - Default storage configuration (e.g., S3).
  - **notification** (array) - Optional - Default webhook notification configuration.

### Request Example
```php
<?php
require_once('vendor/autoload.php');

// Basic client
$coconut = new Coconut\Client('k-api-key');

// Client with a specific AWS region
$coconut = new Coconut\Client('k-api-key', ['region' => 'us-west-2']);

// Client with a custom endpoint
$coconut = new Coconut\Client('k-api-key', ['endpoint' => 'http://localhost:3001/v2']);

// Client with default storage (S3) and webhook notification
$coconut = new Coconut\Client('k-api-key');

$coconut->storage = [
    'service'     => 's3',
    'bucket'      => 'my-video-bucket',
    'region'      => 'us-east-1',
    'path'        => '/encoded/',
    'credentials' => [
        'access_key_id'     => 'AKIAIOSFODNN7EXAMPLE',
        'secret_access_key' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
    ]
];

$coconut->notification = [
    'type' => 'http',
    'url'  => 'https://yoursite/api/coconut/webhook'
];
?>
```
```

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

### Initialize Coconut Client

Source: https://github.com/opencoconut/coconutphp/blob/master/README.md

Initializes the Coconut client with your API key. Optional webhook and storage configurations can be set here for convenience.

```php
<?php

require_once('vendor/autoload.php');

$coconut = new Coconut\Client('k-api-key');

$coconut->notification = [
  'type' => 'http',
  'url' => 'https://yoursite/api/coconut/webhook'
];

$coconut->storage = [
  'service' => 's3',
  'bucket' => 'my-bucket',
  'region' => 'us-east-1',
  'credentials' => [
    'access_key_id' => 'access-key',
    'secret_access_key' => 'secret-key'
  ]
];

?>
```

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

### Create Coconut Client Instance

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Instantiate the Coconut API client with your API key. Optional configuration includes region, endpoint, default storage, and notification settings.

```php
<?php
require_once('vendor/autoload.php');

// Basic client
$coconut = new Coconut
Client('k-api-key');

// Client with a specific AWS region (routes to regional API endpoint)
$coconut = new Coconut
Client('k-api-key', ['region' => 'us-west-2']);
// Resolves endpoint to: https://api-us-west-2.coconut.co/v2

// Client with a custom endpoint (useful for local testing)
$coconut = new Coconut
Client('k-api-key', ['endpoint' => 'http://localhost:3001/v2']);

// Client with default storage (S3) and webhook notification
$coconut = new Coconut
Client('k-api-key');

$coconut->storage = [
    'service'     => 's3',
    'bucket'      => 'my-video-bucket',
    'region'      => 'us-east-1',
    'path'        => '/encoded/',
    'credentials' => [
        'access_key_id'     => 'AKIAIOSFODNN7EXAMPLE',
        'secret_access_key' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
    ]
];

$coconut->notification = [
    'type' => 'http',
    'url'  => 'https://yoursite/api/coconut/webhook'
];
```

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

### Create an encoding job

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Submits a new encoding job to the Coconut API. Requires an input video URL and an outputs map defining desired formats and paths. Client-level storage and notification settings are automatically applied.

```APIDOC
## `$coconut->job->create($data)`

### Description
Submits a new encoding job to the Coconut API (`POST /jobs`). The `$data` array must include an `input` (with the source video URL) and an `outputs` map defining the desired formats and paths. If `storage` and `notification` are set on the client, they are automatically merged into the request. Returns a decoded JSON object with job details including `status`.

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **input** (array) - Required - Contains the source video URL.
  - **url** (string) - Required - The URL of the source video.
- **outputs** (object) - Required - A map defining the desired video formats and paths.
  - **[format:quality]** (object) - Example: `jpg:300x`, `mp4:1080p`, `httpstream`.
    - **path** (string) - Required - The destination path for the output file or stream.
    - **hls** (object) - Required for `httpstream` output type.
      - **path** (string) - Required - The destination path for the HLS package.

### Request Example
```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut\Client('k-api-key');

$coconut->storage = [
    'service'     => 's3',
    'bucket'      => 'my-video-bucket',
    'region'      => 'us-east-1',
    'credentials' => [
        'access_key_id'     => 'AKIAIOSFODNN7EXAMPLE',
        'secret_access_key' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
    ]
];

$coconut->notification = [
    'type' => 'http',
    'url'  => 'https://yoursite/api/coconut/webhook'
];

try {
    $job = $coconut->job->create([
        'input'   => ['url' => 'https://mysite/videos/source.mp4'],
        'outputs' => [
            // JPEG thumbnail at 300px wide
            'jpg:300x'   => ['path' => '/thumbs/image.jpg'],
            // MP4 at 1080p
            'mp4:1080p'  => ['path' => '/encoded/1080p.mp4'],
            // MP4 at 720p
            'mp4:720p'   => ['path' => '/encoded/720p.mp4'],
            // HLS adaptive streaming package
            'httpstream' => [
                'hls' => ['path' => '/encoded/hls/']
            ]
        ]
    ]);

    echo $job->status;    // "job.starting"
    echo $job->id;        // e.g. "OolQXaiU86NFki"

} catch (Coconut\Error $e) {
    // Coconut API-level errors (HTTP 400, 401)
    echo 'Coconut error: ' . $e->getMessage();
    // e.g. "The job 'input' is not a valid object. (input_not_valid)"
} catch (Exception $e) {
    // Network / unexpected errors
    echo 'Error: ' . $e->getMessage();
}
?>
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the job (e.g., "job.starting").
- **id** (string) - The unique identifier for the job.

#### Response Example
```json
{
  "status": "job.starting",
  "id": "OolQXaiU86NFki"
}
```

### Error Handling
- **Coconut\Error**: Catches API-level errors (HTTP 400, 401).
- **Exception**: Catches network or other unexpected errors.
```

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

### `$coconut->metadata->retrieve($jid)` — Retrieve job metadata

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Fetches technical metadata for the source video associated with a job. Returns detailed information about the input file such as codec, resolution, duration, bitrate, and frame rate. This is useful for inspecting source media before or after encoding.

```APIDOC
## `GET /metadata/jobs/{jid}`

### Description
Fetches technical metadata for the source video associated with a job. Returns detailed information about the input file such as codec, resolution, duration, bitrate, and frame rate. This is useful for inspecting source media before or after encoding.

### Method
GET

### Endpoint
`/metadata/jobs/{jid}`

### Parameters
#### Path Parameters
- **jid** (string) - Required - The ID of the job for which to retrieve metadata.

### Response
#### Success Response (200)
- **input.video** (object) - Contains video details like `codec`, `width`, `height`, `duration`, `bitrate`.
- **input.audio** (object) - Contains audio details like `codec`, `sample_rate`.

### Request Example
```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut
Client('k-api-key');

try {
    $metadata = $coconut->metadata->retrieve('OolQXaiU86NFki');

    $video = $metadata->input->video;
    echo $video->codec;
    echo $video->width;
    echo $video->height;
    echo $video->duration;
    echo $video->bitrate;

    $audio = $metadata->input->audio;
    echo $audio->codec;
    echo $audio->sample_rate;

} catch (Coconut\Error $e) {
    echo 'Error: ' . $e->getMessage();
}
?>
```
```

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

### Retrieve Job Metadata with CoconutPHP

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Fetches technical metadata for the source video associated with a job. Useful for inspecting input media details before or after encoding.

```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut\Client('k-api-key');

try {
    $metadata = $coconut->metadata->retrieve('OolQXaiU86NFki');

    // Source video details
    $video = $metadata->input->video;
    echo $video->codec;      // e.g. "h264"
    echo $video->width;      // e.g. 1920
    echo $video->height;     // e.g. 1080
    echo $video->duration;   // e.g. 120.5 (seconds)
    echo $video->bitrate;    // e.g. 4500 (kbps)

    $audio = $metadata->input->audio;
    echo $audio->codec;      // e.g. "aac"
    echo $audio->sample_rate; // e.g. 44100

} catch (Coconut\Error $e) {
    echo 'Error: ' . $e->getMessage();
}

```

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

### Retrieve Metadata

Source: https://github.com/opencoconut/coconutphp/blob/master/README.md

Fetches metadata associated with a specific video processing job. This can include information about the original file and the processing steps.

```php
$metadata = $coconut->metadata->retrieve('OolQXaiU86NFki');
```

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

### Create an Encoding Job

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Submit a new encoding job to the Coconut API. Define input source and desired outputs. Client-level storage and notification settings are automatically applied.

```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut
Client('k-api-key');

$coconut->storage = [
    'service'     => 's3',
    'bucket'      => 'my-video-bucket',
    'region'      => 'us-east-1',
    'credentials' => [
        'access_key_id'     => 'AKIAIOSFODNN7EXAMPLE',
        'secret_access_key' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
    ]
];

$coconut->notification = [
    'type' => 'http',
    'url'  => 'https://yoursite/api/coconut/webhook'
];

try {
    $job = $coconut->job->create([
        'input'   => ['url' => 'https://mysite/videos/source.mp4'],
        'outputs' => [
            // JPEG thumbnail at 300px wide
            'jpg:300x'   => ['path' => '/thumbs/image.jpg'],
            // MP4 at 1080p
            'mp4:1080p'  => ['path' => '/encoded/1080p.mp4'],
            // MP4 at 720p
            'mp4:720p'   => ['path' => '/encoded/720p.mp4'],
            // HLS adaptive streaming package
            'httpstream' => [
                'hls' => ['path' => '/encoded/hls/']
            ]
        ]
    ]);

    echo $job->status;    // "job.starting"
    echo $job->id;        // e.g. "OolQXaiU86NFki"

} catch (Coconut
Error $e) {
    // Coconut API-level errors (HTTP 400, 401)
    echo 'Coconut error: ' . $e->getMessage();
    // e.g. "The job 'input' is not a valid object. (input_not_valid)"
} catch (Exception $e) {
    // Network / unexpected errors
    echo 'Error: ' . $e->getMessage();
}
```

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

### Configure CoconutPHP Client Endpoints

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Manages the base API URL for requests. Supports default, regional, and custom endpoints for lower latency or local development.

```php
<?php
require_once('vendor/autoload.php');

// Default endpoint
$c1 = new Coconut\Client('k-api-key');
echo $c1->getEndpoint(); // https://api.coconut.co/v2

// Regional endpoint
$c2 = new Coconut\Client('k-api-key', ['region' => 'eu-west-1']);
echo $c2->getEndpoint(); // https://api-eu-west-1.coconut.co/v2

// Custom / local endpoint (e.g., integration testing with a mock server)
$c3 = new Coconut\Client('k-api-key', ['endpoint' => 'http://localhost:3001/v2']);
echo $c3->getEndpoint(); // http://localhost:3001/v2

```

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

### Retrieve Job Information

Source: https://github.com/opencoconut/coconutphp/blob/master/README.md

Retrieves detailed information about a specific video processing job using its unique ID. This is useful for checking job status and results.

```php
$job = $coconut->job->retrieve('OolQXaiU86NFki');
```

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

### Retrieve Job Status and Details with CoconutPHP

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Fetches the current state and details of an encoding job using its ID. Poll this endpoint or use webhooks for completion notifications.

```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut\Client('k-api-key');

try {
    $job = $coconut->job->retrieve('OolQXaiU86NFki');

    echo $job->status;   // "job.completed" | "job.starting" | "job.processing" | "job.failed"
    echo $job->id;       // "OolQXaiU86NFki"

    // Inspect individual outputs
    foreach ($job->outputs as $output) {
        echo $output->key . ': ' . $output->status . PHP_EOL;
    }

} catch (Coconut\Error $e) {
    echo 'Error: ' . $e->getMessage();
}

```

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

### `Client::getEndpoint()` — Regional and custom endpoint resolution

Source: https://context7.com/opencoconut/coconutphp/llms.txt

The `getEndpoint()` method determines the base API URL used for all requests. By default it points to `https://api.coconut.co/v2`. Setting a `region` on the client routes traffic to a regional endpoint for lower latency; setting an explicit `endpoint` overrides everything, which is useful for local development or self-hosted environments.

```APIDOC
## `Client::getEndpoint()`

### Description
Determines the base API URL used for all requests. By default it points to `https://api.coconut.co/v2`. Setting a `region` on the client routes traffic to a regional endpoint for lower latency; setting an explicit `endpoint` overrides everything, which is useful for local development or self-hosted environments.

### Usage
```php
<?php
require_once('vendor/autoload.php');

// Default endpoint
$c1 = new Coconut
Client('k-api-key');
echo $c1->getEndpoint(); // https://api.coconut.co/v2

// Regional endpoint
$c2 = new Coconut
Client('k-api-key', ['region' => 'eu-west-1']);
echo $c2->getEndpoint(); // https://api-eu-west-1.coconut.co/v2

// Custom / local endpoint (e.g., integration testing with a mock server)
$c3 = new Coconut
Client('k-api-key', ['endpoint' => 'http://localhost:3001/v2']);
echo $c3->getEndpoint(); // http://localhost:3001/v2
?>
```
```

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

### `Coconut\Error` — Exception handling

Source: https://context7.com/opencoconut/coconutphp/llms.txt

All API-level errors (HTTP 400 and 401 responses from Coconut, or cURL transport failures) throw a `Coconut\Error` exception, which extends PHP's base `Exception`. The message includes a human-readable description and a machine-readable error code in parentheses.

```APIDOC
## `Coconut\Error`

### Description
All API-level errors (HTTP 400 and 401 responses from Coconut, or cURL transport failures) throw a `Coconut\Error` exception, which extends PHP's base `Exception`. The message includes a human-readable description and a machine-readable error code in parentheses.

### Usage
```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut
Client('k-invalid-key');

try {
    $job = $coconut->job->create([
        'input'   => ['url' => 'https://mysite/videos/source.mp4'],
        'outputs' => ['mp4' => ['path' => '/out/video.mp4']]
    ]);

} catch (Coconut\Error $e) {
    // Structured error from the Coconut API
    // Message format: "<description> (<error_code>)"
    echo $e->getMessage();
    // e.g. "Invalid API key. (api_key_not_valid)"
    // e.g. "The job 'input' is not a valid object. (input_not_valid)"
    // e.g. "Server returned HTTP status 500 (server_error)"
    // e.g. "A Curl Error occured (request_error)"

    // Use error_code suffix for programmatic handling:
    if (str_contains($e->getMessage(), 'api_key_not_valid')) {
        // Prompt user to check their API key
    }
}
?>
```
```

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

### Handle CoconutAPI Errors with CoconutPHP

Source: https://context7.com/opencoconut/coconutphp/llms.txt

Catches API-level errors (HTTP 400/401, cURL failures) thrown as Coconut\Error exceptions. The message includes a description and a machine-readable error code.

```php
<?php
require_once('vendor/autoload.php');

$coconut = new Coconut\Client('k-invalid-key');

try {
    $job = $coconut->job->create([
        'input'   => ['url' => 'https://mysite/videos/source.mp4'],
        'outputs' => ['mp4' => ['path' => '/out/video.mp4']]
    ]);

} catch (Coconut\Error $e) {
    // Structured error from the Coconut API
    // Message format: "<description> (<error_code>)"
    echo $e->getMessage();
    // e.g. "Invalid API key. (api_key_not_valid)"
    // e.g. "The job 'input' is not a valid object. (input_not_valid)"
    // e.g. "Server returned HTTP status 500 (server_error)"
    // e.g. "A Curl Error occured (request_error)"

    // Use error_code suffix for programmatic handling:
    if (str_contains($e->getMessage(), 'api_key_not_valid')) {
        // Prompt user to check their API key
    }
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.