Msgpack Laravel Package

Getting Started

Install via Composer: composer require rybakit/msgpack. Start with basic packing/unpacking using MessagePack::pack($value) and MessagePack::unpack($packed). The default behavior handles common PHP types automatically — arrays become MessagePack arrays or maps depending on keys, strings become UTF-8 str by default. First practical use case: serialize small PHP arrays/objects for caching or inter-process communication (e.g., Redis) where compact binary format improves performance over JSON.

Implementation Patterns

• Explicit type control: Use Map, Bin, or packMap()/packArray() to avoid auto-detection overhead and ensure deterministic serialization (e.g., when schema matters for deserialization).
• Streaming & chunked data: Leverage BufferUnpacker with append()/tryUnpack() for network sockets, file streaming, or Redis streams where messages arrive incrementally.
• Large integers: Configure unpacking with UnpackOptions::BIGINT_AS_STR (default), BIGINT_AS_GMP, or BIGINT_AS_DEC when handling 64-bit unsigned IDs (e.g., from databases or APIs).
• Custom types: Implement CanBePacked interface for domain objects you control; use TypeTransformer (e.g., StreamTransformer) for external types like resources or classes you cannot modify.
• Timestamps: Register TimestampExtension to preserve nanosecond precision across DateTime-like needs, or use the built-in Timestamp class with MessagePack::pack(Timestamp::now()).
• Performance: Combine packing options (e.g., PackOptions::FORCE_STR | PackOptions::FORCE_FLOAT32) to bypass auto-detection when data types are known in advance — especially useful in tight loops or high-throughput pipelines.

Gotchas and Tips

• Array → Map ambiguity: PHP arrays with non-sequential or non-zero-starting keys (e.g., [1 => 'a', 3 => 'b']) auto-pack as map. Ensure consumers expect maps, or force with PackOptions::FORCE_ARR/FORCE_MAP.
• Binary string detection: Without PackOptions::FORCE_BIN, strings like "abc\x00" might be auto-detected as bin — test edge cases to avoid unintended type coercion.
• Extension ID collision: Custom extension IDs must be unique (0–127) across all systems consuming your data. Document IDs rigorously; consider reserving ranges per service or module.
• GMP/Decimal dependencies: BIGINT_AS_GMP and BIGINT_AS_DEC require PHP extensions to be installed — failures may surface only in production if dev环境 lacks them.
• Streaming unpacking gotcha: tryUnpack() may return empty [] even when more data is pending — only check for non-empty return to process complete messages.
• Debugging: Use unpackExt() and inspect Ext object’s type code and data to troubleshoot malformed or unexpected binary payloads. Also enable strict error handling by catching PackingFailedException/UnpackingFailedException.