Callable Handler Laravel Package

Product Decisions This Supports

• Middleware Standardization: Enables seamless integration of PSR-7 (HTTP message interfaces) and PSR-15 (middleware) components, reducing fragmentation in PHP-based HTTP stacks (e.g., Laravel, Slim, Symfony).
• Legacy System Modernization: Allows incremental adoption of PSR-15 middleware in older PHP 7.1+ applications without full refactoring, lowering technical debt.
• Vendor Agnosticism: Decouples middleware logic from framework-specific implementations (e.g., Laravel’s Illuminate\Http\Request), improving portability for microservices or multi-framework projects.
• Performance Optimization: Supports double-pass middleware (e.g., for request/response transformations), enabling use cases like:
  • Caching layers (e.g., Stash).
  • Rate limiting with pre/post-processing.
  • Cross-cutting concerns (logging, auth) without duplicating logic.
• Roadmap Flexibility:
  • Build vs. Buy: Justifies not building a custom middleware adapter if PSR compliance is a priority.
  • Tech Debt Reduction: Replaces ad-hoc middleware patterns (e.g., closures, custom traits) with standardized interfaces.
• Use Cases:
  • API gateways (e.g., Laravel + PSR-15 middleware for validation/routing).
  • Headless CMS or SaaS platforms needing middleware for feature flags or A/B testing.
  • Serverless functions (e.g., AWS Lambda with PHP) requiring middleware-like preprocessing.

When to Consider This Package

• Adopt When:

  • Your stack uses PSR-7 (e.g., nyholm/psr7, zend-diactoros) but lacks PSR-15 middleware support.
  • You need double-pass middleware (e.g., for request/response manipulation) without framework bloat.
  • Migrating from Laravel’s Closure-based middleware to PSR-15 for better testability/reusability.
  • PHP version is 7.1+ (min requirement) and you’re not locked into PHP 8.1+ features.
  • You prioritize interoperability over framework-specific optimizations (e.g., Symfony’s HttpKernel).

• Look Elsewhere If:

  • Your project is framework-agnostic and already uses a PSR-15-compliant router (e.g., mezzio/mezzio).
  • You need advanced middleware features (e.g., async support, PSR-17 factories) beyond PSR-15’s scope.
  • Your team lacks PHP middleware experience; consider Laravel’s built-in middleware for simplicity.
  • You’re using PHP 8.2+ and need attributes-based middleware (e.g., Symfony 6+); this package is pre-attributes.
  • Your use case requires stateful middleware (e.g., request-scoped containers), which PSR-15 intentionally avoids.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us standardize how our PHP services handle HTTP requests/responses—like a ‘middleware translator’ that works across frameworks. It’s a lightweight way to modernize legacy systems (e.g., Laravel APIs) without rewriting core logic. Think of it as upgrading from VHS to Blu-ray for middleware: same content, but better compatibility and future-proofing. Low risk (MIT license, minimal PHP 7.1 requirement), high reward for tech debt reduction and cross-team reuse."

For Engineering:

*"Problem: Our middleware is a mix of Laravel closures, custom traits, and PSR-7 components—hard to test, port, or extend. Solution: tuupola/callable-handler bridges PSR-7 and PSR-15, letting us:

• Unify middleware under one standard (PSR-15) while keeping PSR-7 compatibility.
• Add double-pass logic (e.g., pre/post-processing) without framework hacks.
• Swap frameworks (e.g., move from Laravel to Slim) with minimal changes. Tradeoffs:
• No PHP 8.2+ features (attributes, enums).
• Minimal adoption (0 dependents), but PSR-compliance is battle-tested. Next Steps:

1. Benchmark against Laravel’s native middleware for performance.
2. Pilot in a non-critical service (e.g., admin panel).
3. Align with our PSR-15 migration roadmap."*

Key Selling Point: "It’s the ‘duct tape’ for middleware—simple, standards-based, and just enough to avoid reinventing the wheel."