transloadit/php-sdk

Transloadit SDK

维护者

详细信息

github.com/transloadit/php-sdk

主页

源代码

问题

安装次数: 282,629

依赖: 0

建议者: 0

安全: 0

星标: 61

关注者: 7

分支: 23

开放问题: 0

3.1.0 2023-07-04 15:13 UTC

Requires

  • php: >=7.4.0

Requires (Dev)

MIT 4f7481006a2795b1af9af124dcd354a052956fc7

imagefileaudiodocumentvideoencodingwaveformresizingprocessingThumbnailstransloadituploading

This package is auto-updated.

Last update: 2024-09-04 17:56:12 UTC

README

Test Actions Status Code coverage Packagist PHP Version Support License

介绍

Transloadit PHP SDK 提供了一种简单高效的方式，用于在您的 PHP 应用程序中与 Transloadit 的文件处理服务进行交互。使用此 SDK，您可以轻松地

  • 创建和管理文件上传组件
  • 使用预定义的模板进行常见的文件处理任务
  • 处理通知并检索组件状态
  • 将 Transloadit 强大的文件处理功能集成到您的 PHP 项目中

此 SDK 简化了与 Transloadit REST API 的工作流程，使您能够专注于构建优秀应用程序，无需担心文件处理的复杂性。

安装

composer require transloadit/php-sdk

请将您的 Transloadit 账户的 Auth Key & Secret 保存好。您可以在 API 凭证 页面找到这些值。

使用方法

1. 从您的服务器上传并调整图片大小

此示例演示了如何使用 SDK 在您的服务器上创建组件。

它上传一个示例图片文件，将其上传到 Transloadit，并开始对其进行调整大小的作业。

<?php
require 'vendor/autoload.php';

use transloadit\Transloadit;

$transloadit = new Transloadit([
  'key'    => 'YOUR_TRANSLOADIT_KEY',
  'secret' => 'YOUR_TRANSLOADIT_SECRET',
]);

$response = $transloadit->createAssembly([
  'files' => ['/PATH/TO/FILE.jpg'],
  'params' => [
    'steps' => [
      'resize' => [
        'robot' => '/image/resize',
        'width' => 200,
        'height' => 100,
      ],
    ],
  ],
]);

// Show the results of the assembly we spawned
echo '<pre>';
print_r($response);
echo '</pre>';

2. 创建简单的用户上传表单

此示例展示了如何创建一个简单的 Transloadit 上传表单，上传完成后将重定向回您的网站。

一旦脚本接收到重定向请求，将使用 Transloadit::response() 显示此组件的当前状态。

注意：无法保证在获取 $response 时组件已经完成执行。您应该使用 notify_url 参数来处理此问题。
<?php
require 'vendor/autoload.php';

use transloadit\Transloadit;

$transloadit = new Transloadit([
  'key'    => 'YOUR_TRANSLOADIT_KEY',
  'secret' => 'YOUR_TRANSLOADIT_SECRET',
]);

// Check if this request is a Transloadit redirect_url notification.
// If so fetch the response and output the current assembly status:
$response = Transloadit::response();
if ($response) {
  echo '<h1>Assembly Status:</h1>';
  echo '<pre>';
  print_r($response);
  echo '</pre>';
  exit;
}

// This should work on most environments, but you might have to modify
// this for your particular setup.
$redirectUrl = sprintf('http://%s%s', $_SERVER['HTTP_HOST'], $_SERVER['REQUEST_URI']);

// Setup a simple file upload form that resizes an image to 200x100px
echo $transloadit->createAssemblyForm([
  'params' => [
    'steps' => [
      'resize' => [
        'robot' => '/image/resize',
        'width' => 200,
        'height' => 100,
      ],
    ],
    'redirect_url' => $redirectUrl,
  ],
]);
?>
<h1>Pick an image to resize</h1>
<input name="example_upload" type="file">
<input type="submit" value="Upload">
</form>

3. 使用 Uppy 进行文件上传

我们建议使用我们的下一代网页文件上传工具 Uppy，而不是 jQuery SDK。Uppy 为处理与 Transloadit 的文件上传提供了一种更现代、更灵活且功能更丰富的解决方案。

将 Uppy 集成到您的 PHP 后端

  1. 在您的 HTML 中包含 Uppy
<link href="https://releases.transloadit.com/uppy/v3.3.1/uppy.min.css" rel="stylesheet">
<script src="https://releases.transloadit.com/uppy/v3.3.1/uppy.min.js"></script>
  1. 使用 Transloadit 插件初始化 Uppy
<div id="uppy"></div>

<script>
  const uppy = new Uppy.Core()
    .use(Uppy.Dashboard, {
      inline: true,
      target: '#uppy'
    })
    .use(Uppy.Transloadit, {
      params: {
        auth: { key: 'YOUR_TRANSLOADIT_KEY' },
        template_id: 'YOUR_TEMPLATE_ID',
        notify_url: 'https://your-site.com/transloadit_notify.php'
      }
    })

  uppy.on('complete', (result) => {
    console.log('Upload complete! We've uploaded these files:', result.successful)
  })
</script>
  1. 在您的 PHP 后端处理组件状态

在您的项目中创建一个名为 transloadit_notify.php 的新文件

<?php
require 'vendor/autoload.php';

use transloadit\Transloadit;

$transloadit = new Transloadit([
  'key'    => 'YOUR_TRANSLOADIT_KEY',
  'secret' => 'YOUR_TRANSLOADIT_SECRET',
]);

$response = Transloadit::response();
if ($response) {
  // Process the assembly result
  $assemblyId = $response->data['assembly_id'];
  $assemblyStatus = $response->data['ok'];
  
  // You can store the assembly information in your database
  // or perform any other necessary actions here
  
  // Log the response for debugging
  error_log('Transloadit Assembly Completed: ' . $assemblyId);
  error_log('Assembly Status: ' . ($assemblyStatus ? 'Success' : 'Failed'));
  
  // Optionally, you can write the response to a file
  file_put_contents('transloadit_response_' . $assemblyId . '.json', json_encode($response->data));
  
  // Send a 200 OK response to Transloadit
  http_response_code(200);
  echo 'OK';
} else {
  // If it's not a Transloadit notification, return a 400 Bad Request
  http_response_code(400);
  echo 'Bad Request';
}
?>

请确保将 'https://your-site.com/transloadit_notify.php' 替换为托管此 PHP 脚本的实际 URL。

有关使用 Uppy 与 Transloadit 的更多详细信息，请参阅我们的 Uppy 文档。

4. 获取组件状态 JSON

您可以使用 getAssembly 方法来获取组件状态。

<?php
require 'vendor/autoload.php';
$assemblyId = 'YOUR_ASSEMBLY_ID';

$transloadit = new Transloadit([
  'key'    => 'YOUR_TRANSLOADIT_KEY',
  'secret' => 'YOUR_TRANSLOADIT_SECRET',
]);

$response = $transloadit->getAssembly($assemblyId);

echo '<pre>';
print_r($response);
echo '</pre>';

5. 使用模板创建组件。

此示例演示了如何使用 SDK 使用模板创建组件。

您需要在您的 Transloadit 账户仪表板上创建一个模板，并将模板 ID 添加到这里。

<?php
require 'vendor/autoload.php';

use transloadit\Transloadit;

$transloadit = new Transloadit([
  'key'    => 'YOUR_TRANSLOADIT_KEY',
  'secret' => 'YOUR_TRANSLOADIT_SECRET',
]);

$response = $transloadit->createAssembly([
  'files' => ['/PATH/TO/FILE.jpg'],
  'params' => [
    'template_id' => 'YOUR_TEMPLATE_ID',
  ],
]);

// Show the results of the assembly we spawned
echo '<pre>';
print_r($response);
echo '</pre>';

签名认证

PHP SDK 默认内部执行签名认证，因此您无需担心这个问题 :)

示例

要查看完整的示例，请查看 examples/。

API

$Transloadit = new Transloadit($properties = []);

创建一个新的 Transloadit 实例并应用给定的 $properties。

$Transloadit->key = null;

您的 Transloadit 账户的认证密钥。

$Transloadit->secret = null;

您的 Transloadit 账户的认证密钥。

$Transloadit->request($options = [], $execute = true);

使用$Transloadit->key和$Transloadit->secret属性创建一个新的TransloaditRequest。

如果$execute设置为true，将调用$TransloaditRequest->execute()并将其用作返回值。

否则，将返回新的TransloaditRequest实例。

$Transloadit->createAssemblyForm($options = []);

创建一个新的Transloadit组装表单，包括隐藏的'params'和'signature'字段。不包含闭合表单标签。

$options是一个数组，包含用于的TransloaditRequest属性。例如："params"、"expires"、"endpoint"等。

此外，您还可以传递一个"attributes"键，允许您设置自定义表单属性。例如

$Transloadit->createAssemblyForm(array(
  'attributes' => array(
    'id'    => 'my_great_upload_form',
    'class' => 'transloadit_form',
  ),
));

$Transloadit->createAssembly($options);

向Transloadit发送一个新的组装请求。这是从您的服务器上传文件的推荐方法。

$options是一个数组，包含用于的TransloaditRequest属性，除了您可以在此处使用waitForCompletion选项。

waitForCompletion是一个布尔值（默认为false），表示您是否希望在回调被调用之前等待组装完成，并且所有编码结果都存在。如果waitForCompletion为true，此SDK将轮询状态更新，并在所有编码工作完成后返回。

请参阅上面的示例#1以获取更多信息。

$Transloadit->getAssembly($assemblyId);

检索给定组装ID的组装状态json。

$Transloadit->cancelAssembly($assemblyId);

取消正在执行的组装，防止任何进一步的花费金钱的编码。

如果在不再执行的组装上调用，这将导致ASSEMBLY_NOT_FOUND错误。

Transloadit::response()

此静态方法用于解析Transloadit发送到您的服务器的通知。

此方法处理两种类型的通知

  • 当使用redirect_url参数时，如果Transloadit将您的网站重定向回，将添加一个$_GET['assembly_url']查询参数。此方法检测此参数的存在，并从该url获取当前组装状态并返回它作为TransloaditResponse。
  • 当使用notify_url参数时，Transloadit发送一个$_POST['transloadit']参数。此方法检测此，并将通知JSON解析为一个TransloaditResponse对象供您使用。

如果当前请求似乎不是由Transloadit触发的，此方法返回false。

$TransloaditRequest = new TransloaditRequest($properties = []);

创建一个新的TransloaditRequest实例并应用给定的$properties。

$TransloaditRequest->key = null;

您的 Transloadit 账户的认证密钥。

$TransloaditRequest->secret = null;

您的 Transloadit 账户的认证密钥。

$TransloaditRequest->method = 'GET';

从CurlRequest继承。可以用来设置要进行的请求类型。

$TransloaditRequest->curlOptions = [];

从CurlRequest继承。可以用来使用任何PHP/cURL版本支持的cURL选项调整cURL行为。

以下是一个示例，说明如何使用此选项更改请求的超时时间（大幅度，到1ms，仅为了证明可以在您选择的时间后使SDK终止）。

默认超时和选项取决于您的系统上的cURL版本，可以通过检查phpinfo()和curl_setopt文档进行验证。

$TransloaditRequest->endpoint = 'https://api2.transloadit.com';

将此请求发送到的端点。

$TransloaditRequest->path = null;

要请求的url路径。

$TransloaditRequest->url = null;

从CurlRequest继承。允许您使用一个完全定制的url覆盖上述端点/路径属性。

$TransloaditRequest->fields = [];

发送请求时需要附加的额外字段列表。Transloadit 会将这些字段包含在所有与组装相关的通知中。

$TransloaditRequest->files = [];

一个表示您想要上传的本地文件路径的数组。例如

$TransloaditRequest->files = array('/my/file.jpg');

或

$TransloaditRequest->files = array('my_upload' => '/my/file.jpg');

第一个示例在执行请求时将自动为您的文件赋予字段名 'file_1'。

$TransloaditRequest->params = [];

一个表示要发送到 Transloadit 的 JSON 参数的数组。您不需要在此处包含一个 'auth' 键，因为这个类会作为 $TransloaditRequest->prepare() 部分为您处理。

$TransloaditRequest->expires = '+2 hours';

如果您已经配置了 '$TransloaditRequest->secret'，这个类将自动对您的请求进行签名。过期属性允许您配置签名有效的持续时间。

$TransloaditRequest->headers = [];

允许您在请求中发送额外的头信息。您通常不需要更改此属性。

$TransloaditRequest->execute()

将此请求发送到 Transloadit 并返回一个 TransloaditResponse 实例。

$TransloaditResponse = new TransloaditResponse($properties = []);

创建一个新的 TransloaditResponse 实例并应用给定的 $properties。

$TransloaditResponse->data = null;

继承自 CurlResponse。包含从 Transloadit 解析的 JSON 响应数组。

您通常应在使用 $TransloaditResponse->error() 检查错误之后访问此属性。

$TransloaditResponse->error();

返回 false 或一个包含错误解释的字符串。

以下所有情况都将返回一个错误字符串

  • 任何类型的网络问题
  • Transloadit 响应 JSON 包含一个 {"error": "..."} 键
  • 收到一个格式不正确的响应

注意：您需要在 $Transloadit->createAssembly($options) 函数调用中将 waitForCompletion 设置为 True。

贡献

请随意fork此项目。我们将愉快地合并错误修复或其他小改进。对于更大的更改，您在开始之前可能需要先与我们联系，以避免它们没有被合并。

版本控制

此项目实现了语义版本控制指南。

发布将以以下格式编号

<major>.<minor>.<patch>

并遵循以下准则

  • 破坏向后兼容性会提升主版本（并重置次要版本和补丁）
  • 没有破坏向后兼容性的新功能提升次要版本（并重置补丁）
  • 错误修复和杂项更改提升补丁

有关 SemVer 的更多信息，请访问 http://semver.org/。

发布新版本

# 1. update CHANGELOG.md
# 2. update composer.json
# 3. commit all your work
source env.sh && VERSION=3.1.0 ./release.sh

许可

MIT 许可