Fos Http Cache Cloudfront Laravel Package

Product Decisions This Supports

• Performance Optimization: Enables edge caching for Laravel apps via CloudFront, reducing backend load and latency by offloading static/dynamic content delivery to AWS’s global network. Aligns with Core Web Vitals goals (e.g., faster TTFB).
• Cost Efficiency: Reduces origin server costs (e.g., EC2, RDS) by caching responses at the edge, lowering AWS bills for high-traffic routes. Complements Laravel Horizon for queue-heavy apps.
• Build vs. Buy: Avoids custom CloudFront invalidation logic (e.g., manual API calls or cron jobs), accelerating time-to-market for caching features. Leverages FOSHttpCache’s battle-tested proxy pattern. At v1.3.0 the maintenance overhead is now largely CI/Dependabot-driven, which reduces the “who owns this?” risk in a buy decision.
• Roadmap Alignment:
  • Phase 1: Integrate with existing Laravel caching layers (e.g., Redis) for hybrid caching.
  • Phase 2: Extend to multi-CDN support (e.g., Cloudflare, Fastly) by abstracting the proxy interface.
  • Phase 3: Add cache analytics (e.g., hit/miss ratios) via CloudFront metrics.
• Use Cases:
  • High-traffic APIs: Reduce Lambda/EC2 costs for REST/GraphQL endpoints.
  • Static Asset Delivery: Cache JS/CSS/images with CloudFront’s compression and geo-routing.
  • Legacy Migration: Replace Varnish/Nginx caching with a managed AWS service, especially for teams already on FOSHttpCache 3.x.
  • A/B Testing: Invalidate cached routes dynamically without full redeploys.

When to Consider This Package

• Adopt if:
  • Your Laravel app already uses CloudFront for CDN and needs programmatic cache invalidation.
  • You’re using FOSHttpCache/Symfony HttpCache 3.x and want to extend it to CloudFront. (v1.3.0 dropped support for friendsofsymfony/http-cache 2.x — confirm your version before upgrading, and treat this as a hard blocker if you haven’t migrated yet.)
  • You prioritize developer velocity over custom solutions (e.g., no need to build AWS API wrappers).
  • Your caching strategy relies on HTTP-level invalidation (not database-driven, e.g., cache:tags).
  • You’re migrating from self-hosted caches (e.g., Varnish) to a managed service.
• Look elsewhere if:
  • You’re not using CloudFront (e.g., Fastly, Cloudflare, or self-hosted Varnish).
  • You’re still on friendsofsymfony/http-cache 2.x and can’t upgrade yet — v1.3.0 no longer supports it; pin to 1.2.x in the interim.
  • Your primary caching needs are static assets only (use CloudFront’s built-in cache behaviors).
  • You require real-time cache invalidation (e.g., per-user cache; consider Redis or database-backed caching).
  • Your stack is non-Laravel/PHP (e.g., Node.js, Python, or serverless frameworks like AWS Lambda).
  • You need advanced features like:
    • Cache key transformation (e.g., hashing query strings).
    • Multi-CDN support (e.g., failover between CloudFront and Cloudflare).
    • Edge-side includes (ESI) or dynamic content caching (consider CloudFront Functions or Lambda@Edge).
  • Your team lacks AWS infrastructure ownership (e.g., no IAM permissions for CloudFront API calls).

How to Pitch It (Stakeholders)

For Executives

*"This package lets us supercharge Laravel’s performance by offloading caching to CloudFront—AWS’s global edge network. Here’s why it’s a no-brainer:

• Cut costs: Reduce backend server load by 30–70% for cached routes, lowering AWS bills.
• Speed up the app: Slash latency for global users (e.g., 50ms → 100ms TTFB improvements).
• Zero DevOps overhead: Drop-in integration with our existing FOSHttpCache setup; no custom code needed.
• Future-proof: Aligns with our cloud-first roadmap and works alongside Laravel Horizon, Forge, and Envoyer. The recent 1.3.0 release is a hardening release — bug fixes around CloudFront invalidation requests, stricter input typing, and automated dependency updates — which is exactly the kind of maintenance signal we want. Risk: Low, but not zero — the 1.3.0 upgrade drops FOSHttpCache 2.x support, so we need to confirm our dependency version first. MIT license, actively maintained, backed by AWS’s SLA. Let’s pilot it on our /api routes first."*

For Engineering (Tech Leads)

*"The fos-http-cache-cloudfront package bridges FOSHttpCache and CloudFront, giving us seamless edge caching with these tradeoffs: ✅ Pros:

• No reinventing the wheel: Uses AWS SDK under the hood; handles retries, throttling, and invalidation logic.
• Laravel-native: Works with existing Symfony HTTP Cache components (e.g., fos/http-cache-bundle).
• Low maintenance: MIT license, CI-tested, minimal dependencies — and 1.3.0 adds Dependabot + refreshed CI, so we inherit automated dependency hygiene.
• Cost-effective: Reduces origin server costs by caching at the edge.

⚠️ Cons:

• CloudFront-only: Not a multi-CDN solution (but we can abstract the proxy interface later).
• AWS dependency: Requires IAM permissions and CloudFront setup (but we already use it for assets).
• No built-in monitoring: Need to pair with CloudWatch or custom logging.

What changed in 1.3.0 (action required before bumping):

• Dropped friendsofsymfony/http-cache 2.x — the 1.3.0 line requires 3.x. Audit composer.lock first; if we’re on 2.x, either plan the FOSHttpCache upgrade or stay pinned to 1.2.x.
• CloudFront::purge() now type-stricts the URL argument to string — calls that pass Stringable objects or loose scalars will fail. Grep for purge( call sites.
• CallerReference is now passed to createInvalidation as a string — fixes real-world invalidation failures caused by type coercion.
• Corrections to README links/code samples — the integration snippets we’d copy-paste are now accurate.

Recommendation:

1. Pilot: Test on a non-critical Laravel route (e.g., /products) with CloudFront invalidation.
2. Upgrade path: Verify FOSHttpCache 3.x, then bump to 1.3.0; run the test suite against typed purge() calls.
3. Integrate: Bind the proxy to Laravel’s container via a service provider.
4. Monitor: Track cache hit ratios and origin request reductions in CloudFront metrics. Alternatives: If we need multi-CDN, we’d need to build a wrapper or use a broader package like spatie/flysystem-cloudfront (but this is CloudFront-specific)."*

For Developers

*"Here’s how to get started fast with this package (v1.3.0):

1. Install (requires friendsofsymfony/http-cache 3.x):

   composer require jean-beru/fos-http-cache-cloudfront async-aws/cloudfront
   

2. Set up the proxy (in a service provider or bootstrapper):

   $cloudFront = new \Aws\CloudFront\CloudFrontClient([
       'region'  => env('AWS_REGION'),
       'version' => 'latest',
       'credentials' => [
           'key'    => env('AWS_ACCESS_KEY_ID'),
           'secret' => env('AWS_SECRET_ACCESS_KEY'),
       ],
   ]);
   
   $proxy = new \JeanBeru\HttpCacheCloudFront\Proxy\CloudFront(
       client: $cloudFront,
       options: [
           'distribution_id' => env('CLOUDFRONT_DISTRIBUTION_ID'),
           // Optional: Custom caller reference generator
           'caller_reference_generator' => new \JeanBeru\HttpCacheCloudFront\CallerReference\DateCallerReferenceGenerator('YmdHi'),
       ]
   );
   

3. Invalidate cache (URL argument is now strictly typed as string in 1.3.0):

   $proxy->purge('/homepage')->purge('/assets/*')->flush();
   

4. Laravel integration (optional):
   • Bind the proxy to the container and extend the Cache facade for seamless invalidation.

Key Notes:

• AWS Credentials: Must be configured in .env or Laravel’s AWS config.
• CloudFront Setup: Ensure your distribution has CacheBehaviors configured for the paths you’re caching.
• Upgrading to 1.3.0: Expect breakage if you pass non-string URLs to purge() or rely on FOSHttpCache 2.x. Cast call sites with (string).
• Testing: Mock the AWS client in unit tests; use Laravel’s HTTP tests for E2E validation.
• Fallbacks: Handle ProxyResponseException if AWS rejects duplicate invalidations (e.g., retry with a new caller reference)."*

Example Stakeholder Alignment Table: