PHPackages                             wapmorgan/binary-stream - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. wapmorgan/binary-stream

ActiveLibrary[Image & Media](/categories/media)

wapmorgan/binary-stream
=======================

A handy tool for working with binary data

0.4.0(9y ago)52271.1k↓13.9%7[1 issues](https://github.com/wapmorgan/BinaryStream/issues)5MITPHPPHP >=5.3.0

Since Jan 17Pushed 7y ago1 watchersCompare

[ Source](https://github.com/wapmorgan/BinaryStream)[ Packagist](https://packagist.org/packages/wapmorgan/binary-stream)[ RSS](/packages/wapmorgan-binary-stream/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (10)Dependencies (1)Versions (14)Used By (5)

BinaryStream
============

[](#binarystream)

BinaryStream - a handy tool for working with binary data and the best replacement for pack()/unpack() with big list of features.

[![Composer package](https://camo.githubusercontent.com/fc4915cdc6b11e2487fa5b4e944837cca251bdb3dc28dcc01a4701ac21b8ff1d/687474703a2f2f636f6d706f7365722e6e6574776f726b2f62616467652f7761706d6f7267616e2f62696e6172792d73747265616d)](https://packagist.org/packages/wapmorgan/binary-stream)[![Latest Stable Version](https://camo.githubusercontent.com/f200cd899c50112c20397f7950fb72d8a735edb60a8fe21b64445a4582deac33/68747470733a2f2f706f7365722e707567782e6f72672f7761706d6f7267616e2f62696e6172792d73747265616d2f76657273696f6e)](https://packagist.org/packages/wapmorgan/binary-stream)[![Total Downloads](https://camo.githubusercontent.com/fddca6ec4b47e52a1a508d4f78faf753eb7dc0cbf869524d872572a071353e4d/68747470733a2f2f706f7365722e707567782e6f72672f7761706d6f7267616e2f62696e6172792d73747265616d2f646f776e6c6f616473)](https://packagist.org/packages/wapmorgan/binary-stream)[![License](https://camo.githubusercontent.com/244dc3cc8f4cb34dca71147729bf25ea74eb3b8d68d034cd74bf021fce4002db/68747470733a2f2f706f7365722e707567782e6f72672f7761706d6f7267616e2f62696e6172792d73747265616d2f6c6963656e7365)](https://packagist.org/packages/wapmorgan/binary-stream)[![Latest Unstable Version](https://camo.githubusercontent.com/5f5eb8d71d77121547e1ca127b72000dc16110957d6b818c64257a9520c11253/68747470733a2f2f706f7365722e707567782e6f72672f7761706d6f7267616e2f62696e6172792d73747265616d2f762f756e737461626c65)](//packagist.org/packages/wapmorgan/binary-stream)[![Tests](https://camo.githubusercontent.com/effa14913fbdbef7512c272aa7ef9d08fd6a376f235a5063f4c102d63489a772/68747470733a2f2f7472617669732d63692e6f72672f7761706d6f7267616e2f42696e61727953747265616d2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/wapmorgan/BinaryStream)

If you are looking for a convenient tool that would allow read and write binary data (whether existing or created by you format), you choose the correct library.

*BinaryStream* - is a powerful tool for reading and writing binary files. It supports a variety of high-level data types and sometimes lets you forget that you are working with unstructured binary data.

With BinaryStream you can handle network packets, binary files, system protocols and other low-level data.

1. [**Features**](#features)
2. [**Manual**](#manual)
3. [**Reference**](#reference)
    - [Data types](#data-types)
    - [API](#api)
        - [Groups of fields](#groups-of-fields)
        - [Navigation](#navigation)
        - [Auxiliary](#auxiliary)
        - [Configurations](#configurations)
4. [**Advanced usage. Writing**](#advanced-usage-writing)

Features
--------

[](#features)

- Minimal supported **PHP version is 5.3.0** for all features.
- The library supports all major data types and allows both read and write the data.
- Supports both direct order of bytes (big endian) and reverse (little). You can switch between them while reading a file.
- Supports multiple dimensions of **integers** (8, 16, 32 and 64) and also rare (24, 40, 48 and 56).
- Supports multiple dimensions of **fractional numbers** (32 and 64).
- You can read both individual bytes and individual bits.
- For ease of navigation through the file, you can command BinaryStream remember some positions in the file, and later return to them again.
- Supports data groups: save configuration once and then read similar data groups with only it's name.
- Supports configuration files to switch between file formats and versions.
- Unlike standard php functions, **it can work with fractional numbers written in both the direct order of bytes (Big-Endian) and the reverse one (Little-Endian)**.

**Why it's objectively better pack/unpack?**

- 64 bit int's/float's
- selection of byte-order of float's
- rare, but possible int's size (24, 40, 48, 56)
- other features like data groups and configurations ...

And that's all with PHP 5.3.

Manual
------

[](#manual)

### Simple usage

[](#simple-usage)

The easiest way to use BinaryStream - this:

```
use wapmorgan\BinaryStream\BinaryStream;
$stream = new BinaryStream('filename.ext');
$text = $s->readString(20);
```

This example reads 20 bytes at the beginning of the file as a string.

A more complex example, where the data were located in the following order:

- **integer** (int, 32 bit)
- **float** (float, 32 bit)
- **flag byte** (where each bit has its own value, 8 bits): first bit determines whether there after this byte written another data, 5-bit empty, and the last 2 bits of the data type:
    - `0b00` - after this data recorded 1 character (char, 8 bits)
    - `0b01` - after this data recorded 10 characters (string, 10 bytes)
    - `0b10` - after this data time in unixtime format packaged in long integer (long, 64 bits)
    - `0b11` - not used at this moment.

In order to read these data and those that depend on the flags, this example is suitable:

```
use wapmorgan\BinaryStream\BinaryStream;
$stream = new BinaryStream('filename.ext');
$int = $stream->readInteger(32);
$float = $stream->readFloat(32);
$flags = $stream->readBits([
    'additional_data' => 1,
    '_' => 5, // pointless data
    'data_type' => 2,
]);
if ($flags['additional_data']) {
    if ($flags['data_type'] == 0b00)
        $char = $stream->readChar();
    else if ($flags['data_type'] == 0b01)
        $string = $stream->readString(10);
    else if ($flags['data_type'] == 0b10)
        $time = date('r', $stream->readInteger(64));
}
```

In this example, we read the basic data and the additional, based on the value of flags.

But it is unlikely to be so few data. For added convenience, you can use a group reading function. The previous example can be rewritten as follows:

```
use wapmorgan\BinaryStream\BinaryStream;
$stream = new BinaryStream('filename.ext');
$data = $stream->readGroup([
    'i:int' => 32,
    'f:float' => 32,
    'additional_data' => 1,
    '_' => 5,
    'data_type' => 2,
]);
if ($data['additional_data']) {
    if ($data['data_type'] == 0b00)
        $data['char'] = $stream->readChar();
    else if ($data['data_type'] == 0b01)
        $data['string'] = $stream->readString(10);
    else if ($data['data_type'] == 0b10)
        $data['time'] = date('r', $stream->readInteger(64));
}
```

If you are reading a file in which such groups of data are repeated, you can save a group with a name, and then simply refer to it to read the next data. Let us introduce one more value for data\_type: `0b11` - means that this is the last group of data in the file. An example would be:

```
use wapmorgan\BinaryStream\BinaryStream;
$stream = new BinaryStream('filename.ext');
$stream->saveGroup('Data', [
    'i:int' => 32,
    'f:float' => 32,
    'additional_data' => 1,
    '_' => 5,
    'data_type' => 2,
]);

do {
    $data = $stream->readGroup('Data');
    // Some operations with data
} while ($data['data_type'] != 0b11);
```

And now imagine that we have moved to a new file format that is different from the previous one and has a certain mark in the beginning of the file, which will help to distinguish the new from the old format. For example, a new label is a sequence of characters `'A', 'S', 'C'`. We need to check the label and if it is present, parse the file according to another scheme, and if it does not, use the old version of the processor. An example to illustrate this:

```
use wapmorgan\BinaryStream\BinaryStream;
$stream = new BinaryStream('filename.ext');

if ($stream->compare(3, 'ASC')) {
    // parse here new format
} else {
    $stream->saveGroup('DataOld', [
        'i:int' => 32,
        'f:float' => 32,
        'additional_data' => 1,
        '_' => 5,
        'data_type' => 2,
    ]);

    do {
        $data = $stream->readGroup('DataOld');
        // Some operations with data
    } while ($data['data_type'] != 0b11);
}
```

### Installation

[](#installation)

Installation via composer:

```
composer require wapmorgan/binary-stream
```

Reference
---------

[](#reference)

### Data types

[](#data-types)

All used data types are presented in the following table:

TypeDimensionsValues rangeNotesinteger8/16/32/64 bits0 to 255/65 535/4 294 967 295/9 223 372 036 854 775 807Also, there's support for non-standard sizes like 24, 40, 48 and 56 bits.float32/64 bits0 to 3.4 x 10^38/1.798 x 10^308Also, there's support for choosing byte-order when storing a float (unlike `pack()`).char1 byteFrom 0 to 255 ascii chars-string\[n\] of bytes...-bit\[n\] of bits0 or 1Also, there's support for combining few consecutive bits in one value.### API

[](#api)

- Creating an object is possible in several ways: `new BinaryStream($filename | $socket | $stream)`
- Reading data is possible using specialized methods for each data type:

    - **bit**:
        - `readBit(): boolean`

            Example: `$flag = $s->readBit();`
        - `readBits(array $listOfBits): array of boolean and integers`.

            Example: `$flags = $s->readBits(['a' => 2, '_' => 5, 'b' => 3]);`If size of field (an array element value is `1`, then this field will have `true/false`, if larger 1, then `N` consecutive bits will be combined in an `integer`.)
    - **char**:
        - `readChar(): string(1)`

            Example: `$char = $s->readChar();`
        - `readChars($count): array of string(1)`

            Example: `$chars = $s->readChars(4);`
    - **integer**
        - `readInteger($sizeInBits = 32): integer`

            Example: `$int = $s->readInteger(32);`It supports the following dimensions: 8, 16, 32, 64 and 24, 40, 48, 56 bits.
    - **float**:
        - `readFloat($sizeInBits = 32): float`

            Example: `$float = $s->readFloat(32);`It supports the following dimensions: 32, 64 bits.
    - **string**:
        - `readString($length): string($length)`

            Example: `$string = $s->readString(10);`

#### Groups of fields

[](#groups-of-fields)

You can save list of fields definitions with a specific name and use it's name when you need to read the same block few times. A group is defined by **group configuration** - list of fields, their type and size. To compose group configuration create an array: **keys** define type and name of fields, **values** - their size:

- **key** is a name of field and may contain type of field. To specify type prepend name with a type letter and a colon. Type letters:

    - `b` - bit
    - `i` - integer
    - `f` - float
    - `c` - char
    - `s` - string If type is not defined, field will be treated as a `bit`-field. Example: `flag` - `bit`-field, `s:name` - `string`-field
- **value** is a size or a dimension of field:

    - If field has `integer`, `float` or `bit` type, it defines size of field in term of bits.
    - If field has `char` or `string` type, it defines size in term of bytes. Example:

    ```
    'flags' => 16, // bits-field (16 bits = 2 bytes)
    's:name' => 10, // string-field (80 bits = 10 bytes)
    ```

So full example of group configuration:

```
$group = [
    'flags' => 16,
    'i:date' => 32,
    'f:summ' => 32,
    's:name' => 10,
];
```

MethodUsageNotes`saveGroup($name, array $groupConfiguration)``$s->saveGroup('data', ['i:field' => 32, 's:text' => 20]);`Create new group with few fields. If group with that name already exists, it replaces original group.`readGroup($name)``$data = $s->readGroup('data');`It allows you to read data from pre-saved configuration. To save a group under a new name, use the method `saveGroup($name, array $fields)``readGroup(array $groupConfiguration)``$data = $s->readGroup(['i:field' => 32, 's:text' => 20]);`The fields are listed in the as array in which the keys determine the type and the name of the data fields, and values - dimension (understood as bytes for string and chars, and as bits for everything else). Supported: `s`, `c`, `i`, `f` and `b`. If the type is not specified, the field is perceived as a bit (or a few bits). The type and name are separated by a colon (:).#### Navigation

[](#navigation)

- Caret moving: To change the position of the cursor in the file use the following methods.

MethodUsageNotes`go($offset)``$stream->go(-128);`It goes to the absolute position in the file. If you pass a negative value, the value of the cursor will be set to `-$offset` bytes from the end of the file.`go($mark)``$stream->go('FirstTag');`It moves to the position where the `$mark` mark has been set.`skip($bytes)``$stream->skip(4);`Skip the following `$bytes` bytes.- Current position testing:

    ```
    isEnd(): boolean
    ```

    Returns **true** if cursor is at the end of file.
- Remembering the positions in file:

MethodUsageNotes`mark($name)``$stream->mark('Tag');`It saves the current cursor position under the `$name` name.`markOffset($offset, $name)``$stream->markOffset(-128, 'FirstTag');`It saves specific position in file under the `$name` name.`isMarked($name)``$stream->isMarked('Tag');`Check whether the `$name` mark set. Returns **true** or **false**.#### Auxiliary

[](#auxiliary)

- Comparation of bytes:

    ```
    compare($length, $bytes)
    ```

    Compares `$length` bytes from current position with `$bytes`. Carrent position will not be changed. Returns **true** or **false**.
- Endianness: **By default, `BinaryStream` treats `int`'s and `long`'s in little-endian format**. To change the reading order of bytes use `setEndian($endian)` method with one of `BinaryStream` constants:

ConstantMeaning`BinaryStream::BIG`Big-endian for integers and floats`BinaryStream::LITTLE`Little-endian for integers and float#### Configurations

[](#configurations)

MethodUsageNotes`loadConfiguration($file``$stream->loadConfiguration('file_format.conf');`Load configuration (byte order and data groups) from an external file. Configuration format - ini. To see an example of such a file, open the conf/mp3.conf file.`saveConfiguration($file)``$stream->saveConfiguration('file_format.conf');`Saves the current settings of byte order and all created data groups to an external file in ini-format. This configuration can be later restored from the file with the method `loadConfiguration()`.Advanced usage. Writing
-----------------------

[](#advanced-usage-writing)

If you are the one who needs to write data to binary files, you can use additional methods to do so.

Firstly, you need to open a file in one of the modes that allow writing of a file (by default, files are opened in read-only mode). For this when you create an object BinaryStream specify in second argument one of the following modes:

ModeConstantNotesCreation`BinaryStream::CREATE`Creates new file. Fails when file already exists.Recreation`BinaryStream::RECREATE`Clears all file content and sets cursor at the beginning. Fails when file doesn't exist.Rewriting`BinaryStream::REWRITE`Opens file and sets cursor at the beginning. Fails when file doesn't exist.Appending`BinaryStream::APPEND`Opens file and sets cursor at the end. Fails when file doesn't exist.After you have correctly opened the file, you can use the following methods, named by analogy with the other designed for reading.

Data typeMethodExampleNotes**bit**`writeBit($bit)``$s->writeBit(true);``writeBits(array $bits)``$s->writeBits([true, false, [2, 2], [4, 10]]);`You can combine multiple bits into a single number. To do this, instead of using an array of boolean, in which the first element is the number of bits is used to record the number, and the second element - number.**char**`writeChar($char)``$s->writeChar(32);`You can pass a character (string), and the code for this symbol (an integer up to 256).**integer**`writeInteger($integer, $sizeInBits)``$s->writeInteger(256, 32);`It supports the following dimensions: 8, 16, 32, 64 bits.**float**`writeFloat($float, $sizeInBits)``$s->writeFloat(123.123, 32);`It supports the following dimensions: 32, 64 bits.**string**`writeString($string)``$s->writeString('Abracadabra');`

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity46

Moderate usage in the ecosystem

Community17

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~12 days

Recently: every ~18 days

Total

13

Last Release

3303d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6000618?v=4)[Sergey](/maintainers/wapmorgan)[@wapmorgan](https://github.com/wapmorgan)

---

Top Contributors

[![wapmorgan](https://avatars.githubusercontent.com/u/6000618?v=4)](https://github.com/wapmorgan "wapmorgan (84 commits)")

---

Tags

binarybinary-datafilesmedianetwork-analysiswriterreaderbinarybinary data

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wapmorgan-binary-stream/health.svg)

```
[![Health](https://phpackages.com/badges/wapmorgan-binary-stream/health.svg)](https://phpackages.com/packages/wapmorgan-binary-stream)
```

###  Alternatives

[phpoffice/phpword

PHPWord - A pure PHP library for reading and writing word processing documents (OOXML, ODF, RTF, HTML, PDF)

7.6k39.0M235](/packages/phpoffice-phpword)[h4cc/wkhtmltoimage-amd64

Convert html to image using webkit (qtwebkit). Static linked linux binary for amd64 systems.

20311.3M17](/packages/h4cc-wkhtmltoimage-amd64)[veewee/xml

XML without worries

1837.0M39](/packages/veewee-xml)[bcncommerce/json-stream

A bundle of tools to work with JSON in PHP

682.3M3](/packages/bcncommerce-json-stream)[h4cc/wkhtmltoimage-i386

Convert html to image using webkit (qtwebkit). Static linked linux binary for i386 systems.

33684.1k5](/packages/h4cc-wkhtmltoimage-i386)[tiamo/spss

SPSS is a php-based implementation of IBM SPSS Statistics Standard

80344.3k3](/packages/tiamo-spss)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)