Bytebuffer Laravel Package

Getting Started

Install via Composer: composer require trafficcophp/bytebuffer, then import TrafficCophp\ByteBuffer\ByteBuffer. Its core use case is constructing binary protocol frames—e.g., TCP socket messages with fixed headers and variable payloads. Start by allocating a buffer of exact size, then write scalar types (integers, strings) at explicit byte offsets. The README’s socket client example is the canonical first use: build a length-prefixed frame with header fields (writeInt32BE, writeInt8, writeString) and send via socket_write($socket, (string)$buffer, $buffer->length()).

Implementation Patterns

• Protocol framing: Build request/response structures common in low-level networking (e.g., gRPC Lite, custom game protocols): write magic bytes, version, flags, payload length, then raw payload—each at calculated offsets.
• Sequential in-place construction: Since writes are offset-driven (e.g., write($data, $offset)), maintain an internal cursor or precompute field sizes (e.g., 4 + 1 + 4 + strlen($channel)) to avoid overwrites. Wrap frequent sequences (e.g., header write + payload write) in helper methods.
• Socket message batching: For persistent connections, construct multi-message frames by writing buffers sequentially (e.g., send 3 requests back-to-back) and reuse buffer instances with clear() or reinitialize with new sizes.
• Cross-platform interoperability: Use writeInt32BE() for network-byte-order fields (big-endian), writeInt32LE() for little-endian targets (e.g., Windows APIs), and verify against server expectations using bin2hex((string)$buffer).
• Fallback for pack()/unpack() fatigue: When repeating complex pack('Nva*a*', ...) chains, extract the logic into a ByteBuffer-backed class (e.g., HttpRequestFrame) for cleaner maintainability.

Gotchas and Tips

• No automatic cursor: Unlike Node.js Buffers, this package writes only at explicit offsets—no incrementing position. Track offsets manually or subclass ByteBuffer to add a cursor (e.g., $buffer->writeInt32BE(123) → $buffer->writeInt32BE(123, $cursor++) with $cursor++).
• Precompute exact sizes: Buffers don’t auto-resize—over-allocate and __toString() truncates to length(), but under-allocation causes silent overwrites. Log expected vs actual sizes during development.
• Endianness silently breaks interoperability: Mismatched BE/LE is the #1 bug source. Document expected byte order per field in comments (e.g., // Length MUST be big-endian per spec v1.2).
• String length ≠ written bytes: write($str) uses strlen($str), not mb_strlen()—be cautious with multibyte strings; encode first (e.g., utf8_encode() or mb_convert_encoding()).
• Unmaintained = own maintenance burden: The repo lacks read*() methods and concatenation tests. Fork early to add critical features (e.g., concat(), readInt32BE($offset)) and lock to a commit in composer.json—never use dev-master.
• Debug with hex dumps: Use str_pad(dechex(ord($byte)), 2, '0', STR_PAD_LEFT) or bin2hex($buffer->slice($offset, $length)) to validate byte sequences against protocol specs—especially for multi-byte fields where offsets shift silently.