Msgpack Laravel Package

Product Decisions This Supports

• Serialization format for internal payloads in Laravel: cache values (Redis/Memcached), queued job payloads (Horizon), session blobs, broadcast/websocket frames, and internal service-to-service bodies. This is a "pick the wire format" decision, not a feature in itself — the package is one of several candidate implementations.
• Build vs. buy: buying here means adding a small Composer dependency; building means writing and maintaining an encoder. Because MessagePack is a published spec with implementations in most languages, the format choice is not vendor lock-in — only the PHP implementation is a dependency.
• Roadmap enablement: capabilities that JSON cannot express cheaply — binary-safe payloads (no base64 inflation), compact numeric arrays, first-class Timestamp (seconds + nanoseconds), custom extension types (e.g., DateTime serialized natively), and streaming unpacking of multiple framed messages from a single socket/chunked read. These unlock features like efficient time-series/vector/embedding storage, binary blob transport, and multiplexed connections.
• Cost/performance decisions: payload size on the wire and in Redis directly maps to memory, egress, and network cost. Numeric-heavy payloads are the strongest case; string-only, low-cardinality payloads usually are not.
• Use cases that justify evaluation: high-volume queue payloads, numeric matrices/vectors, image or file chunks avoiding base64's ~33% overhead, IoT/telemetry ingestion, and any place where a non-PHP consumer already speaks MessagePack.
• Deployment footprint decision: the pure PHP nature is the product-relevant differentiator. It removes a native-extension requirement from your base image, CI, and hosting contract — which is often the real blocker, not the format.

When to Consider This Package

Adopt when:

• You cannot or don't want to install ext-msgpack — shared hosting, constrained PaaS, locked corporate base images, Lambda layers, or a platform team that won't add extensions. This is the primary reason to choose this library over the C extension.
• Payloads are numeric-heavy or binary, where measured size reduction vs. JSON is material (not assumed).
• You need streaming decode of framed messages from a socket or chunked read (tryUnpack, append, seek, skip, release).
• You need unsigned 64-bit handling with a deliberate policy (BIGINT_AS_STR / GMP / Decimal) — a real correctness decision for IDs and counters.
• You want custom types without touching your domain classes (type transformers for objects you don't own, extensions for both directions).
• You can hide the format behind a single seam (a Serializer interface, a cache decorator, a queue payload cast) so the decision is reversible.

Look elsewhere when:

• ext-msgpack is installable. Then use it — a pure PHP codec will not beat a C implementation on CPU, and you should treat this package as the fallback, not the default.
• Schema evolution and cross-team contracts are the real problem. MessagePack is schemaless like JSON; you want Protobuf/Avro/JSON Schema, not a faster JSON.
• The hot path is CPU-bound and the payload is small. json_encode is native and often wins on throughput; benchmark your actual payloads before committing.
• Humans or browsers consume the payload — debuggability and curl-ability have real operational value.
• You need a vendor SLA or guaranteed maintainer coverage. Single-maintainer project with a limited tracked dependent footprint; treat bus factor as a real risk and mitigate with the abstraction seam plus a fork-ready license (MIT).
• You need encryption/compression middleware out of the box — plan to compose that yourself.

Gating questions for the go/no-go: Have we measured bytes and CPU on a representative payload? Is ext-msgpack genuinely unavailable? Is the format isolated behind one interface? Do we have a rollback (version-tagged payloads or dual-read)?

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost, reversible infrastructure choice. We are evaluating the format for internal payloads to cut Redis memory and network egress, and this library is the option that requires zero changes to our hosting, base images, or CI because it's pure PHP — no native extension to get approved or deployed. It's MIT-licensed and implements a public, multi-language standard, so we're not locked in. Decision cost is low and the escape hatch is a one-method interface swap. Ask: approve a short spike to measure bytes saved and CPU cost on real payloads before we commit.

To engineering: Pure-PHP, Composer-installable, PSR-4, no extension dependency. Fully spec-compliant with explicit pack/unpack options (bitmask, with mutual-exclusion validation and clear exceptions), streaming unpacking for chunked input, configurable unsigned-64-bit handling, and a clean extension/transformer model for custom types and Timestamp. Tested and fuzzed. The trade-off is honest: it will lose to ext-msgpack on raw throughput — so the plan is to put it behind a Serializer interface, benchmark against json_encode on our actual payloads, and feature-flag the rollout with a format version in the payload.

To the product team: The user-visible wins are indirect but real — smaller payloads mean faster cache reads at the tail, lower memory pressure at peak, cheaper storage/egress, and the ability to ship binary and nanosecond-timestamp data without base64 workarounds. The risk to manage is dependency concentration: isolate it so we can swap or fork without a rewrite.