PHP と AWS Textract によるリアルタイム請求書データ抽出
AWS Textract の同期操作 AnalyzeExpense を使い、ローカルの請求書画像を確認用の JSON 候補データに変換します。以下の PHP CLI は、繰り返し出現するフィールド、明細項目、数値の信頼度を保持します。請求書の計算を検証したり、支払いを承認したりするものではありません。
AWS Textract と PHP SDK v3 のセットアップ
cURL、Fileinfo、SimpleXML、および PNG/JPEG 対応の GD を備えた PHP が必要です。さらに、別途インストールした Composer と、シェルコマンド用の Bash が必要です。この例は PHP 8.5.11 と Composer 2.10.3 でテスト済みです。保守されている PHP 8.5 リリースを使用してください。SDK 自体は PHP 8.1 以降に対応していますが、この構成に含まれるすべての依存関係の互換性を保証するものではありません。
SDK の認証情報プロバイダーチェーンを使って、AWS 認証情報を設定してください。呼び出し元には、選択したリージョンでの
textract:AnalyzeExpense 権限が必要です。このバイトアップロードの例では、S3 バケット、SNS トピック、SQS キューは使用しません。サービスへのリクエストごとに料金が発生する可能性があります。
新しい invoice-ocr プロジェクトを作成したいディレクトリで、以下を貼り付けて実行してください。サブシェルを使うため、現在のディレクトリとシェルオプションは変更されません。作成先がすでに存在する場合は、インストール前に停止します。パッケージのバージョンは、テスト済みの SDK と、この例で直接使う Guzzle トランスポートに固定しています。ローカルのマニフェストを使い、Composer のパス上書き設定を解除することで、インストール先をこのプロジェクト内に限定します。
(
for tool in php composer; do
command -v "$tool" >/dev/null || { printf 'Missing prerequisite: %s\n' "$tool" >&2; exit 1; }
done &&
php -r 'foreach (["curl", "fileinfo", "SimpleXML", "gd"] as $extension) { if (!extension_loaded($extension)) { fwrite(STDERR, "Missing PHP extension: $extension\n"); exit(1); } } if (!(imagetypes() & IMG_PNG) || !(imagetypes() & IMG_JPG)) { fwrite(STDERR, "GD needs PNG and JPEG support\n"); exit(1); }' &&
unset COMPOSER COMPOSER_VENDOR_DIR COMPOSER_BIN_DIR &&
mkdir invoice-ocr &&
cd invoice-ocr &&
printf '{"require": {}, "config": {"vendor-dir": "vendor", "bin-dir": "vendor/bin"}}\n' > composer.json &&
composer require aws/aws-sdk-php:3.400.1 guzzlehttp/guzzle:8.2.0 &&
php -r 'require "vendor/autoload.php"; if (!class_exists(Aws\Textract\TextractClient::class) || !class_exists(GuzzleHttp\Handler\CurlHandler::class)) { exit(1); }'
)
composer.json と composer.lock は保持してください。ディレクトリ作成後にインストールが失敗した場合は、報告された前提条件やネットワークの問題を解決し、既存のファイルを保持したまま、そのディレクトリ内で再試行してください。
(
unset COMPOSER COMPOSER_VENDOR_DIR COMPOSER_BIN_DIR &&
cd invoice-ocr &&
{ [ -f composer.json ] || printf '{"require": {}, "config": {"vendor-dir": "vendor", "bin-dir": "vendor/bin"}}\n' > composer.json; } &&
composer require aws/aws-sdk-php:3.400.1 guzzlehttp/guzzle:8.2.0 &&
php -r 'require "vendor/autoload.php"; if (!class_exists(Aws\Textract\TextractClient::class) || !class_exists(GuzzleHttp\Handler\CurlHandler::class)) { exit(1); }'
)
AnalyzeExpense API の概要
AnalyzeExpense は ExpenseDocuments を返します。これには SummaryFields と、入れ子の LineItemGroups が含まれます。フィールドの分類は推論によるものです。有用な合計額や明細を認識できても、取引先名が含まれない場合があります。
この CLI が受け付ける入力は、空でないローカルの PNG または JPEG 一つです。ファイルサイズは最大 5,000,000 バイト、縦横はそれぞれ最大 5,000 ピクセル、総画素数は最大 10,000,000 ピクセルです。これらはファイル末尾のバイトも含むアプリケーション側の制限であり、AWS の最大ペイロードを示すものではありません。GD が警告を報告せずに画像をデコードできる必要があります。デコードは読み取り可能かどうかの確認であり、破損した画像の全ピクセルが無傷である証明にはなりません。PDF、TIFF、URL、複数ページの処理は、この CLI の対象外です。
同期型の請求書 CLI の構築
以下のプログラム全体を invoice-ocr/invoice.php として保存してください。元の画像バイトを送信し、分析と解析の両方が成功した後にのみ JSON を出力します。バイトのシリアライズは SDK が処理するため、入力を自分で base64 エンコードしないでください。
<?php
use Aws\Handler\Guzzle\GuzzleHandler;
use Aws\Textract\TextractClient;
use GuzzleHttp\Client;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\HandlerStack;
if (PHP_SAPI !== 'cli') {
http_response_code(404);
exit;
}
if ($argc !== 2) {
fwrite(STDERR, "Usage: php invoice.php <local-invoice.png|local-invoice.jpg>\n");
exit(1);
}
function parseExpense(array $result): array
{
return array_map(function (array $document): array {
$field = static fn (array $value): array => [
'type' => $value['Type']['Text'] ?? null,
'text' => $value['ValueDetection']['Text'] ?? null,
'confidence' => $value['ValueDetection']['Confidence'] ?? null,
];
$groups = [];
foreach ($document['LineItemGroups'] ?? [] as $group) {
$rows = [];
foreach ($group['LineItems'] ?? [] as $row) {
$rows[] = array_map($field, $row['LineItemExpenseFields'] ?? []);
}
$groups[] = ['index' => $group['LineItemGroupIndex'] ?? null, 'rows' => $rows];
}
return [
'expense_index' => $document['ExpenseIndex'] ?? null,
'summary' => array_map($field, $document['SummaryFields'] ?? []),
'line_item_groups' => $groups,
'requires_review' => true,
];
}, $result['ExpenseDocuments'] ?? []);
}
try {
foreach (['curl', 'fileinfo', 'SimpleXML', 'gd'] as $extension) {
if (!extension_loaded($extension)) {
throw new RuntimeException('Required PHP extension unavailable');
}
}
set_error_handler(static function (int $severity, string $message): never {
throw new RuntimeException('Local image or dependency could not be read');
});
$path = $argv[1];
if (str_contains($path, '://') || !is_file($path) || !is_readable($path)) {
throw new RuntimeException('Use a readable local file');
}
$bytes = file_get_contents($path, false, null, 0, 5_000_001);
if ($bytes === false || $bytes === '' || strlen($bytes) > 5_000_000) {
throw new RuntimeException('Use 1 to 5,000,000 bytes');
}
$mime = (new finfo(FILEINFO_MIME_TYPE))->buffer($bytes);
if (!in_array($mime, ['image/png', 'image/jpeg'], true)) {
throw new RuntimeException('Use PNG or JPEG');
}
$size = getimagesizefromstring($bytes);
if ($size === false || $size[0] > 5_000 || $size[1] > 5_000
|| $size[0] * $size[1] > 10_000_000) {
throw new RuntimeException('Image dimensions exceed the application bounds');
}
$image = imagecreatefromstring($bytes);
if ($image === false) {
throw new RuntimeException('Image cannot be decoded');
}
unset($image);
require __DIR__ . '/vendor/autoload.php';
$textract = new TextractClient([
'region' => getenv('AWS_REGION') ?: 'us-east-1',
'version' => '2018-06-27',
'http_handler' => new GuzzleHandler(new Client([
'handler' => HandlerStack::create(new CurlHandler()),
])),
'http' => ['connect_timeout' => 5, 'timeout' => 30],
'retries' => 2,
]);
$result = $textract->analyzeExpense(['Document' => ['Bytes' => $bytes]]);
$documents = parseExpense($result->toArray());
if ($documents === []) {
throw new RuntimeException('No expense documents returned');
}
echo json_encode($documents, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR), "\n";
} catch (Throwable $error) {
fwrite(STDERR, "Invoice analysis failed. Check local file readability, PNG/JPEG decoding, byte and pixel bounds, PHP extensions, SDK installation, credentials, region, and AnalyzeExpense permission.\n");
exit(1);
}
請求書画像をプロジェクト内に配置し、invoice-ocr があるディレクトリで実行してください。
(cd invoice-ocr && php invoice.php ./invoice.png)
JPEG の場合は、代わりに ./invoice.jpg を渡してください。スペースを含むパスはシェルの引用符で囲む必要があります。ハイフンで始まるファイル名の前には ./ を指定してください。プログラムの書き込み先は標準出力と標準エラー出力のみで、入力や既存の結果ファイルは変更しません。成功を確認する前に、既存の結果ファイルへ標準出力をリダイレクトすることは避けてください。分析が失敗しても、シェルがそのファイルを切り詰める可能性があります。請求書の JSON には機密データが含まれる可能性があるため、公開ログに出力しないでください。
請求書データの抽出と構造化
パーサーは、すべてのサマリー候補と明細候補を type、text、confidence に射影し、順序とドキュメント/グループの区切りを保持します。TOTAL、NAME、OTHER をキーとするマップでは上書きされる同一型の繰り返しも、配列なら保持できます。欠けているプロパティは null のままです。信頼度は値検出器のスコアであり、会計上の正しさを保証するものではありません。
レスポンスの抜粋例
この説明用ドキュメントには、同じ型の候補が二つ含まれています。実際のカテゴリ、値、スコアは異なります。この射影では、位置や形状、ラベル、通貨のメタデータ、元のページ参照を省略しています。
[
{
"expense_index": 1,
"summary": [
{ "type": "TOTAL", "text": "125.00", "confidence": 97.2 },
{ "type": "TOTAL", "text": "125.00 USD", "confidence": 88.5 }
],
"line_item_groups": [],
"requires_review": true
}
]
候補データを買掛金管理に取り込む前に、元の画像を確認し、小数と通貨の表記規則を解釈し、合計額を明細と照合して、確認結果を記録してください。ダッシュボードでは OCR テキストをエスケープしてください。確認に座標やページ参照が必要な場合は、この簡略化した射影だけに頼らず、データポリシーに従って SDK のレスポンス全体を保持してください。前処理やドキュメント変換については、当社のドキュメント処理サービスをご覧ください。
エラー処理と再試行の戦略
cURL ハンドラーは、試行ごとに接続タイムアウトを五秒、タイムアウトを 30 秒に設定します。SDK の再試行設定では、初回の試行後に二回の再試行を許可します。バックオフ、認証情報の検索、ローカル処理には別途時間がかかるため、これらの設定はコマンド全体の制限時間ではありません。接続が遅いと、小さな画像でも失敗する可能性があります。接続を確認し、必要性を判断して再試行してください。呼び出しを繰り返すと料金が発生する可能性があります。
HandlerStack::create は保持してください。Guzzle のデフォルトミドルウェアは、HTTP の失敗を
SDK が解釈できる拒否された Promise に変換します。このスタックを削除すると、サービスエラーの処理経路が変わります。リクエストが拒否された場合は、標準出力を空のまま、機密情報を除去した診断メッセージを出力し、ゼロ以外の終了コードで終了します。シェルのリダイレクトで作成された空ファイルを、請求書処理の成功結果と見なさないでください。
トラブルシューティング早見表
| 症状 | 次の確認事項 |
|---|---|
| プロジェクト作成前にセットアップが停止 | 必要な実行ファイルと PHP 拡張機能をそれぞれ確認 |
| プロジェクト作成後に Composer が失敗 | 報告されたエラーを解決し、上記の手順でインストールを再試行 |
| ローカル画像が拒否される | 空でないこと、実際の内容が PNG/JPEG であること、デコード、縦横と総画素数の両方の制限を確認 |
| ローカル確認後に分析が失敗 | 認証情報、リージョン、ネットワークアクセス、textract:AnalyzeExpense 権限を確認 |
| 想定したフィールドがない | 元の画像とほかの候補を確認。カテゴリや再現率の保証はなし |
| 値がもっともらしく見える | requires_review を保持。信頼度は合計額、通貨、支払いの正しさの証明ではない |
SNS + SQS による非同期処理の実装
複数ページの請求書や、呼び出し元の終了後も続ける必要があるジョブには、非同期の経費処理ワークフローを選んでください。StartExpenseAnalysis は S3 から読み取り、GetExpenseAnalysis は完了した結果をページネーション付きで取得します。AWS の非同期処理ガイドでは、SNS の完了通知と
SQS コンシューマーについて説明しています。これは別のアプリケーションです。必要なリソースと権限を用意し、ジョブの所有者と冪等性の状態を永続化し、永続的な処理が完了した後にのみメッセージの受信を確認してください。上記の同期 CLI には、このワークフローは実装されていません。
