cloudconvert / cloudconvert-laravel
Laravel PHP SDK for CloudConvert APIs
Installs: 286 916
Dependents: 0
Suggesters: 0
Security: 0
Stars: 25
Watchers: 4
Forks: 16
Open Issues: 1
Requires
- php: ^7.1 || ^8.0
- cloudconvert/cloudconvert-php: ^3.1.0
- illuminate/container: ~5.8.0|^6.0|^7.0|^8.0|^9.0|^10.0 || ^11.0
- illuminate/http: ~5.8.0|^6.0|^7.0|^8.0|^9.0|^10.0 || ^11.0
- illuminate/routing: ~5.8.0|^6.0|^7.0|^8.0|^9.0|^10.0 || ^11.0
- illuminate/support: ~5.8.0|^6.0|^7.0|^8.0|^9.0|^10.0 || ^11.0
- nyholm/psr7: ^1.2
- symfony/psr-http-message-bridge: ^1.2|^2.0 || ^7.0
Requires (Dev)
- orchestra/testbench: ~3.8.0|^4.0|^5.0|^6.0|^7.0|^8.0 || ^9.0
- php-http/guzzle7-adapter: ^1.0
- phpunit/phpunit: ^7.0|^8.0|^9.5.10 || ^10.5
README
This is the official Laravel package for the CloudConvert API v2. This package depends on the PHP SDK v3.
Installation
You can install the package alongside Guzzle via composer:
composer require cloudconvert/cloudconvert-laravel guzzlehttp/guzzle
This package is not tied to any specific HTTP client by using PSR-7, PSR-17, PSR-18, and HTTPlug. Therefore, you will also need to install packages that provide psr/http-client-implementation
and psr/http-factory-implementation
(for example Guzzle).
Next you must publish the config file.
php artisan vendor:publish --provider="CloudConvert\Laravel\Providers\CloudConvertServiceProvider"
This is the content that will be published to 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', '') ];
Usage
Once configured you can call all the PHP SDK methods on the CloudConvert
facade.
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') ) );
Please check the PHP SDK repository for the full documentation.
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; $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);
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(Storage::path('out/' . $file->filename), 'w'); stream_copy_to_stream($source, $dest); }
Webhooks
This package can help you handle the CloudConvert webhooks. Out of the box it will verify the CloudConvert signature of all incoming requests. You can easily define event subscribers when specific events hit your app.
Route
You can create your webhook in the webhook settings and point it to something like https://your.app/webhook/cloudconvert
. Make sure to to configure the shown signing secret in the config file of this package.
In the routes file of your app you must pass that route to a controller provided by this package.
Route::post('webhook/cloudconvert', '\CloudConvert\Laravel\CloudConvertWebhooksController');
Because CSRF token validation is not availble for this route, you must also add that route to the except array of the VerifyCsrfToken
middleware:
protected $except = [ 'webhook/cloudconvert', ];
Events
Whenever a webhook event hits your app, the package fires a cloudconvert-webhooks::<event-name>
event (for example cloudconvert-webhooks::job.finished
).
The payload of the event will be a WebhookEvent
from the PHP SDK. An event subscriber in your app could look like this:
<?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' ); } }
Register the subscriber in the 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', ]; }
Tests
vendor/bin/phpunit