qaamgo/onlineconvert-api-sdk

Sdk for using the Online Convert Api version 2

Online Convert API version 2 PHP SDK v 3

This SDK provides a code base to interact with the API version 2 of Online-Convert.com, _(*1)

, _(*2)

Installation

The recommended way to install is through Composer., _(*3)

composer require qaamgo/onlineconvert-api-sdk

Getting started

Configuration

require 'vendor/autoload.php';

$config = new \OnlineConvert\Configuration();
$config->setApiKey('main', 'HERE YOUR API KEY');
$client = new \OnlineConvert\Client\OnlineConvertClient($config, 'main');
$syncApi = new \OnlineConvert\Api($client);
$asyncApi = new \OnlineConvert\Api($client, true);

Sending a full job

$syncJob = [
    'input' => [
        [
        'type' => \OnlineConvert\Endpoint\InputEndpoint::INPUT_TYPE_UPLOAD,
        'source' => '~/example.png'
        ],
        [
        'type' => \OnlineConvert\Endpoint\InputEndpoint::INPUT_TYPE_REMOTE,
        'source' => 'http://cdn.online-convert.com/images/logo-top.png'
        ]
    ],
    'conversion' => [
        [
        'target' => 'png'
        ],
        [
        'target' => 'mp4'
        ]
    ]
];

$asyncJob = [
    'input' => [
        [
        'type' => \OnlineConvert\Endpoint\InputEndpoint::INPUT_TYPE_UPLOAD,
        'source' => '~/example.png'             ],
        [
        'type' => \OnlineConvert\Endpoint\InputEndpoint::INPUT_TYPE_REMOTE,
        'source' => 'http://cdn.online-convert.com/images/logo-top.png'
        ]
    ],
    'conversion' => [
        [
        'target' => 'png'
        ],
        [
        'target' => 'mp4'
        ]
    ],
    'callback' => 'http://alert.me/when/job/is/finished'
];

$syncJob = $syncApi->postFullJob($syncJob)->getJobCreated();
$asyncJob = $asyncApi->postFullJob($asyncJob)->getJobCreated();

var_dump($syncJob, $asyncJob);

Sending a job with a gdrive_picker input

What is google drive picker

Google drive picker allows you to access files stored in your google drive account., _(*4)

You can find information about it in the official page, _(*5)

Meaning of each field: * type * Specifies that we want to use the google drive picker input * source * This must contain the FILE ID given back by the google drive picker * credentials * This must be an array containing the credentials for the selected file * At the moment you only need to pass the "token" field inside it * The "token" field is returned by the google drive picker when a file is selected * content_type * This field is mandatory when you select a Google Document * You can leave this field empty if you are selecting any other kind of file * EG: pdf, png, zip... * filename * This is the file name of the google drive picker file * If this field is not sent the file will be downloaded with the name output.<extension>, _(*6)

$job = [
    'input' => [
        [
            'type' => \OnlineConvert\Endpoint\InputEndpoint::INPUT_TYPE_GDRIVE_PICKER,
            'source' => '<put google drive picker file id here>',
            'credentials' => [
                'token' => '<put google drive picker token for the selected file here>'
            ],
            'content_type' => '<if this is a specific google document>',
            'filename' => '<name of the input file>'
        ]
    ],
    'conversion' => [
        [
            'target' => 'png'
        ]
    ]
];

After this just follow the previous examples on how to effectively send the job to the API., _(*7)

Sending a job using Cloud storage providers

The following is an example to send a job where we want to convert a file that we have stored in our Amazon S3 storage., _(*8)

If you want to know more please check our cloud storage API documentation, _(*9)

$job = [
    'input' => [
        [
            'type' => \OnlineConvert\Endpoint\InputEndpoint::INPUT_TYPE_CLOUD,
            'source' => 'amazons3',
            'parameters' => [
                'bucket' => 'your.bucket.name',
                'file' => 'the complete path to the file',
            ],
            'credentials' => [
                'accesskeyid' => 'your access key id',
                'secretaccesskey' => 'your secret access key',
            ]
        ]
    ],
    'conversion' => [
        [
            'target' => 'png'
        ]
    ]
];

After this just follow the previous examples on how to effectively send the job to the API., _(*10)

Downloading the Converted Files

You can download the converted files using the following code snippet:, _(*11)

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

$config = new \OnlineConvert\Configuration();
$config->setApiKey('main', 'PUT YOUR API KEY HERE');

// Remember to specify your own downloads folder.
$config->downloadFolder = __DIR__ . '/downloads';

$client = new \OnlineConvert\Client\OnlineConvertClient($config, 'main');
$syncApi = new \OnlineConvert\Api($client);
$outputEndpoint = $syncApi->getOutputEndpoint();

$syncJob = [
    'input' => [
        [
            'type' => \OnlineConvert\Endpoint\InputEndpoint::INPUT_TYPE_REMOTE,
            'source' => 'PUT URL HERE'
        ]
    ],
    'conversion' => [
        [
            'target' => 'jpg'
        ]
    ]
];

$job = $syncApi->postFullJob($syncJob)->getJobCreated();

// You will find the file/s in the downloads folder
$outputEndpoint->downloadOutputs($job);

Advanced usage

The class \OnlineConvert\Api::class has some shortcut methods that links it to the endpoints classes (EG: \OnlineConvert\Api::postFullJob()), but from the class you can call the real endpoint and their methods., _(*12)

Also, you can create endpoint classes one by one if you like. For this, check \OnlineConvert\Endpoint\Abstracted::_construct(), _(*13)

IMPORTANT: The class \OnlineConvert\Endpoint\JobsEndpoint can be used to send both synchronous and asynchronuos jobs; check \OnlineConvert\Endpoint\JobsEndpoint::setAsync(), _(*14)

You can also set up different headers into the client, and do some process using the token of a job., _(*15)

    $config = new \OnlineConvert\Configuration();
    $client = new \OnlineConvert\Client\OnlineConvertClient($config);
    $syncApi = new \OnlineConvert\Api($client);

    $ep = $syncApi->getJobsEndpoint();

    //Option 1
    $ep->getClient()->setHeader(\OnlineConvert\Client\Interfaced::HEADER_OC_API_KEY, 'YOUR API KEY');

    //Option 2
    //$client->setHeader(\OnlineConvert\Client\Interfaced::HEADER_OC_API_KEY, 'YOUR API KEY');
    //$ep->setClient($client);

    $job = $ep->postJob([]);

    $ip = $syncApi->getInputEndpoint();

    //WORK WITH TOKENS
    //OPTION 1
    $input = $ip->setUserToken($a['token'])->postJobInputRemote('http://www.online-convert.com/', $a['id']);

    //Option 2 (Apply also the previous options to set a header)
    //$ip->getClient()->setHeader(\OnlineConvert\Client\Interfaced::HEADER_OC_JOB_TOKEN, $a['token']);
    //$b = $ip->postJobInputRemote('http://www.online-convert.com/', $a['id']);

    var_dump($job, $input);

Manage exceptions

If you catch \OnlineConvert\Exception\OnlineConvertSdkException::class, you automatically catch all exception in this SDK, _(*16)

Getting url to upload file

• Send a job request
• Take the following keys from a job: server and id. You can use \OnlineConvert\Api or \OnlineConvert\Endpoint\JobsEndpoint to get the job information. You will get something like:

    [
        [id] => 00000000-0000-0000-0000-000000000000
        [token] => some_token_here
            ...
        [server] => http://www9.online-convert.com/dl
        ...
    ]

• Now with this information you can make this call:

\OnlineConvert\Client\OnlineConvertClient->generateUrl(\OnlineConvert\Endpoint\Resources::URL_POST_FILE, ['server' => $server, 'job_id' => $jobId])

• Also these token can be useful for some operations that you might want to share with your users

Uploading files directly to the Online-Convert.com servers via AJAX

Real life case: I want to send our user files directly to the API, because sending them to my app first and then to the API costs too much time., _(*17)

Considerations: Normally, this will save us process time, space on the hard drive and improve user experience, but it's advised to have a fallback alternative that works without using JS., _(*18)

The following example is using JQuery., _(*19)

IMPORTANT: The upload MUST be done one by one. Thus, you need one form per file., _(*20)

HTML CODE

<form id="postFile" enctype="multipart/form-data" method="post" action="javascript:;" accept-charset="utf-8">
        <input name="file" type="file" id="file"/> <input type="submit" id="upload-btn"/>
</form>

JS

$(document).ready(function () {
        $('#postFile').submit(function (event) {
            event.preventDefault();

            var formData = new FormData($(this)[0]);

            $.ajax({
                url: 'URL_GENERATED_TO_UPLOAD_FILE',
                type: 'POST',
                data: formData,
                async: false,
                cache: false,
                processData: false,
                contentType: false,
                mimeType: 'multipart/form-data',
                headers: {
                    'x-oc-token': 'JOB_TOKEN_HERE',
                    'cache-control': 'no-cache'
                },
                success: function () {
                    window.alert('Success');
                },
                error: function () {
                    window.alert('Error');
                }
            });
        });
    });