Skip to content

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.

Packagist ↗GitHub ↗Changelog ↗v0.1.0Laravel 12+ · PHP 8.2+MIT

Installing

Install it with your package manager. Laravel 12+ · PHP 8.2+.

$ composer require runconvert/runconvert-laravel

Configuration

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 webhooks

Parameters

  • RUNCONVERT_API_KEYenvYour API key from Dashboard → API Keys.Required
  • RUNCONVERT_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']

Convert

Convert a file

RunConvert::convert($file, string $to, array $opts = []): ConvertResult

Converts 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'),
]);

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): array

Creates 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

From a controller
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): array

Polls 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

In a command
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): array

The 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

MP4 → MP3 options
$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(): array

The account, team and credit balance behind the API key.

Example

Credits left
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

routes
php artisan route:list --path=runconvert

#  POST  runconvert/webhook  RunConvert\Laravel\Http\WebhookController

Webhook events

Each verified delivery fires WebhookReceived, plus the event's own class. Every event exposes type(), job(), task() and the raw payload.

Example

Listen
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

Handle errors
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

.env
RUNCONVERT_TIMEOUT=30

Like RunConvert? Set us as a preferred source on Google.

Add to Preferred Sources