Cloudinary PHP SDK

https://github.com/cloudinary/cloudinary_php
Admin
The Cloudinary PHP SDK allows for quick and easy integration with Cloudinary, enabling optimization,...
Tokens:98,177
Snippets:632
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Logging Example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Logging.md

Example of configuring logging in the Cloudinary SDK and accessing the test handler.

```APIDOC
## Logging Example

### Description
Example of configuring logging in the Cloudinary SDK and accessing the test handler.

### Example
```php
use Cloudinary\Cloudinary;

$cloudinary = new Cloudinary([
    'cloud' => ['cloud_name' => 'demo'],
    'logging' => [
        'enabled'   => true,
        'level'     => 'info',
        'error_log' => true,
        'file'      => [
            ['path' => '/var/log/cloudinary.log', 'level' => 'debug'],
        ],
    ],
]);

$cloudinary->uploadApi()->upload('a.jpg');
// captured at debug level: "Making async POST request" / "Response received for async request"
// failures logged at critical: "Request to Cloudinary server returned an error"
```

### Test handler access
```php
use Cloudinary\Configuration\LoggingConfig;
use Cloudinary\Log\LoggerDecorator;

$config = LoggingConfig::fromJson(['test' => ['level' => 'debug']]);
$decorator = new LoggerDecorator($config);
$testHandler = $decorator->getTestHandler();
// $testHandler->hasRecords(...) — Monolog TestHandler API
```
```

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

### Create archive and private download URL examples

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/UploadApi.md

Examples of creating a zip archive from public IDs and generating a private download URL for a raw resource.

```php
$archive = $cloudinary->uploadApi()->createArchive([
    'public_ids' => ['a.jpg', 'b.jpg'],
    'target_format' => 'zip',
]);

$url = $cloudinary->uploadApi()->privateDownloadUrl('secret_doc', 'pdf', ['resource_type' => 'raw']);
```

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

### Ping and usage example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Example usage of the AdminApi client to ping the API and retrieve cloud usage information, printing the credits usage.

```php
$cloudinary->adminApi()->ping();
$usage = $cloudinary->adminApi()->usage();
echo $usage['usage'][0]['credits_usage'];
```

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

### Text rendering example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/UploadApi.md

Example of using the text method to render 'Hello world' with Arial font, size 40, and a public ID of 'hello_world_text'.

```php
$theText = $cloudinary->uploadApi()->text('Hello world', [
    'font_family' => 'Arial',
    'font_size'   => 40,
    'public_id'   => 'hello_world_text',
]);
```

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

### AuthToken usage example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Assets.md

Example of configuring AuthToken with a key and duration, then signing a URL. The token is appended as a __cld_token__ query parameter.

```php
use Cloudinary\Configuration\Configuration;

$config = Configuration::instance(['auth_token' => ['key' => 'my_key', 'duration' => 300]]);
$cloudinary->image('private.jpg')->setUrlConfig('sign_url', true);
// auth token gets appended as __cld_token__=... query parameter
```

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

### EditTrait usage examples

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/UploadApi.md

Example calls for destroy, rename, and updateMetadata using the UploadApi instance.

```php
$cloudinary->uploadApi()->destroy('vacation/beach', ['invalidate' => true]);
$cloudinary->uploadApi()->rename('old_id', 'new_id');
$cloudinary->uploadApi()->updateMetadata(['color' => 'blue'], ['asset_1', 'asset_2']);
```

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

### GET /v1_1/<cloud>/config

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

Get cloud configuration.

```APIDOC
## [GET] /v1_1/<cloud>/config

### Description
Get cloud configuration.

### Method
GET

### Endpoint
/v1_1/<cloud>/config

### Parameters
#### Path Parameters
- **cloud** (string) - Required - Cloud name.

### Response
#### Success Response (200)
- **config** (object) - Cloud configuration details.

#### Response Example
{
  "config": {}
}
```

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

### TagTrait usage examples

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/UploadApi.md

Example calls for addTag and removeAllTags using the UploadApi instance.

```php
$cloudinary->uploadApi()->addTag('featured', ['public_a', 'public_b']);
$cloudinary->uploadApi()->removeAllTags(['public_a']);
```

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

### ImageTag resize example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Tags.md

Example of generating an image tag with a fill resize transformation. The output is shown in the comment.

```php
echo $cloudinary->imageTag('sample')->resize(Resize::fill(100, 100));
// <img src="https://res.cloudinary.com/my_cloud/image/upload/c_fill,h_100,w_100/sample">
```

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

### Create video asset

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Cloudinary.md

Example of creating a video asset using the video() method.

```php
$video = $cloudinary->video('dog.mp4');
```

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

### Add context example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/UploadApi.md

Example of adding context metadata to a public ID using the addContext method.

```php
$cloudinary->uploadApi()->addContext(['alt' => 'beach at sunset'], 'vacation/beach');
```

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

### Creating Configuration from Cloudinary URL

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Example of creating a Configuration from a Cloudinary URL with credentials and a secure flag.

```php
$config = Configuration::fromCloudinaryUrl(
    'cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyz@my_cloud?secure=true'
);
```

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

### BaseAsset (abstract)

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Assets.md

Documentation for the BaseAsset abstract class, including its constructor, methods, and usage example.

```APIDOC
## BaseAsset (abstract)

### Description
BaseAsset is an abstract class that composes traits for asset descriptor, configuration, delivery type, logging, and finalization. It provides methods to build Cloudinary delivery URLs and is the foundation for the HTML tags.

### Constructor

```php
public function __construct(mixed $source, mixed $configuration = null)
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `$source` | `mixed` | yes | — | Public ID string, `AssetDescriptor`, or another asset instance (copy/convert constructor). |
| `$configuration` | `mixed` | no | `null` | Falls back to the `Configuration` singleton. |

### Methods

```php
public function getPublicId(bool $omitExtension = false): string
public function setPublicId(string $publicId): static
public function toUrl(): UriInterface
public function __toString(): string
public function jsonSerialize(bool $includeEmptyKeys = false, bool $includeEmptySections = false): array

public function configuration(Configuration|array $configuration): static
public function importConfiguration(Configuration|array $configuration): static
public function importJson(array|string $json): static
public function importString(string $string): static   // throws BadMethodCallException('Not Implemented')

public function setAssetProperty(string $propertyName, mixed $propertyValue): static
public function setCloudConfig(string $configKey, mixed $configValue): static
public function setUrlConfig(string $configKey, mixed $configValue): static

public static function getSuffixSupportedDeliveryTypes(): array
public static function fromString(string $string): static  // throws BadMethodCallException('Not Implemented')
public static function fromJson(array|string $json): static // throws BadMethodCallException('Not Implemented')
public static function fromParams(string $source, array $params): static

public function deepCopy(BaseAsset $other): void
```

- `toUrl()` returns `Psr\Http\Message\UriInterface`; `__toString()` casts it and triggers an `E_USER_ERROR` on failure.
- `fromParams()` applies legacy "v1" defaults: `secure` enabled and `analytics` disabled unless explicitly set, then creates the asset and imports the params.
- `importString()`/`fromString()`/`fromJson()` (on BaseAsset) are intentionally unimplemented stubs that throw `BadMethodCallException('Not Implemented')`.

### Example

```php
use Cloudinary\Asset\Image;

$img = Image::fromParams('sample.jpg', ['width' => 100]);
echo $img->toUrl();
```
```

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

### List assets with Admin API

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Cloudinary.md

Example of using the Admin API to list assets and print their public IDs.

```php
$response = $cloudinary->adminApi()->assets(['max_results' => 10]);
foreach ($response as $asset) {
    echo $asset['public_id'] . PHP_EOL;
}
```

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

### Create Cloudinary instance and generate image URL

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Cloudinary.md

Example of creating a Cloudinary instance and generating an image URL. The output is shown in the comment.

```php
use Cloudinary\Cloudinary;

$cloudinary = new Cloudinary('cloudinary://my_key:my_secret@my_cloud');
$image      = $cloudinary->image('sample.jpg');
echo $image->toUrl(); // https://res.cloudinary.com/my_cloud/image/upload/sample.jpg
```

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

### Install Cloudinary PHP SDK with Composer

Source: https://github.com/cloudinary/cloudinary_php/blob/master/README.md

Install the Cloudinary PHP SDK using Composer. This command adds the cloudinary/cloudinary_php package to your project's dependencies.

```bash
composer require "cloudinary/cloudinary_php"
```

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

### Example: create, update, and delete a user

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AccountApi.md

Shows how to instantiate AccountApi, create a user with the ADMIN role, then update the role to TECHNICAL_ADMIN and delete the user. The createUser method returns an ApiResponse with the user's id.

```php
use Cloudinary\Api\Provisioning\AccountApi;
use Cloudinary\Api\Provisioning\UserRole;

$api = new AccountApi();
$user = $api->createUser('Jane Doe', 'jane@example.com', UserRole::ADMIN);

$api->updateUser($user['id'], 'Jane Doe', 'jane@example.com', UserRole::TECHNICAL_ADMIN);
$api->deleteUser($user['id']);
```

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

### PictureTag usage example with sources

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Tags.md

Shows how to create a picture tag for the public ID 'sample' using a media query for source definitions with min_width and max_width constraints and transformations.

```php
echo $cloudinary->tag()->pictureTag('sample', [
    ['min_width' => 800, 'max_width' => 1200, 'transformation' => ...],
    ['max_width' => 800, 'transformation' => ...],
]);
```

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

### GET /v1_1/<cloud>/usage

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

Get cloud usage report.

```APIDOC
## [GET] /v1_1/<cloud>/usage

### Description
Get cloud usage report.

### Method
GET

### Endpoint
/v1_1/<cloud>/usage

### Parameters
#### Path Parameters
- **cloud** (string) - Required - Cloud name.

### Response
#### Success Response (200)
- **plan** (string) - Plan type.
- **last_updated** (string) - Last update timestamp.
- **usage** (array) - Usage details.

#### Response Example
{
  "plan": "Free",
  "last_updated": "2023-01-01T00:00:00Z",
  "usage": []
}
```

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

### Upload a local file with options

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/UploadApi.md

Example of uploading a local file with options. The result is an ArrayObject, and the public_id is accessed as vacation/beach.

```php
$result = $cloudinary->uploadApi()->upload('/tmp/photo.jpg', [
    'public_id' => 'vacation/beach',
    'folder'    => 'user_uploads',
    'tags'      => ['summer', 'public'],
]);
echo $result['public_id']; // ArrayObject access: vacation/beach
```

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

### GET /v1_1/<cloud>/resources/<public_id>

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

Get a single asset by public ID.

```APIDOC
## [GET] /v1_1/<cloud>/resources/<public_id>

### Description
Get a single asset by public ID.

### Method
GET

### Endpoint
/v1_1/<cloud>/resources/<public_id>

### Parameters
#### Path Parameters
- **cloud** (string) - Required - Cloud name.
- **public_id** (string) - Required - Public ID of the asset.

#### Query Parameters
- **exif** (boolean) - Optional - Include EXIF data.
- **colors** (boolean) - Optional - Include color data.
- **faces** (boolean) - Optional - Include face data.
- **quality_analysis** (boolean) - Optional - Include quality analysis.
- **image_metadata** (boolean) - Optional - Include image metadata.
- **phash** (boolean) - Optional - Include perceptual hash.
- **pages** (boolean) - Optional - Include page count.
- **coordinates** (boolean) - Optional - Include coordinates.
- **media_metadata** (boolean) - Optional - Include media metadata.
- **derived_next_cursor** (string) - Optional - Cursor for derived assets.

### Response
#### Success Response (200)
- **resource** (object) - The asset object.

#### Response Example
{
  "public_id": "sample",
  "format": "jpg",
  "version": 123
}
```

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

### UploadTag usage example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Tags.md

Example usage of UploadTag with a folder parameter, showing the resulting HTML input element with data attributes.

```php
echo $cloudinary->tag()->uploadTag('image', ['folder' => 'user_uploads']);
// <input data-cloudinary-field="image" data-max-chunk-size="20000000" data-form-data="{...}" data-url="...">
```

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

### Search assets with Search API

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Cloudinary.md

Example of using the Search API to execute a search expression.

```php
$result = $cloudinary->searchApi()
    ->expression('resource_type:image AND tags:summer')
    ->maxResults(50)
    ->execute();
```

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

### ApiResponse usage example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/ApiClients.md

Example of using ApiResponse. Access rate limit properties and iterate over the decoded JSON body as an array.

```php
$res = $cloudinary->adminApi()->assets();
echo $res->rateLimitRemaining;
echo $res->rateLimitResetAt;
foreach ($res['resources'] as $r) { /* ... */ }
```

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

### GET /v1_1/provisioning/accounts/<account_id>/sub_accounts/<id>

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

Get details of a specific sub-account in your Cloudinary account.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/sub_accounts/<id>

### Description
Get details of a specific sub-account in your Cloudinary account.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/sub_accounts/<id>

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.
- **id** (string) - Required - The ID of the sub-account to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Sub-account ID.
- **name** (string) - Sub-account name.
- **cloud_name** (string) - Cloud name.
- **enabled** (boolean) - Enabled status.

#### Response Example
{
  "id": "sub123",
  "name": "My Sub Account",
  "cloud_name": "mycloud",
  "enabled": true
}
```

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

### GET /v1_1/provisioning/accounts/<account_id>/users/<user_id>

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

Get details of a specific user in your Cloudinary account.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/users/<user_id>

### Description
Get details of a specific user in your Cloudinary account.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/users/<user_id>

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.
- **user_id** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **id** (string) - User ID.
- **name** (string) - User name.
- **email** (string) - User email.
- **role** (string) - User role (e.g., master_admin, admin, technical_admin, billing, reports, media_library_admin, media_library_user).
- **sub_account_ids** (array) - Sub-account IDs associated with the user.

#### Response Example
{
  "id": "user123",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "sub_account_ids": ["sub123"]
}
```

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

### Analyze example with google_tagging

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Example usage of the analyze method to perform google_tagging analysis on a URI. The result is accessed via $res['analysis']['data'].

```php
$res = $cloudinary->adminApi()->analyze('uri', 'google_tagging', 'https://example.com/photo.jpg');
var_dump($res['analysis']['data']);
```

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

### Serializing configuration to Cloudinary URL

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Example of serializing a configuration to a Cloudinary URL string. The output shows the URL format with the api_key included.

```php
echo Configuration::fromParams(['cloud' => ['cloud_name' => 'demo'], 'api' => ['api_key' => 'k']]);
// cloudinary://k:@demo?api[api_key]=k...
```

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

### Using Configuration::instance() with array config

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Example of using the singleton accessor with an array configuration. The cloud name is accessed via the cloud property and outputs 'demo'.

```php
$config = Configuration::instance(['cloud' => ['cloud_name' => 'demo']]);
echo $config->cloud->cloudName; // demo
```

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

### GET /v1_1/<cloud>/resources

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

List assets with optional filters.

```APIDOC
## [GET] /v1_1/<cloud>/resources

### Description
List assets.

### Method
GET

### Endpoint
/v1_1/<cloud>/resources

### Parameters
#### Path Parameters
- **cloud** (string) - Required - Cloud name.

#### Query Parameters
- **type** (string) - Optional - Asset type.
- **prefix** (string) - Optional - Prefix filter.
- **asset_folder** (string) - Optional - Asset folder filter.
- **tags** (string) - Optional - Tags filter.
- **context** (string) - Optional - Context filter.
- **moderation** (string) - Optional - Moderation status.
- **start_at** (string) - Optional - Start timestamp.
- **max_results** (integer) - Optional - Maximum results.
- **next_cursor** (string) - Optional - Pagination cursor.
- **direction** (string) - Optional - Sort direction.
- **fields** (string) - Optional - Fields to include.
- **quality_analysis** (boolean) - Optional - Include quality analysis.
- **cinemagraph_analysis** (boolean) - Optional - Include cinemagraph analysis.
- **media_metadata** (boolean) - Optional - Include media metadata.

### Response
#### Success Response (200)
- **resources** (array) - List of assets.
- **next_cursor** (string) - Pagination cursor.
- **rate_limit_allowed** (integer) - Rate limit allowed.
- **rate_limit_remaining** (integer) - Rate limit remaining.

#### Response Example
{
  "resources": [],
  "next_cursor": "abc",
  "rate_limit_allowed": 5000,
  "rate_limit_remaining": 4999
}
```

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

### GET /v1_1/provisioning/accounts/<account_id>/user_groups/<id>

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

Get details of a specific user group in your Cloudinary account.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/user_groups/<id>

### Description
Get details of a specific user group in your Cloudinary account.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/user_groups/<id>

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.
- **id** (string) - Required - The ID of the user group to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Group ID.
- **name** (string) - Group name.

#### Response Example
{
  "id": "group123",
  "name": "My Group"
}
```

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

### Admin API MiscTrait method signatures

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Method signatures for ping, config, usage, and tags operations from the MiscTrait. ping() hits GET /ping, config() returns GET /config, usage() checks cloud usage, and tags() lists tags.

```php
public function ping(): ApiResponse
public function pingAsync(): PromiseInterface

public function config(array $options = []): ApiResponse

public function usage(array $options = []): ApiResponse

public function tags(array $options = []): ApiResponse
```

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

### VideoTag usage example with sources

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Tags.md

Shows how to create a video tag for 'dog.mp4' with two source definitions: MP4 and WebM with a VP9 video codec transformation. Uses the VideoTagDeliveryTypeTrait builders via $cloudinary->videoTag().

```php
echo $cloudinary->videoTag('dog.mp4', [
    ['type' => VideoSourceType::MP4],
    ['type' => VideoSourceType::WEBM,
     'transformation' => (new VideoTransformation())->videoCodec(VideoCodec::vp9())],
]);
```

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

### Admin API asset operations example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Example usage of the Admin API to list assets, update tags, and delete assets. The `assets()` call retrieves up to 25 image resources with tags, then prints each public ID. `update()` sets tags on 'sample', and `deleteAssets()` removes assets 'a' and 'b' of type image.

```php
$assets = $cloudinary->adminApi()->assets([
    'resource_type' => 'image',
    'max_results'   => 25,
    'tags'          => true,
]);
foreach ($assets['resources'] as $a) {
    echo $a['public_id'] . PHP_EOL;
}

$cloudinary->adminApi()->update('sample', ['tags' => ['featured']]);
$cloudinary->adminApi()->deleteAssets(['a', 'b'], ['resource_type' => 'image']);
```

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

### GET /upload_presets

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Lists all upload presets.

```APIDOC
## [GET] /upload_presets

### Description
Lists all upload presets.

### Method
GET

### Endpoint
/upload_presets

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

### Response
#### Success Response (200)
- **ApiResponse** - The API response containing the list of upload presets.

#### Response Example
```json
{
  "presets": []
}
```
```

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

### Generate HTML tags with TagBuilder

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Cloudinary.md

Example of using the TagBuilder to generate image, video, and JS config tags.

```php
echo $cloudinary->tag()->imageTag('sample.jpg'); // <img src="https://res.cloudinary.com/.../sample.jpg">
echo $cloudinary->tag()->videoTag('dog.mp4');
echo $cloudinary->tag()->jsConfigTag();
```

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

### Example: deleteUser with NotFound error handling

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AccountApi.md

Shows how to call deleteUser on the AccountApi and catch a NotFound exception when the user ID does not exist. The comment indicates a 404 error triggers this exception. Requires CLOUDINARY_ACCOUNT_URL configuration.

```php
use Cloudinary\Api\Exception\NotFound;
use Cloudinary\Api\Provisioning\AccountApi;

try {
    $api = new AccountApi();
    $api->deleteUser('non_existent_id');
} catch (NotFound $e) {
    // 404 — the user does not exist
}
```

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

### VideoTag

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Tags.md

Documentation for the VideoTag class, including constructor, methods, delivery type builders, and an example.

```APIDOC
## VideoTag

### Description
Creates an HTML5 video tag with support for multiple sources, transformations, poster images, and fallback content.

### Constructor
`__construct($video, ?array $sources = null, ?Configuration $configuration = null)`

### Methods
- `video(mixed $video, ?Configuration $configuration = null): static` - Sets the video source.
- `sources(array $sourcesDefinitions): static` - Sets the video sources.
- `fallback(string $content): static` - Sets fallback content.
- `poster(ImageTransformation|string|Image $poster): static` - Sets the poster image.
- `serializeAttributes(array $attributes = []): string` - Serializes tag attributes.
- `serializeContent(array $additionalContent = [], bool $prependAdditionalContent = false): string` - Serializes tag content.
- `addTransformation($transformation): static` - Adds a transformation.
- `addAction($action): static` - Adds an action.
- `jsonSerialize(): array` - Serializes to JSON.

### Delivery Type Builders
- `upload($publicId, $configuration)` - Creates a video tag with an uploaded video.
- `fetch($url, $configuration)` - Creates a video tag with a fetched video.

### Example
```php
echo $cloudinary->videoTag('dog.mp4', [
    ['type' => VideoSourceType::MP4],
    ['type' => VideoSourceType::WEBM,
     'transformation' => (new VideoTransformation())->videoCodec(VideoCodec::vp9())],
]);
```
```

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

### GET /v1_1/<cloud>/tags

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

List tags with optional filters.

```APIDOC
## [GET] /v1_1/<cloud>/tags

### Description
List tags.

### Method
GET

### Endpoint
/v1_1/<cloud>/tags

### Parameters
#### Path Parameters
- **cloud** (string) - Required - Cloud name.

#### Query Parameters
- **prefix** (string) - Optional - Prefix filter.
- **max_results** (integer) - Optional - Maximum results.
- **next_cursor** (string) - Optional - Pagination cursor.

### Response
#### Success Response (200)
- **tags** (array) - List of tags.
- **next_cursor** (string) - Pagination cursor.

#### Response Example
{
  "tags": ["tag1", "tag2"],
  "next_cursor": "abc"
}
```

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

### GET /v1_1/<cloud>/ping

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

Connectivity check for the Cloudinary Admin API.

```APIDOC
## [GET] /v1_1/<cloud>/ping

### Description
Connectivity check for the Cloudinary Admin API.

### Method
GET

### Endpoint
/v1_1/<cloud>/ping

### Parameters
#### Path Parameters
- **cloud** (string) - Required - Cloud name.

### Response
#### Success Response (200)
- **message** (string) - Connectivity confirmation.

#### Response Example
{
  "message": "pong"
}
```

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

### GET /v1_1/provisioning/accounts/<account_id>/user_groups

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

List user groups in your Cloudinary account.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/user_groups

### Description
List user groups in your Cloudinary account.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/user_groups

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.

### Response
#### Success Response (200)
- **user_groups** (array) - Array of user group objects.

#### Response Example
{
  "user_groups": [
    {
      "id": "group123",
      "name": "My Group"
    }
  ]
}
```

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

### Sign request parameters with ApiUtils::signRequest

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Utils.md

Example of using ApiUtils::signRequest() to add 'signature' and 'api_key' to a request parameter array by reference. Requires a Cloudinary configuration with cloud credentials.

```php
use Cloudinary\Api\ApiUtils;

$params = ['public_id' => 'a', 'timestamp' => 123];
ApiUtils::signRequest($params, $cloudinary->configuration->cloud);
// $params now contains 'signature' and 'api_key'
```

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

### GET provisioning/accounts/users

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AccountApi.md

Lists users with optional filters such as pending status, user IDs, prefix, and sub-account ID.

```APIDOC
## GET provisioning/accounts/users

### Description
Lists users with optional filters.

### Method
GET

### Endpoint
provisioning/accounts/users

### Parameters
#### Query Parameters
- **pending** (bool|null) - Optional - If true, only pending users are returned.
- **ids** (array) - Optional - Up to 100 user IDs to filter by.
- **prefix** (string|null) - Optional - Case-insensitive prefix for name or email.
- **sub_account_id** (string|null) - Optional - Filter by sub-account ID.

### Response
#### Success Response (200)
Returns a `Cloudinary\Api\ApiResponse` object containing a list of users.

#### Response Example
```json
[
  {
    "id": "user_id",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "role": "admin"
  }
]
```
```

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

### GET /v1_1/provisioning/accounts/<account_id>/sub_accounts/<id>/access_keys

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

List access keys for a sub-account in your Cloudinary account.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/sub_accounts/<id>/access_keys

### Description
List access keys for a sub-account in your Cloudinary account.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/sub_accounts/<id>/access_keys

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.
- **id** (string) - Required - The ID of the sub-account.

### Response
#### Success Response (200)
- **access_keys** (array) - Array of access key objects.

#### Response Example
{
  "access_keys": [
    {
      "api_key": "abc123",
      "name": "My Key",
      "enabled": true
    }
  ]
}
```

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

### GET /v1_1/provisioning/accounts/<account_id>/sub_accounts

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

List sub-accounts in your Cloudinary account with optional filters.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/sub_accounts

### Description
List sub-accounts in your Cloudinary account with optional filters.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/sub_accounts

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.

#### Query Parameters
- **enabled** (boolean) - Optional - Filter by enabled status.
- **ids** (array) - Optional - List of sub-account IDs.
- **prefix** (string) - Optional - Filter by name prefix.

### Response
#### Success Response (200)
- **sub_accounts** (array) - Array of sub-account objects.

#### Response Example
{
  "sub_accounts": [
    {
      "id": "sub123",
      "name": "My Sub Account",
      "cloud_name": "mycloud",
      "enabled": true
    }
  ]
}
```

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

### GET /v1_1/provisioning/accounts/<account_id>/users

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

List users in your Cloudinary account with optional filters.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/users

### Description
List users in your Cloudinary account with optional filters.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/users

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.

#### Query Parameters
- **pending** (boolean) - Optional - Filter by pending status.
- **ids** (array) - Optional - List of user IDs (max 100).
- **prefix** (string) - Optional - Filter by name prefix.
- **sub_account_id** (string) - Optional - Filter by sub-account ID.

### Response
#### Success Response (200)
- **users** (array) - Array of user objects.

#### Response Example
{
  "users": [
    {
      "id": "user123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin"
    }
  ]
}
```

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

### Configure logging with Cloudinary

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Logging.md

Example of configuring logging via the 'logging' section of the Cloudinary configuration. Enables logging, sets the default level to 'info', logs to error_log, and writes debug-level logs to a file. The subsequent upload call produces debug-level log messages for requests and critical-level for failures.

```php
use Cloudinary\Cloudinary;

$cloudinary = new Cloudinary([
    'cloud' => ['cloud_name' => 'demo'],
    'logging' => [
        'enabled'   => true,
        'level'     => 'info',
        'error_log' => true,
        'file'      => [
            ['path' => '/var/log/cloudinary.log', 'level' => 'debug'],
        ],
    ],
]);

$cloudinary->uploadApi()->upload('a.jpg');
// captured at debug level: "Making async POST request" / "Response received for async request"
// failures logged at critical: "Request to Cloudinary server returned an error"
```

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

### Handling ConfigurationException on invalid import

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Example of catching a ConfigurationException when importing an invalid value (12345). The exception message is 'Invalid configuration, please set up your environment'.

```php
use Cloudinary\Exception\ConfigurationException;

try {
    $config->import(12345); // not a URL, array, JSON, or Configuration
} catch (ConfigurationException $e) {
    // "Invalid configuration, please set up your environment"
}
```

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

### GET /v1_1/provisioning/accounts/<account_id>/user_groups/<id>/users

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/endpoints.md

List users in a specific user group in your Cloudinary account.

```APIDOC
## GET /v1_1/provisioning/accounts/<account_id>/user_groups/<id>/users

### Description
List users in a specific user group in your Cloudinary account.

### Method
GET

### Endpoint
/v1_1/provisioning/accounts/<account_id>/user_groups/<id>/users

### Parameters
#### Path Parameters
- **account_id** (string) - Required - Your Cloudinary account ID.
- **id** (string) - Required - The ID of the user group.

### Response
#### Success Response (200)
- **users** (array) - Array of user objects.

#### Response Example
{
  "users": [
    {
      "id": "user123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin"
    }
  ]
}
```

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

### Cloudinary\Log\Logger

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Logging.md

The Logger class is the core logging component. It accepts a LoggingConfig and builds handlers based on the configuration. It provides methods to get handlers, get a test handler, log messages, and get the default log level.

```APIDOC
## Cloudinary\Log\Logger

### Description
Creates a logger instance with handlers configured from LoggingConfig. Handlers are built based on the `errorLog`, `file`, and `test` configuration options. If no handlers are added and `errorLog` is not false, an ErrorLogHandler fallback is added; otherwise a NullHandler is used. If `enabled` is false, no handlers are created and `getLogger()` returns null.

### Constructor
`public function __construct(LoggingConfig $config)`

### Methods

#### getHandlers()
- **Signature**: `public function getHandlers(): array`
- **Returns**: array of `HandlerInterface` instances.

#### getTestHandler()
- **Signature**: `public function getTestHandler(): ?TestHandler`
- **Returns**: The TestHandler if configured, otherwise null.

#### log()
- **Signature**: `public function log(mixed $level, string|\Stringable $message, array $context = []): void`
- **Parameters**:
  - `$level` (mixed) - The log level (e.g., 'debug', 'info', 'critical').
  - `$message` (string|\Stringable) - The log message.
  - `$context` (array) - Optional context data.

#### getDefaultLogLevel()
- **Signature**: `public function getDefaultLogLevel(): int`
- **Returns**: The default PSR-3 log level based on the PHP `error_reporting()` bitmask.

### Handler Construction
- `config.errorLog` as array → `ErrorLogHandler(OPERATING_SYSTEM, level)`; `true` → `ErrorLogHandler` at default level; `false` disables error-log fallback.
- `config.file` (array of `['path' => ..., 'level' => ...]`) → one `StreamHandler` per entry; entries without a string `path` are skipped.
- `config.test` (array) → `TestHandler`.
- If no handlers added and `errorLog !== false`, an `ErrorLogHandler` fallback is added; if still empty, a `NullHandler(DEBUG)` is added.
- `config.enabled === false` → no handlers; `getLogger()` returns `null`.
- Failures during init trigger `trigger_error($e->getMessage(), E_USER_WARNING)` and return `null`.
```

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

### Using Image delivery-type builders

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Assets.md

Shows how to use the static delivery-type builders to create image assets. Each call returns an asset instance with the corresponding URL, and the resize method demonstrates transformation chaining from the Transformation SDK.

```php
use Cloudinary\Asset\Image;

$img = Image::upload('sample.jpg');                       // https://res.../image/upload/sample.jpg
$img = Image::fetch('https://example.com/pic.png');       // …/image/fetch/https://example.com/pic.png
$img = Image::youTube('oHg5SJYRHA0');                     // …/image/youtube/oHg5SJYRHA0.jpg
$img->resize(...);                                        // transformation chaining (from Transformation SDK)
```

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

### Initialize Cloudinary PHP SDK

Source: https://github.com/cloudinary/cloudinary_php/blob/master/README.md

Initializes the Cloudinary PHP SDK. Requires the Cloudinary\Cloudinary class and a configured environment (e.g., CLOUDINARY_URL).

```php
use Cloudinary\Cloudinary;

$cloudinary = new Cloudinary();
```

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

### Configuration::fromJson(), fromParams(), fromCloudinaryUrl()

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Named constructors for creating a Configuration from JSON, an array of parameters, or a Cloudinary URL.

```APIDOC
## fromJson(), fromParams(), fromCloudinaryUrl() (static)

### Description
Named constructors. `fromJson` accepts a JSON string or decoded array; `fromCloudinaryUrl` accepts `cloudinary://key:secret@cloud_name?<section_params>`.

### Methods
- `public static function fromJson(array|string $json): static`
- `public static function fromParams(array $params): static`
- `public static function fromCloudinaryUrl(string $cloudinaryUrl): static`

### Parameters
- **$json** (array|string) - Required - JSON string or decoded array.
- **$params** (array) - Required - Configuration parameters.
- **$cloudinaryUrl** (string) - Required - Cloudinary URL.

### Request Example
```php
$config = Configuration::fromCloudinaryUrl(
    'cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyz@my_cloud?secure=true'
);
```
```

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

### Configuration::__construct()

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Creates a new Configuration instance from a Cloudinary URL, JSON, array, another Configuration, or null to fall back to the CLOUDINARY_URL environment variable.

```APIDOC
## Constructor

### Description
Creates a new Configuration instance.

### Method
`public function __construct(Configuration|array|string|null $config = null, bool $includeSensitive = true)`

### Parameters
- **$config** (Configuration|array|string|null) - Optional - Configuration source: Cloudinary URL, JSON, array, or another Configuration instance. `null` falls back to `CLOUDINARY_URL` env var.
- **$includeSensitive** (bool) - Optional - Whether sensitive keys (api_key, api_secret, oauth_token) take part in serialization.

### Request Example
```php
$config = new Configuration(['cloud' => ['cloud_name' => 'demo']]);
```
```

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

### Verify notification signature example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Utils.md

Example usage of verifyNotificationSignature with the request body and the X-Cld-Timestamp and X-Cld-Signature headers. Returns a boolean indicating validity.

```php
use Cloudinary\Utils\SignatureVerifier;

$isValid = SignatureVerifier::verifyNotificationSignature(
    $requestBody,
    $_SERVER['HTTP_X_CLD_TIMESTAMP'],
    $_SERVER['HTTP_X_CLD_SIGNATURE']
);
```

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

### Creating an ImageTag with class and alt attribute

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Tags.md

Shows how to construct an ImageTag for a sample image, add a CSS class, set an alt attribute, and echo the resulting HTML string.

```php
echo (new ImageTag('sample'))->addClass('hero')->setAttribute('alt', 'A sample image');
```

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

### ProvisioningConfiguration method signatures

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Lists the public methods of ProvisioningConfiguration. With null config, it reads the CLOUDINARY_ACCOUNT_URL env var. Throws ConfigurationException for unparsable input.

```php
public function __construct(array|string|ProvisioningConfiguration|null $config = null)
public function init(array|string|ProvisioningConfiguration|null $config = null): void
public function importAccountUrl(UriInterface|string $accountUrl): static
public function importJson($json): static
public function importConfig(ProvisioningConfiguration $otherConfig): static
public function jsonSerialize(bool $includeSensitive = true, bool $includeEmptyKeys = false, bool $includeEmptySections = false): array
public static function instance(array|string|ProvisioningConfiguration|null $config = null): ProvisioningConfiguration
```

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

### Verify API response signature example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Utils.md

Example usage of verifyApiResponseSignature with the public_id and version from an upload response and the X-Cld-Signature header. Returns a boolean indicating validity.

```php
$isValid = SignatureVerifier::verifyApiResponseSignature(
    $uploadResponse['public_id'],
    $uploadResponse['version'],
    $_SERVER['HTTP_X_CLD_SIGNATURE']
);
```

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

### Create and delete metadata field example

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Example of creating and deleting a metadata field using StringMetadataField. Sets external ID and mandatory flag, then adds and deletes the field via the admin API.

```php
use Cloudinary\Api\Metadata\StringMetadataField;

$field = new StringMetadataField('Color');
$field->setExternalId('color');
$field->setMandatory(true);

$cloudinary->adminApi()->addMetadataField($field);
$cloudinary->adminApi()->deleteMetadataField('color');
```

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

### GET /metadata_fields

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Lists all metadata fields.

```APIDOC
## [GET] /metadata_fields

### Description
Lists all metadata fields.

### Method
GET

### Endpoint
/metadata_fields

### Response
#### Success Response (200)
- **ApiResponse** - The API response containing the list of metadata fields.

#### Response Example
```json
{
  "metadata_fields": []
}
```
```

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

### ProvisioningConfiguration constant

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Defines the environment variable name for the account URL used by the provisioning configuration.

```php
public const CLOUDINARY_ACCOUNT_URL_ENV_VAR = 'CLOUDINARY_ACCOUNT_URL'
```

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

### Configuration::import() method signature

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Imports configuration from the given source. With null, reads CLOUDINARY_URL from the environment; if unset, returns without changes. Dispatches to importCloudinaryUrl(), importJson(), or importConfig() based on input, and throws ConfigurationException for invalid input.

```php
public function import(Configuration|array|string|null $config = null): void
```

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

### GET /upload_mappings

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AdminApi.md

Lists all upload mappings.

```APIDOC
## [GET] /upload_mappings

### Description
Lists all upload mappings.

### Method
GET

### Endpoint
/upload_mappings

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

### Response
#### Success Response (200)
- **ApiResponse** - The API response containing the list of upload mappings.

#### Response Example
```json
{
  "mappings": []
}
```
```

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

### Configuration::import()

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/Configuration.md

Imports configuration from a given source into the current instance, dispatching to the appropriate import method.

```APIDOC
## import()

### Description
Imports the given source into the current instance. With `null`, reads `CLOUDINARY_URL` from the environment; if that env var is also unset, the method returns without changes. Dispatches to `importCloudinaryUrl()`, `importJson()`, or `importConfig()` based on the input, and throws `ConfigurationException` for anything else.

### Method
`public function import(Configuration|array|string|null $config = null): void`

### Parameters
- **$config** (Configuration|array|string|null) - Optional - Configuration source.

### Request Example
```php
use Cloudinary\Exception\ConfigurationException;

try {
    $config->import(12345); // not a URL, array, JSON, or Configuration
} catch (ConfigurationException $e) {
    // "Invalid configuration, please set up your environment"
}
```
```

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

### Constructor signature for AccountApi

Source: https://github.com/cloudinary/cloudinary_php/blob/master/_autodocs/api-reference/AccountApi.md

Defines the constructor for AccountApi, accepting an optional ProvisioningConfiguration. When null, the singleton configuration is used.

```php
public function __construct(?ProvisioningConfiguration $configuration = null)
```
Tokens:
Raw