{"id":20159547,"url":"https://github.com/transloadit/php-sdk","last_synced_at":"2025-05-16T11:05:12.626Z","repository":{"id":1221945,"uuid":"1141410","full_name":"transloadit/php-sdk","owner":"transloadit","description":"Transloadit's official PHP SDK","archived":false,"fork":false,"pushed_at":"2025-01-14T20:06:04.000Z","size":495,"stargazers_count":62,"open_issues_count":0,"forks_count":23,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-09T07:01:53.812Z","etag":null,"topics":["encoding","php","transloadit","uploading"],"latest_commit_sha":null,"homepage":"https://transloadit.com/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/transloadit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-12-05T23:00:39.000Z","updated_at":"2025-02-10T04:00:28.000Z","dependencies_parsed_at":"2024-12-29T18:09:02.633Z","dependency_job_id":"caf9c1e3-8084-49aa-bcf6-8a32d2ab6403","html_url":"https://github.com/transloadit/php-sdk","commit_stats":{"total_commits":251,"total_committers":19,"mean_commits":"13.210526315789474","dds":0.398406374501992,"last_synced_commit":"875644a72de2540607e92281356fbe57fe10288c"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fphp-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fphp-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fphp-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transloadit%2Fphp-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transloadit","download_url":"https://codeload.github.com/transloadit/php-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253405040,"owners_count":21903114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["encoding","php","transloadit","uploading"],"created_at":"2024-11-14T00:08:55.830Z","updated_at":"2025-05-16T11:05:07.618Z","avatar_url":"https://github.com/transloadit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Transloadit PHP SDK\n\n[![Test Actions Status][test_badge]][test_link]\n[![Code coverage][codecov_badge]][codecov_link]\n![Packagist PHP Version Support][php_verison_badge]\n[![License][licence_badge]][licence_link]\n\n## Introduction\n\nThe Transloadit PHP SDK provides a simple and efficient way to interact with Transloadit's file processing service in your PHP applications. With this SDK, you can easily:\n\n- Create and manage file upload assemblies\n- Use pre-defined templates for common file processing tasks\n- Handle notifications and retrieve assembly statuses\n- Integrate Transloadit's powerful file processing capabilities into your PHP projects\n\nThis SDK simplifies the process of working with Transloadit's REST API, allowing you to focus on building great applications without worrying about the complexities of file processing.\n\n## Install\n\n```\ncomposer require transloadit/php-sdk\n```\n\nKeep your Transloadit account's Auth Key \u0026 Secret nearby. You can check\nthe [API credentials](https://transloadit.com/accounts/credentials) page for\nthese values.\n\n## Usage\n\n\u003c!-- This section is generated by: make docs --\u003e\n\n### 1. Upload and resize an image from your server\n\nThis example demonstrates how you can use the SDK to create an \u003cdfn\u003eAssembly\u003c/dfn\u003e\non your server.\n\nIt takes a sample image file, uploads it to Transloadit, and starts a\nresizing job on it.\n\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\n\nuse transloadit\\Transloadit;\n\n$transloadit = new Transloadit([\n  'key'    =\u003e 'MY_TRANSLOADIT_KEY',\n  'secret' =\u003e 'MY_TRANSLOADIT_SECRET',\n]);\n\n$response = $transloadit-\u003ecreateAssembly([\n  'files' =\u003e ['/PATH/TO/FILE.jpg'],\n  'params' =\u003e [\n    'steps' =\u003e [\n      'resize' =\u003e [\n        'robot' =\u003e '/image/resize',\n        'width' =\u003e 200,\n        'height' =\u003e 100,\n      ],\n    ],\n  ],\n]);\n\n// Show the results of the assembly we spawned\necho '\u003cpre\u003e';\nprint_r($response);\necho '\u003c/pre\u003e';\n\n```\n\n### 2. Create a simple end-user upload form\n\nThis example shows you how to create a simple Transloadit upload form\nthat redirects back to your site after the upload is done.\n\nOnce the script receives the redirect request, the current status for\nthis \u003cdfn\u003eAssembly\u003c/dfn\u003e is shown using `Transloadit::response()`.\n\n\u003cdiv class=\"alert alert-note\"\u003e\n  \u003cstrong\u003eNote:\u003c/strong\u003e There is no guarantee that the \u003cdfn\u003eAssembly\u003c/dfn\u003e has already finished\n  executing by the time the \u003ccode\u003e$response\u003c/code\u003e is fetched. You should use\n  the \u003ccode\u003enotify_url\u003c/code\u003e parameter for this.\n\u003c/div\u003e\n\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\n\nuse transloadit\\Transloadit;\n\n$transloadit = new Transloadit([\n  'key'    =\u003e 'MY_TRANSLOADIT_KEY',\n  'secret' =\u003e 'MY_TRANSLOADIT_SECRET',\n]);\n\n// Check if this request is a Transloadit redirect_url notification.\n// If so fetch the response and output the current assembly status:\n$response = Transloadit::response();\nif ($response) {\n  echo '\u003ch1\u003eAssembly Status:\u003c/h1\u003e';\n  echo '\u003cpre\u003e';\n  print_r($response);\n  echo '\u003c/pre\u003e';\n  exit;\n}\n\n// This should work on most environments, but you might have to modify\n// this for your particular setup.\n$redirectUrl = sprintf('http://%s%s', $_SERVER['HTTP_HOST'], $_SERVER['REQUEST_URI']);\n\n// Setup a simple file upload form that resizes an image to 200x100px\necho $transloadit-\u003ecreateAssemblyForm([\n  'params' =\u003e [\n    'steps' =\u003e [\n      'resize' =\u003e [\n        'robot' =\u003e '/image/resize',\n        'width' =\u003e 200,\n        'height' =\u003e 100,\n      ],\n    ],\n    'redirect_url' =\u003e $redirectUrl,\n  ],\n]);\n?\u003e\n\u003ch1\u003ePick an image to resize\u003c/h1\u003e\n\u003cinput name=\"example_upload\" type=\"file\"\u003e\n\u003cinput type=\"submit\" value=\"Upload\"\u003e\n\u003c/form\u003e\n\n```\n\n### 3. Use Uppy for file uploads\n\nWe recommend using [Uppy](https://transloadit.com/docs/sdks/uppy/), our next-gen file uploader for the web, instead of the jQuery SDK. Uppy provides a more modern, flexible, and feature-rich solution for handling file uploads with Transloadit.\n\nTo integrate Uppy with your PHP backend:\n\n1. Include Uppy in your HTML:\n\n```html\n\u003clink\n  href=\"https://releases.transloadit.com/uppy/v3.3.1/uppy.min.css\"\n  rel=\"stylesheet\"\n/\u003e\n\u003cscript src=\"https://releases.transloadit.com/uppy/v3.3.1/uppy.min.js\"\u003e\u003c/script\u003e\n```\n\n2. Initialize Uppy with Transloadit plugin:\n\n```html\n\u003cdiv id=\"uppy\"\u003e\u003c/div\u003e\n\n\u003cscript\u003e\n  const uppy = new Uppy.Core()\n    .use(Uppy.Dashboard, {\n      inline: true,\n      target: '#uppy'\n    })\n    .use(Uppy.Transloadit, {\n      params: {\n        auth: { key: 'MY_TRANSLOADIT_KEY' },\n        template_id: 'MY_TEMPLATE_ID',\n        notify_url: 'https://your-site.com/transloadit_notify.php'\n      }\n    })\n\n  uppy.on('complete', (result) =\u003e {\n    console.log('Upload complete! We've uploaded these files:', result.successful)\n  })\n\u003c/script\u003e\n```\n\n3. Handle the assembly status on your PHP backend:\n\nCreate a new file named `transloadit_notify.php` in your project:\n\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\n\nuse transloadit\\Transloadit;\n\n$transloadit = new Transloadit([\n  'key'    =\u003e 'MY_TRANSLOADIT_KEY',\n  'secret' =\u003e 'MY_TRANSLOADIT_SECRET',\n]);\n\n$response = Transloadit::response();\nif ($response) {\n  // Process the assembly result\n  $assemblyId = $response-\u003edata['assembly_id'];\n  $assemblyStatus = $response-\u003edata['ok'];\n\n  // You can store the assembly information in your database\n  // or perform any other necessary actions here\n\n  // Log the response for debugging\n  error_log('Transloadit Assembly Completed: ' . $assemblyId);\n  error_log('Assembly Status: ' . ($assemblyStatus ? 'Success' : 'Failed'));\n\n  // Optionally, you can write the response to a file\n  file_put_contents('transloadit_response_' . $assemblyId . '.json', json_encode($response-\u003edata));\n\n  // Send a 200 OK response to Transloadit\n  http_response_code(200);\n  echo 'OK';\n} else {\n  // If it's not a Transloadit notification, return a 400 Bad Request\n  http_response_code(400);\n  echo 'Bad Request';\n}\n?\u003e\n```\n\nMake sure to replace `'https://your-site.com/transloadit_notify.php'` with the actual URL where you'll host this PHP script.\n\nFor more detailed information on using Uppy with Transloadit, please refer to our [Uppy documentation](https://transloadit.com/docs/sdks/uppy/).\n\n### 4. Fetch the Assembly Status JSON\n\nYou can use the `getAssembly` method to get the \u003cdfn\u003eAssembly\u003c/dfn\u003e Status.\n\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\n$assemblyId = 'MY_ASSEMBLY_ID';\n\n$transloadit = new Transloadit([\n  'key'    =\u003e 'MY_TRANSLOADIT_KEY',\n  'secret' =\u003e 'MY_TRANSLOADIT_SECRET',\n]);\n\n$response = $transloadit-\u003egetAssembly($assemblyId);\n\necho '\u003cpre\u003e';\nprint_r($response);\necho '\u003c/pre\u003e';\n\n```\n\n### 5. Create an Assembly with a Template.\n\nThis example demonstrates how you can use the SDK to create an \u003cdfn\u003eAssembly\u003c/dfn\u003e\nwith \u003cdfn\u003eTemplates\u003c/dfn\u003e.\n\nYou are expected to create a \u003cdfn\u003eTemplate\u003c/dfn\u003e on your Transloadit account dashboard\nand add the \u003cdfn\u003eTemplate\u003c/dfn\u003e ID here.\n\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\n\nuse transloadit\\Transloadit;\n\n$transloadit = new Transloadit([\n  'key'    =\u003e 'MY_TRANSLOADIT_KEY',\n  'secret' =\u003e 'MY_TRANSLOADIT_SECRET',\n]);\n\n$response = $transloadit-\u003ecreateAssembly([\n  'files' =\u003e ['/PATH/TO/FILE.jpg'],\n  'params' =\u003e [\n    'template_id' =\u003e 'MY_TEMPLATE_ID',\n  ],\n]);\n\n// Show the results of the assembly we spawned\necho '\u003cpre\u003e';\nprint_r($response);\necho '\u003c/pre\u003e';\n\n```\n\n### Signature Auth (Assemblies)\n\n\u003cdfn\u003eSignature Authentication\u003c/dfn\u003e is done by the PHP SDK by default internally so you do not need to worry about this :)\n\n### Signature Auth (Smart CDN)\n\nYou can use the `signedSmartCDNUrl` method to generate signed URLs for Transloadit's [Smart CDN](https://transloadit.com/services/content-delivery/):\n\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\n\nuse transloadit\\Transloadit;\n\n$transloadit = new Transloadit([\n  'key'    =\u003e 'MY_TRANSLOADIT_KEY',\n  'secret' =\u003e 'MY_TRANSLOADIT_SECRET',\n]);\n\n// Basic usage\n$url = $transloadit-\u003esignedSmartCDNUrl(\n  'your-workspace-slug',\n  'your-template-slug',\n  'avatars/jane.jpg'\n);\n\n// Advanced usage with custom parameters and expiry\n$url = $transloadit-\u003esignedSmartCDNUrl(\n  'your-workspace-slug',\n  'your-template-slug',\n  'avatars/jane.jpg',\n  ['width' =\u003e 100, 'height' =\u003e 100],  // Additional parameters\n  1732550672867,                      // Expiry date in milliseconds since epoch\n);\n\necho $url;\n```\n\nThe generated URL will be in the format:\n\n```\nhttps://{workspace-slug}.tlcdn.com/{template-slug}/{input-field}?{query-params}\u0026sig=sha256:{signature}\n```\n\nNote that:\n\n- The URL will expire after the specified time (default: 1 hour)\n- All parameters are properly encoded\n- The signature is generated using HMAC SHA-256\n- Query parameters are sorted alphabetically before signing\n\n## Example\n\nFor fully working examples take a look at [`examples/`](https://github.com/transloadit/php-sdk/tree/HEAD/examples).\n\n## API\n\n### $Transloadit = new Transloadit($properties = []);\n\nCreates a new Transloadit instance and applies the given $properties.\n\n#### $Transloadit-\u003ekey = null;\n\nThe auth key of your Transloadit account.\n\n#### $Transloadit-\u003esecret = null;\n\nThe auth secret of your Transloadit account.\n\n#### $Transloadit-\u003erequest($options = [], $execute = true);\n\nCreates a new `TransloaditRequest` using the `$Transloadit-\u003ekey` and\n`$Transloadit-\u003esecret` properties.\n\nIf `$execute` is set to `true`, `$TransloaditRequest-\u003eexecute()` will be\ncalled and used as the return value.\n\nOtherwise the new `TransloaditRequest` instance is being returned.\n\n#### $Transloadit-\u003ecreateAssemblyForm($options = []);\n\nCreates a new Transloadit assembly form including the hidden 'params' and\n'signature' fields. A closing form tag is not included.\n\n`$options` is an array of `TransloaditRequest` properties to be used.\nFor example: `\"params\"`, `\"expires\"`, `\"endpoint\"`, etc..\n\nIn addition to that, you can also pass an `\"attributes\"` key, which allows\nyou to set custom form attributes. For example:\n\n```php\n$Transloadit-\u003ecreateAssemblyForm(array(\n  'attributes' =\u003e array(\n    'id'    =\u003e 'my_great_upload_form',\n    'class' =\u003e 'transloadit_form',\n  ),\n));\n```\n\n#### $Transloadit-\u003ecreateAssembly($options);\n\nSends a new assembly request to Transloadit. This is the preferred way of\nuploading files from your server.\n\n`$options` is an array of `TransloaditRequest` properties to be used with the exception that you can\nalso use the `waitForCompletion` option here:\n\n`waitForCompletion` is a boolean (default is false) to indicate whether you want to wait for the\nAssembly to finish with all encoding results present before the callback is called. If\nwaitForCompletion is true, this SDK will poll for status updates and return when all encoding work\nis done.\n\nCheck example #1 above for more information.\n\n#### $Transloadit-\u003egetAssembly($assemblyId);\n\nRetrieves the Assembly status json for a given Assembly ID.\n\n#### $Transloadit-\u003ecancelAssembly($assemblyId);\n\nCancels an assembly that is currently executing and prevents any further encodings costing money.\n\nThis will result in `ASSEMBLY_NOT_FOUND` errors if invoked on assemblies that are not currently\nexecuting (anymore).\n\n#### Transloadit::response()\n\nThis static method is used to parse the notifications Transloadit sends to\nyour server.\n\nThere are two kinds of notifications this method handles:\n\n- When using the `redirect_url` parameter, and Transloadit redirects\n  back to your site, a `$_GET['assembly_url']` query parameter gets added.\n  This method detects the presence of this parameter and fetches the current\n  assembly status from that url and returns it as a `TransloaditResponse`.\n- When using the `notify_url` parameter, Transloadit sends a\n  `$_POST['transloadit']` parameter. This method detects this, and parses\n  the notification JSON into a `TransloaditResponse` object for you.\n\nIf the current request does not seem to be invoked by Transloadit, this\nmethod returns `false`.\n\n### $TransloaditRequest = new TransloaditRequest($properties = []);\n\nCreates a new TransloaditRequest instance and applies the given $properties.\n\n#### $TransloaditRequest-\u003ekey = null;\n\nThe auth key of your Transloadit account.\n\n#### $TransloaditRequest-\u003esecret = null;\n\nThe auth secret of your Transloadit account.\n\n#### $TransloaditRequest-\u003emethod = 'GET';\n\nInherited from `CurlRequest`. Can be used to set the type of request to be\nmade.\n\n#### $TransloaditRequest-\u003ecurlOptions = [];\n\nInherited 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).\n\nHere is an [example](examples/6-assembly-with-timeout.php) that illustrates\nusing 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).\n\nThe 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.\n\n#### $TransloaditRequest-\u003eendpoint = 'https://api2.transloadit.com';\n\nThe endpoint to send this request to.\n\n#### $TransloaditRequest-\u003epath = null;\n\nThe url path to request.\n\n#### $TransloaditRequest-\u003eurl = null;\n\nInherited from `CurlRequest`. Lets you overwrite the above endpoint / path\nproperties with a fully custom url alltogether.\n\n#### $TransloaditRequest-\u003efields = [];\n\nA list of additional fields to send along with your request. Transloadit\nwill include those in all assembly related notifications.\n\n#### $TransloaditRequest-\u003efiles = [];\n\nAn array of paths to local files you would like to upload. For example:\n\n```php\n$TransloaditRequest-\u003efiles = array('/my/file.jpg');\n```\n\nor\n\n```php\n$TransloaditRequest-\u003efiles = array('my_upload' =\u003e '/my/file.jpg');\n```\n\nThe first example would automatically give your file a field name of\n`'file_1'` when executing the request.\n\n#### $TransloaditRequest-\u003eparams = [];\n\nAn array representing the JSON params to be send to Transloadit. You\ndo not have to include an `'auth'` key here, as this class handles that\nfor you as part of `$TransloaditRequest-\u003eprepare()`.\n\n#### $TransloaditRequest-\u003eexpires = '+2 hours';\n\nIf you have configured a '`$TransloaditRequest-\u003esecret`', this class will\nautomatically sign your request. The expires property lets you configure\nthe duration for which the signature is valid.\n\n#### $TransloaditRequest-\u003eheaders = [];\n\nLets you send additional headers along with your request. You should not\nhave to change this property.\n\n#### $TransloaditRequest-\u003eexecute()\n\nSends this request to Transloadit and returns a `TransloaditResponse`\ninstance.\n\n### $TransloaditResponse = new TransloaditResponse($properties = []);\n\nCreates a new TransloaditResponse instance and applies the given $properties.\n\n#### $TransloaditResponse-\u003edata = null;\n\nInherited from `CurlResponse`. Contains an array of the parsed JSON\nresponse from Transloadit.\n\nYou should generally only access this property after having checked for\nerrors using `$TransloaditResponse-\u003eerror()`.\n\n#### $TransloaditResponse-\u003eerror();\n\nReturns `false` or a string containing an explanation of what went wrong.\n\nAll of the following will cause an error string to be returned:\n\n- Network issues of any kind\n- The Transloadit response JSON contains an `{\"error\": \"...\"}` key\n- A malformed response was received\n\n**_Note_**: You will need to set waitForCompletion = True in the $Transloadit-\u003ecreateAssembly($options) function call.\n\n## Contributing\n\nFeel free to fork this project. We will happily merge bug fixes or other small\nimprovements. For bigger changes you should probably get in touch with us\nbefore you start to avoid not seeing them merged.\n\n### Testing\n\n#### Basic Tests\n\n```bash\nmake test\n```\n\n#### System Tests\n\nSystem tests require:\n\n1. Valid Transloadit credentials in environment:\n\n```bash\nexport TRANSLOADIT_KEY='your-auth-key'\nexport TRANSLOADIT_SECRET='your-auth-secret'\n```\n\nThen run:\n\n```bash\nmake test-all\n```\n\n#### Node.js Reference Implementation Parity Assertions\n\nThe SDK includes assertions that compare URL signing with our reference Node.js implementation. To run these tests:\n\n1. Requirements:\n\n   - Node.js installed\n   - tsx installed globally (`npm install -g tsx`)\n\n2. Install dependencies:\n\n```bash\nnpm install -g tsx\n```\n\n3. Run the test:\n\n```bash\nexport TRANSLOADIT_KEY='your-auth-key'\nexport TRANSLOADIT_SECRET='your-auth-secret'\nTEST_NODE_PARITY=1 make test-all\n```\n\nCI opts-into `TEST_NODE_PARITY=1`, and you can optionally do this locally as well.\n\n### Releasing a new version\n\nTo release, say `3.2.0` [Packagist](https://packagist.org/packages/transloadit/php-sdk), follow these steps:\n\n1. Make sure `PACKAGIST_TOKEN` is set in your `.env` file\n1. Make sure you are in main: `git checkout main`\n1. Update `CHANGELOG.md` and `composer.json`\n1. Commit: `git add CHANGELOG.md composer.json \u0026\u0026 git commit -m \"Release 3.2.0\"`\n1. Tag, push, and release: `source env.sh \u0026\u0026 VERSION=3.2.0 ./release.sh`\n\nThis project implements the [Semantic Versioning](http://semver.org/) guidelines.\n\n## License\n\n[MIT Licensed](LICENSE)\n\n[test_badge]: https://github.com/transloadit/php-sdk/actions/workflows/ci.yml/badge.svg\n[test_link]: https://github.com/transloadit/php-sdk/actions/workflows/ci.yml\n[codecov_badge]: https://codecov.io/gh/transloadit/php-sdk/branch/main/graph/badge.svg\n[codecov_link]: https://codecov.io/gh/transloadit/php-sdk\n[php_verison_badge]: https://img.shields.io/packagist/php-v/transloadit/php-sdk\n[licence_badge]: https://img.shields.io/badge/License-MIT-green.svg\n[licence_link]: https://github.com/transloadit/php-sdk/blob/main/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransloadit%2Fphp-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransloadit%2Fphp-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransloadit%2Fphp-sdk/lists"}