Intervention Request Laravel Package

Technical Evaluation

• Architecture fit: For a Laravel/PHP product team, the strongest fit is as a standalone image transformation/proxy service (Docker sidecar or internal service) rather than in-process library code. v7’s stateless InterventionRequest and worker-mode support improve fit for long-running runtimes such as FrankenPHP, Laravel Octane, RoadRunner, or Swoole, but only if all custom integration code is stateless.
• Breaking change impact: Removing InterventionRequest::getResponse is a hard API break. Any Laravel controller, middleware, command, or custom service that calls getResponse() or assumes handleRequest() only dispatches work must migrate to handleRequest($request)->send() or adapt the returned response into the Laravel response lifecycle. Direct send() inside Laravel should be used carefully because it bypasses normal framework response handling.
• Docker path break: Changing the image root from /var/www/html/web to /app/public will break existing volume mounts and IR_IMAGES_PATH / IR_CACHE_PATH configuration. Misconfigured deployments may appear healthy but return 404s, fail to write cache, or write into ephemeral container storage.
• Worker-mode opportunity and risk: Statelessness is a real scalability benefit, but worker mode introduces long-running-process concerns: request isolation, memory growth, opcache behavior, restart policy, and any custom stateful extensions. The plain PHP + Nginx + cron image remains lower-risk for teams not ready for FrankenPHP.
• PHP 8.4 base image: If the package is consumed as a Docker service, PHP 8.4 is mostly isolated from the Laravel app runtime. If embedded, confirm the package’s actual PHP requirement and whether the host Laravel version supports PHP 8.4.
• Feature value: Hotspot initial cropping area is useful for editorial/zoom-to-region image workflows and is backward compatible when only x/y are supplied. The crop processor fix without width/height reduces edge-case failures but should be regression-tested against existing image URLs.
• Documentation inconsistency: The hotspot syntax is described with : separators but the example uses ; between normalized coordinates. This must be confirmed before exposing the feature to users or building URL-generation helpers.
• Version/tag clarity: The release is titled v7.0.0, while Docker examples reference 7.0.1. Confirm package version, image tag, and whether latest is moving. Pin immutable tags or digests in production.
• Key questions: Are we embedding the package or running the Docker image? Which Laravel/PHP versions are in scope? Do we rely on getResponse() or any stateful service usage? Which Docker flavor will we standardize on: plain PHP or FrankenPHP? Who owns cache cleanup if FrankenPHP has no cron? Are transformation URLs public, signed, rate-limited, and validated? Do we need backward compatibility for existing hotspot URLs?

Integration Approach

• Stack fit: Prefer Docker image deployment behind Laravel’s routing/reverse proxy for least coupling. Laravel serves application routes and delegates image URLs to the intervention service; shared read-only image storage and writable cache volumes are mounted into the service. Embedded package usage should be reserved for teams that need in-process transformations and can own the API migration.
• Migration path: Inventory every usage of InterventionRequest, getResponse, Docker Compose paths, environment variables, and volume mappings. Pin the current 6.x image first. Create a branch upgrading code to handleRequest($request)->send() or equivalent response adaptation. Update Compose paths to /app/public/assets and /app/public/images, update IR_IMAGES_PATH and IR_CACHE_PATH, then test in staging with representative image URLs.
• Compatibility checks: Verify PHP 8.4 compatibility for embedded use. Verify Laravel response handling if calling the package from a controller. Confirm volume permissions for /app/public/assets and /app/public/images. If using FrankenPHP, add Caddy /data and /config volumes and confirm port/reverse-proxy configuration.
• Sequencing: 1) pin and baseline current 6.x behavior; 2) update code for removed getResponse on a branch; 3) update Docker image tag and path configuration; 4) stage with cache cleared and image fixtures; 5) run side-by-side or blue/green rollout; 6) monitor 404/5xx rates, cache hit ratio, latency, and worker restarts; 7) document rollback to 6.x tag and old volume paths until confidence is established.
• Cache and URL compatibility: Clear or version the image cache after migration. Re-test existing transformation URLs, especially hotspot URLs, crop URLs without width/height, and any cached derivatives. If public URLs are persisted in content, confirm v7 output remains stable or plan cache warming.
• Feature rollout: Treat hotspot initial cropping as an additive feature with validation and documentation. Confirm separator syntax, normalized coordinate bounds, and error behavior for invalid values before allowing content editors or public URL builders to generate the new syntax.

Operational Impact

• Maintenance: Pin exact image tags/digests; avoid latest. Track upstream releases, PHP 8.4 lifecycle, and FrankenPHP maturity. Maintain separate runbooks for plain PHP and FrankenPHP flavors because cron behavior differs.
• Support: The main support burden is configuration drift: volume paths, environment variables, Caddy volumes, and worker restarts. Add health checks and startup validation that confirms image storage is readable, cache storage is writable, and expected paths exist.
• Scaling: Stateless request handling supports horizontal scaling and worker-mode deployments. Scaling still depends on shared cache/storage performance and reverse-proxy limits. If using FrankenPHP, plan worker count, memory limits, restart policies, and graceful shutdown.
• Failure modes: Watch for path mismatch after /app/public change, permission errors on cache volumes, stale cached images, 404s from missing source images, worker memory growth, FrankenPHP restart loops, missing cron-based cache cleanup, invalid hotspot parameters, and image-processing timeouts on large assets.
• Monitoring: Track request latency, 4xx/5xx rate by transformation route, cache hit/miss ratio, disk usage, worker restart count, and memory usage. Alert on cache write failures and source-image read failures.
• Ramp-up: Low-to-moderate for teams already running the Docker image as a sidecar; moderate for embedded Laravel usage because of the API break and response-handling changes; higher for FrankenPHP worker mode because of long-running process operations and Caddy configuration. Provide a short migration guide and test fixtures before broad rollout.