[neuhaus]

The legacy socket APPEND implementation normalizes line endings throughout the message, which can alter binary MIME payloads.

This adds a per-message binary option:

$client->append('Objects', [
    ['data' => $messageStream, 'binary' => true],
]);

When enabled, the client preserves bytes, requires the server’s BINARY capability, and sends a literal8 (~{n}). Server rejection does not trigger a fallback to ordinary APPEND. CATENATE inputs are assembled locally because RFC 4469 TEXT parts do not permit literal8.

Callers must supply a valid MIME message with CRLF headers and appropriate content-transfer-encoding. Existing behavior remains unchanged when the option is omitted or false. The modern namespaced API is unchanged.

Validation

• 13 regression tests cover strings, streams, byte preservation, wire output, capability checks, batching, and rejection handling.
• Full unit suite: 1,634 tests, no failures or errors; 55 skipped, two incomplete, and one unrelated PHP 8.5 deprecation.
• Live APPEND/BINARY FETCH round trips against Dovecot verified exact length and SHA-256 for 1 MiB and 512 MiB payloads.
• The 512 MiB round trip completed under a 64 MiB PHP memory limit, with 10 MiB peak PHP memory.

Protocol references

• RFC 3516 §4.4 — APPEND Command Extensions
• RFC 3516 §6 — Implementation Considerations
• RFC 4469 §4 — Formal Syntax

[what-the-diff]

PR Summary

• Adds opt-in support for byte-preserving binary APPEND uploads. Messages marked for binary upload retain their original bytes, including line endings, instead of being altered during upload.
• Protects uploads from unsupported or unsafe fallbacks. The client checks that the server supports the required capability before sending a batch and won’t retry a failed binary upload as a standard APPEND, which could change message contents.
• Documents how to use binary APPEND. The documentation explains message requirements, server support, stream handling, and how failures and retries are handled.
• Adds test coverage for binary uploads. Tests verify byte preservation, server capability checks, batch behavior, and that existing standard APPEND behavior remains unchanged.

[ralflang]

I need to ensure after merging there is a feature parity for the src/ branch.