This example project demonstrates the uploadcare-php capabilities.

The project is based on the Symfony Framework, and the library can be used in any PHP environment on its own.

• Demo-project installation
• Container initialization
• Direct initialization
• Project info
• File operations
  • Upload file
  • Get files list and file info
  • Example of store file
  • Example of delete file
  • Batch store files
  • Batch delete files
• Group operations
  • Create group of files
• Conversion operations
  • Convert document
  • Get document conversion job status
  • Convert video
  • Video conversion job status
• Webhook operations
  • List of project webhooks
  • Create webhook
  • Update webhook
  • Delete webhook

Docker is an easy option to run this project in a package. Here’s how to deploy this demo project with Docker.

1. Clone this repository and build a Docker image:

docker build -t uploadcare-example-project -f Dockerfile .

2. Run the image:

docker run -it --rm -p 8000:8000 -e UPLOADCARE_PUBLIC_KEY=<your public key> -e UPLOADCARE_SECRET_KEY=<your secret key> uploadcare-example-project sh

3. Install composer packages (composer install) in the container shell and run a simple dev-server:

php -S 0.0.0.0:8000 public/index.php

4. Open the project’s web-interface in your web browser locally:

http://localhost:8000.

Requirements:

• php 8.1
• ext-ctype
• ext-iconv
• ext-curl

First steps:

1. Clone this repository.
2. Run composer install from project's root.
3. Check out examples.

parameters:
    uploadcare_public_key: '%env(UPLOADCARE_PUBLIC_KEY)%'
    uploadcare_secret_key: '%env(UPLOADCARE_SECRET_KEY)%'

services:
    Uploadcare\Interfaces\ConfigurationInterface:
        class: Uploadcare\Configuration
        factory: ['Uploadcare\Configuration', 'create']
        arguments: ['%uploadcare_public_key%', '%uploadcare_secret_key%']

    uploadcare.configuration:
        alias: 'Uploadcare\Interfaces\ConfigurationInterface'

    Uploadcare\Api:
        arguments:
            - '@uploadcare.configuration'

See working example in config/services.yaml

// config/uploadcare.php
return [
    'uploadcare_public_key' => env('UPLOADCARE_PUBLIC_KEY'),
    'UPLOADCARE_SECRET_KEY' => env('UPLOADCARE_SECRET_KEY'),
];

// app/providers/UploadcareServiceProvider.php
namespace App\Providers;

use Illuminate\Foundation\Application;
use Illuminate\Support\ServiceProvider;
use Uploadcare\Api;
use Uploadcare\Configuration;
use Uploadcare\Interfaces\ConfigurationInterface;

class UploadcareProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->bind(ConfigurationInterface::class, function () {
            return Configuration::create(config('uploadcare.public_key'), config('uploadcare.secret_key'));
        });

        $this->app->bind(Api::class, function (Application $app) {
            return new Api($app->get(ConfigurationInterface::class));
        });
    }
}

Define variables or constants with Uploadcare public and secret keys:

(new \Symfony\Component\Dotenv\Dotenv())->bootEnv(__DIR__ . '/.env');

// Or something like that
defined('UPLOADCARE_PUBLIC_KEY') or define('UPLOADCARE_PUBLIC_KEY', '<Your public key>');
defined('UPLOADCARE_SECRET_KEY') or define('UPLOADCARE_SECRET_KEY', '<Your secret key>');

Make a configuration object and API instance:

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

Or make an API instance with factory:

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

All web-examples are accessible with a development web-server by Symfony CLI.

You can get the project information by its public key.

Console example, Web example. The web example sits in the / (root) directory.

See App\Command\UploadFileCommand (src/Command/UploadFileCommand.php);

There are a few ways to upload files. You can upload files from a file path, a resource created by \fopen() function of the SplFileObject implementation, from a remote URL, and from the string contents.

All these uploading options are supported as console commands. For example, this command will upload a file from the path:

bin/console app:upload-file /path/to/file

Read help to learn more about other parameters:

app:upload-file --help

Check out the controller example App\Controller\UploadController and the markup template templates/upload/index.html.twig.

This example shows upload operations in the web UI. Most web-services provide an option to limit the uploading file size. In this simple example, you’ll limit the file size on a server, and can perform one-piece uploading.

Steps to run:

1. Open https://localhost:8000/upload in your web browser.
2. Select a file to upload and then see how it’s uploaded.

You can also add metadata to the file before upload.

If you have files in your project, you can see them in the /file-list directory or by using a app:file-info [file-id] command. There are console examples in src/Command/FileInfoCommand.php and web examples in the src/Controller/FileInfoController.php

On the file info page you will see the common information (uuid, original file name, type, url, etc.) and add-ons info. Addons are:

• Objects recognition info — allows you to get the information about objects on the image.
• Remove Background info — you can automatically remove background from the image.
• Antivirus scan info — all uploaded files are scan for viruses with ClamAV.

This option makes sense when you upload a file with the store field option set to 0. Anyway, you can call the store method on any file. See examples in StoreFileController.

Please, remember that your files will be deleted after 24 hours in case you not store them and your project has not "Auto store" option.

You can delete any file from the file-info screen. Find examples in DeleteFileController.

You can apply the Store operation for all files or for selected files. Look at /batch-store and BatchStoreController for examples.

You can delete all files or selected files with a batch delete operation. See /batch-delete and BatchDeleteController for examples.

You can see your groups of files in /groups ("Group list" menu item). You can go deeper and see the group info by clicking the to group ID in the list. Find examples in GroupController::index and GroupController::info.

You can see your file list In the /group-create directory ("Create group" menu item). Also, you can select files and create a group. Find examples in GroupController::createGroup.

After creating a group, your browser will redirect to the /group-info page.

Uploadcare API provides options to convert documents (DOCs, PDFs, etc.) and video-files to various formats. See Document Conversion and Video Encoding documentation.

In this library, you don’t need to create the conversion URLs manually, and just create a special object for each conversion (document or video) and use it through the library API.

To convert a document from one format to another, create Uploadcare\Conversion\DocumentConversionRequest and set it as a target data. For example:

$configuration = \Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'], $_ENV['UPLOADCARE_SECRET_KEY']);
$api = new \Uploadcare\Api($configuration);
$dcr = (new Uploadcare\Conversion\DocumentConversionRequest())
    ->setTargetFormat('png')
    ->setStore(true)
    ->setThrowError(false)
    ->setPageNumber(2);
$file = $api->file()->fileInfo('1822793d-5cdb-418e-8545-6bd6a5dd74bd');

$result = $api->conversion()->convertDocument($file, $dcr);

In this case, we take a PDF file and convert its second page to a PNG image. The $result variable will contain either:

• Uploadcare\Interfaces\Conversion\ConvertedItemInterface if everything is okay.
• Uploadcare\Interfaces\Response\ResponseProblemInterface in case the conversion cannot be done, or your account plan doesn’t support the document conversion.

ConvertedItemInterface contains UUID of the converted document and a token, that can be used in a conversion status request.

If you pass true to the setThrowError method of DocumentConversionRequest, any conversion problem will throw Uploadcare\Exception\ConversionException. Otherwise, the response will contain ResponseProblemInterface. Examples can be found in /convert-document ("Convert Document" menu item), and the code examples in DocumentConversionController

After the document is converted successfully, you’ll be redirected to the Document conversion status page:

See the code example in DocumentConversionController::conversionResult.

To create a video conversion request, make the Uploadcare\Conversion\VideoEncodingRequest and add request data to it. See Video Encoding documentation for the detailed description and Uploadcare\Interfaces\Conversion\VideoEncodingRequestInterface for library API options.

For example, you can request converting a video file to the WebM format, resize it to 720px in width, while preserving the aspect ratio, compress the file and store it:

$configuration = \Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'], $_ENV['UPLOADCARE_SECRET_KEY']);
$api = new \Uploadcare\Api($configuration);
$ver = (new \Uploadcare\Conversion\VideoEncodingRequest())
    ->setTargetFormat('webm')
    ->setHorizontalSize(720)
    ->setResizeMode('preserve_ratio')
    ->setQuality('lightest')
    ->setStore(true);
$file = $api->file()->fileInfo('f24a5fdd-8318-4b3f-a77e-00be2ec47576');

$result = $api->conversion()->convertVideo($file, $ver);

You can also trim the video by setting start and end time in H:MM:SS.sss or MM:SS.sss formats.

The $result (as in document conversion) will contain either ConvertedItemInterface or ResponseProblemInterface.

You can see how it works by opening any video file info in the web UI and clicking the "Request video conversion" button.

See code examples in VideoConversionController::conversionRequest.

After the video is converted successfully, your browser will redirect to the Video conversion status page. This page looks like the Document conversion status, because the conversion status object implements the same interface.

Uploadcare provides an option to call any URL by the file uploading (webhooks). The library API provides methods to create, update and delete webhooks.

You can see the list of project webhooks in /webhooks ("List of project webhooks" menu item). Also, you can call the method $api->webhook()->listWebhooks() to get this list (CollectionInterface will be returned).

See code examples in WebhooksController::index.

The webhook creation runs in /webhook-create ("Create new webhook" menu item). You need to set the target URL to create a webhook.

See code examples in WebhooksController::createWebhook

You can click on "Update" button in the webhook list and get the update form. There, you can change the URL or a webhook’s event. See code examples in WebhooksController::updateWebhook.

You can delete a webhook from a webhook list. Code examples in WebhooksController::deleteWebhook.