README

这是 CloudConvert API v2 的官方 PHP SDK。

安装

要安装 PHP SDK，您需要在项目中使用 Composer。

与 Guzzle 一起安装 SDK

composer require cloudconvert/cloudconvert-php guzzlehttp/guzzle

该包通过使用 PSR-7、PSR-17、PSR-18 和 HTTPlug 不绑定到任何特定的 HTTP 客户端。因此，您还需要安装提供 psr/http-client-implementation 和 psr/http-factory-implementation（例如 Guzzle）的包。

创建作业

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)

您可以使用 CloudConvert 作业构建器 查看各种任务类型的可用选项。

上传文件

通过 import/upload 任务（见文档）上传到 CloudConvert。此 SDK 提供了一个方便的上传方法

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


$job = (new Job())
    ->addTask(new Task('import/upload','upload-my-file'))
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'upload-my-file')
            ->set('output_format', 'pdf')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

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

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

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

upload() 方法接受一个字符串、PHP 资源或 PSR-7 StreamInterface 作为第二个参数。

您还可以直接允许客户端将文件上传到 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>

下载文件

CloudConvert 可以通过 export/url 任务生成用于使用的公共 URL。作业完成后，您可以使用 PHP SDK 下载输出文件。

$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);

}

download() 方法返回一个 PSR-7 StreamInterface，可以使用 detach() 作为 PHP 资源。

Webhooks

您可以在 CloudConvert 仪表板 上创建 Webhooks 并在那里找到所需的签名密钥。

$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()
            ->whereStatus(Task::STATUS_FINISHED) // get the task with 'finished' status ...
            ->whereName('export-it')[0];        // ... and with the name 'export-it'
// ...

或者，您可以使用 PSR-7 RequestInterface 构建 WebhookEvent

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

签名 URL

签名 URL 允许仅使用 URL 查询参数按需转换文件。PHP SDK 允许生成此类 URL。因此，您需要在 CloudConvert 仪表板 上获取签名 URL 基和签名密钥。

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

$job = (new Job())
    ->addTask(
        (new Task('import/url', 'import-my-file'))
            ->set('url', 'https://my.url/file.docx')
    )
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'import-my-file')
            ->set('output_format', 'pdf')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$signedUrlBase = 'SIGNED_URL_BASE';
$signingSecret = 'SIGNED_URL_SIGNING_SECRET';
$url = $cloudConvert->signedUrlBuilder()->createFromJob($signedUrlBase, $signingSecret, $job, 'CACHE_KEY');

设置区域

默认情况下，您的 账户设置 中的区域将被使用。或者，您可以设置一个固定区域

// Pass the region to the constructor
$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false,
    'region'  => 'us-east'
]);

单元测试

vendor/bin/phpunit --testsuite unit

集成测试

vendor/bin/phpunit --testsuite integration

默认情况下，此操作将针对具有官方 CloudConvert 账户的沙盒 API 运行集成测试。如果您想使用自己的账户，可以使用 CLOUDCONVERT_API_KEY 环境变量设置您的 API 密钥。在这种情况下，您需要将以下 MD5 哈希值列入白名单以用于沙盒 API（使用 CloudConvert 仪表板）。

53d6fe6b688c31c565907c81de625046  input.pdf
99d4c165f77af02015aa647770286cf9  input.png

资源

• API 文档
• CloudConvert 博客