Transloadit を効率的に使う非同期 PHP 連携
アップロードが完了するまでは待つ必要がありますが、画像処理中もブラウザーを開いておく必要はありません。Assembly Notifications を使うと、Transloadit が処理の終了を PHP バックエンドに通知します。バックエンドは、ブラウザーとは独立してその結果を記録できます。

この記事は Joseph による 2021年7月のチュートリアルを更新したものです。廃止された Robodog アップローダーに代えて、Uppy の Dashboard と Transloadit プラグインを使います。MySQL の受信記録テーブル、サーバー側で署名するアップロード、認証付きコールバックを備えた、単独の運用担当者向けの小さな PHP アプリケーションを作成します。PDO MySQL を備えた PHP 8.2 以降を使い、アカウントのすべてのシークレットをサーバー上に保持します。
Web サイトの設定
common.php と public/ ディレクトリを含むプロジェクトを作成します。ドキュメントルートは public/ のみです。アプリケーションの運用担当者は、HTTPS 経由の HTTP Basic 認証でログインします。一方、通知の認証には Transloadit の署名を使います。これにより、チュートリアルに本格的なユーザーアカウントシステムを導入せずに、署名と受信記録の閲覧を非公開にできます。
デプロイ環境のシークレットマネージャーを通じて、次の環境変数を PHP に渡します。
- アカウントの
TRANSLOADIT_KEY、TRANSLOADIT_SECRET、TRANSLOADIT_TEMPLATE_ID。 - このチュートリアルの運用担当者用の
APP_USERと、長いランダムなAPP_PASSWORD。 APP_ORIGIN:アプリケーションの正確な HTTPS オリジン。末尾のスラッシュは不要。TRANSLOADIT_NOTIFY_URL:そのオリジンに/notify.phpを付けたもの。DB_DSN:例としてmysql:host=127.0.0.1;dbname=transloadit;charset=utf8mb4。DB_USERとDB_PASSWORD:受信記録テーブルに対するSELECTとINSERTの権限だけを持つデータベースアカウント。
シークレットを含むファイルは public/ の外に置き、ソース管理にも含めないでください。複数ユーザーのアプリケーションでは、Basic 認証を既存のセッション認可に置き換え、受信記録へのアクセスを所有者に限定し、署名エンドポイントでユーザーごとのアップロード割り当てとレート制限を適用してください。
データベースの設定
管理者権限の MySQL 接続で、データベースとテーブルを作成します。
CREATE DATABASE transloadit CHARACTER SET utf8mb4;
USE transloadit;
CREATE TABLE assemblies (
id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin PRIMARY KEY,
status VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
http_code SMALLINT UNSIGNED NOT NULL,
received_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
Assembly ID が受信記録の一意キーです。通知の再試行で余分な行を作成したり、業務上のアクションを繰り返したりしてはいけません。この例では終端ステータスのみを保存し、結果ファイルの公開や後続ジョブの実行は行いません。
Template の作成
次の処理設定でアカウントに Template を作成し、その ID をサーバーの設定にコピーします。コールバック先は署名エンドポイントが指定します。ブラウザーのフィールドや、ユーザー入力に基づく Template の式では指定しません。
{
"steps": {
":original": { "robot": "/upload/handle" },
"resized": {
"robot": "/image/resize",
"use": ":original",
"width": 500,
"format": "jpeg",
"resize_strategy": "fit",
"imagemagick_stack": "v3.0.2"
}
}
}
Auth Key の Signature Authentication を有効にし、改ざんされた処理設定や署名のない処理設定を拒否するようにします。サーバーはシリアライズされた params 文字列そのものに HMAC-SHA384 で署名し、@transloadit/utils が使う形式に合わせます。
開発中のローカル Notifications の公開
このチュートリアルでは、Cloudflare Quick Tunnel を使います。cloudflared をインストールしたら、トンネルを起動します。
cloudflared tunnel --url http://127.0.0.1:8000
APP_ORIGIN に割り当てられた HTTPS オリジンを設定し、TRANSLOADIT_NOTIFY_URL にその /notify.php URL を設定します。続いて、残りの環境変数を設定した後、プロジェクトディレクトリから PHP を起動します。
php -d display_errors=0 -d log_errors=1 -d post_max_size=512K \
-d upload_max_filesize=256K -d max_input_vars=10 -d file_uploads=0 \
-S 127.0.0.1:8000 -t public
ブラウザーで HTTPS トンネルの URL を開きます。Uppy は引き続き https://api2.transloadit.com を使い、アップロードは PHP を経由しません。テスト後は Ctrl+C で両方のプロセスを停止します。一時的なトンネルのホスト名が変わるたびに、二つの URL 設定を更新して PHP を再起動してください。
公式の通知リレーも、開発時の選択肢です。ただし、ローカルプロキシ経由で Assembly 作成の通信を受信し、Assembly のステータスをポーリングし、Auth Secret で転送する通知に署名する必要があります。Uppy が通常の API エンドポイントを使っている状態で起動するだけでは、このアプリケーションの通知は中継されません。上記のトンネル設定では、リレーも Template 内の localhost コールバックも不要です。
データベースへの接続
次の内容を、公開ドキュメントルートの外に common.php として保存します。四つすべての PHP ファイルに対して、設定、ログイン、データベースアクセス、機密情報を除去した共通のエラー処理境界を提供します。
<?php
declare(strict_types=1);
set_exception_handler(function (Throwable $error): void {
error_log('Notification application request failed.');
respond(500, 'Request could not be completed.');
});
function respond(int $status, string $message): never {
http_response_code($status);
header('Content-Type: text/plain; charset=utf-8');
header('Cache-Control: no-store');
echo $message;
exit;
}
function setting(string $name): string {
$value = getenv($name);
if ($value === false || $value === '') {
throw new RuntimeException('Missing server configuration.');
}
return $value;
}
function requireOperator(): void {
if (!hash_equals(setting('APP_USER'), $_SERVER['PHP_AUTH_USER'] ?? '') ||
!hash_equals(setting('APP_PASSWORD'), $_SERVER['PHP_AUTH_PW'] ?? '')) {
header('WWW-Authenticate: Basic realm="Upload demo", charset="UTF-8"');
respond(401, 'Sign in to continue.');
}
header('Cache-Control: no-store');
}
function database(): PDO {
return new PDO(setting('DB_DSN'), setting('DB_USER'), setting('DB_PASSWORD'), [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_EMULATE_PREPARES => false,
]);
}
署名エンドポイントを public/sign.php として保存します。呼び出し元が指定する処理設定は一切受け付けません。Origin とカスタムヘッダーの検証により、認証情報付きのこの POST をクロスサイトのフォーム送信から保護します。制限の緩い CORS ヘッダーを追加しないでください。Uppy のクライアント側の制限が回避されても、短い有効期限と署名付きのアップロードサイズ制限は適用されます。
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/common.php';
requireOperator();
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
respond(405, 'Use POST.');
}
$origin = setting('APP_ORIGIN');
if (!preg_match('~\Ahttps://[a-zA-Z0-9.-]+(?::[0-9]+)?\z~D', $origin) ||
setting('TRANSLOADIT_NOTIFY_URL') !== $origin . '/notify.php') {
throw new RuntimeException('Invalid server URL configuration.');
}
if (($_SERVER['HTTP_ORIGIN'] ?? '') !== $origin ||
($_SERVER['HTTP_X_UPLOAD_REQUEST'] ?? '') !== '1') {
respond(403, 'Request not allowed.');
}
if (!preg_match('/\A[a-f0-9]{32}\z/D', setting('TRANSLOADIT_TEMPLATE_ID'))) {
throw new RuntimeException('Invalid Template configuration.');
}
$params = json_encode([
'auth' => [
'key' => setting('TRANSLOADIT_KEY'),
'expires' => gmdate('Y-m-d\TH:i:s\Z', time() + 300),
'max_size' => 10 * 1024 * 1024,
],
'template_id' => setting('TRANSLOADIT_TEMPLATE_ID'),
'notify_url' => setting('TRANSLOADIT_NOTIFY_URL'),
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
$signature = 'sha384:' . hash_hmac('sha384', $params, setting('TRANSLOADIT_SECRET'));
header('Content-Type: application/json');
echo json_encode(['params' => $params, 'signature' => $signature], JSON_THROW_ON_ERROR);
データベースへのデータ追加
次の内容を public/notify.php として保存します。JSON をデコードする前に、元の transloadit フォームフィールドのバイト列を検証します。先に JSON を再エンコードすると、署名対象のメッセージが変わってしまいます。対応アルゴリズムの許可リストには、通知の互換性のために SDK のレガシーな SHA-1 形式も含まれています。上記の新しいアップロード用の処理設定では SHA384 を使います。未知のアルゴリズム、不正な形式のフィールド、無効な署名は拒否されます。
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/common.php';
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
respond(405, 'Use POST.');
}
$raw = $_POST['transloadit'] ?? null;
$signature = $_POST['signature'] ?? null;
if (!is_string($raw) || strlen($raw) > 262144 || !is_string($signature) ||
strlen($signature) > 140 || count($_POST) !== 2 || count($_FILES) !== 0) {
respond(400, 'Invalid notification.');
}
$parts = explode(':', $signature, 2);
[$algorithm, $digest] = count($parts) === 2 ? $parts : ['sha1', $signature];
$lengths = ['sha1' => 40, 'sha256' => 64, 'sha384' => 96, 'sha512' => 128];
if (!isset($lengths[$algorithm]) || strlen($digest) !== $lengths[$algorithm] ||
!ctype_xdigit($digest) ||
!hash_equals(hash_hmac($algorithm, $raw, setting('TRANSLOADIT_SECRET')), $digest)) {
respond(403, 'Invalid notification signature.');
}
try {
$assembly = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
} catch (JsonException $error) {
respond(400, 'Invalid notification JSON.');
}
if (!is_array($assembly) || array_is_list($assembly)) {
respond(400, 'Invalid notification.');
}
$id = $assembly['assembly_id'] ?? null;
$status = $assembly['error'] ?? $assembly['ok'] ?? null;
$httpCode = $assembly['http_code'] ?? null;
if (!is_string($id) || !preg_match('/\A[a-f0-9]{32}\z/D', $id) ||
!is_string($status) || !preg_match('/\A[A-Z][A-Z0-9_]{0,63}\z/D', $status) ||
!is_int($httpCode) || $httpCode < 100 || $httpCode > 599 ||
(!isset($assembly['error']) && !in_array($status, ['ASSEMBLY_COMPLETED', 'ASSEMBLY_CANCELED'], true))) {
respond(400, 'Invalid terminal Assembly status.');
}
$db = database();
try {
$insert = $db->prepare('INSERT INTO assemblies (id, status, http_code) VALUES (?, ?, ?)');
$insert->execute([$id, $status, $httpCode]);
} catch (PDOException $error) {
// MySQL error 1062 is the unique receipt key, not a successful new delivery.
if (($error->errorInfo[1] ?? null) !== 1062) {
throw $error;
}
$existing = $db->prepare('SELECT status, http_code FROM assemblies WHERE id = ?');
$existing->execute([$id]);
$row = $existing->fetch(PDO::FETCH_ASSOC);
if (!$row || $row['status'] !== $status || (int) $row['http_code'] !== $httpCode) {
respond(409, 'Conflicting notification receipt.');
}
}
respond(200, 'Notification recorded.');
同一内容の再試行には、保存済みの結果を確認したうえで 200 を返します。同じ Assembly ID に対して矛盾する結果が届いた場合は、調査できるよう 409 を返します。データベース障害時には汎用的な 500 を返し、送信元が再試行できるようにします。主キーは、同時配信による重複も防ぎます。後続ジョブを追加する場合は、受信記録と同じデータベーストランザクションでジョブをアウトボックスに挿入し、冪等なワーカーで処理してください。受信記録を保存する前にメールの送信やファイルの公開を行わないでください。
データベースからのデータ取得
次の完全なアップロードページを public/index.php として保存します。認証済みの運用担当者に、直近に受信した五つの Assembly の結果を表示します。データベースの値はすべて、表示前にエスケープします。Uppy の Transloadit プラグインは、バックエンドに署名付きオプションを要求します。
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/common.php';
requireOperator();
$rows = database()->query(
'SELECT id, status, received_at FROM assemblies ORDER BY received_at DESC, id DESC LIMIT 5'
)->fetchAll(PDO::FETCH_ASSOC);
function escape(string $value): string {
return htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
}
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Asynchronous image uploads</title>
<link rel="stylesheet" href="https://releases.transloadit.com/uppy/v5.2.1/uppy.min.css">
</head>
<body>
<h1>Upload an image</h1>
<p>Wait until the upload finishes. Processing continues after you close this page.</p>
<div id="dashboard"></div>
<h2>Recent processing outcomes</h2>
<p>Refresh this page to see newly received notifications.</p>
<ul>
<?php foreach ($rows as $row): ?>
<li><?= escape($row['id']) ?> — <?= escape($row['status']) ?> — <?= escape($row['received_at']) ?></li>
<?php endforeach; ?>
</ul>
<?php if (count($rows) === 0): ?><p>No notifications received yet.</p><?php endif; ?>
<script type="module">
import { Uppy, Dashboard, Transloadit } from 'https://releases.transloadit.com/uppy/v5.2.1/uppy.min.mjs'
new Uppy({ restrictions: { maxNumberOfFiles: 1, maxFileSize: 10 * 1024 * 1024, allowedFileTypes: ['image/*'] } })
.use(Dashboard, { target: '#dashboard', inline: true })
.use(Transloadit, {
waitForEncoding: false,
async assemblyOptions() {
const response = await fetch('/sign.php', {
method: 'POST',
credentials: 'same-origin',
headers: { 'X-Upload-Request': '1' },
})
if (!response.ok) throw new Error('Could not authorize this upload.')
return response.json()
},
})
</script>
</body>
</html>
テスト
まず、ページと署名エンドポイントへの未認証リクエストに 401 が返り、/notify.php への署名なしの POST に、行を挿入せず 403 が返ることを確認します。ペイロードがない場合や形式が不正な場合は 400 が返ります。SQL 構文を含む Assembly ID を送信した場合も、検証で拒否されなければなりません。
任意のエンドツーエンドテストとして、自分のアカウントを使い、HTTPS ページから小さなテスト画像を一つアップロードして、アップロード完了を待ち、処理後にページを再読み込みします。アップロード用のタブを閉じていても、完了した受信記録が表示されるはずです。処理の失敗は、完成した画像としてではなく、失敗ステータスとして表示されなければなりません。Assembly ページから通知を再送しても、受信記録は一つのままであるはずです。
ローカルでは、署名付きの合成通知もテストしてください。変更のない再試行には 200、本文を変更して古い署名を付けたものには 403、署名は有効でも保存済みの終端結果と矛盾するものには 409 が返るはずです。トンネルのテストを通すために署名検証を無効にしてはいけません。上記の開発用の本文サイズ制限は、画像一つを扱うこの例に合わせたものです。本番環境の通知ペイロードに適したリバースプロキシと PHP の明示的な制限を設定し、拒否された配信を監視してください。
まとめ
これで、ブラウザーがアップロードを担当し、PHP が認証済みの処理結果を記録するようになりました。通知の再試行や自分で行う再送に十分対応できる期間、受信記録を保持し、アカウントで通知の失敗を監視してください。署名認証によって送信元を確認できますが、アプリケーションの認可、受信記録の所有権、後続処理の冪等性は、引き続きバックエンドが担います。
