Plugin to convert anything to anything using cloudconvert
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Kirby 3 Cloudconvert

GitHub release License Kirby Version

Plugin to convert anything to anything using cloudconvert.

Commerical Usage

This plugin is free but if you use it in a commercial project please consider to


  • for devkit-setup use composer require bnomei/kirby3-cloudconvert or
  • extract latest release of as folder site/plugins/kirby3-cloudconvert

Installation as a gitsubmodule is not supported.


TD;DR Calling File-Method is performant since it only converts the file if it was modified or new.


Using Kirby\Cms\File object for $options['file'] is recommended. In that case the modified timestamp will be checked against a cached value and a conversion triggered only if a file was modified or output does not exist. This is the default behaviour for the FileMethod provided by this plugin.

DANGER: There is no check (yet) if a file is currently processed by cloudconvert. This might be improved at a later point.


When a path is used then file will be created only if ouput does not exist. You need to do modification checks and removing of old files yourself before starting the conversion.

How to convert files on demand (synchronously)?

Example 1: docx to pdf

if($fileWord = $page->file('test.docx')) {
    $filePDF = $fileWord->cloudconvert(
            'inputformat' => 'docx',
            'outputformat' => 'pdf',
        str_replace('.docx', '.pdf', $fileWord->root()),
        false // wait for conversion to be done
    echo $fileWord->url().PHP_EOL;
    if($filePDF) {
        echo $filePDF->url();

Hooks: How to convert files on upload/replace (asynchronously by default)?

Example 2: gif to webm and mp4

In Kirbys config file add this... then use panel to upload a gif to an image/file section.

function customConvertHook($file) {
    if($file->extension() == 'gif') {

                'inputformat' => 'gif',
                'outputformat' => 'webm',
                'save' => true, // keep file at cloud to avoid another download from cloudconvert-server

                'inputformat' => 'gif',
                'outputformat' => 'mp4',

return [
    // ... other config settings
    'hooks' => [
        'file.create:after' => function($file) {
        'file.replace:after' => function($newFile, $oldFile) {

Other Usecases

Example 3: convert ai to svg and optimize

This example shows how to use this plugin with my thumb imageoptim plugin.

$fileSvg = $file->cloudconvert(
        'inputformat' => 'ai',
        'outputformat' => 'svg',
    null, // auto-rename with extension
    false // on-demand aka synchonous aka wait
if($fileSvg) {
    // NOTE: resize() is called to trigger stuff like optimziers (see thumb-imageoptim plugin)
    $fileSvgOptimized = $fileSvg->resize();
    echo svg($fileSvgOptimized->root()); // use kirbys svg helper to inline the svg

Example 4: How to convert image files for srcsets? jpg to webp.

This example shows how to use this plugin with my srcset plugin.

config file

return [
    // ... other settings
    'bnomei.srcset.types' => ['jpg', 'webp'],
    'bnomei.srcset.resize' => function (\Kirby\Cms\File $file, int $width, string $type) {
        // NOTE: resize() is called to trigger stuff like optimziers (see thumb-imageoptim plugin)

        // use jpg to create webp
        if($file->extension() == 'jpg' && $type == 'webp') {
            $fileWebp = $file->cloudconvert(
                    'inputformat' => 'jpg',
                    'outputformat' => 'webp',
                null, // auto-rename with extension
                false // on-demand aka synchonous aka wait
            if($fileWebp) {
                return $fileWebp->resize($width);
        // otherwise default to returning image
        return $file->resize($width);

Global cloudconvert helper function

This plugin provides a helper function to call the cloudconvert api.

$obj = cloudconvert($options); // will change extension but keep path
$obj = cloudconvert($options, $outputPath); // provide different path
$obj = cloudconvert($options, $outputPath, $async); // a/sync

Retrun Values

  • Kirby\Cms\File if $options['file'] is one as well and $async == false
  • otherwise it returns an instance of CloudConvert\Process
  • or null on error


All settings have to be prefixed with bnomei.cloudconvert..


  • default: null – your cloudconvert apikey


  • default: asynchronous or synchronous conversion depending on params.


  • default: true


  • default: By default this plugin requires the file to be public otherwise use upload here. On localhost upload is used as a default.
    'input' => 'download', // but automatically uses 'upload' on localhost

TIP: consider setting up presets to manage your settings from within the cloudconvert dashboard instead of the Kirby config file.


  • default: false


  • default: callback to kirbyLog()


This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.



It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.