Laravel Cloudflare Laravel Package

Technical Evaluation

Architecture Fit

• Core Purpose: The package extends Laravel’s built-in TrustProxies middleware to dynamically include Cloudflare IP ranges as trusted proxies, ensuring accurate client IP detection behind Cloudflare. This aligns perfectly with Laravel applications using Cloudflare for CDN, security, or DDoS protection.
• Leverages Native Laravel Patterns: The package integrates seamlessly with Laravel’s middleware stack and caching system, avoiding reinventing core functionality. It replaces the default TrustProxies middleware, which is a clean architectural approach.
• Extensibility: Supports custom proxy callbacks (e.g., for enterprise use cases like private IP ranges or hybrid setups) via LaravelCloudflare::getProxiesUsing(). This allows TPMs to adapt the package for niche requirements without forking.

Integration Feasibility

• Minimal Boilerplate: Installation requires only a Composer dependency and middleware replacement in bootstrap/app.php. No database migrations or complex configurations are needed.
• Laravel Version Agnostic: Supports Laravel 11–13 (as of v4.x) and older versions via separate branches, reducing version-specific risks. The TPM can choose the branch aligning with their stack.
• Dependency Lightweight: Replaces the deprecated fideloper/proxy package with Laravel’s native TrustProxies, reducing external dependencies. No additional services (e.g., queues, jobs) are required.

Technical Risk

• Cloudflare IP Cache Staleness: The package caches Cloudflare’s IP ranges (default: 24h). If not refreshed, stale IPs may cause false positives/negatives in IP-based logic (e.g., geo-blocking, rate limiting). Mitigation: Schedule cloudflare:reload via Laravel’s task scheduler.
• Middleware Replacement Risk: Replacing TrustProxies globally affects all requests. If other middleware relies on the original TrustProxies behavior (e.g., custom proxy logic), conflicts may arise. Validation Required: Test with existing middleware (e.g., ThrottleRequests, GeoBlock).
• IPv6 Support: Cloudflare’s IP ranges include IPv6. The package handles this natively, but the TPM should verify their stack supports IPv6 proxies (e.g., PHP’s filter_var with FILTER_VALIDATE_IP).
• Performance Overhead: Fetching and caching Cloudflare IPs adds ~50–100ms on first load. For high-traffic apps, pre-warm the cache during deployments or use a cron job.

Key Questions for the TPM

1. Cloudflare Configuration:
   • Is Cloudflare configured as a proxy (not "Under Attack" mode) for the target Laravel app?
   • Are there additional proxy layers (e.g., load balancers) that need inclusion in trusted_proxies?
2. IP-Based Logic:
   • Does the app use IP-based features (e.g., request()->ip(), ThrottleRequests) that must align with Cloudflare’s CF-Connecting-IP header? If so, test thoroughly.
3. Cache Strategy:
   • What’s the optimal cache TTL for Cloudflare IPs in your environment? (Default: 24h may be too long for dynamic IPs.)
4. Fallback Behavior:
   • Should the app fall back to the original TrustProxies if Cloudflare IPs fail to load? (Configurable via laravelcloudflare.enabled.)
5. Monitoring:
   • How will you monitor for stale Cloudflare IPs or middleware failures? (e.g., log TrustProxies errors, track CF-Connecting-IP vs. REMOTE_ADDR mismatches.)

Integration Approach

Stack Fit

• Laravel-Centric: Designed exclusively for Laravel, leveraging its middleware, caching, and service container. No framework-agnostic abstractions are needed.
• PHP Version Compatibility: Supports PHP 8.1+ (as of v4.x). Ensure your stack meets this requirement.
• Cloudflare-Specific: Optimized for Cloudflare’s IP ranges and headers (e.g., CF-Connecting-IP). Not suitable for other CDNs (e.g., CloudFront, Fastly) without modification.

Migration Path

1. Assessment Phase:
   • Audit existing trusted_proxies in config/app.php or .env (e.g., TRUSTED_PROXIES="192.168.1.0/24").
   • Identify middleware relying on TrustProxies (e.g., custom IP validation logic).
2. Staging Integration:
   • Install the package in a staging environment:

     composer require monicahq/laravel-cloudflare
     

   • Replace TrustProxies middleware in bootstrap/app.php:

     ->withMiddleware(function (Middleware $middleware) {
         $middleware->replace(
             \Illuminate\Http\Middleware\TrustProxies::class,
             \Monicahq\Cloudflare\Http\Middleware\TrustProxies::class
         );
     })
     

   • Publish config (optional):

     php artisan vendor:publish --provider="Monicahq\Cloudflare\TrustedProxyServiceProvider"
     

3. Testing:
   • Unit Tests: Verify request()->ip() returns CF-Connecting-IP for Cloudflare requests.
   • Integration Tests: Test IP-based features (e.g., ThrottleRequests, geo-blocking) with Cloudflare traffic.
   • Load Testing: Simulate traffic spikes to validate cache performance.
4. Production Rollout:
   • Schedule cloudflare:reload in routes/console.php:

     Schedule::command('cloudflare:reload')->daily();
     

   • Monitor logs for TrustProxies errors or IP mismatches.

Compatibility

• Laravel Versions: Use the branch matching your Laravel version (e.g., 4.x for Laravel 13). Avoid mixing branches.
• Cloudflare Plan: Works with all Cloudflare plans (Free, Pro, Enterprise). Enterprise may need custom proxy callbacks for private networks.
• Existing Middleware: Conflicts unlikely if other middleware doesn’t assume TrustProxies behavior. Test with:
  • ThrottleRequests
  • GeoBlock (e.g., spatie/laravel-geo-blocking)
  • Custom IP validation middleware.

Sequencing

1. Pre-requisite: Ensure Cloudflare is properly configured as a proxy for the Laravel app (not "Under Attack" mode).
2. Order of Operations:
   • Install package → Replace middleware → Publish config (if needed) → Schedule cache refresh → Test.
3. Rollback Plan:
   • Revert middleware replacement to restore TrustProxies if issues arise.
   • Temporarily disable the package via .env:

     LARAVEL_CLOUDFLARE_ENABLED=false
     

Operational Impact

Maintenance

• Cache Management:
  • Proactive: Schedule cloudflare:reload daily or post-deployment.
  • Reactive: Monitor artisan cloudflare:view for IP changes or use Cloudflare’s API webhooks to trigger updates.
• Configuration:
  • Minimal ongoing maintenance. Only update if:
    • Laravel version requires a new package branch.
    • Cloudflare’s IP ranges change significantly (rare).
• Dependency Updates:
  • Monitor for new package versions (e.g., Laravel 14 support). Test updates in staging.

Support

• Troubleshooting:
  • Stale IPs: Run php artisan cloudflare:reload manually or adjust the cache TTL in config/laravelcloudflare.php.
  • Middleware Failures: Check Laravel logs for TrustProxies errors. Verify Cloudflare headers (CF-Connecting-IP) are present.
  • IP Mismatches: Compare request()->ip() with request()->header('CF-Connecting-IP') in logs.
• Documentation:
  • Package README is comprehensive but lacks advanced scenarios (e.g., hybrid proxy setups). Supplement with internal runbooks.
• Vendor Support:
  • MIT-licensed; community-driven. No SLA. Rely on GitHub issues for bugs or feature requests.

Scaling

• Performance:
  • Cache: Pre-fetch Cloudflare IPs during deployments to avoid runtime delays.
  • High Traffic: The package is stateless and lightweight. No known bottlenecks at scale.
• Horizontal Scaling:
  • Works seamlessly in multi-server environments (e.g., Kubernetes, ECS) as long as Cloudflare IPs are cached locally.
• Edge Cases:
  • IPv6: Test with IPv6 traffic if enabled in Cloudflare.
  • Shared Hosting: Ensure PHP’s allow_url_fopen is enabled for IP fetching (default: uses Laravel’s HTTP client).

Failure Modes