Psr 18 Guzzle Adapter Laravel Package

Product Decisions This Supports

• Standardization & Interoperability: Enables adoption of PSR-18 across the Laravel ecosystem, ensuring compatibility with modern PHP HTTP standards. This simplifies integration with other PSR-compliant libraries (e.g., middleware, testing tools like Pest, or HTTP clients like Symfony’s).
• Decoupling from Guzzle: Allows teams to abstract Guzzle-specific logic, reducing vendor lock-in and enabling future migrations to alternative PSR-18-compliant clients (e.g., Symfony’s HTTP Client or ReactPHP). This aligns with Laravel’s evolving architecture, particularly in microservices or modular monoliths.
• Testability & Mocking: Facilitates easier HTTP mocking in unit/integration tests by leveraging PSR-18’s standardized interface. This is critical for API-heavy applications where HTTP dependencies are prevalent (e.g., webhooks, third-party integrations).
• Roadmap for API-First Development: Supports Laravel’s shift toward modular HTTP clients, especially in Laravel 10+ where PSR-18 is increasingly emphasized. Ideal for projects building API layers, event-driven architectures, or serverless functions.
• Build vs. Buy Decision: Buy this package to avoid reinventing PSR-18 adapters, but justify adoption with long-term scalability gains. The low maintenance burden (minimal abstraction overhead) makes it a cost-effective choice for teams already using Guzzle.
• Performance Optimization: Enables A/B testing of HTTP clients (e.g., comparing Guzzle vs. Symfony’s client) without rewriting business logic, aiding performance-driven roadmaps.

When to Consider This Package

Adopt if:

• Your Laravel application uses Guzzle but lacks PSR-18 standardization, and you’re planning to scale HTTP-dependent services (e.g., microservices, API gateways).
• You’re building a modular architecture where HTTP clients should be interchangeable (e.g., for testing, performance tuning, or cost optimization).
• Your team prioritizes testability and needs to mock HTTP calls without Guzzle-specific quirks (e.g., for CI/CD pipelines or contract testing).
• You’re adopting PSR-15 middleware or other PSR standards (e.g., PSR-7 for messages) and want consistency across your HTTP layer.
• You’re maintaining legacy Guzzle code but want to incrementally migrate to PSR-18 for future-proofing.
• Your project aligns with Laravel’s long-term roadmap (e.g., Laravel 11+), which may further emphasize PSR-18 compliance.

Look Elsewhere if:

• You’re not using Guzzle (the adapter is redundant; use Laravel’s native Http\Client or another PSR-18 client directly).
• Your team lacks buy-in for PSR-18 adoption, making the ROI of standardization low for short-term projects.
• You need Guzzle-specific features (e.g., advanced middleware like retry queues, event system, or TransferStats) that aren’t exposed via PSR-18. In this case, consider wrapping the adapter with custom middleware or using Guzzle directly.
• Your project is short-lived (e.g., a proof-of-concept) with no plans for refactoring or scaling.
• You’re using Laravel 10+ and can leverage the built-in Http\Client (PSR-18 compliant) without needing Guzzle’s legacy features.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us standardize HTTP requests across our Laravel applications using PSR-18, a modern PHP standard. By wrapping Guzzle behind this interface, we unlock flexibility to swap clients later—reducing technical debt and easing testing. It’s a low-risk move with high long-term payoff, especially for our API-heavy services and microservices roadmap. The minimal upfront cost (just a Composer install) pays off in maintainability and scalability."

Key Outcomes:

• Future-proof architecture: Avoid vendor lock-in to Guzzle.
• Faster development: Standardized HTTP layer speeds up onboarding and reduces bugs.
• Cost savings: Easier to optimize performance or costs by switching clients (e.g., to Symfony’s HTTP Client).

For Engineers:

*"By adopting this PSR-18 adapter for Guzzle, we gain:

• Easier testing: Mock HTTP calls with PSR-18 interfaces instead of Guzzle-specific classes, cutting test flakiness.
• Vendor agility: Swap Guzzle for another PSR-18 client (e.g., Symfony’s) without rewriting business logic.
• Cleaner code: PSR-18’s explicit methods (e.g., sendRequest()) are more readable than Guzzle’s fluent interface.
• Laravel alignment: Prepares us for Laravel’s future emphasis on PSR-18 (e.g., Laravel 11+).

Tradeoffs:

• Limited Guzzle features: Some middleware or events won’t translate 1:1 to PSR-18 (we can layer custom solutions on top).
• Learning curve: Team members new to PSR-18 will need to adjust to the interface (but it’s worth it for long-term gains)."*

Action Items:

1. Start by using the adapter in new HTTP services (not legacy code).
2. Update tests to mock ClientInterface instead of GuzzleHttp\Client.
3. Gradually refactor Guzzle-specific logic to PSR-18 where possible.

For Architects:

*"This adapter supports our goal of decoupled, testable HTTP clients in Laravel. Here’s how it fits our roadmap:

• Microservices: Enables interchangeable HTTP clients for different services (e.g., Guzzle for legacy, Symfony’s client for new services).
• Testing: Critical for our contract-testing strategy (e.g., mocking third-party APIs).
• Performance: Allows us to benchmark clients (e.g., Guzzle vs. Symfony) without rewriting code.
• PSR Ecosystem: Aligns with our adoption of PSR-15 middleware and PSR-7 messages.

Recommendation:

• Use this for new projects or HTTP-heavy services.
• Pair with Laravel’s Http\Client for projects not tied to Guzzle.
• Avoid for highly customized Guzzle setups (e.g., complex middleware chains) unless we build wrappers.

Risk Mitigation:

• Start with a pilot project (e.g., a new API service) to validate the adapter’s fit.
• Document Guzzle-specific gaps (e.g., event system) and plan custom solutions if needed."*

For QA/Test Engineers:

*"This adapter will supercharge our testing by:

• Mocking HTTP calls: Use Mockery or PHPUnit to stub ClientInterface instead of Guzzle, reducing flaky tests.
• Isolated environments: Test API integrations without hitting real endpoints (e.g., for webhooks or payment gateways).
• Consistent interfaces: No more Guzzle-specific test doubles—just PSR-18 standards.

How to Leverage It:

1. Replace GuzzleHttp\Client with ClientInterface in test doubles.
2. Use PsrTest\Psr18\MockClient (or similar) for pre-built mocks.
3. Focus on behavioral tests (e.g., ‘when the API returns 500, retry 3 times’) instead of implementation details.

Example:

// Before (Guzzle-specific)
$mock = Mockery::mock(GuzzleHttp\Client::class);
$mock->shouldReceive('request')->andReturn(...);

// After (PSR-18)
$mock = Mockery::mock(ClientInterface::class);
$mock->shouldReceive('sendRequest')->andReturn(...);
```"*

---
### **For DevOps/Cloud Engineers:**
*"This adapter has **minimal operational impact** but enables:
- **Client flexibility**: Easily switch HTTP clients in different environments (e.g., Guzzle in dev, Symfony’s client in production).
- **Consistent logging**: PSR-18 responses are easier to normalize for monitoring (e.g., Laravel Horizon logs).
- **CI/CD optimizations**: Faster tests due to mockable HTTP layers.

**Considerations:**
- **No runtime overhead**: The adapter adds <1% latency (verified in benchmarks).
- **Guzzle updates**: Isolate Guzzle-specific changes behind the adapter to reduce deployment risks.
- **Middleware**: If using Guzzle middleware (e.g., retries), ensure it’s compatible with PSR-18 or refactor it."*

---