Enhance modes by kduma · Pull Request #3 · kduma-OSS/PHP-binary-tools

kduma · 2025-09-18T12:35:36Z

This pull request introduces a significant refactor and enhancement to the binary reading and writing utilities. The main focus is on improving flexibility for variable-length and padded binary data parsing, modernizing the API, and enhancing documentation for maintainability. Deprecated methods have been replaced with more configurable alternatives, and new helper methods have been added for safer and more expressive binary operations.

BinaryReader API modernization and flexibility

Introduced the readBytesWith and readStringWith methods, allowing flexible reading of variable-length, terminator-based, optional terminator, and padding-based binary fields, replacing the older fixed-length methods. Deprecated legacy methods (readBytesWithLength, readStringWithLength, readUint16BE) now delegate to the new API. [1] [2] [3]
Added support for reading integers with arbitrary width, signedness, and endianness via the new readInt(IntType $type) method, improving platform compatibility and error handling.

Documentation and developer experience

Added detailed PHPDoc comments to all public methods in BinaryReader, BinaryWriter, and BinaryString to clarify usage, parameters, and error conditions. [1] [2] [3]
Improved error messages for out-of-bounds seeking and invalid data conditions, aiding debugging and reliability.

BinaryString enhancements

Added new helper methods: contains(BinaryString $needle) for timing-safe substring checks, and improved parameter documentation and naming for encoding/decoding methods.

BinaryWriter improvements

Added PHPDoc comments to all public methods, clarifying buffer management and error conditions.

Tooling and developer workflow

Added a new docs script to composer.json for generating API documentation, improving maintainability and onboarding.

github-actions · 2025-09-18T12:36:05Z

🔍 Test Results - PHP 8.4

❌ Code Style Check Failed

Code style violations found. Please run composer fix to automatically fix them.

✅ Tests Passed

✅ Code Coverage: 100%

This comment was automatically generated by the test workflow.

Copilot

Pull Request Overview

This PR extends the BinaryReader with support for little-endian integer formats and 64-bit integers. It introduces a new IntType enum to handle various integer types and their properties, while updating the reading logic to support endianness conversion and platform-specific integer size validation.

Replaces specific integer reading methods with a unified readInt method that uses IntType enum
Adds comprehensive test coverage for all integer types including little-endian variants
Implements endianness conversion and platform compatibility checks

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/IntType.php	New enum defining integer types with helper methods for bytes, signedness, and endianness
src/BinaryReader.php	Updated to use unified readInt method with endianness handling and platform size validation
tests/BinaryReaderTest.php	Comprehensive test suite covering all integer types and endianness combinations

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/BinaryReader.php

…inttype

kduma · 2025-09-18T15:02:21Z

@codex review

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

tests/BinaryWriterTest.php:1

The Deprecated attribute should be #[\\Deprecated('Use writeInt(IntType::UINT16, $value) instead')] with a backslash prefix to properly reference the global attribute class.

<?php declare(strict_types=1);

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/BinaryReader.php

chatgpt-codex-connector

Codex Review: Here are some suggestions.

Reply with @codex fix comments to fix any unresolved comments.

About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you open a pull request for review, mark a draft as ready, or comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex fix this CI failure" or "@codex address that feedback".

src/BinaryReader.php

kduma · 2025-09-18T15:57:25Z

@codex review

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

tests/BinaryReaderTest.php

chatgpt-codex-connector

Codex Review: Here are some suggestions.

Reply with @codex fix comments to fix any unresolved comments.

About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you open a pull request for review, mark a draft as ready, or comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex fix this CI failure" or "@codex address that feedback".

src/BinaryReader.php

Copilot

Pull Request Overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/BinaryReader.php:1

The error message uses string interpolation but doesn't provide context about valid range. Consider changing to 'Invalid seek position: $value (valid range: 0-{$this->length})'.

<?php declare(strict_types=1);

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

…ex/refactor-readuint16be-to-readint-with-inttype

kduma · 2025-09-18T19:17:18Z

@codex review

Copilot

Pull Request Overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-18T19:18:19Z

src/IntType.php

+    }
+
+    public function isSupported(): bool
+    {


The isSupported() method only checks byte size but doesn't account for the fact that unsigned 64-bit integers on 64-bit platforms cannot represent the full range (they're limited to PHP_INT_MAX). This could lead to incorrect support detection for UINT64 types.

Suggested change

{

{

// For unsigned 64-bit types, check that PHP_INT_MAX is large enough

if (

($this === self::UINT64 || $this === self::UINT64_LE)

&& PHP_INT_SIZE === 8

&& PHP_INT_MAX < 0xFFFFFFFFFFFFFFFF

) {

return false;

}

Copilot · 2025-09-18T19:18:20Z

src/BinaryWriter.php

+        }
+
+        // Handle negative values for signed types
+        if ($type->isSigned() && $value < 0) {


The two's complement conversion for negative values will overflow on 64-bit signed integers when $bytesCount * 8 equals or exceeds PHP_INT_SIZE * 8, causing incorrect bit manipulation results.

Suggested change

if ($type->isSigned() && $value < 0) {

if ($type->isSigned() && $value < 0) {

if (($bytesCount * 8) >= (PHP_INT_SIZE * 8)) {

throw new \RuntimeException(

sprintf(

'Two\'s complement conversion for negative values will overflow on %d-bit signed integers when %d bytes are used (requested: %d bits, platform: %d bits)',

PHP_INT_SIZE * 8,

$bytesCount,

$bytesCount * 8,

PHP_INT_SIZE * 8

)

);

}

Copilot · 2025-09-18T19:18:20Z

src/BinaryReader.php

+            if ($bits <= PHP_INT_SIZE * 8) {
+                $signBit = 1 << ($bits - 1);
+                if (($value & $signBit) !== 0) {
+                    $value -= 1 << $bits;
+                }


The sign extension logic has the same overflow issue as the writer - when $bits equals PHP_INT_SIZE * 8, the bit shift operations (1 << ($bits - 1) and 1 << $bits) will overflow, producing incorrect results for 64-bit signed integers on 64-bit platforms.

Suggested change

if ($bits <= PHP_INT_SIZE * 8) {

$signBit = 1 << ($bits - 1);

if (($value & $signBit) !== 0) {

$value -= 1 << $bits;

}

if ($bits < PHP_INT_SIZE * 8) {

$signBit = 1 << ($bits - 1);

if (($value & $signBit) !== 0) {

$value -= 1 << $bits;

}

} elseif ($bits == PHP_INT_SIZE * 8) {

// Use GMP for sign extension to avoid overflow

if (!function_exists('gmp_init')) {

throw new RuntimeException('GMP extension required for 64-bit signed integer parsing');

}

$gmpValue = gmp_init($value, 10);

$signBit = gmp_init('1', 10);

$signBit = gmp_mul($signBit, gmp_pow(2, $bits - 1));

if (gmp_cmp(gmp_and($gmpValue, $signBit), 0) !== 0) {

$gmpValue = gmp_sub($gmpValue, gmp_pow(2, $bits));

}

// Convert back to PHP int if possible, else string

$value = gmp_strval($gmpValue);

if (gmp_cmp($gmpValue, PHP_INT_MIN) >= 0 && gmp_cmp($gmpValue, PHP_INT_MAX) <= 0) {

$value = (int)$value;

}

chatgpt-codex-connector · 2025-09-18T19:22:49Z

Codex Review: Didn't find any major issues. Can't wait for the next one!

About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you open a pull request for review, mark a draft as ready, or comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex fix this CI failure" or "@codex address that feedback".

Support little-endian and 64-bit integer reads

5713695

kduma added the codex label Sep 18, 2025 — with ChatGPT Codex Connector

kduma requested a review from Copilot September 18, 2025 12:35

Copilot AI reviewed Sep 18, 2025

View reviewed changes

src/BinaryReader.php Outdated Show resolved Hide resolved

src/BinaryReader.php Outdated Show resolved Hide resolved

kduma added 2 commits September 18, 2025 16:36

Merge branch 'main' into codex/refactor-readuint16be-to-readint-with-…

15a3a03

…inttype

Finish implementation in BinaryReader, Implement in BinaryWriter

91451cc

kduma requested a review from Copilot September 18, 2025 15:02

Copilot AI reviewed Sep 18, 2025

View reviewed changes

src/BinaryReader.php Show resolved Hide resolved

src/BinaryReader.php Outdated Show resolved Hide resolved

src/BinaryReader.php Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Sep 18, 2025

View reviewed changes

src/BinaryReader.php Show resolved Hide resolved

kduma added 4 commits September 18, 2025 17:08

Import Deprecated attribute

ad84ac8

Reinplement (read|write)(Bytes|String)WithLength

9203ee4

Reorganize deprecations

1e626c0

Fix complaints from AI

4841dfc

kduma marked this pull request as ready for review September 18, 2025 15:57

kduma requested a review from Copilot September 18, 2025 15:57

Copilot AI reviewed Sep 18, 2025

View reviewed changes

tests/BinaryReaderTest.php Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Sep 18, 2025

View reviewed changes

src/BinaryReader.php Outdated Show resolved Hide resolved

kduma mentioned this pull request Sep 18, 2025

PHP-binary-tools PR #3 docs kduma-OSS/opensource.duma.sh#15

Merged

Add support for terminated bytes and strings

f99ccb8

kduma requested a review from Copilot September 18, 2025 16:58

Copilot AI reviewed Sep 18, 2025

View reviewed changes

kduma added 6 commits September 18, 2025 18:59

Fix empty terminator

cec8708

Fix negative lengths

91329ec

Make Invalid seek position exception more verbose

8dd37b9

Implement fixed-size field padding

80c769b

Update documentation

91558fb

Merge branch 'main' of github.com:kduma-OSS/PHP-binary-tools into cod…

c7c5776

…ex/refactor-readuint16be-to-readint-with-inttype

kduma added 4 commits September 18, 2025 21:09

Update docs

e48d7f4

API docs generator

146693b

Merge branch 'main' of github.com:kduma-OSS/PHP-binary-tools into cod…

d0db96d

…ex/refactor-readuint16be-to-readint-with-inttype

Style

96ef390

kduma requested a review from Copilot September 18, 2025 19:17

Copilot AI reviewed Sep 18, 2025

View reviewed changes

kduma changed the title ~~Support little-endian and 64-bit integer reads~~ Enhance modes Sep 18, 2025

kduma merged commit bd839a1 into main Sep 18, 2025
1 check passed

-    {
+    {
+        // For unsigned 64-bit types, check that PHP_INT_MAX is large enough
+        if (
+            ($this === self::UINT64 || $this === self::UINT64_LE)
+            && PHP_INT_SIZE === 8
+            && PHP_INT_MAX < 0xFFFFFFFFFFFFFFFF
+        ) {
+            return false;
+        }

-        if ($type->isSigned() && $value < 0) {
+        if ($type->isSigned() && $value < 0) {
+            if (($bytesCount * 8) >= (PHP_INT_SIZE * 8)) {
+                throw new \RuntimeException(
+                    sprintf(
+                        'Two\'s complement conversion for negative values will overflow on %d-bit signed integers when %d bytes are used (requested: %d bits, platform: %d bits)',
+                        PHP_INT_SIZE * 8,
+                        $bytesCount,
+                        $bytesCount * 8,
+                        PHP_INT_SIZE * 8
+                    )
+                );
+            }

-            if ($bits <= PHP_INT_SIZE * 8) {
-                $signBit = 1 << ($bits - 1);
-                if (($value & $signBit) !== 0) {
-                    $value -= 1 << $bits;
-                }
+            if ($bits < PHP_INT_SIZE * 8) {
+                $signBit = 1 << ($bits - 1);
+                if (($value & $signBit) !== 0) {
+                    $value -= 1 << $bits;
+                }
+            } elseif ($bits == PHP_INT_SIZE * 8) {
+                // Use GMP for sign extension to avoid overflow
+                if (!function_exists('gmp_init')) {
+                    throw new RuntimeException('GMP extension required for 64-bit signed integer parsing');
+                }
+                $gmpValue = gmp_init($value, 10);
+                $signBit = gmp_init('1', 10);
+                $signBit = gmp_mul($signBit, gmp_pow(2, $bits - 1));
+                if (gmp_cmp(gmp_and($gmpValue, $signBit), 0) !== 0) {
+                    $gmpValue = gmp_sub($gmpValue, gmp_pow(2, $bits));
+                }
+                // Convert back to PHP int if possible, else string
+                $value = gmp_strval($gmpValue);
+                if (gmp_cmp($gmpValue, PHP_INT_MIN) >= 0 && gmp_cmp($gmpValue, PHP_INT_MAX) <= 0) {
+                    $value = (int)$value;
+                }

Conversation

kduma commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

BinaryReader API modernization and flexibility

Documentation and developer experience

BinaryString enhancements

BinaryWriter improvements

Tooling and developer workflow

Uh oh!

github-actions bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Test Results - PHP 8.4

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

kduma commented Sep 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kduma commented Sep 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

kduma commented Sep 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot commented Sep 18, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

kduma commented Sep 18, 2025 •

edited

Loading

github-actions bot commented Sep 18, 2025 •

edited

Loading