README

这是CloudConvert API v2的官方Laravel包。此包依赖于PHP SDK v3。

安装

您可以通过Composer安装此包，同时安装Guzzle。

composer require cloudconvert/cloudconvert-laravel guzzlehttp/guzzle

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

接下来，您必须发布配置文件。

php artisan vendor:publish --provider="CloudConvert\Laravel\Providers\CloudConvertServiceProvider"

以下内容将被发布到config/cloudconvert.php

<?php
return [

    /**
     * You can generate API keys here: https://cloudconvert.com/dashboard/api/v2/keys.
     */

    'api_key' => env('CLOUDCONVERT_API_KEY', ''),

    /**
     * Use the CloudConvert Sanbox API (Defaults to false, which enables the Production API).
     */
    'sandbox' => env('CLOUDCONVERT_SANDBOX', false),

    /**
     * You can find the secret used at the webhook settings: https://cloudconvert.com/dashboard/api/v2/webhooks
     */
    'webhook_signing_secret' => env('CLOUDCONVERT_WEBHOOK_SIGNING_SECRET', '')

];

使用方法

配置完成后，您可以在CloudConvert外观上调用所有PHP SDK方法。

use \CloudConvert\Laravel\Facades\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;

CloudConvert::jobs()->create(
    (new Job())
    ->setTag('myjob-123')
    ->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')
    )
);

请参阅PHP SDK存储库以获取完整文档。

上传文件

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

use \CloudConvert\Models\Job;

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

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

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

$inputStream = fopen(Storage::path('my/input.docx'), 'r');

CloudConvert::tasks()->upload($uploadTask, $inputStream);

下载文件

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(Storage::path('out/' . $file->filename), 'w');
    
    stream_copy_to_stream($source, $dest);

}

Webhooks

此包可以帮助您处理CloudConvert的webhooks。默认情况下，它会验证所有传入请求的CloudConvert签名。当特定事件击中您的应用程序时，您可以轻松定义事件订阅者。

路由

您可以在webhook设置中创建您的webhook并将其指向类似https://your.app/webhook/cloudconvert的内容。请确保在包的配置文件中配置显示的签名密钥。

在应用程序的路由文件中，您必须将该路由传递给由本包提供的控制器。

Route::post('webhook/cloudconvert', '\CloudConvert\Laravel\CloudConvertWebhooksController');

由于此路由没有提供CSRF令牌验证，因此您还必须将该路由添加到VerifyCsrfToken中间件的except数组中

protected $except = [
    'webhook/cloudconvert',
];

事件

每当webhook事件击中您的应用程序时，该包将触发一个cloudconvert-webhooks::<event-name>事件（例如cloudconvert-webhooks::job.finished）。

事件的负载将是一个来自PHP SDK的WebhookEvent。应用程序中的事件订阅者可能看起来像这样

<?php

namespace App\Listeners;

use CloudConvert\Models\WebhookEvent;
use CloudConvert\Models\Job;
use CloudConvert\Models\Task;
use Illuminate\Support\Facades\Log;

class CloudConvertEventListener
{

    public function onJobFinished(WebhookEvent $event) {
        
        $job = $event->getJob();
        
        $job->getTag(); // can be used to store an ID
        
        $exportTask = $job->getTasks()
            ->whereStatus(Task::STATUS_FINISHED) // get the task with 'finished' status ...
            ->whereName('my-export-task')[0];    // ... and with the name 'my-export-task'
        
        // $exportTask->getResult() ...
        
    }

    public function onJobFailed(WebhookEvent $event) {
        
        $job = $event->getJob();
        
        $job->getTag(); // can be used to store an ID
        
        $failingTask =  $job->getTasks()->whereStatus(Task::STATUS_ERROR)[0];
        
        Log::error('CloudConvert task failed: ' . $failingTask->getId());
        
    }

    public function subscribe($events)
    {
        $events->listen(
            'cloudconvert-webhooks::job.finished',
            'App\Listeners\CloudConvertEventListener@onJobFinished'
        );

        $events->listen(
            'cloudconvert-webhooks::job.failed',
            'App\Listeners\CloudConvertEventListener@onJobFailed'
        );
    }

}

在EventServiceProvider中注册订阅者

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Event;
use Illuminate\Auth\Events\Registered;
use Illuminate\Auth\Listeners\SendEmailVerificationNotification;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        
    ];

    /**
     * The subscriber classes to register.
     *
     * @var array
     */
    protected $subscribe = [
        'App\Listeners\CloudConvertEventListener',
    ];
}

测试

vendor/bin/phpunit 

资源

• PHP SDK
• API文档
• CloudConvert博客