Relay Mono Connector Generic Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require dbp/relay-mono-connector-generic-bundle
   

2. Register Bundles Update config/bundles.php to include:

   return [
       // ...
       Dbp\Relay\MonoBundle\DbpRelayMonoBundle::class => ['all' => true],
       Dbp\Relay\MonoConnectorGenericBundle\DbpRelayMonoConnectorGenericBundle::class => ['all' => true],
       Dbp\Relay\CoreBundle\DbpRelayCoreBundle::class => ['all' => true],
   ];
   

3. Clear Cache

   php bin/console cache:clear
   

4. Create Config File Generate a minimal config at config/packages/dbp_relay_mono_connector_generic.yaml:

   dbp_relay_mono_connector_generic: {}
   

First Use Case: Relay API Gateway Integration

To send a test request via Relay’s Mono API:

use Dbp\Relay\MonoConnectorGenericBundle\Service\RelayMonoConnector;

class PaymentController extends AbstractController
{
    public function __invoke(RelayMonoConnector $connector)
    {
        $response = $connector->sendRequest(
            'POST',
            '/mono/payments',
            ['amount' => 100, 'currency' => 'EUR'],
            ['Authorization' => 'Bearer YOUR_RELAY_API_KEY']
        );

        return $this->json($response);
    }
}

Implementation Patterns

Core Workflows

1. Request Handling Use the RelayMonoConnector service to interact with Relay’s Mono API:

   $connector->sendRequest(
       string $method,
       string $endpoint,
       array $data = [],
       array $headers = []
   );
   

   • Example: Initiate a payment:

     $connector->sendRequest('POST', '/mono/payments', [
         'amount' => 5000, // cents
         'currency' => 'EUR',
         'reference' => 'ORDER_123',
     ]);
     

2. Webhook Validation Validate incoming Relay webhooks using the RelayMonoWebhookValidator:

   use Dbp\Relay\MonoConnectorGenericBundle\Validator\RelayMonoWebhookValidator;
   
   $validator = new RelayMonoWebhookValidator();
   $isValid = $validator->validate(
       $rawPayload,
       $signatureHeader,
       'YOUR_WEBHOOK_SECRET'
   );
   

3. Event-Driven Integration Subscribe to Relay events via Symfony’s event dispatcher:

   # config/services.yaml
   services:
       App\EventListener\RelayMonoEventListener:
           tags:
               - { name: kernel.event_listener, event: relay.mono.payment.created, method: onPaymentCreated }
   

Integration Tips

• Dependency Injection: Prefer injecting RelayMonoConnector over instantiating it directly.
• Configuration: Extend dbp_relay_mono_connector_generic.yaml for:

  dbp_relay_mono_connector_generic:
      api_base_url: 'https://api.relay.example.com' # Override default
      timeout: 30 # Seconds
  

• Logging: Enable debug mode for detailed API logs:

  dbp_relay_mono_connector_generic:
      debug: true
  

Gotchas and Tips

Pitfalls

1. Authentication

   • Issue: Missing or incorrect Authorization headers cause 401 Unauthorized errors.
   • Fix: Always include the Relay API key in headers:

     $headers = ['Authorization' => 'Bearer ' . config('services.relay.api_key')];
     

2. Webhook Signatures

   • Issue: Webhook payloads may fail validation if the X-Relay-Signature header is malformed.
   • Fix: Verify the secret matches the one configured in Relay’s dashboard.

3. Rate Limiting

   • Issue: Relay may throttle requests if timeout or retry logic is misconfigured.
   • Fix: Set reasonable timeouts and implement exponential backoff:

     dbp_relay_mono_connector_generic:
         timeout: 10
         max_retries: 3
     

4. Idempotency

   • Issue: Duplicate requests may cause unintended side effects (e.g., double payments).
   • Fix: Use Relay’s idempotency_key parameter:

     $connector->sendRequest('POST', '/mono/payments', [
         'amount' => 1000,
         'idempotency_key' => uniqid(),
     ]);
     

Debugging

• Enable Debug Mode: Set debug: true in config to log raw API responses.
• Check Events: Use Symfony’s profiler to inspect dispatched relay.mono.* events.
• Test Locally: Mock the RelayMonoConnector in tests:

  $this->mock(RelayMonoConnector::class)
       ->shouldReceive('sendRequest')
       ->once()
       ->andReturn(['status' => 'success']);
  

Extension Points

1. Custom Responses Extend the RelayMonoResponse class to add domain-specific logic:

   class CustomRelayMonoResponse extends RelayMonoResponse
   {
       public function isPaymentSuccessful(): bool
       {
           return $this->getData()['status'] === 'completed';
       }
   }
   

2. Middleware Add request/response middleware via Symfony’s kernel.request/kernel.response events:

   public function onKernelRequest(GetResponseEvent $event)
   {
       $request = $event->getRequest();
       if ($request->attributes->get('_route') === 'relay_mono_webhook') {
           $request->headers->set('X-Custom-Header', 'value');
       }
   }
   

3. Configuration Overrides Dynamically override settings per environment:

   # config/packages/dev/dbp_relay_mono_connector_generic.yaml
   dbp_relay_mono_connector_generic:
       debug: true
       api_base_url: 'https://sandbox.relay.example.com'