Download the PHP package uploadcare/uploadcare-php without Composer

Uploadcare PHP

Uploadcare PHP integration handles uploads and further operations with files by wrapping Upload and REST APIs.

• Requirements
• Install
• Usage
  • Uploading files
  • File operations
  • Addons operations
  • Group operations
  • Project operations
  • Webhooks
  • Conversion operations
  • Secure delivery
  • Tests
• Useful links

Requirements

• php7.4+ or php8.0+
• php-curl
• php-json

Install

Prior to installing uploadcare-php get the Composer dependency manager for PHP because it'll simplify installation.

Step 1 — update your composer.json:

Step 2 — run Composer:

Or, you can run the composer.phar require uploadcare/uploadcare-php instead of steps 1 and 2.

Step 3 — define your Uploadcare public and secret API keys in a way you prefer (e.g., by using a $_ENV variable):

Add API keys to your configuration object. For example:

Step 4 — include a standard composer autoload file:

Step 5 — create an object of the Uploadcare\Configuration class,

All further operations will use this configuration object.

Configuration object

There are a few ways to make a valid configuration object. We recommend using the static method of the class:

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

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

Usage

You can find the full example in this Uploadcare example project.

First, create an API object:

Uploading files

This section describes multiple ways of uploading files to Uploadcare.

You can use the core API object for any upload type:

First of all, files can be uploaded from URL. The following code returns a token to check file upload status,

You can upload files from URL synchronically,

Check an uploading file status,

Another way of uploading files is by using a path,

It’s also relevant when using file pointers,

There's an option of uploading a file from its contents. You’ll need to specify MIME-types as well:

Secure signature. If you are using secure uploads, you can use getSignature method to fetch an instance of SignatureInterface. For example:

File metadata

Every upload method can set a file metadata. For example:

You will see this values in a metadata object of Uploadcare\File response.

Multipart upload

If you have a large file (more than 100Mb / 10485760 bytes), the uploader will automatically process it with a multipart upload. It'll take more time to upload, and also we don’t recommend it for a web environment.

Uploadcare\File class

This class implements Uploadcare\Interfaces\File\FileInfoInterface and it has additional methods (besides the interface):

• store() — Stores this file in storage. Returns Uploadcare\File object.
• delete() — Deletes this file. Returns Uploadcare\File object.
• copyToLocalStorage($store = true) — Copies this file to local storage.
• copyToRemoteStorage($target, $makePublic = true, $pattern = null) — Copies this file to remote storage.

All these operations are accessible via File API, and you can access them through the Uploadcare\File object as well.

File operations

For any file operation type, you’ll need to create an Uploadcare\Api instance with configuration object and call the file() method:

After that, you can access to file operation methods:

• listFiles($limit = 100, $orderBy = 'datetime_uploaded', $from = null, $addFields = [], $stored = null, $removed = false) — a list of files. Returns an Uploadcare\FileCollection instance (see below). Each element of collection is an Uploadcare\File. Arguments:
  • int $limit A preferred amount of files in a list for a single response. Defaults to 100, while the maximum is 1000.
  • string $orderBy Specifies the way to sort files in a returned list.
  • string|int|null $from A starting point for a file filter. The value depends on your $orderBy parameter value.
  • array $addFields Deprecated This parameter is deprecated since v4.0.1 and will be removed in v4.1
  • bool|null $stored true includes the only stored files, false includes temporary files. If not set (default): both stored and not stored files will be included.
  • bool $removed true to only include removed files in the response, false to include existing files. The default value is false.

• nextPage(FileListResponseInterface $response) — next page from previous answer, if next pages exist. You can use it in a simple while loop, for example:

• getPageRequestParameters(string | null $url) — Get an array with next page request parameters. Use it to create links to the previous/next page of the list.
• storeFile(string $id) — Stores a single file by UUID. Returns the Uploadcare\File (FileInfoInterface). Takes file UUID as an argument.
• deleteFile(string $id) — Removes individual files. Returns file info. Takes file UUID as an argument.
• fileInfo(string $id) — Once you obtain a list of files, you might want to acquire some file-specific info. Returns FileInfoInterface. Takes array of file UUID's as an argument.
• batchStoreFile(array $ids) — Used to store multiple files in one step. Supports up to 100 files per request. Takes an array of file UUID's as an argument.
• batchDeleteFile(array $ids) — Used to delete multiple files in one step. Takes an array of file UUID's as an argument.
• copyToLocalStorage(string $source, bool $store) — Used to copy original files, or their modified versions to a default storage. Arguments:
  • $source — A CDN URL or just UUID of a file subjected to copy.
  • $store Parameter only applies to the Uploadcare storage.
• copyToRemoteStorage(string $source, string $target, bool $makePublic = true, string $pattern = '${default}') — copies original files, or their modified versions to a custom storage. Arguments:
  • $source — CDN URL or just UUID of a file that’s being copied.
  • $target — Defines a custom storage name related to your project and implies you are copying a file to a specified custom storage. Keep in mind that you can have multiple storages associated with one S3 bucket.
  • $makePublic — true to make copied files available via public links, false to reverse the behavior.
  • $pattern — The parameter is used to specify file names Uploadcare passes to a custom storage. In case when the parameter is omitted, we use a pattern of your custom storage. Use any combination of allowed values.

See the API documentation for more details.

Uploadcare\FileCollection class

This class implements Uploadcare\Interfaces\File\CollectionInterface and has additional methods besides the interface:

• store() — Stores all files in a collection. Calls FileApi::batchStoreFile() under the hood.
• delete() — Deletes all files in a collection.

Each file in the collection is an object of the Uploadcare\File class.

Uploadcare\File class

This class implements FileInfoInterface and has additional methods for file operations:

• store() — Stores the current file.
• delete() — Deletes the current file.
• copyToLocalStorage($store = true) — Copies the current file to the default storage.
• copyToRemoteStorage($target, $makePublic = true, $pattern = null) — Copies the current file to a custom storage;

As you can see, additional methods help you to call API methods without direct API calls.

Addons operations

Uploadcare provide a few additional operations with images.

Object Recognition

To call object recognition from library:

Unsafe content detection

To call unsafe content detection from the library:

Remove background

Remove background from image:

Antivirus scan

Group operations

For any type of group operation you need to create an Uploadcare\Api instance with a configuration object and call the group() method:

After that, you can access group operation methods:

• createGroup($files) — Creates a file group. You can pass the array of IDs or Uploadcare\File\FileCollection as an argument. Returns an Uploadcare\File\Group object.
• listGroups($limit, $asc = true) — Gets a paginated list of groups. The default limit is 100, and the default sorting is by the date and time created (ascending). You can reverse the sorting order to descending dates with $asc = false. Returns Uploadcare\Response\GroupListResponse.
• groupInfo($id) — Gets a file group info by UUID. Returns an Uploadcare\Group object.
• removeGroup($id): void — delete group by UUID or Uploadcare\Group object.

Uploadcare\Group class

This class implements Uploadcare\Interfaces\GroupInterface.
The getFiles() method of the Uploadcare\Group object returns FileCollection.

Project operations

As usual, Project API is accessible by the main API object:

You can get the project information by calling the getProjectInfo method:

Now, the $projectInfo variable contains the Uploadcare\Interfaces\Response\ProjectInfoInterface implementation with the following methods:

• getCollaborators() — Array with collaborators information. Keys are collaborator emails and values are collaborator names.
• getName() — Project name as a string.
• getPubKey() — Project public key as string.
• isAutostoreEnabled() — Returns true if the project files are stored automatically.

Webhooks

Call the webhook API:

The methods are:

• listWebhooks() — Returns a list of project webhooks as an instance of an Uploadcare\WebhookCollection class. Each element of this collection is an instance of a Uploadcare\Webhook class (see below);
• createWebhook(string $targetUrl, bool $isActive = true, string $signingSecret = null, string $event = 'file.uploaded') — Creates a new webhook for the event. Returns the Uploadcare\Webhook class. Event types described here
• updateWebhook($id, array $parameters) — Updates an existing webhook with these parameters. Parameters can be:
  • target_url — A target callback URL;
  • event — The only file.uploaded event is supported at the moment.
  • is_active — Returns the webhook activity status.
  • signing_secret — Webhook signing secret. See Secure Webhooks
• deleteWebhook — Deletes a webhook by URL.

Uploadcare\Webhook class

This class implements Uploadcare\Interfaces\Response\WebhookInterface and has additional methods besides the interface:

• delete() — Deletes a webhook. Calls Uploadcare\Interfaces\Api\WebhookApiInterface::deleteWebhook() under the hood;
• updateUrl($url) — Updates a webhook with a new URL (WebhookApiInterface::updateWebhook()).
• activate() — Sets a webhook active (WebhookApiInterface::updateWebhook()).
• deactivate() — Sets a webhook as not active (WebhookApiInterface::updateWebhook()).

Conversion operations

You can convert documents, images and encode video files with Conversion API.

Document and image conversion

Create a new object for a subsequent conversion request:

The default arguments and examples are:

• $targetFormat = 'pdf' — Target format.
• $throwError = false — If set to true, a wrong request will throw an exception, otherwise, it'll return null.
• $store = true — The conversion results will go to your default storage.
• $pageNumber = 1 — Specifies pages to convert in multi-page documents.

After that, you can convert your file:

Result will contain one of two objects:

• ConvertedItemInterface object with conversion result in case of successful operation, or
• ResponseProblemInterface object in case of error (and $throwError in request sets to false).

The ConvertedItemInterface will contain a UUID of converted document and token with conversion job ID. You can request the conversion job status with this ID (or the ConvertedItemInterface object itself):

You can also pass the true to the setSaveInGroup method to the Request object.

In this case, the result of the document conversion will be stored in a group. See further details here.

This status object will implement ConversionStatusInterface with these methods:

• getStatus() — Status string. Pending, processing, finished, failed or canceled.
• getError() — An error string in case of error or null.
• getResult() — The StatusResultInterface object.

You can request batch conversion to process multiple documents:

$files can be an array / collection of file IDs or FileInfo objects and the result will be the implementation of BatchResponseInterface.

Video processing

Get the conversion API as in the previous step and perform VideoEncodingRequest

You can set various parameters for this request through the object setters:

If you don’t set any option to conversion request, the defaults will be as follows: mp4 format, full length and normal quality.

As a result of the Conversion API convertVideo method, you will get the ConversionResult or ResponseProblemobject. ConversionResult object that contains the uuid and token. You can use a token to request the status of a video conversion job with videoJobStatus method.

Also, you can request a batch video conversion with batchConvertVideo method. The first argument must be a collection of FileInfo or file uuid's, and the second — VideoEncodingRequest object.

Secure delivery

You can use your own custom domain and CDN provider for deliver files with authenticated URLs (see original documentation).

To generate authenticated URL from the library, you should do this:

• make a configuration as usual;
• make Uploadcare\AuthUrl\AuthUrlConfig object. This object will provide token, expire timestamp and your custom domain URL generator. $token in the constructor must be an instance of Uploadcare\AuthUrl\Token\TokenInterface;
• generate secure url from FileApi::generateSecureUrl($id) or from Uploadcare\File::generateSecureUrl()

For example:

Secure delivery for transformed images

You can set a custom ACL on a Secure URL with Image Transformations applied. Just add an Image UUID with transformations to the generateSecureUrl method:

Tests

PHP 7.1+ tests can be found in the "tests" directory. All tests are based on PHPUnit, so you need to have it installed prior to running tests.

Run tests with this command:

--exclude-group local-only means that a test will not send real API-requests. If you want to run all tests, create the .env.local file in the tests directory and place the following variables with your real public and secret API keys:

Useful links

Uploadcare documentation
Upload API reference
REST API reference
Changelog
Contributing guide
Security policy
Support