Download the PHP package aurynx/http-compression without Composer

Aurynx | HttpCompression

Modern PHP library for HTTP compression with native type safety

gzip • brotli • zstd — simple, safe, and fast

Installation • Quick Start • Features • Use Cases • API • Advanced Usage • AI Guide

Why HttpCompression?

Modern web applications need efficient compression to reduce bandwidth and improve response times. HttpCompression makes it simple with a clean, modern API focused on:

• 🔷 Native PHP 8.4+ types — zero docblock types, full IDE autocomplete
• 🎯 Single facade pattern — one intuitive API for all scenarios
• 🚀 Glob pattern support — compress entire directories with wildcards
• 💾 Memory-safe streaming — handle large files without memory limits
• 🛡️ Fail-fast validation — catch errors at configuration time
• 🤖 AI-friendly design — perfect for code generation and assistants

Installation

Requirements:

• PHP 8.4 or higher
• ext-zlib (required for gzip)
• ext-brotli (optional, for brotli compression)
• ext-zstd (optional, for zstd compression)

Quick Start

Single File Compression

Batch Compression

Features

✨ Native Type Safety

The public API uses native PHP 8.4+ types everywhere (parameters, return types, readonly DTOs). This makes the library:

• Easier for IDEs and AI agents to navigate (no docblock type guessing)
• Safer at runtime thanks to engine-level type checks
• More self-documenting due to explicit signatures

Example signature:

🎯 Fluent Facade API

Two facades for different scenarios:

CompressorFacade::make() — Batch compression

CompressorFacade::once() — Quick single-item tasks

🚀 Glob Pattern Support

Compress entire directories with powerful glob patterns:

💾 Memory-Safe Streaming

Handle large files without loading into memory:

🔌 Callback Streaming (no resources)

Stream compressed data directly into callbacks without dealing with stream resources.

Single algorithm (sendToCallback):

Multiple algorithms (sendAllToCallbacks):

See more patterns and caveats in Advanced Usage:

• Callback streaming (single/multi)
• Low-level WritableStream wrapper

👉 Read: ./docs/advanced-usage.md

🛡️ Fail-Fast Validation

Errors are caught at configuration time, not during compression:

📈 Rich Result Objects

Detailed statistics and easy access:

Use Cases

1. Static Site Pre-Compression

Compress assets during build for nginx gzip_static:

Nginx configuration:

2. Dynamic HTTP Response Compression

Compress content on-the-fly with caching:

3. API Response Compression

Compress JSON API responses:

4. Log File Archival

Compress and archive old log files:

5. Asset Pipeline Integration

Integrate with your build tools:

API Reference

Facades

CompressorFacade::make() — Batch Compression

CompressorFacade::once() — Single Item

Notes on Saving Files

• saveTo(path):

  • Atomic write (tmp + rename) to the target path
  • Existing target is replaced (OverwritePolicy=Replace)
  • The target directory must already exist (no auto-create)
• saveAllTo(directory, basename, options):
  • basename must be a plain filename (no '/' or '\', not '.' or '..')
  • Options:
  • overwritePolicy: fail|replace|skip (default fail)
  • atomicAll: bool (default true) — all-or-nothing semantics
  • allowCreateDirs: bool (default true)
  • permissions: int|null — chmod after successful rename

Configuration

ItemConfig — Compression Configuration

AlgorithmSet — Algorithm Configuration

Results

CompressionResult — Batch Results

CompressionItemResult — Single Item Result

CompressionSummaryResult — Aggregated Statistics

For AI Assistants

This library is designed to be AI-friendly with:

• ✅ Native types — no docblock parsing needed
• ✅ Explicit naming — CompressionResult, AlgorithmEnum, etc.
• ✅ Fluent API — easy to chain methods
• ✅ Fail-fast — errors are obvious and immediate
• ✅ Immutable value objects — no side effects

For a deeper, agent-focused walkthrough, see the AI Guide: docs/ai-manifest.json.

Common Patterns

Avoid These Mistakes

❌ Multiple algorithms with saveTo():

✅ Use compress() instead:

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Development Setup

License

The MIT License (MIT). Please see License File for more information.

Credits

Created and maintained by Anton Semenov.

Crafted by Aurynx 🔮