PHP でファイルを Amazon S3 にエクスポートする総合ガイド
PHP からローカルファイルを Amazon S3 にエクスポートするには、AWS SDK をインストールし、SourceFile を指定して putObject を呼び出します。このガイドでは、メタデータとサーバー側暗号化を設定して非公開オブジェクトを保存し、終了ステータスで失敗を通知する、マルチパートアップロード対応の CLI スクリプトを作成します。さらに、オブジェクトを別途ダウンロードし、S3 が受信したバイト列が元と完全に一致するか検証します。
前提条件とセットアップ
PHP、Composer 2、AWS CLI v2 をインストールした Linux の Bash シェルを使用します。サンプルは PHP 8.5.10、Composer 2.10.3、AWS CLI 2.37.10、AWS SDK for PHP 3.399.2 でテストしています。PHP 8.5 は保守対象のリリースブランチです。新規インストールには、その最新パッチリリースを使用してください。これらはテスト済みのバージョンであり、SDK の最小要件ではありません。
SDK は PHP 8.1 以降と SimpleXML を必要とします。この手順では、HTTPS 用に PHP の cURL 拡張機能と OpenSSL 拡張機能も使用します。不足しているツールは、PHP インストールガイド、Composer ダウンロード手順、AWS CLI v2 インストール手順に従ってインストールしてください。ファイル比較に使用する GNU cmpは、GNU Diffutils パッケージに含まれています。
プロジェクトファイルを作成する前に、各前提条件を確認します。
(
for tool in php composer aws cmp; do
if ! command -v "$tool" >/dev/null 2>&1; then
printf 'Missing prerequisite: %s\n' "$tool" >&2
exit 1
fi
done
php -r 'foreach (["simplexml", "curl", "openssl"] as $extension) {
if (!extension_loaded($extension)) {
fwrite(STDERR, "Missing PHP extension: $extension\n"); exit(1);
}
}'
)
AWS SDK for PHP のインストール
アプリケーションの公開 Web ディレクトリの外に、新しい空のディレクトリを作成して作業します。次の内容を composer.json として保存してください。既存アプリケーションのマニフェストは置き換えないでください。
{
"require": {
"aws/aws-sdk-php": "3.399.2"
}
}
テスト済みの SDK バージョンを、このディレクトリの vendor/ フォルダーにインストールします。
COMPOSER=composer.json COMPOSER_VENDOR_DIR=vendor \
composer install --no-interaction --no-plugins --no-scripts
再現可能なインストールのため、生成された composer.lock を保持してください。インストールに失敗した場合は、報告された前提条件またはネットワークの問題を解決し、同じディレクトリで同じコマンドを再実行します。マニフェストやロックファイルの削除は不要です。ロックファイルによる依存関係の固定については、Composer の基本的な使い方のガイドで説明されています。
AWS 認証情報の設定
必要な権限を持つ既存の AWS プロファイルを使用します。CLI と SDK はどちらも共有認証情報プロバイダーに対応しています。プロファイルとバケットのリージョンを選択し、アップロード前にアカウントを確認します。
export AWS_PROFILE=default
export AWS_DEFAULT_REGION=us-east-1
aws sts get-caller-identity --query Account --output text
default と us-east-1 を実際の値に置き換えてください。認証情報の有効期限が切れている場合は、認可済みのセッションを更新してから続行します。環境変数の認証情報はプロファイルより優先されるため、想定外のアカウントが表示された場合は、意図しない認証情報一式が環境変数に設定されていないか確認してください。アクセスキーを PHP ファイルに記載しないでください。AWS 上のアプリケーションでは、有効期間の長いキーではなく、ワークロード用の IAM ロールを優先してください。
シンプルな S3 バケットの作成
このスクリプトは、既存の非公開の汎用 S3 バケットを使用します。新たに必要な場合は、バケット管理者に AWS のバケット作成ガイドに従ってもらってください。Block Public Access は有効のままにし、Object Ownership は Bucket owner enforced に設定します。AWS_DEFAULT_REGION にはバケットの実際のリージョンを指定してください。バケットの管理はエクスポートスクリプトとは別に行います。
以下のコマンド用に、バケット名と、自分が所有するプレフィックス配下の未使用のオブジェクトキーを設定します。
export S3_BUCKET=your-private-bucket
export S3_KEY=php-export-test/sample.bin
サンプルの値を両方とも置き換えてください。既存のキーにアップロードすると、現在のオブジェクトが置き換わります。バージョニングが有効な場合は、新しいバージョンが作成されます。これらのテストでは一意のキーを使用し、エクスポートは一度に一つずつ実行してください。
ファイルをエクスポートする PHP スクリプトの開発
次のプログラム全体を export.php として、composer.json と同じディレクトリに保存します。引数はローカルファイル、バケット、オブジェクトキー、および任意指定のモードです。モードには put または multipart を指定します。
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
$mode = $argv[4] ?? 'put';
if ($argc < 4 || $argc > 5 || !in_array($mode, ['put', 'multipart'], true)) {
fwrite(STDERR, "Usage: php export.php LOCAL_FILE BUCKET KEY [put|multipart]\n");
exit(2);
}
[$script, $sourceFile, $bucket, $key] = $argv;
$region = getenv('AWS_DEFAULT_REGION');
if (!$region || $bucket === '' || $key === '') {
fwrite(STDERR, "Set AWS_DEFAULT_REGION and provide a nonempty bucket and key.\n");
exit(2);
}
if (!is_file($sourceFile) || !is_readable($sourceFile)) {
fwrite(STDERR, "Cannot read source file: $sourceFile\n");
exit(2);
}
try {
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => $region,
'retries' => 0,
'http' => ['connect_timeout' => 10, 'timeout' => 60],
]);
$options = [
'Bucket' => $bucket,
'Key' => $key,
'ContentType' => 'application/octet-stream',
'Metadata' => [
'original-filename' => rawurlencode(basename($sourceFile)),
'upload-date' => gmdate('c'),
],
'ServerSideEncryption' => 'AES256',
'CacheControl' => 'no-store',
];
if ($mode === 'multipart' && filesize($sourceFile) > 0) {
$uploader = new MultipartUploader($s3Client, $sourceFile, [
'bucket' => $bucket,
'key' => $key,
'part_size' => 5 * 1024 * 1024,
'concurrency' => 1,
'params' => $options,
]);
$uploader->upload();
} else {
$s3Client->putObject($options + ['SourceFile' => $sourceFile]);
}
echo "Export complete: s3://$bucket/$key\n";
} catch (Throwable $e) {
if (isset($uploader)) {
$id = $uploader->getState()->getId();
if (!empty($id['UploadId'])) {
try {
$s3Client->abortMultipartUpload($id);
fwrite(STDERR, "Aborted incomplete multipart upload.\n");
} catch (Throwable $abortError) {
fwrite(STDERR, "Abort failed; clean up upload ID: {$id['UploadId']}\n");
}
}
}
if ($e instanceof MultipartUploadException) {
fwrite(STDERR, "Multipart export failed for: $sourceFile\n");
} elseif ($e instanceof AwsException) {
fwrite(STDERR, 'S3 export failed: ' . ($e->getAwsErrorCode() ?? 'request error') . "\n");
fwrite(STDERR, 'Request ID: ' . ($e->getAwsRequestId() ?? 'unavailable') . "\n");
} else {
fwrite(STDERR, "Export failed; check the local file, SDK installation, and credentials.\n");
}
exit(1);
}
小さなテスト用ファイルを作成してアップロードします。
printf 'S3 export check\n' > sample.bin &&
php export.php ./sample.bin "$S3_BUCKET" "$S3_KEY"
スクリプトは、SDK がリクエストを完了した後にのみ Export complete を出力し、続けて非公開オブジェクトの S3 URI を表示します。この URI はオブジェクトの識別子であり、公開ダウンロードリンクではありません。エクスポートに失敗すると、診断情報を stderr に出力し、ゼロ以外のステータスで終了します。プログラムはローカルファイルを読み取りますが、削除はしません。検証が完了するまで、このファイルを変更しないでください。
ファイルメタデータの効率的な処理
$options 配列は、両方のアップロードモードに同じメタデータ、コンテンツタイプ、キャッシュポリシー、SSE-S3 暗号化を適用します。original-filename は、空白や非 ASCII 文字を HTTP メタデータヘッダーで表せるようにパーセントエンコードされます。upload-date は UTC のタイムスタンプを記録します。S3 キーはローカルファイル名とは独立しているため、エクスポートしたファイルを探す際は完全なキーを保持してください。
application/octet-stream は任意のバイナリファイルに適しています。アプリケーションで形式がわかっている場合は、より具体的な ContentType を設定し、利用側に合わせて CacheControl を選択してください。このサンプルでは no-store を使用します。AES256 は SSE-S3 暗号化を明示的に要求します。公開アクセスを許可するものでも、アクセス制御を代替するものでもありません。
統合のテストとデバッグ
保存されたメタデータと暗号化を確認し、新しいローカル検証用ディレクトリにダウンロードします。
aws s3api head-object --bucket "$S3_BUCKET" --key "$S3_KEY" \
--region "$AWS_DEFAULT_REGION" \
--query '{bytes:ContentLength,type:ContentType,encryption:ServerSideEncryption,metadata:Metadata}'
(
mkdir s3-verify &&
aws s3api get-object --bucket "$S3_BUCKET" --key "$S3_KEY" \
--region "$AWS_DEFAULT_REGION" s3-verify/download.bin &&
cmp -- ./sample.bin s3-verify/download.bin
)
メタデータのレスポンスには、AES256、指定したファイル名、想定したバイト数が表示されるはずです。cmp は、空ファイルも含め、すべてのバイトが一致するとゼロを返します。実行ごとに新しい検証用ディレクトリを使用してください。ダウンロードに失敗した場合は、作成した使い捨ての s3-verify ディレクトリだけを削除し、ブロックを再実行します。以前のダウンロードを保護するため、既存のディレクトリは受け付けません。S3 ETag を汎用的なファイルハッシュとして使用しないでください。マルチパートオブジェクトでは ETag の意味が異なる場合があります。
スクリプトをジョブに組み込む前に、手元の非テキストのバイナリファイルと空ファイルを、異なるキーで試してください。スケジュール実行するジョブでは、stderr を取得し、プロセスの終了ステータスを確認します。利用者に公開されるログには、認証情報、署名付き URL、SDK の例外メッセージの生データを含めないでください。
高度なユースケース:マルチパートアップロード
AWS は 100 MB を超えるオブジェクトにマルチパートアップロードを推奨しています。このスクリプトでは、より小さなテスト用ファイルでもその処理を試せます。少なくとも二つのパートに分かれるよう、5 MiB を超えるファイルを選び、sample.bin として保存して、未使用のキーを選択します。
php export.php ./sample.bin "$S3_BUCKET" "$S3_KEY" multipart
その後、同じメタデータ検証とバイト比較を実行します。このテスト用ファイルでは、アップローダーは
5 MiB のパートを使用して一度に一つずつ転送し、CompleteMultipartUpload を待ってから成功を表示します。はるかに大きいファイルでは、SDK がパートサイズを増やす場合があります。空ファイルには結合するパートがないため、マルチパートモードを選択しても
putObject を使用します。
再試行は無効で、各 HTTP リクエストには接続タイムアウト 10 秒、転送タイムアウト 60 秒が設定されています。これらはリクエストごとの制限であり、マルチパートアップロード全体の期限ではありません。接続が遅い場合は、小さなファイルでも失敗することがあります。このサンプルは、失敗したマルチパートアップロードを再開せず、中止します。問題を解決し、同じローカルソースで再実行してください。中止自体に失敗すると、バケット管理者が削除できるよう stderr にアップロード ID が出力されます。AWS のマルチパートアップロードの概要で説明されているとおり、アップロード済みパートには、完了または中止するまでストレージ料金が発生します。
完了レスポンスが失われると、結果が不確定になる場合があります。クライアントが失敗を報告しても、S3 ではオブジェクトの保存が確定している可能性があります。再試行する前に、正確なキーとバイト列を確認してください。未完了のマルチパートアップロードは、完成したオブジェクトではありません。
セキュリティのベストプラクティス
エクスポート用の ID には、所有するプレフィックスに対する s3:PutObject と、失敗時のクリーンアップ用の s3:AbortMultipartUpload を付与します。検証用の ID には、オブジェクトの調査とダウンロードのために s3:GetObject も必要です。これらの権限は、対象のバケットとキーに限定してください。スクリプトには、バケットの作成やポリシー変更の権限は不要です。関連する権限は AWS のマルチパートアップロードの概要に記載されています。
このサンプルは ACL を送信せず、非公開バケットを前提としています。SSE-S3 を明示的に使用するため、SSE-KMS を必須とするバケットポリシーでは、暗号化設定を意図的に変更し、対応する KMS 権限を設定する必要があります。TLS 証明書の検証は有効のままにしてください。
よくある問題のトラブルシューティング
- AccessDenied: 選択したアカウント、プレフィックスの権限、バケットの暗号化ポリシーを確認してください。
- リージョンまたはエンドポイントのエラー:
AWS_DEFAULT_REGIONをバケットのリージョンに合わせてください。 - ファイルが見つからない: 読み取り可能なローカルパスを渡してください。空白を含むファイル名は引用符で囲み、ハイフンで始まるファイル名にはシェルで
./を前置してください。 - マルチパートアップロードの失敗: stderr で中止の失敗を確認してください。残っているマルチパートアップロードを保存済みファイルとして扱わず、完了結果が不確定な場合は再試行前に検証してください。
- バイト列の不一致: キーとローカルファイルがアップロード時のものか確認し、別の書き込み処理がオブジェクトを置き換えていないか調べてください。
まとめと次のステップ
非公開オブジェクトがダウンロード比較に合格したら、同じアップロード処理と終了ステータス処理を PHP ジョブで使用します。統合テストでは独立したバイト検証を継続し、エクスポートを確認するまでローカルソースを保持してください。失敗したマルチパート転送の再開については、まず AWS の MultipartUploader の復旧ドキュメントを参照し、アプリケーションでアップロード状態を保持する方法と、放置されたパートをクリーンアップする方法を決めてください。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
