cloudconvert/cloudconvert-php

There is no license information available for the latest version (3.0.1) of this package.

PHP SDK for CloudConvert APIs

3.0.1 2019-12-22 15:05 UTC

This package is auto-updated.

Last update: 2020-01-22 15:22:06 UTC


README

This is the official PHP SDK v3 for the CloudConvert API v2. For API v1, please use v2 branch of this repository.

Build Status Latest Stable Version Total Downloads License

Install

To install the PHP SDK you will need to be using Composer in your project. To install it please see the docs.

composer require cloudconvert/cloudconvert-php

This package (cloudconvert/cloudconvert-php) is not tied to any specific library that sends HTTP messages. Instead, it uses Httplug to let users choose whichever PSR-7 implementation and HTTP client they want to use.

If you just want to get started quickly you should run the following command:

composer require cloudconvert/cloudconvert-php php-http/guzzle6-adapter guzzlehttp/psr7

This will install the library itself along with an HTTP client adapter that uses Guzzle as transport method (provided by Httplug) and a PSR-7 implementation (provided by Guzzle).

Creating Jobs

use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;


$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);


$job = (new Job())
    ->setTag('myjob-1')
    ->addTask(
        (new Task('import/url', 'import-my-file'))
            ->set('url','https://my-url')
    )
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'import-my-file')
            ->set('output_format', 'pdf')
            ->set('some_other_option', 'value')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$cloudconvert->jobs()->create($job)

You can use the CloudConvert Job Builder to see the available options for the various task types.

Uploading Files

Uploads to CloudConvert are done via import/upload tasks (see the docs). This SDK offers a convenient upload method:

use \CloudConvert\Models\Job;
use \CloudConvert\Models\ImportUploadTask;


$job = (new Job())
    ->addTask(new Task('import/upload','upload-my-file'));
//  ->addTask(...);

$cloudconvert->jobs()->create($job);

$uploadTask = $job->getTasks()->name('upload-my-file')[0];

$cloudconvert->tasks()->upload($uploadTask, fopen('./file.pdf', 'r'));

The upload() method accepts a string, PHP resource or PSR-7 StreamInterface as second parameter.

You can also directly allow clients to upload files to CloudConvert:

<form action="<?=$uploadTask->getResult()->form->url?>"
      method="POST"
      enctype="multipart/form-data">
    <? foreach ((array)$uploadTask->getResult()->form->parameters as $parameter => $value) { ?>
        <input type="hidden" name="<?=$parameter?>" value="<?=$value?>">
    <? } ?>
    <input type="file" name="file">
    <input type="submit">
</form>

Downloading Files

CloudConvert can generate public URLs for using export/url tasks. You can use the PHP SDK to download the output files when the Job is finished.

$cloudconvert->jobs()->wait($job); // Wait for job completion

foreach ($job->getExportUrls() as $file) {

    $source = $cloudconvert->getHttpTransport()->download($file->url)->detach();
    $dest = fopen('output/' . $file->filename, 'w');
    
    stream_copy_to_stream($source, $dest);

}

The download() method returns a PSR-7 StreamInterface, which can be used as a PHP resource using detach().

Webhooks

Webhooks can be created on the CloudConvert Dashboard and you can also find the required signing secret there.

$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);

$signingSecret = '...'; // You can find it in your webhook settings

$payload = @file_get_contents('php://input');
$signature = $_SERVER['HTTP_CLOUDCONVERT_SIGNATURE'];

try {
    $webhookEvent = $cloudconvert->webhookHandler()->constructEvent($payload, $signature, $signingSecret);
} catch(\CloudConvert\Exceptions\UnexpectedDataException $e) {
    // Invalid payload
    http_response_code(400);
    exit();
} catch(\CloudConvert\Exceptions\SignatureVerificationException $e) {
    // Invalid signature
    http_response_code(400);
    exit();
}

$job = $webhookEvent->getJob();

$job->getTag(); // can be used to store an ID

$exportTask = $job->getTasks()
            ->status(Task::STATUS_FINISHED) // get the task with 'finished' status ...
            ->name('export-it')[0]);        // ... and with the name 'export-it'
// ...

Alternatively, you can construct a WebhookEvent using a PSR-7 RequestInterface:

$webhookEvent = $cloudconvert->webhookHandler()->constructEventFromRequest($request, $signingSecret);

Unit Tests

vendor/bin/phpunit --testsuite unit

Integration Tests

vendor/bin/phpunit --testsuite integration

By default, this runs the integration tests against the Sandbox API with an official CloudConvert account. If you would like to use your own account, you can set your API key using the CLOUDCONVERT_API_KEY enviroment variable. In this case you need to whitelist the following MD5 hashes for Sandbox API (using the CloudConvert dashboard).

53d6fe6b688c31c565907c81de625046  input.pdf
99d4c165f77af02015aa647770286cf9  input.png

Resources