Integer Constructors

[zanbaldwin]

No description provided.

[greptile-apps]

Greptile Summary

This PR adds integer-based conversion APIs for IP addresses. The main changes are:

• Native IPv4 integer construction and output via fromInteger() and toInteger().
• Arbitrary-precision decimal string construction and output via fromIntegerString() and toIntegerString().
• Fixed-width lowercase hexadecimal output via toHexString().
• Base-256/base-10 conversion helpers in Util\Binary, with GMP acceleration and a pure-PHP fallback.
• Documentation, API contracts, workflow pins, and tests for the new conversion paths.

Confidence Score: 5/5

Safe to merge with minimal risk.

The changes are well-scoped around conversion APIs and include validation, overflow handling, and broad tests for IPv4, IPv6, Multi, GMP parity, pure-PHP fallback, and edge cases.

No files require special attention.

T-Rex Logs

What T-Rex did

• T-Rex captured the base checkout command, the PHP validation script content, and the failing run with exit code 127.
• T-Rex captured the head checkout command, the PHP validation script content, and the same environment failure with exit code 127.
• T-Rex confirmed the runtime blocker by inspecting which php, composer, docker, and podman as well as php -v.
• T-Rex observed the base checkout and execution ending with UNCAUGHT: Error: Call to undefined method Darsyn\\IP\\Util\\Binary::toDecimalString() and EXIT_CODE: 99.
• T-Rex observed the head checkout with all assertions passing, including ALL ASSERTIONS PASSED and EXIT_CODE: 0.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src/Contracts/Factory4Interface.php	Introduces an IPv4-specific factory contract for native integer construction.
src/Contracts/FactoryInterface.php	Adds the arbitrary-precision decimal-string constructor contract.
src/Util/Binary.php	Implements GMP-backed and pure-PHP base-256/base-10 conversion with overflow validation.
src/Version/IPv4.php	Adds native integer and decimal-string constructors plus unsigned integer output for IPv4.
src/Version/IPv6.php	Adds arbitrary-precision decimal-string construction for IPv6.
src/Version/Multi.php	Adds integer and decimal-string constructors plus IPv4 integer output for embedded Multi addresses.
tests/Util/BinaryTest.php	Covers decimal conversion round trips, GMP parity, overflow, invalid inputs, and pure-PHP fallback behavior.
tests/Version/IPv4Test.php	Covers IPv4 native integer, decimal-string, and hex conversion APIs.
tests/Version/IPv6Test.php	Covers IPv6 decimal-string and hex conversion APIs.
tests/Version/MultiTest.php	Covers Multi integer APIs, full-width outputs, embedding strategies, and invalid inputs.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Caller
participant IP as IPv4/IPv6/Multi
participant Binary as Util\\Binary
participant GMP as ext-gmp (optional)

Caller->>IP: fromIntegerString(decimal)
IP->>Binary: fromDecimalString(decimal, width)
alt GMP loaded
    Binary->>GMP: gmp_init + gmp_export
    GMP-->>Binary: minimal big-endian bytes
else Pure PHP fallback
    Binary->>Binary: long division by 256
end
Binary-->>IP: fixed-width binary bytes
IP-->>Caller: IP instance

Caller->>IP: toIntegerString()/toHexString()
IP->>Binary: toDecimalString()/toHex(binary)
Binary-->>IP: string representation
IP-->>Caller: decimal or fixed-width hex

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Caller
participant IP as IPv4/IPv6/Multi
participant Binary as Util\\Binary
participant GMP as ext-gmp (optional)

Caller->>IP: fromIntegerString(decimal)
IP->>Binary: fromDecimalString(decimal, width)
alt GMP loaded
    Binary->>GMP: gmp_init + gmp_export
    GMP-->>Binary: minimal big-endian bytes
else Pure PHP fallback
    Binary->>Binary: long division by 256
end
Binary-->>IP: fixed-width binary bytes
IP-->>Caller: IP instance

Caller->>IP: toIntegerString()/toHexString()
IP->>Binary: toDecimalString()/toHex(binary)
Binary-->>IP: string representation
IP-->>Caller: decimal or fixed-width hex

Loading

_{Reviews (1): Last reviewed commit: "feature(contracts): ✨ convert IP address..." | Re-trigger Greptile}