Managing files

PHP API Client

PHP integration handles uploads and file operations by wrapping Uploadcare Upload API and REST API. This comprehensive API client lets you use most of the Uploadcare features from within your PHP app.

GitHub →

Check out an example project that showcases various usage scenarios.

Features

Uploading (Upload API):

  • 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):

  • 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):

  • 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:

$php -v

How to check modules:

$php -m

You should see curl and json in the list:

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

Install

Prior to installing uploadcare-php, get the Composer dependency manager for PHP to simplify installation.

1. Update

  1. Update composer.json:
1"require": {
2    "uploadcare/uploadcare-php": "^4.0"
3}

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

2. Run

Run Composer:

$php composer.phar update

3. Define

Define Uploadcare API keys:

Add API keys to your configuration object. For example:

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

4. Include Composer

Include Composer’s autoload file:

1require_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:

1$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:

1$sign = new \Uploadcare\Security\Signature('<your secret key>', 3600); // Must be an instance of \Uploadcare\Interfaces\SignatureInterface
2$client = \Uploadcare\Client\ClientFactory::createClient(); // Must be an instance of \GuzzleHttp\ClientInterface
3$serializer = new \Uploadcare\Serializer\Serializer(new \Uploadcare\Serializer\SnackCaseConverter()); // Must be an instance of \Uploadcare\Interfaces\Serializer\SerializerInterface
4
5$configuration = new \Uploadcare\Configuration('<your public key>', $sign, $client, $serializer);

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

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

1require_once 'vendor/autoload.php';
2
3$configuration = Uploadcare\Configuration::create(
4    $_ENV['UPLOADCARE_PUBLIC_KEY'],
5    $_ENV['UPLOADCARE_SECRET_KEY']
6);
7$api = new \Uploadcare\Api($configuration);
8
9// Upload a file
10$file = $api->uploader()->fromPath('/path/to/file.jpg', 'image/jpeg');
11echo $file->getUuid();
12echo $file->getOriginalFileUrl(); // CDN delivery URL

Upload

Upload from path

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

Upload from URL

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

Synchronous upload from URL (blocks until done)

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

Upload from content

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

Upload with metadata

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

File operations

Get file info

1$file = $api->file()->fileInfo('YOUR_FILE_UUID');
2echo $file->getMimeType();
3echo $file->getSize();

Store a file

1$api->file()->storeFile('YOUR_FILE_UUID');

Delete a file

1$api->file()->deleteFile('YOUR_FILE_UUID');

File metadata

1// Get all metadata
2$metadata = $api->metadata()->getMetadata('YOUR_FILE_UUID');
3
4// Remove a metadata key
5$api->metadata()->removeKey('YOUR_FILE_UUID', 'kind');

Copy

Copy to local storage

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

Copy to remote storage

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

Secure delivery

1use Uploadcare\AuthUrl\AuthUrlConfig;
2use Uploadcare\AuthUrl\Token\AkamaiToken;
3
4$authUrlConfig = new AuthUrlConfig('YOUR_CDN_URL', new AkamaiToken('YOUR_AKAMAI_SECRET_KEY'));
5$configuration = Uploadcare\Configuration::create(
6    $_ENV['UPLOADCARE_PUBLIC_KEY'],
7    $_ENV['UPLOADCARE_SECRET_KEY']
8)->setAuthUrlConfig($authUrlConfig);
9
10$api = new \Uploadcare\Api($configuration);
11$secureUrl = $api->file()->generateSecureUrl('YOUR_FILE_UUID');

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

generateSecureUrl returns null if AuthUrlConfig is not set on the configuration object.

Webhooks

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

File conversion

Document conversion

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

Document conversion to group (multi-page)

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

Usage example

For a full list of supported operations, see the uploadcare-php GitHub repository and the example project.