## Getting Started

### Minimal Setup
1. **Installation**
   Add the bundle via Composer:
   ```bash
   composer require dbp/relay-proxy-bundle

Enable it in config/bundles.php:

return [
    // ...
    DigitalBlueprint\RelayProxyBundle\DbpRelayProxyBundle::class => ['all' => true],
];

Configuration Publish the default config:
```
php artisan vendor:publish --tag=relay-proxy-config
```
Edit config/relay_proxy.php to define your API gateway routes, proxied endpoints, and middleware.

First Use Case: Proxying a Simple API Define a route in config/relay_proxy.php:

'routes' => [
    'api/v1/users' => [
        'target' => 'https://external-api.example.com/users',
        'methods' => ['GET', 'POST'],
        'middleware' => ['auth.api', 'throttle:60'],
    ],
],

Now, requests to /api/v1/users will be proxied to the external API with the specified middleware applied.

Implementation Patterns

Core Workflow: Proxying with Middleware

Route Definition Use the config/relay_proxy.php to map Laravel routes to external endpoints:

'routes' => [
    'graphql' => [
        'target' => 'https://graphql.example.com',
        'methods' => ['POST'],
        'transform_request' => DigitalBlueprint\RelayProxyBundle\Transformer\RequestTransformer::class,
        'transform_response' => DigitalBlueprint\RelayProxyBundle\Transformer\ResponseTransformer::class,
    ],
],

Middleware Integration Leverage Laravel’s middleware stack for pre/post-processing:

'middleware' => [
    'auth:api',
    'throttle:100,1', // 100 requests per minute
    DigitalBlueprint\RelayProxyBundle\Http\Middleware\LogProxyRequest::class,
],

Request/Response Transformation Extend the bundle’s transformer classes to modify payloads:

namespace App\Transformers;

use DigitalBlueprint\RelayProxyBundle\Transformer\AbstractTransformer;

class CustomRequestTransformer extends AbstractTransformer {
    public function transform($request) {
        $request->merge(['api_key' => config('services.external_api.key')]);
        return $request;
    }
}

'transform_request' => App\Transformers\CustomRequestTransformer::class,

Dynamic Routing Use route parameters to dynamically construct proxy targets:

'routes' => [
    'api/v1/products/{id}' => [
        'target' => 'https://external-api.example.com/products/{id}',
        'methods' => ['GET'],
    ],
],

Advanced Patterns

Caching Responses Cache proxied responses using Laravel’s cache system:

'cache' => [
    'enabled' => true,
    'ttl' => 300, // 5 minutes
    'prefix' => 'relay_proxy_',
],

Rate Limiting Combine with Laravel’s throttle middleware to limit external API calls:
```
'middleware' => ['throttle:external_api,5'], // 5 requests per minute
```

Webhook Handling Proxy webhook requests to internal services:

'webhooks' => [
    'stripe' => [
        'target' => 'https://internal-service.example.com/webhooks/stripe',
        'secret' => config('services.stripe.webhook_secret'),
        'verify_signature' => true,
    ],
],

Gotchas and Tips

Common Pitfalls

CORS Issues If the proxied API enforces CORS, ensure your Laravel app includes the correct headers:

'headers' => [
    'Access-Control-Allow-Origin' => '*',
    'Access-Control-Allow-Methods' => 'GET, POST, PUT, DELETE',
],

Middleware Order Middleware defined in config/relay_proxy.php runs after Laravel’s global middleware but before route-specific middleware. Adjust order if needed:

// In RouteServiceProvider
public function boot() {
    $this->app['router']->pushMiddlewareToGroup('web', \App\Http\Middleware\CustomProxyMiddleware::class);
}

SSL/TLS Verification Disable SSL verification only if absolutely necessary (e.g., for internal APIs):
```
'client_options' => [
    'verify' => false, // Not recommended for production
],
```
Route Conflict Avoid naming conflicts with existing Laravel routes. Prefix proxied routes (e.g., /proxy/api/v1/...).
Large Payloads For large requests/responses, increase PHP’s limits in php.ini:
```
post_max_size = 256M
max_execution_time = 300
```

Debugging Tips

Log Proxy Requests Enable logging in config/relay_proxy.php:
```
'debug' => [
    'log_requests' => true,
    'log_responses' => true,
],
```
Check logs in storage/logs/laravel.log.

Test Locally Use curl to test proxy behavior:

curl -X GET http://your-app.test/api/v1/proxied-endpoint -v

Inspect HTTP Clients The bundle uses Symfony’s HttpClient. Customize it in config:

'client_options' => [
    'headers' => ['User-Agent' => 'Laravel-Relay-Proxy/1.0'],
    'timeout' => 30,
],

Extension Points

Custom HTTP Clients Override the default client by binding your own:

// In a service provider
$this->app->bind(\Symfony\Contracts\HttpClient\HttpClientInterface::class, function () {
    return \Symfony\Contracts\HttpClient\HttpClient::create([
        'base_uri' => 'https://custom-base.example.com',
    ]);
});

Event Listeners Listen to proxy events (e.g., ProxyRequestSent, ProxyResponseReceived):

// In EventServiceProvider
protected $listen = [
    \DigitalBlueprint\RelayProxyBundle\Events\ProxyRequestSent::class => [
       \App\Listeners\LogProxyRequest::class,
   ],
];

Dynamic Configuration Load proxy routes dynamically (e.g., from a database):

// In a service provider
$this->app->afterResolving(\DigitalBlueprint\RelayProxyBundle\RelayProxyBundle::class, function ($bundle) {
    $bundle->addRoute('dynamic/{id}', [
        'target' => 'https://api.example.com/dynamic/' . request('id'),
    ]);
});

Health Checks Add a health check endpoint for the proxy:

'health_check' => [
    'enabled' => true,
    'route' => '/proxy/health',
    'target' => 'https://external-api.example.com/health',
],

Accessible at /proxy/health to verify proxy connectivity.

---

Relay Proxy Bundle Laravel Package