Image Optimizer Laravel Package

Technical Evaluation

Architecture fit

• ps/image-optimizer is a framework-agnostic PHP orchestration library, not a Laravel package. There is no service provider, facade, publishable config, queue hook, or event integration. It exposes a small composition API: assemble an OptimizerChain from optimizer objects (Optipng, Pngquant, Jpegoptim, Gifsicle, Svgo, etc.) and call optimize($source, $destination).
• For a TPM this is a feature, not a gap. It slots in as an infrastructure adapter behind a domain-owned ImageOptimizer contract, so the vendor decision (this package vs. Spatie's wrapper vs. a managed CDN) stays reversible without touching call sites. Treat the interface as the product surface and the package as an implementation detail.
• It performs no image decoding — it shells out to native binaries through Symfony Process. The real architecture question is therefore not "do we adopt this library?" but "do we own and operate an image-toolchain in our runtime image?" That framing matters for how the decision is reviewed.
• It does not resize, crop, transcode, or negotiate formats by URL. Those are separate concerns (image manipulation library or CDN). The package is a compression step, and scoping it as such prevents roadmap confusion later.

Integration feasibility

• Composer install is trivial and Symfony Process is already present transitively in Laravel. No dependency-tree conflict expected.
• The genuine effort is environmental: provisioning optipng, pngquant, pngcrush, pngout, gifsicle, jpegoptim, jpegtran, and svgo at known absolute paths across app containers, worker containers, and CI.
• Realistic estimate: a viable end-to-end spike (upload → optimize → store) is about one engineer-day. Productionising it — base image, adapter, queued job, feature flag, backfill, runbook, metrics — is roughly one to two engineer-weeks for a single engineer, plus legal review calendar time in parallel.

Technical risk

• Maintenance staleness (high). The project is in low-maintenance mode. Verify the PHP version constraint on the latest tag against our target (8.2/8.3) before committing; older tags cap at PHP 7 and would force a fork. The near-zero listed dependents is a weak but real health signal — it may understate true usage, but it should not be ignored.
• System-dependency surface (high). Seven-plus optional binaries with independent release cadences, distro-specific builds, and mixed licenses (optipng/zlib, gifsicle GPL-2, pngquant GPL/libpng, jpegtran IJG). Our distribution model needs a written legal answer on invoking GPL binaries as separate processes — the common interpretation is permissive, but this must not be assumed.
• Quality/correctness risk (medium). Lossy transforms (pngquant, aggressive jpegoptim) are irreversible and visibly observable. Without agreed quality thresholds and a visual-regression check, this becomes a customer-facing incident rather than an engineering ticket.
• Format coverage (medium). WebP and AVIF are not addressed by this toolchain. If modern formats are on the 12-month roadmap, this is a tactical bridge, not the terminal state — say so explicitly in the decision record.
• Security (medium). The library invokes external processes against user-supplied files. Decompression bombs, malformed inputs, and metadata/PII passing through CLI arguments need explicit handling. Run in an isolated, resource-limited worker, never on the web request path.
• Synchronous CPU cost (medium). Blocking, CPU-bound work. Must be queued; inline optimization will show up as p95 latency regression on uploads.

Key questions

1. What are the agreed quality thresholds (byte-savings targets, SSIM/visual-diff tolerance) and who signs off on lossy compression per asset class?
2. Is the binary toolchain already in our base image, or does this create a new build-and-patch obligation owned by platform?
3. What deployment targets must be supported — Fargate, shared hosting, Lambda? Serverless materially changes the calculus (binary packaging, cold-start, /tmp limits).
4. Is WebP/AVIF required within 12 months? If yes, what is the documented path off this toolchain?
5. What is current monthly image volume, storage cost, and egress cost? Does measured savings beat a managed image CDN on total cost of ownership, not just unit price?
6. Has legal cleared GPL-family binaries in our container image and distribution model?

Integration Approach

Stack fit

• Laravel 9–11 on PHP 8.1+ is a comfortable fit with no framework coupling to fight. Bind ImageOptimizerInterface in a service provider with two implementations: the ps/image-optimizer adapter and a no-op passthrough for local and test environments.
• All tunables belong in config/images.php: absolute binary paths, per-format optimizer chains, quality levels, process timeout, max input size, and a global kill-switch flag. Binary paths and quality values must not live in application code.
• Storage reality: the optimizers require real local files. Pair with a Storage::disk('local') scratch workspace — pull from S3, optimize locally, push result back. Do not attempt to stream object storage through the optimizer.

Migration path

1. Inventory current image write paths (uploads, CMS media, imports, generated avatars, product catalog). Select one low-blast-radius surface as the pilot — usually avatars or thumbnails.
2. Ship the adapter behind a feature flag defaulted off. Run in shadow mode over a sample of real traffic, capturing byte-savings and visual diffs before enabling.
3. Add a batched, rate-limited backfill for legacy assets, with originals preserved in cold storage for 30–90 days as a rollback guarantee.
4. Turn on for new uploads only after pilot metrics clear the agreed thresholds, then backfill the long tail.

Compatibility

• Verify both the package's PHP constraint and its Process dependency before pinning. Test the exact tag in CI, not just on a laptop.
• macOS and Windows developer machines will not have these binaries. Standardise local development on Sail/Docker with the toolchain baked in, and use the same image in CI — otherwise tests silently skip and coverage becomes fictional.
• If multiple services exist, publish the toolchain image once so binary versions are pinned in exactly one place across the org.

Sequencing Spike + PHP-matrix verification → Toolchain baked into base image and CI → Adapter interface + config + feature flag → Queued job with timeout, retry, and input-size guard → Pilot on one surface with quality metrics → Backfill with originals retained → Default-on and decommission of the legacy path. Run the legal/licensing review in parallel with the spike — it is the most likely late-stage blocker and the cheapest thing to start early. Gate each arrow with an explicit go/no-go so the project can stop cleanly at any step.

Operational Impact

Maintenance

• Two maintenance loops, not one: the PHP package (low churn, but stale — expect to pin or fork) and the OS-level binaries (patching, CVE response, base-image rebuilds). The second is the loop that will surprise platform teams mid-upgrade.
• The library is small enough that forking and patching is a genuine escape hatch. Keep the adapter boundary clean so a fork remains cheap.
• Review the upstream repo quarterly. If it goes fully dormant and a CVE lands in a transitive dependency, the fork stops being optional.

Support

• Support volume will be dominated by "my upload failed" reports. Process failures surface with opaque stderr; map them into a small taxonomy (binary missing, timeout, corrupt/unsupported input, disk full) and attach original-file metadata to logs so triage does not require reproducing customer files.
• Publish a runbook covering: verifying binaries inside a container, reproducing a failure locally, reverting a batch to originals, and disabling via the kill-switch. On-call needs the runbook more than the code.
• Decide customer-facing failure behaviour up front. The default should almost always be "accept the original, optimize asynchronously" rather than failing the upload — a slightly larger image is a far better outcome than a blocked workflow.

Scaling

• Throughput is CPU-bound on the worker tier. Isolate a dedicated images queue with its own worker pool so a bulk backfill cannot starve transactional jobs.
• Build a cost model early: measure ms/image per format at target quality on production-class hardware, multiply by projected volume, and compare against image-CDN pricing including engineering toil. At low volume self-hosting wins clearly; above roughly a million images/month the CDN usually wins on total cost, primarily by eliminating the toolchain and the storage round-trip.
• Horizontal scaling is straightforward — stateless workers, files in object storage — but ceiling is set by per-file CPU cost. Tune concurrency against measured CPU, don't just add workers.

Failure modes

• Missing or mismatched binary on one host during a rolling deploy → intermittent, hard-to-reproduce failures. Pin versions in the image and assert binary presence/version at boot.
• Timeouts on large or pathological files → stuck workers. Enforce both a process timeout and an input-size/ dimension limit, and fail fast rather than retrying blindly.
• Disk exhaustion in the scratch workspace from concurrent large files → cascading failures across unrelated jobs. Cap concurrency and clean up temp files in finally blocks.
• Quality regressions shipped silently after a binary upgrade → sudden user complaints with no code change to blame. Pin binary versions and run the visual-diff check against a small golden-image set in CI on any toolchain bump.
• Storage round-trip failures (S3 throttling, partial writes) → half-written outputs. Write to a temp key and move atomically; make the job idempotent.

Ramp-up

• Expect one to two weeks for the initial engineer to become genuinely productive, most of it spent on container/toolchain plumbing rather than the library API.
• Broader team ramp-up is bounded by the interface, not the package: if the adapter is well documented, most engineers never need to learn the optimizer internals.
• Budget explicit time for platform/DevOps involvement (base image, CI, binary patching) and for a legal review cycle. Both sit outside the feature team's control and are the most common sources of schedule slip on a project this small in code terms.
• Document the exit criteria for revisiting a managed service — volume thresholds, WebP/AVIF requirement, or toolchain maintenance burden exceeding an agreed hours-per-quarter budget — so the decision to move on is triggered by data rather than by whoever is on call that week.