thesis / io
Fast binary I/O: byte buffer with typed encoding, non-blocking streams and stdio.
Fund package maintenance!
Requires
- php: ^8.5
- php-64bit: *
- revolt/event-loop: ^1.0.9
- thesis/async: ^0.1
- thesis/time: ^0.3
Requires (Dev)
- testo/assert: ^0.1.17
- testo/codecov: ^0.2.5
- testo/data: ^0.1.10
- testo/lifecycle: ^0.1.9
- testo/test: ^0.1.8
- testo/testo: ^0.10.29
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 08:51:09 UTC
README
Fast binary I/O for PHP: an in-memory byte buffer with typed big/little-endian encoding and varints,
minimal Reader / Writer / Closer interfaces for streams, and the streams themselves: non-blocking
streams over PHP resources and stdio.
Streams wait through thesis/async: every wait is cancelled by the task tree.
It is the byte layer for binary protocol implementations (AMQP, Kafka, protobuf, gRPC, NATS, ...):
codecs work on a Buffer, connections move bytes between a Buffer and a socket.
Installation
composer require thesis/io
Requires 64-bit PHP 8.5+. No extensions.
Usage
Encoding
use Thesis\Io\Buffer; use Thesis\Io\Order; $buffer = new Buffer(); // Order::Network (big endian) by default $buffer ->writeUint8(1) ->writeUint16(0) ->writeInt32(-200) ->writeDouble(2.5) ->writeUvarint(300) ->write('raw bytes'); $bytes = $buffer->drain(); // returns all unread bytes and clears the buffer
Decoding
$buffer = new Buffer(Order::Little, $bytes); $type = $buffer->readUint8(); $value = $buffer->readInt64(); $payload = $buffer->read(16); // exactly 16 bytes $header = $buffer->peek(4); // does not advance the cursor $buffer->skip(2); $nested = $buffer->slice(32); // next 32 bytes as a separate Buffer, e.g. a nested message $left = $buffer->count(); // number of unread bytes; count($buffer) works too, but is slower
Reading past the end throws Thesis\Io\UnexpectedEof and leaves the cursor where it was.
Length prefixes known only after writing
$mark = $buffer->reserve(4); // 4 zero bytes to be patched later foreach ($table as $key => $value) { // write entries... } $buffer->patchUint32($mark, $buffer->sizeSince($mark) - 4);
patchUint8(), patchUint16(), patchUint32() and patchUint64() overwrite bytes in place without copying the buffer.
Marks are invalidated by fill(), flush() and drain().
Varints
$buffer->writeUvarint(300); // unsigned LEB128: protobuf varint, Kafka unsigned varint $buffer->writeVarint(-1); // zigzag: protobuf sint32/sint64, Kafka varint/varlong $buffer->readUvarint(); $buffer->readVarint();
Streams
Reader::read(int $max) returns from 1 to $max bytes, throws UnexpectedEof at the end of the stream
and ReadFailed if the read fails otherwise (a connection reset),
Writer::write(string $bytes) writes all the bytes. Both may suspend the fiber while they wait.
A read that throws, Cancelled included, has taken nothing, so a timeout() around a read loses no bytes.
Buffer turns them into exact, buffered reads and batched writes:
use Thesis\Io\Buffer; use function Thesis\Net\connect; $socket = connect('localhost', 5672); // thesis/net, a Reader and a Writer $in = new Buffer(); $out = new Buffer(); // write a frame and send it in one call $out->writeUint8(1)->writeUint16(0)->writeUint32(\strlen($payload))->write($payload)->writeUint8(0xCE); $out->flush($socket); // read a frame: fill() reads in large chunks until enough bytes are buffered $in->fill($socket, 7); $type = $in->readUint8(); $channel = $in->readUint16(); $size = $in->readUint32(); $in->fill($socket, $size + 1); $payload = $in->read($size);
Line-based protocols:
// the bytes before the delimiter, or null if the delimiter is not buffered yet $line = $in->readUntil("\r\n"); if ($line === null) { // read from the socket only when the buffered bytes do not contain a whole line $in->fillUntil($socket, "\r\n"); // throws \OverflowException if no delimiter within 64 KiB $line = $in->readUntil("\r\n"); }
Streams over resources and stdio
Stream adapts a PHP stream resource that the process owns (a pipe of proc_open(), a file, a socket without TLS)
to Reader, Writer and Closer. It makes the resource non-blocking: a read waits for bytes and a write
for room in the pipe without blocking the event loop. As with sockets of thesis/net, one fiber reads at a time,
writes of concurrent fibers never interleave, and a write that fails after a part of its bytes closes the stream.
One read returns at most 1 MiB, whatever $max is: PHP allocates the whole length before reading.
Reads and writes that never have to wait (a file, /dev/null, a fast peer) still yield to the event loop
now and then, so a loop of them does not starve the other tasks.
stdin(), stdout() and stderr() are streams over the standard descriptors, the same object every time:
use function Thesis\Io\stdin; use function Thesis\Io\stdout; $line = new Buffer(); $line->fillUntil(stdin(), "\n"); stdout()->write(strtoupper($line->readUntil("\n")) . "\n");
A standard descriptor shares its blocking mode with the shell, the other jobs of the terminal and the children
that inherit it, so these streams never change it: they read and write only once stream_select() says
the call will not block, and wait through the event loop otherwise. echo and the processes that share
the descriptor keep working: an echo while a write of stdout() waits for room blocks as usual and may land
in the middle of that write. A write cancelled after a part leaves stdout() open, the next one goes on
after the half: there are no messages to break. The uv driver makes every descriptor it watches non-blocking,
so on it these streams do not watch: a wait checks the descriptor every 10 ms.
Supported types
| Methods | PHP type | Size, bytes | Range |
|---|---|---|---|
readInt8 / writeInt8 |
int |
1 | −128 .. 127 |
readUint8 / writeUint8 |
int |
1 | 0 .. 255 |
readInt16 / writeInt16 |
int |
2 | −32768 .. 32767 |
readUint16 / writeUint16 |
int |
2 | 0 .. 65535 |
readInt32 / writeInt32 |
int |
4 | −2147483648 .. 2147483647 |
readUint32 / writeUint32 |
int |
4 | 0 .. 4294967295 |
readInt64 / writeInt64 |
int |
8 | −2⁶³ .. 2⁶³−1 |
readUint64 / writeUint64 |
int |
8 | 0 .. 2⁶³−1, see below |
readFloat / writeFloat |
float |
4 | 32-bit IEEE 754 |
readDouble / writeDouble |
float |
8 | 64-bit IEEE 754 |
readUvarint / writeUvarint |
int |
1 .. 10 | 64-bit pattern, see below |
readVarint / writeVarint |
int |
1 .. 10 | −2⁶³ .. 2⁶³−1, zigzag |
Design decisions
Read cursor instead of cutting the string
Reads advance an offset instead of substr()-ing the consumed bytes away, so every read is O(1)
regardless of the buffer size. Consumed bytes are discarded lazily in fill(): immediately when everything
has been read, otherwise once they reach 64 KiB.
Byte order per buffer
A protocol uses one byte order, so it is fixed in the constructor instead of being an argument of every call.
pack()/unpack() formats are selected once, and there is no match on the hot path.
Native int for 64-bit values
The package requires 64-bit PHP, where int is exactly int64. readUint64() throws \OverflowException
for values above PHP_INT_MAX instead of silently returning a negative number. Varints keep the raw 64-bit pattern:
readUvarint() returns uint64 values above PHP_INT_MAX as negative int, the way Java's long does,
so that a codec can decide how to represent them.
Range checks via assert()
Write methods accept plain int and check the range with assert():
full validation in development and zero overhead in production with zend.assertions = -1.
No narrow types and no value objects
8/16/32-bit integers are native int: no allocations and no method calls per value,
which matters in the tight loops of protocol parsing.