【PHP8.x】pack()関数の使い方

Copy
1<?php
2
3/**
4 * pack関数を使用して、複数のデータ型を特定のバイナリフォーマットにパックするシンプルな例。
5 * この関数は、数値や文字列などのデータを指定された規則に従ってバイト列に変換し、
6 * 低レベルのバイナリデータ構造（例：カスタムファイルフォーマット、ネットワークプロトコル）を構築する際に利用されます。
7 *
8 * @param int $itemId パックするアイテムの整数ID (符号なしショート、リトルエンディアン)
9 * @param string $itemName パックするアイテムの名前 (10バイト固定長、NULL埋め)
10 * @param float $itemPrice パックするアイテムの価格 (単精度浮動小数点数、リトルエンディアン)
11 * @return string|false パックされたバイナリ文字列、またはパックに失敗した場合はfalse
12 */
13function packItemData(int $itemId, string $itemName, float $itemPrice): string|false
14{
15    // フォーマット文字列の定義:
16    // 'v': 符号なしショート (16ビット、リトルエンディアン)
17    // 'a10': 10バイトの文字列 (NULLまたはスペースで埋められ、必要に応じて切り詰め)
18    // 'g': 単精度浮動小数点数 (IEEE 754形式、リトルエンディアン)
19    $format = 'v a10 g';
20
21    // アイテム名を10バイトに切り詰める。pack関数も自動で処理しますが、明示的に切り詰めることもできます。
22    $trimmedName = substr($itemName, 0, 10);
23
24    // 指定されたフォーマットに従ってデータをバイナリ文字列にパック
25    $packedData = pack($format, $itemId, $trimmedName, $itemPrice);
26
27    if ($packedData === false) {
28        // パック処理が失敗した場合のエラーハンドリング
29        return false;
30    }
31
32    // パックされたバイナリデータとその内容をデバッグ表示
33    echo "--- パック処理結果 ---\n";
34    echo "アイテムID: " . $itemId . "\n";
35    echo "アイテム名: '" . $itemName . "' (パックされた名前: '" . $trimmedName . "')\n";
36    echo "アイテム価格: " . $itemPrice . "\n";
37    echo "パックされたバイナリデータ (16進数): " . bin2hex($packedData) . "\n";
38    echo "----------------------\n\n";
39
40    return $packedData;
41}
42
43// サンプル実行
44packItemData(101, "Laptop", 1200.50);
45packItemData(205, "USB Drive X", 15.99);
46packItemData(300, "External Hard Drive (1TB)", 89.95); // 名前が10バイトを超える場合の例
47
48?>

PHPのpack関数は、整数や文字列、浮動小数点数といった様々なデータ型を、指定された規則に従ってバイナリデータに変換するために使用されます。この関数は、カスタムファイルフォーマットの構築やネットワークプロトコルの実装など、低レベルのバイナリデータを扱う場面で特に役立ちます。

第一引数$formatには、データをどのようにバイナリに変換するかを定義する文字列を指定します。例えば、サンプルコードの'v'は符号なしショート整数（16ビット、リトルエンディアン）、'a10'は10バイトのNULL埋め文字列、'g'は単精度浮動小数点数（リトルエンディアン）を表します。第二引数以降の...$valuesには、$formatで指定した型と順序で変換したい値を渡します。

サンプルコードでは、アイテムID（整数）、アイテム名（文字列）、アイテム価格（浮動小数点数）を一つのバイナリデータにパックする例を示しています。packItemData関数は、これらの値を'v a10 g'というフォーマットでパックし、結果としてバイナリ文字列を返します。もしパック処理に失敗した場合はfalseが戻り値として返されるため、エラーハンドリングを行うことが重要です。成功したバイナリデータは、bin2hex関数などを使って16進数で内容を確認できます。

Copy
1<?php
2
3/**
4 * Creates a simple binary data packet using the pack function.
5 *
6 * This function demonstrates how to assemble different data types
7 * (like integers and strings) into a single binary string.
8 * Such binary strings are often used for network protocols,
9 * binary file formats, or inter-process communication,
10 * effectively "packaging" data for specific transmission or storage needs.
11 *
12 * @param int    $packetType    An integer representing the type of packet (e.g., 1 for command, 2 for data).
13 * @param int    $packetId      A unique identifier for this packet.
14 * @param string $payloadData   The actual data content to be included in the packet.
15 * @return string|false         The binary packed string, or false on error.
16 */
17function createBinaryPacket(int $packetType, int $packetId, string $payloadData): string|false
18{
19    // Define the format string for packing values:
20    // C:  unsigned char (1 byte) for packet type.
21    // n:  unsigned short (2 bytes), network byte order (big-endian) for packet ID.
22    // n:  unsigned short (2 bytes), network byte order (big-endian) for payload length.
23    // a*: null-padded string for payload data. When '*' is used, it packs the exact length
24    //     of the string provided as the argument.
25    $format = "Cnn a*";
26
27    // Calculate the length of the payload data.
28    // This length is packed into the packet itself so that a receiver knows
29    // exactly how many bytes to read for the variable-length string payload.
30    $payloadLength = strlen($payloadData);
31
32    // Pack the values into a binary string according to the defined format.
33    // The 'pack' function returns a binary string representing the assembled data.
34    $packedPacket = pack($format, $packetType, $packetId, $payloadLength, $payloadData);
35
36    return $packedPacket;
37}
38
39// --- Example Usage ---
40// This section demonstrates how to use the createBinaryPacket function.
41// To adhere strictly to output conditions, this example does not print directly
42// to the console, but shows how the function would typically be used and
43// what kind of result to expect.
44
45$packetType = 1; // Example: A type identifier for the packet
46$packetId = 12345; // Example: A unique identifier for this specific packet
47$payloadData = "Hello, PHP pack functionality!"; // The actual data content to be packaged
48
49$binaryPacket = createBinaryPacket($packetType, $packetId, $payloadData);
50
51if ($binaryPacket !== false) {
52    // The $binaryPacket variable now holds the binary string.
53    // For the given example inputs, its hexadecimal representation would be:
54    // "013039001a48656c6c6f2c20504850207061636b2066756e6374696f6e616c69747921"
55    // And its total length would be 31 bytes:
56    // (1 byte for 'packetType' + 2 bytes for 'packetId' + 2 bytes for 'payloadLength' + 26 bytes for 'payloadData')
57    // This binary string could then be saved to a file, sent over a network, etc.
58    //
59    // To inspect the result (e.g., for debugging):
60    // var_dump(bin2hex($binaryPacket));
61    // var_dump(strlen($binaryPacket));
62} else {
63    // Handle error case: pack() returns false if an error occurs (e.g., invalid format string).
64    // In a real-world application, this would typically involve logging the error
65    // or throwing an exception to indicate a failure in packet creation.
66    // error_log("Failed to create binary packet.");
67}
68

PHPのpack関数は、複数の異なるデータ（数値や文字列など）を、指定されたフォーマットに従って一つのバイナリ文字列に結合（パッケージング）する機能を提供します。これは、ネットワーク通信で特定のプロトコルに合わせたデータを送受信したり、バイナリファイル形式のデータを作成したりする際に非常に便利です。

サンプルコードのcreateBinaryPacket関数は、pack関数を使用して、パケットの種類、パケットID、データ本体の長さをバイナリ形式でまとめ、その後にデータ本体を連結したバイナリパケットを作成しています。pack関数の第一引数$formatには、各データがどのようにバイナリ化されるかを定義するフォーマット文字列を指定します。例えば、"Cnn a*"というフォーマットは、1バイトの符号なし整数（C）、2バイトのネットワークバイトオーダーの符号なし整数（n）を2回、そして文字列の長さに応じた文字列（a*）が続くことを意味します。第二引数以降の...$valuesには、このフォーマット文字列に対応する値を順番に渡します。

pack関数は、これらの値をフォーマットに従って変換し、結合されたバイナリ文字列を返します。もしフォーマット文字列に誤りがあるなど、処理に失敗した場合はfalseを返します。このバイナリ文字列は、そのままネットワークに送信したり、ファイルに書き込んだりして活用できます。

Copy
1<?php
2
3/**
4 * pack 関数と unpack 関数の使用例を示します。
5 *
6 * pack 関数は、PHP の値を指定されたフォーマットに基づいてバイナリ文字列にパック（変換）します。
7 * unpack 関数は、パックされたバイナリ文字列を読み取り、元の PHP の値にアンパック（復元）します。
8 * これらの関数は、ネットワークプロトコルやファイル形式など、固定長のバイナリデータ構造を
9 * 扱う際に特に有用です。
10 */
11function demonstratePackUnpack(): void
12{
13    // 1. パックする元のデータを用意します。
14    // ここでは、ユーザーID (1バイト整数)、年齢 (2バイト整数)、ユーザー名 (文字列) を例とします。
15    $original_userId = 123;
16    $original_age = 30;
17    $original_userName = "Alice Smith";
18
19    echo "--- オリジナルデータ ---" . PHP_EOL;
20    echo "ユーザーID: " . $original_userId . PHP_EOL;
21    echo "年齢: " . $original_age . PHP_EOL;
22    echo "ユーザー名: " . $original_userName . PHP_EOL . PHP_EOL;
23
24    // 2. pack 関数を使ってデータをバイナリ文字列に変換します。
25    // フォーマット指定の例:
26    // 'C': 符号なし char (1バイト整数)
27    // 'n': 符号なし short (2バイト整数、ネットワークバイトオーダー = ビッグエンディアン)
28    // 'A*': NULLバイトで埋められる文字列 ('*' は残りのバイトすべてを意味)
29    $packedData = pack(
30        'CnA*', // フォーマット文字列: 1バイト、2バイト(ビッグエンディアン)、可変長文字列
31        $original_userId,
32        $original_age,
33        $original_userName
34    );
35
36    if ($packedData === false) {
37        echo "エラー: pack 関数が失敗しました。" . PHP_EOL;
38        return;
39    }
40
41    echo "--- pack 後のデータ ---" . PHP_EOL;
42    // バイナリ文字列は通常表示できないため、16進数に変換して表示します。
43    echo "バイナリ文字列 (16進数): " . bin2hex($packedData) . PHP_EOL;
44    echo "バイト数: " . strlen($packedData) . PHP_EOL . PHP_EOL;
45
46    // 3. unpack 関数を使ってバイナリ文字列を元のデータに復元します。
47    // フォーマット指定の例:
48    // 'CuserId': 1バイト符号なし char を 'userId' というキーで取り出す
49    // 'nage': 2バイト符号なし short (ネットワークバイトオーダー) を 'age' というキーで取り出す
50    // 'A*userName': NULLバイトで埋められる文字列を 'userName' というキーで取り出す
51    $unpackedData = unpack(
52        'CuserId/nage/A*userName', // フォーマット文字列: キー名を含めることで連想配列として結果が得られます
53        $packedData
54    );
55
56    if ($unpackedData === false) {
57        echo "エラー: unpack 関数が失敗しました。" . PHP_EOL;
58        return;
59    }
60
61    echo "--- unpack 後のデータ ---" . PHP_EOL;
62    echo "ユーザーID: " . ($unpackedData['userId'] ?? 'N/A') . PHP_EOL;
63    echo "年齢: " . ($unpackedData['age'] ?? 'N/A') . PHP_EOL;
64    echo "ユーザー名: " . ($unpackedData['userName'] ?? 'N/A') . PHP_EOL . PHP_EOL;
65
66    // 4. 結果の検証
67    echo "--- 検証 ---" . PHP_EOL;
68    if (
69        ($unpackedData['userId'] ?? null) === $original_userId &&
70        ($unpackedData['age'] ?? null) === $original_age &&
71        ($unpackedData['userName'] ?? null) === $original_userName
72    ) {
73        echo "データは正しくパックされ、元の状態にアンパックされました。" . PHP_EOL;
74    } else {
75        echo "エラー: パック/アンパックされたデータが元のデータと一致しません。" . PHP_EOL;
76    }
77}
78
79// 関数を実行します
80demonstratePackUnpack();

PHPのpack関数は、複数のPHPの値を指定されたフォーマットに従って、単一のバイナリ文字列に変換する役割を持ちます。この関数は、主にネットワークプロトコルやファイル形式など、固定長のバイナリデータ構造を扱う際に非常に有用です。

第一引数$formatには、変換する値の型やバイト数、バイトオーダーなどを定義するフォーマットコード（例: Cは1バイト符号なし整数、nは2バイト符号なし整数）を文字列で指定します。続く引数...$valuesには、$formatに指定された順序で変換対象のPHPの値を複数渡します。処理が成功するとバイナリ文字列が戻り値として返され、失敗した場合はfalseが返されます。

サンプルコードでは、ユーザーID、年齢、ユーザー名といったPHPの値をpack関数でバイナリ文字列に変換しています。生成されたバイナリ文字列は、通常表示できないため、bin2hex関数で16進数表示することで内容を確認できます。さらに、pack関数で生成したバイナリ文字列を、unpack関数を使って元のPHPの値に復元する一連の流れも示されています。unpack関数もフォーマット文字列を使用し、キー名を含めることで元のデータを連想配列として取り出す挙動をします。これにより、packとunpackはPHPと外部システム間でのバイナリデータ交換において重要な役割を果たします。

Copy
1<?php
2
3/**
4 * 簡易的なパッケージ情報リストをバイナリデータとしてパックします。
5 * 各パッケージはIDと名前を持ち、これらがまとめて一つの「データパッケージ」として表現されます。
6 * これは、システム間でデータを効率的にやり取りする際や、特定のバイナリファイル形式を生成する際に役立ちます。
7 *
8 * @param array<array{id: int, name: string}> $packages パックするパッケージ情報のリスト。
9 *                                                      各要素は 'id' (int) と 'name' (string) を含む連想配列である必要があります。
10 * @return string|false パックされたバイナリデータ。パックに失敗した場合は false を返します。
11 */
12function packPackageList(array $packages): string|false
13{
14    // 全体パッケージのヘッダー情報
15    // 簡易的なバージョン番号とリスト内のパッケージ数を含めます。
16    $packageListVersion = 1; // パッケージリストのバージョン（1バイト）
17    $packageCount = count($packages); // リスト内のパッケージ数（1バイト）
18
19    // ヘッダーをバイナリ形式にパックします。
20    // 'C' は符号なし char（1バイト）を表し、それぞれバージョンと数値をパックします。
21    $packedHeader = pack('CC', $packageListVersion, $packageCount);
22    if ($packedHeader === false) {
23        // pack関数が失敗した場合（例: 不正なフォーマット文字列）
24        return false;
25    }
26
27    $packedItemsData = '';
28    foreach ($packages as $package) {
29        // 各パッケージ情報の名前の長さを計算します。
30        // これにより、後でunpackする際に名前のデータを正しく読み込むことができます。
31        $nameLength = strlen($package['name']);
32
33        // 各パッケージの情報をバイナリ形式にパックします。
34        // 'n' はネットワークバイトオーダー（ビッグエンディアン）の符号なし short（2バイト）でIDをパックします。
35        // 'C' は符号なし char（1バイト）で名前の長さをパックします。
36        // 'a*' は残りの文字列をそのままパックします（ここではパッケージ名）。
37        $packedItem = pack('nCa*', $package['id'], $nameLength, $package['name']);
38        if ($packedItem === false) {
39            // pack関数が失敗した場合
40            return false;
41        }
42        $packedItemsData .= $packedItem;
43    }
44
45    // ヘッダーと全てのパッケージデータを結合し、最終的なバイナリパッケージデータとします。
46    return $packedHeader . $packedItemsData;
47}
48
49// --- サンプルコードの実行 ---
50
51// パックするパッケージ情報のリストを作成します。
52$packageListToPack = [
53    ['id' => 101, 'name' => 'CoreLib'],
54    ['id' => 202, 'name' => 'UtilKit'],
55    ['id' => 303, 'name' => 'DataBridge'],
56    ['id' => 404, 'name' => 'AppModuleX'],
57];
58
59// packageListToPack をバイナリデータとしてパックします。
60$binaryPackageData = packPackageList($packageListToPack);
61
62if ($binaryPackageData !== false) {
63    echo "パッケージリストをバイナリデータとして正常にパックしました。\n";
64    echo "生成されたバイナリデータの長さ: " . strlen($binaryPackageData) . " バイト\n";
65
66    // バイナリデータは通常、直接表示すると文字化けするため、
67    // 16進数表現に変換して表示することで内容を確認しやすくします。
68    echo "16進数表現: " . bin2hex($binaryPackageData) . "\n";
69
70    // このバイナリデータは、ファイルに保存したり、ネットワーク経由で送信したりすることができます。
71    // 例: file_put_contents('package_list.bin', $binaryPackageData);
72} else {
73    echo "パッケージリストのパックに失敗しました。\n";
74}

PHPのpack関数は、指定された値をバイナリデータに変換し、文字列として返す機能です。この機能は、システム間でデータを効率的にやり取りする際や、特定のバイナリファイル形式を生成する際に利用されます。

このサンプルコードは、IDと名前を持つパッケージのリストをバイナリデータとしてパックする方法を示しています。pack関数は、第一引数$formatで変換ルール（例: Cは1バイト整数、nは2バイト整数、a*は文字列）を、第二引数以降$valuesで変換したい値を指定します。

コードでは、まずリスト全体のバージョンとパッケージ数をCフォーマットでパックし、ヘッダーを作成しています。次に、各パッケージのIDをnフォーマット、名前の長さをCフォーマット、名前自体をa*フォーマットでパックし、これらを結合しています。これにより、元のデータがコンパクトなバイナリ形式で表現されます。

pack関数は成功するとバイナリ文字列を、失敗するとfalseを返します。そのため、戻り値を確認し、エラー処理を行うことが重要です。生成されたバイナリデータは、ファイル保存やネットワーク通信に活用できます。