TIMEOUT
TIMEOUT = 300
Seconds a single binary invocation may run before it is killed.
Shared machinery for a codec that shells out to a compressor on disk.
A PHP extension is a build-time decision and a binary is a package-manager one, so the two are
absent on different hosts. zstd and brotli are both on the PATH of a great many machines whose
PHP was built without the matching extension, and reading a frame back matters more than writing
one quickly: a bucket written on a box with ext-brotli has to stay readable on a box without it,
or the backup is not a backup.
Nothing built on this may be a per-frame writer. A process spawn dominates the work at frame
sizes - 1,000 separate zstd invocations measured 5.88 seconds against sub-millisecond
compression - so CodecRegistry::register() takes these with $perFrame FALSE, and they serve
reading, compaction, dictionary training and export instead. PipeCodec::compress() spawns once
per call and is correct for a one-off; PipeCodec::compressBatch() runs the binary ONCE across the
whole batch, which is what bulk work uses.
Both binaries follow the same file convention, which is what lets one implementation drive them:
given several inputs they write beside each one, adding the suffix when compressing and stripping
it when decompressing. A batch is therefore laid out as <n> and <n><suffix> in a private
scratch directory and read back by name.
COMMON_DIRECTORIES = ['/usr/bin', '/usr/local/bin', '/bin', '/opt/homebrew/bin', '/opt/local/bin', '/snap/bin']
Directories searched after PATH.
A php-fpm pool frequently runs with a minimal PATH that a login shell does not have, so a binary the operator can see is regularly one PHP cannot. These are where the common package managers put one.
__construct(string|null $binaryPath = null, string|null $scratchDirectory = null) : mixed
Constructs the codec.
| string|null | $binaryPath | An explicit path to the binary, or NULL to search PATH and the common directories. |
| string|null | $scratchDirectory | Directory for batch scratch files, or NULL for the system temporary directory. |
compress(string $data, ?int $level = null, ?string $dictionary = null) : string
Compresses a buffer.
| string | $data | The bytes to compress. An empty string compresses to an empty string, so that an absent payload never becomes a non-empty frame. |
| ?int | $level | A level within CompressionCodecInterface::levels(), or NULL for the default. |
| ?string | $dictionary | Raw dictionary bytes, or NULL. Ignored by codecs that report no dictionary support, so a caller never has to branch on it. |
The compressed bytes.
compressBatch(list$buffers, int|null $level = null, string|null $dictionary = null) : list<string>
Compresses many buffers in one process.
| list |
$buffers | The buffers to compress, in order. |
| int|null | $level | A level within PipeCodec::levels(), or NULL for the default. |
| string|null | $dictionary | Raw dictionary bytes, or NULL. |
When the codec is unavailable, or the binary fails.
The compressed buffers, in the same order.
decompressBatch(list$buffers, string|null $dictionary = null) : list<string>
Decompresses many buffers in one process.
| list |
$buffers | The buffers to decompress, in order. |
| string|null | $dictionary | The same dictionary bytes used to compress, or NULL. |
When the codec is unavailable, or the binary fails.
The original buffers, in the same order.
arguments(bool $compressing, int $level, string|null $dictionaryPath) : list<string>
The flags one invocation runs with, before the input paths.
| bool | $compressing | TRUE to compress, FALSE to decompress. |
| int | $level | A level already brought into range by PipeCodec::clamp(). |
| string|null | $dictionaryPath | Where the dictionary was written, or NULL when there is none. |
The arguments, without the binary itself.
batch(list$buffers, bool $compressing, int|null $level, string|null $dictionary) : list<string>
Runs one binary invocation across a whole batch.
| list |
$buffers | The buffers to process, in order. |
| bool | $compressing | TRUE to compress, FALSE to decompress. |
| int|null | $level | Compression level, ignored when decompressing. |
| string|null | $dictionary | Raw dictionary bytes, or NULL. |
When the codec is unavailable, or the binary fails.
The processed buffers, in the same order.
run(list$command) : void
Executes one command and fails loudly on a non-zero exit.
| list |
$command | The argument vector. Never a shell string, so a path with a space or a quote cannot become an injection. |
When the process cannot start, times out, or exits non-zero.