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

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関数を使用して、複数のデータ型を特定のバイナリフォーマットにパックするシンプルな例。
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進数で内容を確認できます。