Utopia Compression

Utopia Compression is a lightweight PHP library maintained by the Appwrite team that wraps seven compression algorithms — Brotli, Deflate, GZIP, LZ4, Snappy, XZ, and Zstd — behind a single abstract interface. Instead of learning each algorithm’s native PHP extension API, developers call the same compress() and decompress() methods regardless of which codec is selected at runtime.

The library also implements HTTP content-negotiation logic via fromAcceptEncoding(), parsing a browser or client’s Accept-Encoding header, including quality weights and the ‘br’ alias, and returning the best-supported compression algorithm automatically. This makes it a natural fit for HTTP servers and frameworks — like the broader Utopia Framework it’s part of — that need to pick a response encoding on the fly.

What You Get

• An abstract Compression base class with concrete implementations for Brotli, Deflate, GZIP, LZ4, Snappy, XZ, and Zstd
• A fromName() factory method to instantiate the right algorithm from a string identifier
• A fromAcceptEncoding() helper that parses HTTP Accept-Encoding headers, including quality weights, and picks the best supported codec
• isSupported() checks on every algorithm so you can detect missing PHP extensions before compressing

Common Use Cases

• Choosing a response compression algorithm dynamically based on a client’s Accept-Encoding header
• Compressing files or backups before storage in a self-hosted or cloud storage backend
• Swapping compression algorithms without changing calling code, since every algorithm shares the same interface
• Building HTTP servers or frameworks that need built-in content-encoding negotiation

Under The Hood

Architecture Utopia Compression is architected around a single abstract Compression base class (src/Compression/Compression.php) that defines the contract — compress(), decompress(), getName(), getContentEncoding(), and a static isSupported() — implemented by seven concrete subclasses under src/Compression/Algorithms/ (Brotli, Deflate, GZIP, LZ4, Snappy, XZ, Zstd), each wrapping a single PHP extension’s function pair (GZIP wraps gzencode()/gzdecode(), Brotli wraps brotli_compress()/brotli_uncompress(), and so on). Two static factory methods on the base class, fromName() and fromAcceptEncoding(), select and instantiate the right subclass — the latter parsing an HTTP Accept-Encoding header, including quality weights and the ‘br’ alias, to pick the highest-priority supported algorithm. This is a textbook strategy pattern with no dependency injection or layering beyond the base class and its implementations; changing the abstract contract would require touching all seven algorithm files, but given the codebase’s small, single-purpose scope that’s a contained blast radius rather than a structural risk.

Tech Stack The library targets PHP 8.1+ and declares zero required runtime dependencies in composer.json — each compression algorithm instead depends on an optional native PHP extension (ext-brotli, ext-zstd, ext-lz4, ext-snappy, ext-xz, ext-zlib) listed under ‘suggest’ rather than ‘require’, so consumers only install the extensions for the algorithms they actually use. Development tooling is PHPUnit (phpunit.xml) for testing and PHPStan (phpstan.neon, extending a shared monorepo config) for static analysis. The package is distributed via Packagist under PSR-4 autoloading (Utopia\Compression), and this GitHub repository is explicitly a read-only mirror of the packages/compression path inside the utopia-php/monorepo, where actual development happens.

Code Quality Test coverage is thorough for the library’s small surface area — a dedicated *Test.php file exists per algorithm (BrotliTest, GZIPTest, LZ4Test, SnappyTest, XZTest, ZstdTest) plus a CompressionTest for the factory and Accept-Encoding negotiation logic, and each algorithm test exercises real round-trip compression/decompression against multiple file types (plain text, JPG, PNG, and a large text file) with exact byte-size assertions rather than shallow smoke tests. Extension-dependent tests are correctly guarded with #[RequiresPhpExtension] attributes so the suite degrades gracefully when optional extensions aren’t installed. All files use declare(strict_types=1) and typed method signatures throughout. The GitHub Actions workflow visible in this mirror only syncs commits from the monorepo (mirror.yml) — the real test/lint CI pipeline lives in the upstream utopia-php/monorepo and isn’t visible from this repository alone.

API Design The public API is deliberately minimal: consumers either call Compression::fromName(‘gzip’) or Compression::fromAcceptEncoding($header) to get a ready-to-use algorithm instance, then call the same compress()/decompress() methods regardless of which of the seven algorithms was selected — there’s no configuration object or setup boilerplate beyond that single factory call. isSupported() gives callers a cheap way to feature-detect before compressing, and getContentEncoding() maps directly onto HTTP header values so the library slots straight into response-encoding logic. It doesn’t introduce novel compression techniques — it’s a thin, well-designed wrapper around existing PHP extensions — but the negotiation helper, parsing quality-weighted Accept-Encoding strings with alias resolution, saves meaningfully more boilerplate than most raw compression bindings, which is where the design earns most of its practical value.