Getting Started

Minimal Steps

Installation:
```
composer require boson-php/http-bridge
```
Ensure your project uses PHP 8.4+ (Laravel 10/11 compatible).

First Use Case:

Bridge a PSR-18 HTTP client (e.g., Guzzle/Symfony) to a custom interface.

Example: Create a simple HTTP client wrapper using the package’s BridgeInterface:

use Boson\HttpBridge\BridgeInterface;
use Boson\HttpBridge\Psr18Bridge;
use Psr\Http\Client\ClientInterface;

// Bind the bridge to Laravel's container (e.g., in a service provider)
$this->app->bind(BridgeInterface::class, function ($app) {
    $client = new Psr18Bridge($app->make(ClientInterface::class));
    return $client;
});

// Usage in a controller/job
$bridge = app(BridgeInterface::class);
$response = $bridge->sendRequest(new \Psr\Http\Message\Request('GET', 'https://api.example.com'));

Where to Look First:
- Interfaces: BridgeInterface (core contract) and Psr18Bridge (PSR-18 implementation).
- Middleware: Check for HttpBridgeMiddleware or similar for request/response interception.
- Boson Docs: Laravel Adapter Guide (if available).

Implementation Patterns

Usage Patterns

Standardizing HTTP Clients:
- Use BridgeInterface to abstract underlying clients (e.g., Guzzle, Symfony HTTPClient).
- Example: Swap implementations without changing consumer code:
```
// In config/http.php
'bridges' => [
  'default' => Boson\HttpBridge\Psr18Bridge::class,
  'custom'  => App\Bridges\CustomHttpBridge::class,
];
```
Middleware Integration:
- Leverage the package’s middleware support to add cross-cutting concerns (e.g., logging, auth).
- Example: Attach middleware to a bridge instance:
```
$bridge = new Psr18Bridge($client);
$bridge->pushMiddleware(new \Boson\HttpBridge\Middleware\LoggingMiddleware());
```

Request/Response Transformation:

Use the bridge to normalize requests/responses before sending/receiving.

Example: Transform a Laravel Request to PSR-7:

use Boson\HttpBridge\Psr7Converter;

$psrRequest = Psr7Converter::toPsr7($laravelRequest);
$response = $bridge->sendRequest($psrRequest);
$laravelResponse = Psr7Converter::toLaravelResponse($response);

Laravel Service Provider Binding:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton(BridgeInterface::class, function ($app) {
        return new Psr18Bridge(
            $app->make(\Psr\Http\Client\ClientInterface::class)
        );
    });
}

Dynamic Bridge Resolution:
- Resolve bridges dynamically based on configuration or runtime needs:
```
$bridge = app()->make(BridgeInterface::class, ['config' => 'custom']);
```

Workflows

API Client Workflow:

Replace Laravel’s HttpClient with a bridge for external API calls:

$bridge = app(BridgeInterface::class);
$response = $bridge->sendRequest(
    new \Psr\Http\Message\Request('GET', 'https://api.example.com/data')
);
$data = json_decode($response->getBody(), true);

Legacy System Integration:
- Bridge legacy HTTP services (e.g., SOAP/XML-RPC) to modern Laravel apps:
```
$legacyBridge = new LegacyHttpBridge();
$response = $legacyBridge->sendRequest($request);
```

Testing Workflow:

Mock HTTP bridges in tests:

$mockBridge = Mockery::mock(BridgeInterface::class);
$mockBridge->shouldReceive('sendRequest')
    ->once()
    ->andReturn(new \Psr\Http\Message\Response(200, [], 'Mocked'));

$this->app->instance(BridgeInterface::class, $mockBridge);

Integration Tips

Leverage Laravel’s HTTP Stack:

Combine the bridge with Laravel’s HttpClient for hybrid workflows:

$http = new \Illuminate\Http\Client\PendingRequest();
$bridgeResponse = $bridge->sendRequest($http->toPsrRequest());

Facade Support:

Create a Laravel Facade for the bridge (e.g., HttpBridge):

// app/Facades/HttpBridge.php
namespace App\Facades;
use Illuminate\Support\Facades\Facade;
class HttpBridge extends Facade {
    protected static function getFacadeAccessor() { return BridgeInterface::class; }
}

Usage:

$response = \App\Facades\HttpBridge::get('https://api.example.com');

Event-Driven Extensions:

Extend the bridge to emit Laravel events (e.g., HttpBridgeRequestSent):

$bridge->sendRequest($request)->then(function ($response) {
    event(new HttpBridgeResponseReceived($response));
});

Caching Layer:

Add caching middleware to the bridge for repeated requests:

$bridge->pushMiddleware(new \Boson\HttpBridge\Middleware\CacheMiddleware(
    $cache = app(\Illuminate\Cache\CacheManager::class)
));

Gotchas and Tips

Pitfalls

Boson Framework Dependency:
- The package may assume Boson’s DI/event systems. Risk: Laravel’s service container may not align.
- Fix: Check for Boson-specific classes (e.g., Boson\Container) and replace with Laravel equivalents.
PSR Compliance Assumptions:
- The package might expect PSR-18/PSR-7 compliance. Risk: Laravel’s HttpClient or Request objects may need conversion.
- Fix: Use Psr7Converter or similar utilities to bridge gaps.
Middleware Ordering:
- Middleware applied to the bridge may conflict with Laravel’s global middleware.
- Fix: Apply bridge middleware after Laravel’s middleware in the pipeline.

Error Handling:

The package may not handle Laravel-specific exceptions (e.g., HttpException).

Fix: Wrap bridge responses in try-catch blocks:

try {
    $response = $bridge->sendRequest($request);
} catch (\Boson\HttpBridge\Exception\BridgeException $e) {
    throw new \Illuminate\Http\Client\ConnectionException($e->getMessage());
}

Performance Overhead:
- Abstraction layers can add latency. Risk: Unoptimized bridges may slow down API calls.
- Fix: Benchmark against Laravel’s native HttpClient and optimize critical paths.
Testing Complexity:
- Mocking the bridge may require complex setups (e.g., PSR-7 objects).
- Fix: Use Laravel’s MockHttp or Mockery to stub bridge interactions:
```
$this->mock(BridgeInterface::class)->shouldReceive('sendRequest')
    ->andReturn(new \Psr\Http\Message\Response(200, [], '{}'));
```

Debugging

Logging HTTP Bridge Traffic:
- Enable debug logging for the bridge:
```
$bridge->pushMiddleware(new \Boson\HttpBridge\Middleware\DebugMiddleware());
```
- Check Laravel’s logs for bridge activity.

Inspecting Request/Response Objects:

Dump PSR-7 objects to debug issues:

\Log::debug('Bridge Request:', [
    'method' => $request->getMethod(),
    'uri' => (string) $request->getUri(),
    'headers' => $request->getHeaders(),
]);

Common Errors:
- ClassNotFoundException: Missing Boson classes. Solution: Replace with Laravel equivalents.
- RuntimeException: Invalid PSR-7 objects. Solution: Validate objects before passing to the bridge.
- ConnectionException: Network issues. Solution: Check middleware or underlying client (e.g., Guzzle).

Config Quirks

Service Provider Binding:

Ensure the bridge is bound after the underlying HTTP client (e.g., Guzzle):

$this->app->bind(\Psr\Http\Client\ClientInterface::class, function ($app) {
    return new \GuzzleHttp\Client();
});

Middleware Configuration:

Http Bridge Laravel Package