 |
VOOZH | about |
|
VOOZH | about |
This document provides an overview of PackStream serialization in the PHP Bolt driver, including the bidirectional conversion between PHP types and binary PackStream format. PackStream is the binary protocol used by Bolt to efficiently encode structured data for transmission between client and server.
For detailed information on specific topics, see:
PackStream is a binary serialization format designed for efficient encoding of typed data in the Bolt protocol. It provides:
The serialization layer is version-specific, with PackStream v1 being the primary implementation supporting Bolt protocol versions 1 through 6.
Sources: src/packstream/v1/Packer.php1-250 src/packstream/v1/Unpacker.php1-294
The serialization system is organized around two core interfaces and their implementations:
Sources: src/packstream/v1/Packer.php16-17 src/packstream/v1/Unpacker.php17-18 src/protocol/v6/AvailableStructures.php1-64 src/protocol/AProtocol.php
The Packer class converts PHP values to binary PackStream format. It implements a generator-based architecture that yields chunks for efficient memory usage.
| Method | Purpose | Line Reference |
|---|---|---|
pack() | Main entry point for packing messages with signature | src/packstream/v1/Packer.php33-63 |
packInteger() | Variable-length integer encoding (TINY_INT to INT_64) | src/packstream/v1/Packer.php140-158 |
packFloat() | 64-bit float encoding (FLOAT_64) | src/packstream/v1/Packer.php132-135 |
packString() | UTF-8 string encoding with size variants | src/packstream/v1/Packer.php115-130 |
packList() | List/array encoding | src/packstream/v1/Packer.php188-207 |
packDictionary() | Map/object encoding | src/packstream/v1/Packer.php163-183 |
packStructure() | Custom structure encoding with signature | src/packstream/v1/Packer.php212-231 |
packByteArray() | Raw bytes encoding | src/packstream/v1/Packer.php236-248 |
The private p() method implements type dispatching based on PHP's native type system:
Sources: src/packstream/v1/Packer.php68-110
The Packer detects system endianness at construction and reverses byte order for integers when running on little-endian systems:
Sources: src/packstream/v1/Packer.php23-31 src/packstream/v1/Packer.php148
PackStream uses different encoding variants based on value size:
| Constant | Value | Purpose |
|---|---|---|
SMALL | 16 | Threshold for TINY variants |
MEDIUM | 256 | Threshold for 8-bit variants |
LARGE | 65536 | Threshold for 16-bit variants |
HUGE | 4294967295 | Maximum for 32-bit variants |
Sources: src/packstream/v1/Packer.php18-21
The Unpacker class reverses the packing process, converting binary PackStream data back to PHP types.
| Method | Purpose | Line Reference |
|---|---|---|
unpack() | Main entry point for unpacking messages | src/packstream/v1/Unpacker.php32-42 |
getSignature() | Retrieve message signature after unpacking | src/packstream/v1/Unpacker.php47-50 |
unpackInteger() | Variable-length integer decoding | src/packstream/v1/Unpacker.php210-231 |
unpackFloat() | 64-bit float decoding | src/packstream/v1/Unpacker.php237-245 |
unpackString() | UTF-8 string decoding | src/packstream/v1/Unpacker.php188-203 |
unpackList() | List/array decoding | src/packstream/v1/Unpacker.php252-272 |
unpackDictionary() | Map/object decoding | src/packstream/v1/Unpacker.php163-182 |
unpackStructure() | Custom structure decoding with instantiation | src/packstream/v1/Unpacker.php123-156 |
unpackByteArray() | Raw bytes decoding | src/packstream/v1/Unpacker.php278-291 |
The unpacker reads a marker byte and dispatches to the appropriate handler:
Sources: src/packstream/v1/Unpacker.php68-116
When unpacking structures, the Unpacker uses reflection to instantiate classes registered in $structuresLt:
Sources: src/packstream/v1/Unpacker.php123-156
Protocol versions define which structures are available through the AvailableStructures trait:
Note that graph structures (Node, Relationship, Path) appear only in unpackStructuresLt because they are server-to-client only. The client cannot create these structures for sending to the server.
Sources: src/protocol/v6/AvailableStructures.php34-62
PackStream supports the following type categories:
| PHP Type | PackStream Encoding | Marker Byte(s) |
|---|---|---|
null | NULL | 0xC0 |
bool (true) | TRUE | 0xC3 |
bool (false) | FALSE | 0xC2 |
int | TINY_INT to INT_64 | -16 to 127, 0xC8-0xCB |
float | FLOAT_64 | 0xC1 |
string | TINY_STRING to STRING_32 | 0x80-0x8F, 0xD0-0xD2 |
| PHP Type | PackStream Encoding | Marker Byte(s) |
|---|---|---|
array (list) | TINY_LIST to LIST_32 | 0x90-0x9F, 0xD4-0xD6 |
array (assoc) | TINY_MAP to MAP_32 | 0xA0-0xAF, 0xD8-0xDA |
Bytes | BYTES_8 to BYTES_32 | 0xCC-0xCE |
Structures are encoded with a signature byte following the structure header. For details on specific structures, see:
Sources: src/packstream/v1/Packer.php68-110 src/packstream/v1/Unpacker.php68-116
The Packer implements chunking for large messages, breaking them into 65535-byte chunks:
This allows streaming of arbitrarily large messages without loading the entire payload into memory.
Sources: src/packstream/v1/Packer.php50-63
The library provides generator interfaces for memory-efficient serialization of large collections:
These generators enable processing of large datasets (e.g., 50,000 records) without loading them entirely into memory, as validated by performance tests.
Sources: src/packstream/v1/Packer.php98-101 tests/PerformanceTest.php19-63 tests/packstream/v1/PackerTest.php188-226
The AProtocol class instantiates Packer and Unpacker with the appropriate structure registries:
Protocol versions define their available structures through traits like AvailableStructures, which populate $packStructuresLt and $unpackStructuresLt arrays.
Sources: src/protocol/AProtocol.php src/protocol/v6/AvailableStructures.php32-63
The PackStream implementation is thoroughly tested through multiple test suites:
| Test Class | Purpose | Line Reference |
|---|---|---|
PackerTest | Validates packing of all PHP types | tests/packstream/v1/PackerTest.php1-229 |
UnpackerTest | Validates unpacking of all PackStream types | tests/packstream/v1/UnpackerTest.php1-201 |
BytesTest | Tests Bytes object serialization | tests/packstream/v1/BytesTest.php1-59 |
The PerformanceTest validates memory-efficient serialization with generators:
This ensures that large datasets can be processed without excessive memory consumption.
Sources: tests/packstream/v1/PackerTest.php1-229 tests/packstream/v1/UnpackerTest.php1-201 tests/PerformanceTest.php19-63
Packer uses yield to stream chunks, avoiding memory buildupIPackListGenerator and IPackDictionaryGenerator enable streaming of large collectionsThe library detects system endianness once at construction and caches the result, avoiding repeated detection on every integer pack/unpack operation.
PackStream's variable-length encoding minimizes wire size:
Sources: src/packstream/v1/Packer.php23-31 src/packstream/v1/Packer.php140-158 tests/PerformanceTest.php19-63
Refresh this wiki