README

Conversion Tools is an online service for converting files between formats — XML, Excel, PDF, Word, CSV, JSON, images, audio, video, and more.

This library integrates file conversion into PHP applications via the Conversion Tools REST API.

Requirements

PHP 8.1 or later
ext-curl, ext-json (enabled by default in standard PHP installs)

Installation

composer require conversiontools/conversiontools-php

Quick Start

Get your API token from conversiontools.io/profile.

<?php

require_once __DIR__ . '/vendor/autoload.php';

use ConversionTools\ConversionToolsClient;

$client = new ConversionToolsClient([
    'api_token' => 'your-api-token',
]);

$client->convert('convert.pdf_to_word', 'input.pdf', 'output.docx');

Examples

Convert a file

$client->convert('convert.xml_to_csv', 'data.xml', 'data.csv', [
    'delimiter' => 'tabulation',
]);

Convert a URL

$client->convert('convert.website_to_pdf', ['url' => 'https://example.com'], 'result.pdf');

Use a pre-uploaded file

$fileId = $client->files->upload('input.pdf');

$client->convert('convert.pdf_to_word', ['file_id' => $fileId], 'output.docx');

Manual control (upload → task → wait → download)

$fileId = $client->files->upload('input.pdf');

$task = $client->createTask('convert.pdf_to_word', ['file_id' => $fileId]);

$task->wait([
    'on_progress' => function (array $status): void {
        echo "{$status['conversionProgress']}% [{$status['status']}]\n";
    },
]);

$task->downloadTo('output.docx');

Fire and forget (webhook)

$taskId = $client->convert(
    conversionType: 'convert.pdf_to_word',
    input:          'input.pdf',
    wait:           false,
    callbackUrl:    'https://your-app.com/webhook',
);

Error handling

use ConversionTools\Exceptions\ConversionToolsException;
use ConversionTools\Exceptions\RateLimitException;
use ConversionTools\Exceptions\ConversionException;

try {
    $client->convert('convert.pdf_to_word', 'input.pdf', 'output.docx');
} catch (RateLimitException $e) {
    echo "Quota exceeded. Daily remaining: {$e->limits['daily']['remaining']}\n";
} catch (ConversionException $e) {
    echo "Conversion failed for task {$e->taskId}: {$e->taskError}\n";
} catch (ConversionToolsException $e) {
    echo "Error [{$e->errorCode}]: {$e->getMessage()}\n";
}

API

`new ConversionToolsClient(array $config)`

Key	Type	Default	Description
`api_token`	string	required	API token from your profile
`base_url`	string	`https://api.conversiontools.io/v1`	API base URL
`timeout`	float (ms)	`300000`	Request timeout
`retries`	int	`3`	Retry attempts on transient errors
`retry_delay`	float (ms)	`1000`	Initial retry delay (doubles each attempt)
`polling_interval`	float (ms)	`5000`	How often to poll task status
`max_polling_interval`	float (ms)	`30000`	Max polling interval (with backoff)
`polling_backoff`	float	`1.5`	Polling backoff multiplier
`webhook_url`	string	`null`	Default webhook URL for all tasks
`on_conversion_progress`	callable	`null`	Called on each poll with progress info

`convert(string $conversionType, string|array $input, ?string $output, array $options, bool $wait, ?string $callbackUrl): string`

One-call conversion. Returns the output file path (if $wait=true) or task ID (if $wait=false).

Input formats:

'path/to/file.pdf' — local file path
['url' => 'https://...'] — URL-based conversion
['file_id' => '...'] — pre-uploaded file

`createTask(string $conversionType, array $options, ?string $callbackUrl): Task`

Create a task without waiting. Returns a Task object.

`getTask(string $taskId): Task`

Retrieve an existing task by ID.

`getRateLimits(): ?array`

Returns rate limit info from the last API response.

$limits = $client->getRateLimits();
// ['daily' => ['limit' => 30, 'remaining' => 25], 'monthly' => [...]]

`Task`

Method	Description
`wait(array $options = [])`	Poll until complete. Accepts `polling_interval`, `max_polling_interval`, `timeout`, `on_progress`
`downloadTo(?string $path)`	Download result to file, returns resolved path
`downloadBytes()`	Download result as string
`refresh()`	Re-fetch status from API
`getStatus()`	Returns current status string
`isSuccess()` / `isError()` / `isRunning()` / `isComplete()`	Status helpers
`toArray()`	Serialize task state

`$client->files`

Method	Description
`upload(string $filePath): string`	Upload file, returns `file_id`
`getInfo(string $fileId): array`	Get file metadata
`downloadBytes(string $fileId): string`	Download as string
`downloadTo(string $fileId, ?string $outputPath): string`	Download to file

`$client->tasks`

Method	Description
`create(array $request): array`	Create task (low-level)
`getStatus(string $taskId): array`	Get task status
`list(?string $status): array`	List tasks, optionally filtered by status

Exceptions

All exceptions extend ConversionToolsException and expose $errorCode and $httpStatus.

Exception	Trigger
`AuthenticationException`	Invalid or missing API token
`ValidationException`	Bad request parameters
`RateLimitException`	Quota exceeded — has `$limits` property
`FileNotFoundException`	File ID not found
`TaskNotFoundException`	Task ID not found
`ConversionException`	Task failed — has `$taskId` and `$taskError`
`TimeoutException`	Request or polling timed out
`NetworkException`	Connection error

Documentation

Full list of conversion types and options: conversiontools.io/api-documentation

conversiontools / conversiontools-php

Maintainers

Details