Compress Test Utilities Laravel Package

Getting Started

This is a dev-only package, so it belongs in require-dev:

composer require --dev wyrihaximus/compress-test-utilities

Where to look first, in order:

1. README.md — with zero stars and zero dependents, the README is the only documentation you can trust. Skim it end-to-end before writing a line of code; the API surface is small but the method names matter.
2. src/ — the package is small enough to read in a sitting. Identify the trait(s)/constraint classes it exposes and note the exact signatures; don't guess from the README alone.
3. tests/ inside the package itself — packages like this typically dogfood their own helpers, so the package's own test suite is a working usage manual showing you the intended integration pattern.

Your first use case is almost certainly this: you have code that emits gzip/deflate/brotli/zstd payloads (a middleware, a stream filter, a response encoder) and you want assertions that don't devolve into hand-rolled gzencode() calls in every test. Pull the trait into your base test case, then write a round-trip assertion instead of a byte-equality assertion:

use WyriHaximus\Compress\TestUtilities\...; // check src/ for the exact FQCN

final class ResponseEncoderTest extends TestCase
{
    use CompressionAssertions; // illustrative name — confirm in src/

    public function testEncodesGzip(): void
    {
        $encoded = (new Encoder())->encode('hello world');
        $this->assertCompressesTo('hello world', $encoded); // verify actual method name
    }
}

Start with a single round-trip test against plain ext-zlib. Add the other algorithms once you've confirmed the helper behaves as expected — the package's value compounds as your CI matrix widens.

Implementation Patterns

Trait-in-base-class. These utilities are designed to be mixed into a TestCase, not instantiated. Put the trait on an abstract CompressionTestCase so every encoder/decoder test in your app shares the same assertion vocabulary, and so a future API change in the package is a one-line fix.

Round-trip over byte-equality. The most robust pattern is always decompress-and-compare-plaintext. Asserting exact compressed bytes is brittle across zlib versions, library builds, and even OS-level implementations — reserve byte assertions for cases where you specifically control the encoder and need regression protection on wire format.

Data providers for algorithm matrices. If your code supports multiple codecs, drive tests from a provider that lists codec + fixture pairs, skipping entries whose extension is absent:

public static function codecs(): iterable
{
    yield 'gzip' => ['gzip', 'gzencode', 'gzdecode'];
    if (extension_loaded('zstd')) {
        yield 'zstd' => ['zstd', ...];
    }
}

Fixtures as files, not string literals. Keep binary fixtures in tests/fixtures/ and read them with file_get_contents. Inline binary literals in PHP source are a maintenance trap — editors mangle them, diffs are unreadable, and PHPStan can't help you.

Pair with stream/PSR-7 tests. If your compression output flows through a PSR-7 body or a ReactPHP stream (common in WyriHaximus's ecosystem), use the assertions against the stringified result of the body rather than the stream itself. (string) $response->getBody() then assert — this keeps the helper applicable to both sync and async paths.

CI matrix integration. Run the suite on each PHP version you support, and install the optional extensions (ext-brotli, ext-zstd) in at least one CI job so the codec branches actually execute. Everything else can rely on conditional skips.

Gotchas and Tips

Binary strings are hostile to debugging. Never var_dump() a compressed payload — you'll get mojibake and truncated output. Use bin2hex() or dump to a file and inspect with gunzip/zstd -d. When an assertion fails, the diff view will be useless for binary data, so wrap failures with a hex dump yourself.

Determinism: gzip embeds metadata. gzencode() writes an mtime and an OS byte into the header by default, so two runs on different machines produce different bytes for identical input. If you compare bytes, force mtime = 0 (the second argument to gzencode()). Note that this only controls the header — the deflate body is still implementation-dependent.

Don't trust byte-equality across implementations. PHP's ext-zlib, a bundled libdeflate, and a system zlib can all produce valid but different streams at different compression levels. Round-trip assertions are the only portable contract.

Conditional extension skips must be explicit. Use markTestSkipped() with a clear message rather than silently returning; a skipped test that looks like a pass will hide a broken codec branch for months. Also confirm the skip count in CI output — a job where everything skipped is a green build that tested nothing.

Zero dependents means zero community troubleshooting. There's no Stack Overflow corpus for this package. When something is wrong, the answer is in src/. Pin to a specific minor version in composer.json and treat upgrades as deliberate changes, not routine composer update collateral. With a last release dated in the future relative to normal release cadence (2026-07-08), also sanity-check the tag list and CHANGELOG before bumping.

Extension points are likely narrow. Expect the customization surface to be limited to method overrides on the trait and fixture path configuration. If you need codec-specific behavior the package doesn't expose, wrap it in your own helper rather than forking — a fork of a zero-dependent package becomes unmaintainable fast.

License is MIT, so forking and vendoring are legally unencumbered. That's your escape hatch if the package goes stale: the surface area is small enough to copy the two or three assertions you actually use into your own test-support namespace.

Score context. The opportunity score (59.57) against zero stars and zero dependents signals a package that's useful but unproven. Adopt it behind your own trait wrapper so you can swap it out without touching every test file.