Skip to content

Commit c401874

Browse files
kdumakduma
committed
Merge branch 'main' of github.com:kduma-OSS/PHP-binary-tools
2 parents ea329a3 + ec2f5e0 commit c401874

File tree

1 file changed

+7
-222
lines changed

1 file changed

+7
-222
lines changed

‎README.md‎

Lines changed: 7 additions & 222 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
11
# Binary Tools
22

3+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/kduma/binary-tools.svg?style=flat-square)](https://packagist.org/packages/kduma/binary-tools)
4+
[![Tests](https://img.shields.io/github/actions/workflow/status/kduma-OSS/PHP-binary-tools/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/kduma-OSS/PHP-binary-tools/actions/workflows/run-tests.yml)
5+
[![Total Downloads](https://img.shields.io/packagist/dt/kduma/binary-tools.svg?style=flat-square)](https://packagist.org/packages/kduma/binary-tools)
6+
37
A PHP library for binary data manipulation and encoding/decoding operations. This library provides safe, efficient tools for working with binary data, including UTF-8 validation and secure string comparisons.
48

9+
Check full documentation: [opensource.duma.sh/libraries/php/binary-tools](https://opensource.duma.sh/libraries/php/binary-tools)
10+
511
## Installation
612

713
```bash
@@ -37,227 +43,6 @@ Stream-like writer for building binary data structures.
3743

3844
Stream-like reader for parsing binary data with position tracking.
3945

40-
## Usage Examples
41-
42-
### BinaryString
43-
44-
```php
45-
use KDuma\BinaryTools\BinaryString;
46-
47-
// Create from different sources
48-
$binary = BinaryString::fromString("\x48\x65\x6c\x6c\x6f");
49-
$fromString = BinaryString::fromString("Hello");
50-
$fromHex = BinaryString::fromHex("48656c6c6f");
51-
$fromBase64 = BinaryString::fromBase64("SGVsbG8=");
52-
53-
// All represent "Hello"
54-
echo $binary->toString(); // "Hello"
55-
56-
// Convert to different formats
57-
echo $binary->toHex(); // "48656c6c6f"
58-
echo $binary->toBase64(); // "SGVsbG8="
59-
echo $binary->size(); // 5
60-
61-
// Secure comparison
62-
$other = BinaryString::fromString("Hello");
63-
if ($binary->equals($other)) {
64-
echo "Strings are equal";
65-
}
66-
```
67-
68-
### BinaryWriter
69-
70-
```php
71-
use KDuma\BinaryTools\BinaryWriter;
72-
use KDuma\BinaryTools\BinaryString;
73-
74-
$writer = new BinaryWriter();
75-
76-
// Write different data types
77-
$writer->writeByte(0x42) // Single byte
78-
->writeUint16BE(1234) // 16-bit big-endian integer
79-
->writeBytes(BinaryString::fromHex("abcd")) // Raw bytes
80-
->writeString(BinaryString::fromString("Hello")); // UTF-8 string
81-
82-
// Write strings with length prefixes
83-
$text = BinaryString::fromString("Hello World");
84-
$writer->writeStringWithLength($text); // 8-bit length + string
85-
$writer->writeStringWithLength($text, true); // 16-bit length + string
86-
87-
// Get the result
88-
$result = $writer->getBuffer();
89-
echo $result->toHex(); // Complete binary data as hex
90-
```
91-
92-
### BinaryReader
93-
94-
```php
95-
use KDuma\BinaryTools\BinaryReader;
96-
use KDuma\BinaryTools\BinaryString;
97-
98-
$data = BinaryString::fromHex("4204d2abcd48656c6c6f0548656c6c6f20576f726c64000b48656c6c6f20576f726c64");
99-
$reader = new BinaryReader($data);
100-
101-
// Read different data types
102-
$byte = $reader->readByte(); // 0x42
103-
$uint16 = $reader->readUint16BE(); // 1234
104-
$bytes = $reader->readBytes(2); // Raw bytes
105-
$string = $reader->readBytes(5); // "Hello"
106-
107-
// Read strings with length prefixes
108-
$stringWithLength = $reader->readStringWithLength(); // 8-bit length
109-
$stringWithLength16 = $reader->readStringWithLength(true); // 16-bit length
110-
111-
// Position management
112-
echo $reader->position; // Current position
113-
echo $reader->remaining_bytes; // Bytes left
114-
echo $reader->has_more_data; // Boolean
115-
116-
// Peek without advancing
117-
$nextByte = $reader->peekByte();
118-
$next3Bytes = $reader->peekBytes(3);
119-
120-
// Seek to specific position
121-
$reader->seek(0); // Go to start
122-
$reader->skip(5); // Skip 5 bytes
123-
```
124-
125-
## Common Use Cases
126-
127-
### Protocol Implementation
128-
129-
```php
130-
// Writing a simple protocol message
131-
$writer = new BinaryWriter();
132-
$message = BinaryString::fromString("Hello, Protocol!");
133-
134-
$writer->writeByte(0x01) // Message type
135-
->writeUint16BE(time() & 0xFFFF) // Timestamp (16-bit)
136-
->writeStringWithLength($message); // Payload
137-
138-
$packet = $writer->getBuffer();
139-
140-
// Reading the protocol message
141-
$reader = new BinaryReader($packet);
142-
$messageType = $reader->readByte();
143-
$timestamp = $reader->readUint16BE();
144-
$payload = $reader->readStringWithLength();
145-
146-
echo "Type: {$messageType}, Time: {$timestamp}, Message: {$payload->toString()}";
147-
```
148-
149-
### File Header Parsing
150-
151-
```php
152-
// Parse a file with magic bytes and metadata
153-
$fileData = BinaryString::fromHex("4d5a90000300000004000000ffff0000");
154-
$reader = new BinaryReader($fileData);
155-
156-
$magic = $reader->readBytes(2)->toString(); // "MZ"
157-
if ($magic === "MZ") {
158-
$bytesOnLastPage = $reader->readUint16BE();
159-
$pagesInFile = $reader->readUint16BE();
160-
// ... continue parsing
161-
}
162-
```
163-
164-
### Data Serialization
165-
166-
```php
167-
// Serialize complex data
168-
$writer = new BinaryWriter();
169-
170-
$users = [
171-
['id' => 1, 'name' => 'Alice'],
172-
['id' => 2, 'name' => 'Bob'],
173-
];
174-
175-
$writer->writeByte(count($users)); // User count
176-
177-
foreach ($users as $user) {
178-
$writer->writeUint16BE($user['id']);
179-
$writer->writeStringWithLength(BinaryString::fromString($user['name']));
180-
}
181-
182-
$serialized = $writer->getBuffer();
183-
184-
// Deserialize
185-
$reader = new BinaryReader($serialized);
186-
$userCount = $reader->readByte();
187-
188-
for ($i = 0; $i < $userCount; $i++) {
189-
$userId = $reader->readUint16BE();
190-
$userName = $reader->readStringWithLength()->toString();
191-
echo "User {$userId}: {$userName}\n";
192-
}
193-
```
194-
195-
## API Reference
196-
197-
### BinaryString
198-
199-
| Method | Description |
200-
|--------|-------------|
201-
| `toString(): string` | Get raw binary data |
202-
| `toHex(): string` | Convert to hexadecimal string |
203-
| `toBase64(): string` | Convert to base64 string |
204-
| `size(): int` | Get byte length |
205-
| `equals(BinaryString $other): bool` | Secure comparison |
206-
| `fromString(string $value): static` | Create from string |
207-
| `fromHex(string $hex): static` | Create from hex string |
208-
| `fromBase64(string $base64): static` | Create from base64 |
209-
210-
### BinaryWriter
211-
212-
| Method | Description |
213-
|--------|-------------|
214-
| `getBuffer(): BinaryString` | Get written data |
215-
| `getLength(): int` | Get buffer length |
216-
| `reset(): void` | Clear buffer |
217-
| `writeByte(int $byte): self` | Write single byte (0-255) |
218-
| `writeBytes(BinaryString $bytes): self` | Write binary data |
219-
| `writeUint16BE(int $value): self` | Write 16-bit big-endian integer |
220-
| `writeString(BinaryString $string): self` | Write UTF-8 string |
221-
| `writeStringWithLength(BinaryString $string, bool $use16BitLength = false): self` | Write string with length prefix |
222-
| `writeBytesWithLength(BinaryString $bytes, bool $use16BitLength = false): self` | Write bytes with length prefix |
223-
224-
### BinaryReader
225-
226-
| Property/Method | Description |
227-
|-----------------|-------------|
228-
| `$position` | Current read position |
229-
| `$length` | Total data length |
230-
| `$remaining_bytes` | Bytes remaining |
231-
| `$has_more_data` | Whether more data available |
232-
| `$data` | Get original data as BinaryString |
233-
| `$remaining_data` | Get remaining data |
234-
| `readByte(): int` | Read single byte |
235-
| `readBytes(int $count): BinaryString` | Read N bytes |
236-
| `readUint16BE(): int` | Read 16-bit big-endian integer |
237-
| `readString(int $length): BinaryString` | Read UTF-8 string of specific length |
238-
| `readStringWithLength(bool $use16BitLength = false): BinaryString` | Read string with length prefix |
239-
| `readBytesWithLength(bool $use16BitLength = false): BinaryString` | Read bytes with length prefix |
240-
| `peekByte(): int` | Peek next byte without advancing |
241-
| `peekBytes(int $count): BinaryString` | Peek N bytes without advancing |
242-
| `seek(int $position): void` | Seek to position |
243-
| `skip(int $count): void` | Skip N bytes |
244-
245-
## Error Handling
246-
247-
The library throws appropriate exceptions for error conditions:
248-
249-
- `InvalidArgumentException` - Invalid parameters (e.g., byte values > 255)
250-
- `RuntimeException` - Runtime errors (e.g., reading past end of data, invalid UTF-8)
251-
252-
```php
253-
try {
254-
$reader = new BinaryReader(BinaryString::fromHex("41"));
255-
$reader->readBytes(5); // Trying to read more than available
256-
} catch (RuntimeException $e) {
257-
echo "Error: " . $e->getMessage();
258-
}
259-
```
260-
26146
## License
26247

263-
This library is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
48+
This library is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)