README

A lightweight PHP library for parsing binary data from byte arrays. Supports signed and unsigned integers, arrays, and endian-aware formats (big/little endian). Ideal for reading hardware data streams, binary protocols, or any low-level byte-oriented data.

Features

Supports 8, 16, 24, 32, and 64-bit integers
Signed and unsigned parsing
Little-endian and big-endian support
Bytes are consumed from the buffer after each read
Multi-read support (readMany())
Resettable buffer with resetBuffer()
Type-safe with meaningful exceptions

Installation

You can install via Composer:

composer require pigeonboys/php-binary-parser

PHP version 8.0+ is required.

Usage

Basic Usage

use PigeonBoys\PhpBinaryParser\BinaryParser;

$buffer = [0x12, 0x34, 0x56, 0x78];
$parser = new BinaryParser($buffer);

// Read an unsigned 16-bit integer in big-endian
$value = $parser->int16()->unsigned()->bigEndian()->read();
echo $value; // 4660

// After this read, the first two bytes are removed from the buffer
echo $parser->bytesRemaining(); // 2

Reading Multiple Values

$parser = new BinaryParser([0x01, 0x02, 0x03, 0x04]);

// Read two unsigned 8-bit integers
$values = $parser->int8()->unsigned()->readMany(2);
print_r($values); // [1, 2]

// Only remaining bytes are left in the buffer
echo $parser->bytesRemaining(); // 2

Resetting Buffer

$parser->resetBuffer(); // restores all original bytes

Methods

int8(), int16(), int24(), int32(), int64() — Set the bitness
signed(), unsigned() — Set the signedness
littleEndian(), bigEndian() — Set the endianness
read() — Read a single value and consume bytes from the buffer
readMany(int $count) — Read multiple values and consume bytes from the buffer
resetBuffer() — Reset buffer to original content
bytesRemaining() — Get the number of bytes left

Exceptions

BitnessAlreadySetException — Thrown if you try to set the bitness more than once before reading.
EndiannessAlreadySetException — Thrown if you try to set the endianness more than once before reading.
SignednessAlreadySetException — Thrown if you try to set signedness more than once before reading.
BitnessNotSetException — Thrown if you attempt to read an integer without first specifying the bitness.
EndiannessNotSetException — Thrown if you attempt to read a multi-byte integer without specifying endianness (except 8-bit).
SignednessNotSetException — Thrown if you attempt to read an integer without specifying signed or unsigned.
InvalidLengthException — Thrown if the number of bytes requested for readBytes() is less than 1.
InvalidCountException — Thrown if readMany() is called with a count less than 1.
CurrentBufferUnderflowException — Thrown if there are not enough bytes left in the buffer to satisfy a read.

pigeonboys / php-binary-parser

Maintainers

Details