Nyholm Bridge Laravel Package

Getting Started

1. Install the package via Composer:

   composer require spiral/nyholm-bridge
   

2. Register the bridge in your Spiral application (typically in app/config/app.php or via bootstrapping logic), importing Nyholm’s factories into Spiral’s DI container:

   use Nyholm\Psr7\Factory\Psr17Factory;
   use Spiral\NyholmBridge\NyholmBridge;
   
   $bridge = new NyholmBridge(new Psr17Factory());
   $bridge->register($app);
   

3. First use case: Integrate Nyholm-backed PSR-7/PSR-17 implementations into your middleware or controllers. For example, inject Psr\Http\Message\ServerRequestInterface or Psr\Http\Message\ResponseFactoryInterface and let the bridge handle instantiation.

Implementation Patterns

• Middleware Interception: Use PSR-7/17 types directly in middleware without manual message creation — e.g., mutate ServerRequestInterface or return ResponseInterface from Nyholm using type-hinted factories.
• Testing with Mocks: Replace Nyholm factories with test doubles (e.g., in unit tests) by binding custom Psr17Factory implementations, enabling predictable HTTP mocking.
• Hybrid Migration: During codebase transitions (e.g., from Spiral-native HTTP to PSR-compliant stacks), wire Nyholm as the default message factory while maintaining legacy Spiral components via bridge adapters.
• Tooling Compatibility: Plug in PSR-7-aware libraries (e.g., ringcentral/psr7, slimphp/Slim-Psr7) safely — Nyholm is battle-tested and lightweight, reducing incompatibility risks.

Gotchas and Tips

• Factory duplication risk: Avoid mixing multiple PSR-17 factory implementations — ensure only one Psr17Factory is registered (Nyholm) to prevent inconsistent message instances.
• Legacy Spiral behaviors: Some Spiral versions inject custom request classes (e.g., Spiral\Http\Request) — the bridge overrides these only after registration. Ensure it’s registered early in the container setup.
• Nyholm is not PSR-15 compliant: The bridge does not convert PSR-15 middleware to PSR-15. You still need explicit adapters if using older Spiral middleware stacks.
• No auto-detection: You must explicitly instantiate and register NyholmBridge; it doesn’t auto-discover or fallback silently.
• Last updated in 2022: Verify compatibility with newer Nyholm versions (^1.5+), and confirm PHP version support (tested up to 8.1 at time of release).