Laravel SDK
The RunConvert SDK for Laravel 12 and 13: a facade, config from your .env, and a webhook route that checks signatures and fires Laravel events. Every method of the PHP SDK is available through the facade or dependency injection.
Installing
Install it with your package manager. Laravel 12+ · PHP 8.2+.
$ composer require runconvert/runconvert-laravel$ php artisan vendor:publish --tag=runconvert-configConfiguration
The package registers itself (auto-discovery). Put your API key in .env; publish config/runconvert.php only if you want to change more. Keep the key on the server.
Example
RUNCONVERT_API_KEY=rc_live_...
RUNCONVERT_WEBHOOK_SECRET=whsec_... # only if you use webhooksreturn [
'api_key' => env('RUNCONVERT_API_KEY'),
'base_url' => env('RUNCONVERT_BASE_URL', 'https://api.runconvert.com/v3'),
'timeout' => (int) env('RUNCONVERT_TIMEOUT', 60),
'webhook' => [
'path' => env('RUNCONVERT_WEBHOOK_PATH', 'runconvert/webhook'),
'secret' => env('RUNCONVERT_WEBHOOK_SECRET'),
'middleware' => [],
],
];Parameters
RUNCONVERT_API_KEYenvYour API key from Dashboard → API Keys.RequiredRUNCONVERT_BASE_URLenvDefaults to https://api.runconvert.com/v3.RUNCONVERT_TIMEOUTenvSeconds per API request. Default 60. Uploads and downloads have no limit.RUNCONVERT_WEBHOOK_PATHenvWhere webhooks are received. Default runconvert/webhook; null turns the route off.RUNCONVERT_WEBHOOK_SECRETenvYour webhook endpoint's signing secret.
Quick start
Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result. Use the facade anywhere, or type-hint RunConvert\RunConvert to get the same client injected.
Example
use RunConvert\Laravel\Facades\RunConvert;
$result = RunConvert::convert(
storage_path('app/report.docx'),
'pdf',
['out_dir' => storage_path('app/converted')],
);
$result->saved; // ['.../converted/report.pdf']use RunConvert\RunConvert;
public function store(Request $request, RunConvert $rc)
{
$result = $rc->convert($request->file('doc')->path(), 'pdf', [
'filename' => $request->file('doc')->getClientOriginalName(),
'out_dir' => storage_path('app/converted'),
]);
return ['files' => $result->saved];
}Convert
Convert a file
RunConvert::convert($file, string $to, array $opts = []): ConvertResultConverts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits. For big files, run it in a queued job and keep requests fast.
Example
$result = RunConvert::convert(storage_path('app/report.docx'), 'pdf', [
'out_dir' => storage_path('app/converted'),
]);class ConvertToMp3 implements ShouldQueue
{
use Queueable;
public function __construct(public string $url) {}
public function handle(): void
{
RunConvert::convert($this->url, 'mp3', [
'options' => ['audioBitrate' => '192k'],
'out_dir' => storage_path('app/audio'),
]);
}
}Parameters
$filestring|resourceA local path, an http(s) URL (imported by RunConvert), or a stream.Required$tostringThe target format, e.g. "pdf" or "mp3".Required'from'stringThe source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.'options'arrayEngine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.'out_dir'stringSave the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.'filename'stringThe file's name when you pass bytes or a stream.'tag'stringA label to find the job later, e.g. "invoices".'timeout'floatSeconds to wait for the job before giving up.
Returns
ConvertResult with ->job, ->files and ->saved.
Jobs
Create a job
$rc->jobs->create(array $tasks, ?string $tag = null, ?array $metadata = null): arrayCreates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to. Start it in a request and finish it in a webhook listener, instead of waiting.
Example
use RunConvert\RunConvert;
public function store(Request $request, RunConvert $rc)
{
$job = $rc->jobs->create([
'import' => ['operation' => 'import/url', 'source_url' => $request->input('url')],
'convert' => ['operation' => 'convert', 'input' => 'import', 'input_format' => 'mp4', 'output_format' => 'mp3'],
'export' => ['operation' => 'export/url', 'input' => 'convert'],
], tag: 'user-' . $request->user()->id);
return ['job' => $job['id']]; // finish it in a webhook listener
}Parameters
$tasksarrayNamed task definitions. Names use letters, digits, - or _ (up to 64 characters).Required$tag?stringA label to find the job later, e.g. "invoices".$metadata?arrayYour own key-value data, returned with the job and in webhooks.
Returns
The job, with its tasks. All job methods (get, list, all, wait, cancel, delete) are as in the PHP reference.
Wait for a job
$rc->jobs->wait(string $id, ?float $timeout = null, ?callable $onUpdate = null, bool $throwOnError = true): arrayPolls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one. Prefer webhooks in web requests; waiting is fine in queued jobs and commands.
Example
use RunConvert\Jobs;
$done = app(\RunConvert\RunConvert::class)->jobs->wait($id, timeout: 300);
foreach (Jobs::exportedFiles($done) as $file) {
Storage::put('converted/' . $file['filename'], Http::get($file['url'])->body());
}Parameters
$idstringThe job's ID.Required$timeout?floatSeconds to wait. Throws WaitTimeoutException after it.
Formats
Engines for a pair
$rc->operations->forPair(string $input, string $output): arrayThe engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public. forInput() and list() work the same way.
Example
$pair = app(\RunConvert\RunConvert::class)->operations->forPair('mp4', 'mp3');{
"input": "mp4",
"output": "mp3",
"engines": [
{ "name": "ffmpeg", "credits": 1,
"options": [
{ "name": "audioBitrate", "type": "string",
"description": "Target audio bitrate in kbps.",
"supported_values": ["32k", "48k", "64k", "80k", …] },
…
] }
]
}Parameters
$inputstringThe input format, e.g. "mp4".Required$outputstringThe output format, e.g. "mp3".Required
Account
Credits and team
RunConvert::me(): arrayThe account, team and credit balance behind the API key.
Example
RunConvert::me()['credits']['total_remaining'];{
"user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
"team": { "name": "Acme" },
"credits": { "mode": "wallet", "total_remaining": 4820 }
}Webhooks
Webhook route
The package adds POST /runconvert/webhook (config: webhook.path). In Dashboard → Webhooks, point an endpoint at https://your-app.com/runconvert/webhook and put its secret in RUNCONVERT_WEBHOOK_SECRET. Every delivery's X-RunConvert-Signature is checked; bad ones get 400. No CSRF token is needed.
Example
php artisan route:list --path=runconvert
# POST runconvert/webhook RunConvert\Laravel\Http\WebhookControllerWebhook events
Each verified delivery fires WebhookReceived, plus the event's own class. Every event exposes type(), job(), task() and the raw payload.
Example
use Illuminate\Support\Facades\Event;
use RunConvert\Jobs;
use RunConvert\Laravel\Events\JobFinished;
Event::listen(function (JobFinished $event) {
$job = app(\RunConvert\RunConvert::class)->jobs->get($event->job()['id']);
foreach (Jobs::exportedFiles($job) as $file) {
// $file['url'] is a temporary download link
}
});{
"event": "job.finished",
"job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}Events
WebhookReceivedevery eventFired for every verified delivery.JobCreated / JobProcessingjob.created / job.processingA job was created / started.JobFinishedjob.finishedAll tasks finished: download the results.JobFailedjob.errorA task failed: task() has code, reason and message.TaskFinished / TaskFailedtask.finished / task.errorOne task finished / failed.
More
Errors
Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA.
Example
use RunConvert\JobFailedException;
use RunConvert\RunConvertException;
try {
RunConvert::convert($path, 'pdf', ['out_dir' => storage_path('app/converted')]);
} catch (JobFailedException $e) {
report($e); // $e->getTask()['reason']
} catch (RunConvertException $e) {
abort(502, $e->getErrorCode());
}Error types
RunConvert\RunConvertExceptionclassThe API said no: getStatus(), getErrorCode() (e.g. BILLING_INSUFFICIENT_CREDITS), getMessage().RunConvert\JobFailedExceptionclassThe job ended in error: getJob(), getTask() with code, reason and message.RunConvert\WaitTimeoutExceptionclasswait() ran past its timeout.
Retries and timeouts
Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice. Set RUNCONVERT_TIMEOUT for the per-request limit.
Example
RUNCONVERT_TIMEOUT=30