> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# PHP API Client

> PHP Uploadcare API client for Fast & Reliable File Uploads; File, Group, Project Operations; Video + Document Conversion & More.

PHP integration handles uploads and file operations by wrapping Uploadcare
[Upload API](https://uploadcare.com/docs/api/upload/) and [REST API](https://uploadcare.com/docs/api/rest/). This
comprehensive API client lets you use most of the Uploadcare features from within
your PHP app.

[GitHub →](https://github.com/uploadcare/uploadcare-php#readme)

Check out an [example project](https://github.com/uploadcare/uploadcare-php-example/) that showcases various usage scenarios.

## Features

Uploading ([Upload API](https://uploadcare.com/docs/api/upload/)):

* Upload files from local storage and URLs (up to 5 TB)
* Multipart uploading for large files
* Uploading network to speed uploading jobs (like CDN)

File management ([REST API](https://uploadcare.com/docs/api/rest/)):

* Get file info and perform various operations (store/delete/copy) with them
* Work with groups of files
* Manage webhooks
* Remove image background
* Recognize objects on the picture
* Check for viruses
* Convert documents
* Encode and transform videos

Image processing ([URL API](https://uploadcare.com/docs/api/url/)):

* Compression
* Geometry
* Colors
* Definition
* Image and text overlays
* Rotations
* Recognition
* File info
* Proxy (fetch)

Security features:

* Secure authentication
* Secure uploads (signed uploads)
* Secure delivery (signed URLs)
* Secure webhooks (signing secret)

## Requirements

* `PHP 7.4 and later` or `PHP 8 and later`
* `php-curl`
* `php-json`

How to check PHP version via CLI:

```bash
php -v
```

How to check modules:

```bash
php -m
```

You should see `curl` and `json` in the list:

```bash
workstation:home user$ php -m
[PHP Modules]
bcmath
...
curl
...
json
...

[Zend Modules]
```

## Install

Prior to installing `uploadcare-php`, get the [Composer](https://getcomposer.org/)
dependency manager for PHP to simplify installation.

### 1. Update

1. Update `composer.json`:

```js
"require": {
    "uploadcare/uploadcare-php": "^4.0"
}
```

> **Info**
>
> This constraint resolves to the latest v4.x release. Current stable version is 4.2.1.

### 2. Run

Run [Composer](https://getcomposer.org/):

```bash
php composer.phar update
```

### 3. Define

Define Uploadcare [API keys](https://app.uploadcare.com/projects/-/api-keys/):

Add API keys to your configuration object. For example:

```php
# config.php
$_ENV['UPLOADCARE_PUBLIC_KEY'] = '<your public key>';
$_ENV['UPLOADCARE_SECRET_KEY'] = '<your secret key>';
```

### 4. Include Composer

Include Composer's autoload file:

```php
require_once 'vendor/autoload.php';
```

### 5. Create a `configuration` object

There're a few ways to create a configuration object. We recommend that you use
this static method of the `Uploadcare\Configuration` class:

```php
$configuration = Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'], $_ENV['UPLOADCARE_SECRET_KEY']);
```

Alternatively, you can create a Security signature, HTTP client, and Serializer
classes explicitly. After that, you can create a configuration object:

```php
$sign = new \Uploadcare\Security\Signature('<your secret key>', 3600); // Must be an instance of \Uploadcare\Interfaces\SignatureInterface
$client = \Uploadcare\Client\ClientFactory::createClient(); // Must be an instance of \GuzzleHttp\ClientInterface
$serializer = new \Uploadcare\Serializer\Serializer(new \Uploadcare\Serializer\SnackCaseConverter()); // Must be an instance of \Uploadcare\Interfaces\Serializer\SerializerInterface

$configuration = new \Uploadcare\Configuration('<your public key>', $sign, $client, $serializer);
```

As you can see, the factory method is more convenient for standard usage.

> **Tip**
>
> **Tip:** The factory method `Configuration::create()` is recommended for standard usage. The manual constructor is available for advanced scenarios such as custom HTTP clients or serializers.

That's it! All further operations will use this configuration object.

## Quick start

```php
require_once 'vendor/autoload.php';

$configuration = Uploadcare\Configuration::create(
    $_ENV['UPLOADCARE_PUBLIC_KEY'],
    $_ENV['UPLOADCARE_SECRET_KEY']
);
$api = new \Uploadcare\Api($configuration);

// Upload a file
$file = $api->uploader()->fromPath('/path/to/file.jpg', 'image/jpeg');
echo $file->getUuid();
echo $file->getOriginalFileUrl(); // CDN delivery URL
```

## Upload

#### Upload from path

```php
$file = $api->uploader()->fromPath('/path/to/file.jpg', 'image/jpeg');
```

#### Upload from URL

```php
$token = $api->uploader()->fromUrl('https://example.com/image.jpg', 'image/jpeg');
// fromUrl is asynchronous and returns a token. Poll it with checkStatus()
// until the file is ready, or use syncUploadFromUrl() below for a blocking call.
$file = $api->uploader()->checkStatus($token);
// $file->isReady() is false until the upload completes — keep polling if needed.
```

#### Synchronous upload from URL (blocks until done)

```php
$file = $api->uploader()->syncUploadFromUrl('https://example.com/image.jpg', 'image/jpeg');
echo $file->getUuid();
```

#### Upload from content

```php
$content = file_get_contents('/path/to/file.jpg');
$file = $api->uploader()->fromContent($content, 'image/jpeg');
```

#### Upload with metadata

```php
$file = $api->uploader()->fromPath('/path/to/file.jpg', 'image/jpeg', null, 'auto', ['kind' => 'profile']);
```

## File operations

#### Get file info

```php
$file = $api->file()->fileInfo('YOUR_FILE_UUID');
echo $file->getMimeType();
echo $file->getSize();
```

#### Store a file

```php
$api->file()->storeFile('YOUR_FILE_UUID');
```

#### Delete a file

```php
$api->file()->deleteFile('YOUR_FILE_UUID');
```

#### File metadata

```php
// Get all metadata
$metadata = $api->metadata()->getMetadata('YOUR_FILE_UUID');

// Remove a metadata key
$api->metadata()->removeKey('YOUR_FILE_UUID', 'kind');
```

## Copy

#### Copy to local storage

```php
$file = $api->file()->copyToLocalStorage('YOUR_FILE_UUID', true);
```

#### Copy to remote storage

```php
$result = $api->file()->copyToRemoteStorage('YOUR_FILE_UUID', 'custom_storage');
```

## Secure delivery

```php
use Uploadcare\AuthUrl\AuthUrlConfig;
use Uploadcare\AuthUrl\Token\AkamaiToken;

$authUrlConfig = new AuthUrlConfig('YOUR_CDN_URL', new AkamaiToken('YOUR_AKAMAI_SECRET_KEY'));
$configuration = Uploadcare\Configuration::create(
    $_ENV['UPLOADCARE_PUBLIC_KEY'],
    $_ENV['UPLOADCARE_SECRET_KEY']
)->setAuthUrlConfig($authUrlConfig);

$api = new \Uploadcare\Api($configuration);
$secureUrl = $api->file()->generateSecureUrl('YOUR_FILE_UUID');
```

> **Note**
>
> **Note:** The Akamai secret key must be a hex string (characters a-f, 0-9, even length). A non-hex placeholder will throw a `TokenException`.

> **Note**
>
> **Note:** `generateSecureUrl` returns `null` if `AuthUrlConfig` is not set on the configuration object.

## Webhooks

```php
$webhook = $api->webhook()->createWebhook('https://example.com/callback', true, 'sign-secret', 'file.uploaded');
echo $webhook->getTargetUrl();
```

## File conversion

#### Document conversion

```php
$request = new \Uploadcare\Conversion\DocumentConversionRequest('pdf');
$result = $api->conversion()->convertDocument('YOUR_FILE_UUID', $request);
```

#### Document conversion to group (multi-page)

```php
$request = (new \Uploadcare\Conversion\DocumentConversionRequest('pdf'))
    ->setSaveInGroup(true);
$result = $api->conversion()->convertDocument('YOUR_FILE_UUID', $request);
```

## Usage example

For a full list of supported operations, see the [uploadcare-php GitHub repository](https://github.com/uploadcare/uploadcare-php#readme) and the [example project](https://github.com/uploadcare/uploadcare-php-example/).

## Related guides

* [File Upload PHP Script for Your Website](https://uploadcare.com/blog/file-upload-php/)
* [PHP Image Resizing & Optimization](https://uploadcare.com/blog/image-optimization-php/)