PHP と jpegtran によるアップロード画像の回転補正
横向きの JPEG アップロードを補正するには、EXIF の向きに従って保存済みの画像を変換し、その後で向きの値をリセットします。以下の PHP コマンドは、非可逆圧縮を再度行わずに、正しい向きの JPEG を別ファイルとして保存します。破損した入力や、画像の端に未補正の帯状領域が残る回転は拒否します。
EXIF の向きデータの仕組み
EXIF の向きタグは、保存された画像の表示方法をビューアーに伝えます。タグだけを変更しても画像データは回転しません。タグをリセットせずにデータを回転すると、ビューアーが再び回転させることがあります。埋め込みサムネイルではなく、メイン画像の IFD0 の向きを読み取ってください。
鏡像を含む全8種類の値を扱う必要があります。保存済みの画像に適用する操作は次のとおりです。回転角度は時計回りです。
| EXIF 値 | 補正 | jpegtran の引数 |
|---|---|---|
| 1 | 正立のまま維持 | 変換なし |
| 2 | 左右反転 | -flip horizontal |
| 3 | 上下を逆に回転 | -rotate 180 |
| 4 | 上下反転 | -flip vertical |
| 5 | 左上から右下への対角線を軸に反転 | -transpose |
| 6 | 90°回転 | -rotate 90 |
| 7 | 右上から左下への対角線を軸に反転 | -transverse |
| 8 | 270°回転 | -rotate 270 |
この対応は ExifTool の向きの定義に従っています。メイン画像に向きタグがない場合、この例では画像の幾何学的な状態を変更しません。タグのない写真が本来どちらを向くべきかは推測できません。1–8 以外の値はエラーになります。
jpegtran による可逆回転
jpegtran は量子化済みの DCT 係数を並べ替えるため、GD や ImageMagick による回転で発生する JPEG のデコードと再圧縮を回避します。ここでの「可逆」は係数の変換を指し、出力ファイルのバイト列やメタデータは変わります。
完全な変換ができるかどうかは JPEG のブロック境界に依存します。-perfect は対応できない変換を拒否します。-trim を使うと端のピクセルが破棄されます。画像データの切り詰めを含むデコーダーの警告も失敗として扱うため、-strict も使用してください。これらのオプションは
libjpeg-turbo の使用ガイドに記載されています。
この例では表示用のコピーを作成します。-copy icc はカラープロファイルを保持しますが、GPS、カメラ情報、著作権フィールド、XMP、コメント、埋め込みサムネイルなど、元の画像のその他のメタデータは破棄します。その後、ExifTool が EXIF Orientation の値を新たに 1 として書き込みます。メタデータが必要な場合は元画像を保存してください。代わりに
-copy all を使う場合は、古い向きフィールドやプレビューの扱いについて別途方針を決める必要があります。
Linux コマンドラインの準備
EXIF 拡張を備えた PHP CLI、libjpeg-turbo の jpegtran、ExifTool をインストールし、PATH から利用できるようにしてください。この手順は Linux 上の PHP 8.5.10、libjpeg-turbo 3.2.0、ExifTool 13.55 で検証しました。出力先には、ハードリンクをサポートするファイルシステム上の非公開ローカルディレクトリを使用します。
スクリプトを保存する前に、既存のインストール環境を確認してください。
php -d extension=exif -r 'if (!extension_loaded("exif") || !function_exists("proc_open")) { fwrite(STDERR, "PHP needs EXIF and proc_open.\n"); exit(1); } echo "PHP ", PHP_VERSION, ": EXIF and proc_open available\n";' &&
jpegtran -version &&
exiftool -ver
-d extension=exif オプションは、インストール済みの共有 EXIF 拡張を今回の呼び出しで有効にします。EXIF がすでに有効な場合は、以降すべての呼び出しでこのオプションを省略してください。二重に読み込むと警告が発生します。PHP が拡張を読み込めない場合は、続行する前に PHP のビルドに対応する拡張をインストールしてください。PHP の EXIF インストール手順と
CLI 設定オプションを参照してください。バージョン確認では libjpeg-turbo と ExifTool が識別され、PHP の起動警告が出ないことを確認します。
完全な PHP コマンドの保存
次のコードを orient-jpeg.php として保存してください。入力パスと新しい出力パスを受け取ります。exif_read_data()でセクションを分けて読み取り、メタデータの読み取り警告を拒否します。向きが 1 の JPEG やタグのない JPEG も
jpegtran で処理します。向きタグがないからといって、未検証のバイト列をコピーすることはありません。
引数配列を指定した proc_open()で、シェルを介さずにツールを起動します。入力パスは絶対パスに解決するため、ハイフンで始まるファイル名がツールのオプションとして解釈されることはありません。このコマンドをワーカー向けに変更する際は、アプリケーションコード内でパスを選択してください。この例では、HTTP クライアントから渡されたパスのアクセス権限を検証しません。
<?php
declare(strict_types=1);
function runTool(array $arguments): void
{
$process = proc_open($arguments, [
0 => ['file', '/dev/null', 'r'],
1 => ['file', '/dev/null', 'w'],
2 => STDERR,
], $pipes);
if ($process === false || proc_close($process) !== 0) {
throw new RuntimeException($arguments[0] . ' failed; see the diagnostic above.');
}
}
function orientJpeg(string $input, string $output): string
{
$source = realpath($input);
if ($source === false || !is_file($source) || !is_readable($source)) {
throw new RuntimeException('Input must be an existing, readable local file.');
}
$directory = realpath(dirname($output));
if ($directory === false || !is_dir($directory) || !is_writable($directory)) {
throw new RuntimeException('Output directory must exist and be writable.');
}
$destination = $directory . DIRECTORY_SEPARATOR . basename($output);
if (file_exists($destination) || is_link($destination)) {
throw new RuntimeException('Output already exists; choose a new filename.');
}
$metadata = exif_read_data($source, null, true);
if ($metadata === false) {
throw new RuntimeException('Cannot read JPEG headers.');
}
$orientation = $metadata['IFD0']['Orientation'] ?? 1;
$transforms = [
1 => [],
2 => ['-flip', 'horizontal'],
3 => ['-rotate', '180'],
4 => ['-flip', 'vertical'],
5 => ['-transpose'],
6 => ['-rotate', '90'],
7 => ['-transverse'],
8 => ['-rotate', '270'],
];
if (!is_int($orientation) || !isset($transforms[$orientation])) {
throw new RuntimeException('EXIF Orientation must be an integer from 1 to 8.');
}
$temporary = tempnam($directory, '.orient-');
if ($temporary === false) {
throw new RuntimeException('Cannot create a temporary output.');
}
try {
runTool([
'jpegtran', '-strict', '-perfect', '-copy', 'icc',
...$transforms[$orientation], '-outfile', $temporary, $source,
]);
runTool(['exiftool', '-overwrite_original', '-IFD0:Orientation#=1', $temporary]);
$written = exif_read_data($temporary, null, true);
if (($written['IFD0']['Orientation'] ?? null) !== 1) {
throw new RuntimeException('Could not verify the output orientation tag.');
}
// A hard link publishes the finished file without replacing an existing name.
if (!link($temporary, $destination)) {
throw new RuntimeException('Could not create the output; choose a new filename.');
}
} finally {
unlink($temporary);
}
return $destination;
}
// Reject PHP warnings, including unreadable or malformed metadata, instead of guessing.
set_error_handler(static function (int $severity, string $message): never {
throw new ErrorException($message, 0, $severity);
});
try {
if ($argc !== 3) {
throw new RuntimeException('Usage: php orient-jpeg.php INPUT.jpg OUTPUT.jpg');
}
if (!extension_loaded('exif') || !function_exists('proc_open')) {
throw new RuntimeException('PHP needs EXIF and proc_open enabled.');
}
$output = orientJpeg($argv[1], $argv[2]);
fwrite(STDOUT, "Saved: $output\n");
} catch (Throwable $error) {
fwrite(STDERR, 'Failed: ' . $error->getMessage() . "\n");
exit(1);
}
ExifTool の
-overwrite_original
オプションに渡すのは一時ファイルだけです。元ファイルは変更しません。PHP の link()は、処理が成功した後に出力先を作成します。既存のファイルやシンボリックリンクは拒否します。finally ブロックで、成功時も通常のエラー時も一時ファイル名を削除します。
アップロードした JPEG での実行
実際の JPEG を photo.jpg という名前でスクリプトと同じディレクトリに置き、次を実行してください。
php -d extension=exif orient-jpeg.php photo.jpg photo-fixed.jpg
成功すると Saved: に続けて出力先の絶対パスを表示し、終了ステータス 0 で終了します。失敗した場合は標準エラー出力に診断情報を書き込み、終了ステータス 1 で終了します。同じコマンドを再実行すると、photo-fixed.jpg の上書きを拒否します。空白を含むパスは引用符で囲んでください。
出力されたメタデータを調べます。
exiftool -n -IFD0:Orientation -ImageWidth -ImageHeight ./photo-fixed.jpg
Orientation が 1 になっていることを確認してください。向きが 5–8 の場合は幅と高さが入れ替わります。出力を開き、文字などの非対称な特徴を確認して、回転方向と鏡像の状態が両方とも正しいことを検証します。この出力を別のファイル名に再処理しても、画像の幾何学的な状態は変わらないはずです。
拒否されたファイルとバッチジョブへの対応
「transformation is not perfect」という診断は、要求した操作では端のブロックをすべて変換できないことを意味します。たとえば、下端に不完全なブロックがある JPEG の
90°回転が該当します。元画像を保存し、切り抜きや、デコードして再エンコードした派生画像をアプリケーションで許可するかどうかを決めてください。-perfect を削除すると、明示的な判断なしにこの方針が変わり、端の帯状領域が誤った向きのまま残ることがあります。
空ファイル、JPEG 以外のファイル、切り詰められた画像データ、不正な向きの値は、成功メッセージを出さずに失敗します。プログレッシブ JPEG の入力は受け付けますが、このコマンドはプログレッシブ出力を要求しません。また、特定の JPEG 互換性プロファイルへの変換も保証しません。
キューやバッチでは、入力ごとに異なる出力先を指定してコマンドを実行し、各終了ステータスを記録してください。拒否されたファイルの再試行は、失敗への対処方法を決めてから行います。これらのジョブは HTTP リクエストの外で実行してください。アップロードサイズとリソースの上限を適用し、ツールの診断情報はワーカーのログに保存し、クライアントには簡潔な失敗メッセージを返します。このローカルコマンドが扱うのは向きの正規化であり、アップロードの認証やワーカーのタイムアウトではありません。
