Add PHP implementation of PCF v1.0 (Partitioned Container Format)

[kduma]

This PR adds a complete PHP implementation of the Partitioned Container Format (PCF) v1.0 specification, mirroring the reference Rust implementation field-for-field and reproducing the canonical test vector byte-for-byte.

Summary

The implementation provides a full-featured reader/writer for PCF files—a language-agnostic binary container format that stores multiple independent byte regions ("partitions") in a single file. The library is production-ready, fully spec-compliant, and extensively tested.

Key Changes

• Core Container API (Container.php): High-level interface for creating, opening, reading, and modifying PCF files with support for:

  • In-memory and stream-backed storage backends
  • Partition addition, removal, and in-place data updates
  • Automatic overflow-block chaining for >255 partitions
  • Compacted image generation for tightly-packed output

• Data Structures: Complete implementation of all PCF on-disk formats:

  • FileHeader.php: 20-byte file header with magic, version, and table offset
  • TableBlockHeader.php: 74-byte table-block header with partition count and chaining
  • PartitionEntry.php: 141-byte partition entry with type, UID, label, offsets, and data hash

• Hash Algorithm Registry (HashAlgo.php): Support for 9 algorithms per spec section 8:

  • CRC-32/ISO-HDLC, CRC-32C, CRC-64/XZ (pure-PHP implementation in Crc64.php)
  • MD5, SHA-1, SHA-256, SHA-512, BLAKE3 (via tourze/blake3-php)
  • None (no-op verification)

• Storage Abstraction (Storage/): Two implementations of StorageInterface:

  • MemoryStorage: In-memory string buffer for building containers and testing
  • StreamStorage: Seekable stream wrapper for file-based I/O

• Error Handling (PcfException.php, ErrorKind.php): Single exception type with discriminated error kinds for precise error branching

• Comprehensive Test Suite:

  • SpecComplianceTest.php: 30+ tests tracing to specific MUST/SHALL clauses in the spec
  • RoundtripTest.php: End-to-end container lifecycle tests (create, add, read, verify, reopen)
  • HashTest.php: Hash algorithm validation with known test vectors
  • EntryTest.php, HeaderTest.php, TableTest.php: Low-level format tests
  • All tests port the reference Rust test suite

• Tooling:

  • examples/gen_testvector.php: Generates the canonical 395-byte test vector from spec section 15
  • .github/workflows/php.yml: CI pipeline testing PHP 8.1–8.4
  • composer.json: Dependency management with PHPUnit and BLAKE3 support

Notable Implementation Details

• Spec Compliance: Every constant, field layout, and validation rule is normative and traceable to the specification (Appendix A field layout summary, conformance checks C1–C7)
• Pure-PHP CRC-64/XZ: Custom implementation with correct handling of 64-bit two's-complement arithmetic and unsigned right-shift masking
• Lazy BLAKE3 Dependency: BLAKE3 is optional; the dependency is isolated to a single method so it's only loaded if used
• Auditability Over Performance: Code prioritizes clarity and spec traceability over optimization
• Byte-for-Byte Compatibility: Reproduces the canonical test vector exactly, enabling cross-implementation validation

https://claude.ai/code/session_018yzCMkuQCHA2h8iEkQAota