Download the PHP package transloadit/php-sdk without Composer

Transloadit PHP SDK

[![Test Actions Status][test_badge]][test_link] [![Code coverage][codecov_badge]][codecov_link] ![Packagist PHP Version Support][php_verison_badge] [![License][licence_badge]][licence_link]

A PHP Integration for Transloadit's file uploading and encoding service

Intro

Transloadit is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, Transloadit is the Swiss Army Knife for your files.

This is a PHP SDK to make it easy to talk to the Transloadit REST API.

Install

Keep your Transloadit account's Auth Key & Secret nearby. You can check the API credentials page for these values.

Usage

1. Upload and resize an image from your server

This example demonstrates how you can use the SDK to create an Assembly on your server.

It takes a sample image file, uploads it to Transloadit, and starts a resizing job on it.

2. Create a simple end-user upload form

This example shows you how to create a simple Transloadit upload form that redirects back to your site after the upload is done.

Once the script receives the redirect request, the current status for this Assembly is shown using Transloadit::response().

3. Integrate the jQuery plugin into the previous example

Integrating the jQuery plugin simply means adding a few lines of JavaScript to the previous example. Check the HTML comments below to see what changed.

Alternatively, check out Uppy, our next-gen file uploader for the web.

4. Fetch the Assembly Status JSON

You can use the getAssembly method to get the Assembly Status.

5. Create an Assembly with a Template.

This example demonstrates how you can use the SDK to create an Assembly with Templates.

You are expected to create a Template on your Transloadit account dashboard and add the Template ID here.

Signature Auth

Signature Authentication is done by the PHP SDK by default internally so you do not need to worry about this :) ## Example For fully working examples take a look at [`examples/`](https://github.com/transloadit/php-sdk/tree/HEAD/examples). ## API ### $Transloadit = new Transloadit($properties = []); Creates a new Transloadit instance and applies the given $properties. #### $Transloadit->key = null; The auth key of your Transloadit account. #### $Transloadit->secret = null; The auth secret of your Transloadit account. #### $Transloadit->request($options = [], $execute = true); Creates a new `TransloaditRequest` using the `$Transloadit->key` and `$Transloadit->secret` properties. If `$execute` is set to `true`, `$TransloaditRequest->execute()` will be called and used as the return value. Otherwise the new `TransloaditRequest` instance is being returned. #### $Transloadit->createAssemblyForm($options = []); Creates a new Transloadit assembly form including the hidden 'params' and 'signature' fields. A closing form tag is not included. `$options` is an array of `TransloaditRequest` properties to be used. For example: `"params"`, `"expires"`, `"endpoint"`, etc.. In addition to that, you can also pass an `"attributes"` key, which allows you to set custom form attributes. For example: #### $Transloadit->createAssembly($options); Sends a new assembly request to Transloadit. This is the preferred way of uploading files from your server. `$options` is an array of `TransloaditRequest` properties to be used with the exception that you can also use the `waitForCompletion` option here: `waitForCompletion` is a boolean (default is false) to indicate whether you want to wait for the Assembly to finish with all encoding results present before the callback is called. If waitForCompletion is true, this SDK will poll for status updates and return when all encoding work is done. Check example #1 above for more information. #### $Transloadit->getAssembly($assemblyId); Retrieves the Assembly status json for a given Assembly ID. #### $Transloadit->cancelAssembly($assemblyId); Cancels an assembly that is currently executing and prevents any further encodings costing money. This will result in `ASSEMBLY_NOT_FOUND` errors if invoked on assemblies that are not currently executing (anymore). #### Transloadit::response() This static method is used to parse the notifications Transloadit sends to your server. There are two kinds of notifications this method handles: - When using the `redirect_url` parameter, and Transloadit redirects back to your site, a `$_GET['assembly_url']` query parameter gets added. This method detects the presence of this parameter and fetches the current assembly status from that url and returns it as a `TransloaditResponse`. - When using the `notify_url` parameter, Transloadit sends a `$_POST['transloadit']` parameter. This method detects this, and parses the notification JSON into a `TransloaditResponse` object for you. If the current request does not seem to be invoked by Transloadit, this method returns `false`. ### $TransloaditRequest = new TransloaditRequest($properties = []); Creates a new TransloaditRequest instance and applies the given $properties. #### $TransloaditRequest->key = null; The auth key of your Transloadit account. #### $TransloaditRequest->secret = null; The auth secret of your Transloadit account. #### $TransloaditRequest->method = 'GET'; Inherited from `CurlRequest`. Can be used to set the type of request to be made. #### $TransloaditRequest->curlOptions = []; Inherited from `CurlRequest`. Can be used to tweak cURL behavior using [any cURL option that your PHP/cURL version supports](https://www.php.net/manual/en/function.curl-setopt.php). Here is an [example](examples/6-assembly-with-timeout.php) that illustrates using this option to change the timeout of a request (drastically, to `1ms`, just to prove you can make the SDK abort after a time of your choosing). The default timeouts and options depend on the cURL version on your system and can be verified by checking `phpinfo()` and the [curl_setopt](https://www.php.net/manual/en/function.curl-setopt.php) documentation. #### $TransloaditRequest->endpoint = 'https://api2.transloadit.com'; The endpoint to send this request to. #### $TransloaditRequest->path = null; The url path to request. #### $TransloaditRequest->url = null; Inherited from `CurlRequest`. Lets you overwrite the above endpoint / path properties with a fully custom url alltogether. #### $TransloaditRequest->fields = []; A list of additional fields to send along with your request. Transloadit will include those in all assembly related notifications. #### $TransloaditRequest->files = []; An array of paths to local files you would like to upload. For example: or The first example would automatically give your file a field name of `'file_1'` when executing the request. #### $TransloaditRequest->params = []; An array representing the JSON params to be send to Transloadit. You do not have to include an `'auth'` key here, as this class handles that for you as part of `$TransloaditRequest->prepare()`. #### $TransloaditRequest->expires = '+2 hours'; If you have configured a '`$TransloaditRequest->secret`', this class will automatically sign your request. The expires property lets you configure the duration for which the signature is valid. #### $TransloaditRequest->headers = []; Lets you send additional headers along with your request. You should not have to change this property. #### $TransloaditRequest->execute() Sends this request to Transloadit and returns a `TransloaditResponse` instance. ### $TransloaditResponse = new TransloaditResponse($properties = []); Creates a new TransloaditResponse instance and applies the given $properties. #### $TransloaditResponse->data = null; Inherited from `CurlResponse`. Contains an array of the parsed JSON response from Transloadit. You should generally only access this property after having checked for errors using `$TransloaditResponse->error()`. #### $TransloaditResponse->error(); Returns `false` or a string containing an explanation of what went wrong. All of the following will cause an error string to be returned: - Network issues of any kind - The Transloadit response JSON contains an `{"error": "..."}` key - A malformed response was received **_Note_**: You will need to set waitForCompletion = True in the $Transloadit->createAssembly($options) function call. ## Contributing Feel free to fork this project. We will happily merge bug fixes or other small improvements. For bigger changes you should probably get in touch with us before you start to avoid not seeing them merged. ## Versioning This project implements the Semantic Versioning guidelines. Releases will be numbered with the following format: `..` And constructed with the following guidelines: - Breaking backward compatibility bumps the major (and resets the minor and patch) - New additions without breaking backward compatibility bumps the minor (and resets the patch) - Bug fixes and misc changes bumps the patch For more information on SemVer, please visit http://semver.org/. ## Releasing a new version ## License [MIT Licensed](LICENSE) [test_badge]: https://github.com/transloadit/php-sdk/actions/workflows/tests.yml/badge.svg [test_link]: https://github.com/transloadit/php-sdk/actions/workflows/tests.yml [codecov_badge]: https://codecov.io/gh/transloadit/php-sdk/branch/main/graph/badge.svg [codecov_link]: https://codecov.io/gh/transloadit/php-sdk [php_verison_badge]: https://img.shields.io/packagist/php-v/transloadit/php-sdk [licence_badge]: https://img.shields.io/badge/License-MIT-green.svg [licence_link]: https://github.com/transloadit/php-sdk/blob/main/LICENSE