CloudConvert Laravel

A Laravel wrapper for the CloudConvert API

View project on GitHub

CloudConvert Laravel API

A Laravel wrapper for the CloudConvert API. See https://cloudconvert.org for more details.

Build Status

Installation

Install this package through Composer.

Add this to your composer.json dependencies:

"require": {
   "robbiep/cloudconvert-laravel": "1.*@dev"
}

Run composer install to download the required files.

Next you need to add the service provider to config/app.php

'providers' => array(
    ...
    'RobbieP\CloudConvertLaravel\CloudConvertLaravelServiceProvider'
)

One more step.

You need to publish the config php artisan config:publish robbiep/cloudconvert-laravel

Just enter your API key in config/packages/robbiep/cloudconvert-laravel/config.php

You can get your free API key by just registering at https://cloudconvert.org

Now you can use CloudConvert in your application!

Usage

There's many ways to use CloudConvert. I'll cover a few of them here, for all the converter options I suggest checking out the API docs.

File conversion

# Convert the file to /a/path/to/file.mp4
CloudConvert::file('/a/path/to/file.mov')->to('mp4');


# Convert the file and save it in a different location /a/new/path/to/new.mp4
CloudConvert::file('/a/path/to/biggles.webm')->to('/a/new/path/to/new.mp4');


# It also works with Laravel's file upload
if (Input::hasFile('photo'))
{
    CloudConvert::file( Input::file('photo') )->to('/a/local/path/profile_image.jpg');
}


# Convert the image to kitty.jpg with quality of 70%
CloudConvert::file('kitty.png')->quality(70)->to('jpg');


# Convert a PowerPoint presentation to a set of images, let's say you only want slides 2 to 4
# This will save presentation-2.jpg, presentation-3.jpg and presentation-4.jpg
CloudConvert::file('presentation.ppt')->pageRange(2, 4)->to('jpg');

Converter options

There are many more conversion options. I've put shortcuts like the ones above for the most common. However you can pass through any options you like using the withOptions method, such as:

# Convert the meow.wav to meow.mp3 with a frequecy of 44100 Hz and normalize the audio to +20dB
CloudConvert::file('meow.wav')->withOptions([
    'audio_frequency' => '44100', 
    'audio_normalize' => '+20dB'
])->to('mp3');


# Convert the fido_falls_over.mp4 to fido.gif but you only want 10 seconds of it, starting at 1:02
CloudConvert::file('fido_falls_over.mp4')->withOptions([
    'trim_from' => '62', 
    'trim_to' => '72'
])->to('fido.gif');

# Or the same with using the shortcuts:
CloudConvert::file('fido_falls_over.mp4')->trimFrom(62)->trimTo(72)->to('fido.gif');

Chaining multiple conversions

You can also chain multiple conversions on one process, like this:

# Convert a TrueType font in to all the fonts you need for a cross browser web font pack
CloudConvert::file('claw.ttf')->to('eot')->to('otf')->to('woff')->to('svg');

Remote files

It will also work with converting remote files (just make sure you provide a path to save it to)

# Convert Google's SVG logo hosted on Wikipedia to a png on your server
CloudConvert::file('http://upload.wikimedia.org/wikipedia/commons/a/aa/Logo_Google_2013_Official.svg')
            ->to('images/google.png');

Website screenshot

CloudConvert will also take a screenshot of a website and convert it to an image or pdf for you:

# Take a screenshot with the default options: 1024px with with full height of webpage
CloudConvert::website('www.nyan.cat')->to('screenshots/nyan.jpg');


# You can also specify the width and the height as converter options
CloudConvert::website('www.nyan.cat')
            ->withOptions([
                 'screen_width' => 1024,
                 'screen_height' => 700
            ])->to('screenshots/nyan.png');

Converting to and from external storage options

At the moment CloudConvert let you use FTP or Amazon S3 as storage options. However it looks like in the future they will add Google Drive and Dropbox to the API

**Please note: ** To use these storage options you will need to provide the configuration in the config/packages/robbiep/cloudconvert-laravel/config.php 

# Lets say you have a PDF and you want to convert it to an ePub file and 
# store it on your Amazon S3 bucket (defined in your config). It's this simple:
CloudConvert::file('/a/local/path/garfield.pdf')->to(CloudConvert::S3('Garfield_converted.epub'));


# You can also override the default options by providing them as an array as the second argument
CloudConvert::file('/a/local/path/garfield.pdf')
            ->to(CloudConvert::S3('Garfield_converted.epub', [
                'bucket'  => 'a-different-bucket',
                'acl'     => 'public-read',
                'region'  => 'us-east-1'
            ]));


# Now you want to convert the file on your S3 to a txt file and store it on a server via FTP
CloudConvert::file(CloudConvert::S3('Garfield_converted.epub'))
            ->to(CloudConvert::FTP('path/to/garfield.txt'));

It's that simple. The storage options CloudConvert::S3($path) and CloudConvert::FTP($path) can be used for both input files and output files.

Non-blocking conversion using a callback URL

If the conversion might take a long you could use:

# Script: send_conversion.php
CloudConvert::file('/a/path/to/file.mov')
            ->callback('http://myserver.com/save_file.php')
            ->convert('mp4');

# Script save_file.php
CloudConvert::useProcess($_REQUEST['url'])
            ->save();

Non-blocking conversion using a queue

To use queues you will need have set-up either beanstalk or iron in your config/queue.php

# The queue will check every second if the conversion has finished. 
# It times out after 120 seconds (configurable).
CloudConvert::file('/a/path/to/file.mov')->queue('to', '/a/path/to/file.mp4')

Conversion types

You can view the conversion types using the conversionTypes() method. It always returns a Laravel collection.

# To get all possible types
$types = CloudConvert::conversionTypes();


# To get all possible types in a specific group
$types = CloudConvert::conversionTypes('video');


# To get all possible output formats if you know the input format
$types = CloudConvert::input('pdf')->conversionTypes();


# Same if you know the output format and want to see what can be inputted
$types = CloudConvert::output('jpg')->conversionTypes();

Processes status

You may want to list all your processes, running, finished and failed. It always returns a Laravel collection.

# To get all possible types
$processes = CloudConvert::processes();

# To delete a process by ID
CloudConvert::deleteProcess($process_id);

Artisan commands

If you want to do quick conversions or calls to the API from your console, you can use the following commands:

Convert a file

# Options: --opions, --queue, --storage, --path
php artisan cloudconvert:convert video.mov mp4
php artisan cloudconvert:convert /path/to/video.mov converted.mp4 --storage='s3'

Website screenshot

# Options: --opions, --storage, --path
php artisan cloudconvert:website www.laravel.com jpg

Processes list

# Options: --delete (used with process_id)
# Argument: process_id (optional) - will show the status of that process
php artisan cloudconvert:processes <process_id>

Conversion types

# Options: --input, --output 
# (both optional - however if you included both you will see all the 
# possible converter options for those types, not just the default ones)
php artisan cloudconvert:types
php artisan cloudconvert:types --input='nice.pdf'
php artisan cloudconvert:types --input='doc' --output='jpg'

Todo

  • [x] Release
  • [ ] Write some more tests
  • [ ] Enable merging of multiple files
  • [x] Enable multiple conversions using one process
  • [ ] Refactor the commands

Contributing

  1. Fork it
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request

Credits

Thanks to Lunaweb Ltd. for their API. Go check it out.

Resources