README

A high-performance, object-oriented PHP image proxy designed for maximum TTFB (Time to First Byte) rescue, memory protection, and next-gen format conversion.

The Origin Story

This proxy was not built in a vacuum; it was built out of necessity. When content managers upload raw, high-resolution, uncompressed images directly into a CMS dashboard, frontend performance and Time to First Byte (TTFB) drop dead.

Instead of forcing a rewrite of the entire legacy upload logic, the Miranda Image Proxy acts as a bulletproof middleware. It intercepts these massive payloads, bypasses processing when unnecessary, optimizes formats on the fly, and caches the result. It is designed to survive heavy loads without triggering PHP memory limits (OOM crashes).

Core Features

• Aggressive Desktop-Bypass: If the requested size matches the original (and it is not a mobile device), PHP logic halts instantly and delivers the file via readfile.
• Next-Gen Formatting: Automatically converts standard images to AVIF or WebP based on the browser's Accept headers.
• Smart Mobile Detection: Dynamically reduces quality and scales down massive images when mobile user agents are detected.
• Memory Protection: Pre-calculates required memory allocation. Safely falls back to original image delivery if the server's memory_limit threshold is reached.
• Built-in Cache Engine: Generates ETag-hashed, immutable cached assets to eliminate redundant processing.

Requirements

• PHP 8.0+
• GD Library enabled

Installation

Method A: Composer (Recommended)

The most robust way to install the proxy and utilize the PSR-4 autoloader.

composer require phings-studio/miranda-image-proxy