Omnipay Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle & Omnipay Gateway

   composer require creatortsv/omnipay-manager-bundle
   composer require <vendor>/omnipay-<gateway>  # e.g., omnipay/stripe
   

2. Create a Custom Adapter Extend OmnipayGatewayAdapter and define getOmnipayGatewayAlias():

   // src/Adapter/KuberacoAdapter.php
   namespace App\Adapter;
   
   use Creatortsv\OmnipayManagerBundle\Adapter\OmnipayGatewayAdapter;
   
   class KuberacoAdapter extends OmnipayGatewayAdapter
   {
       public static function getOmnipayGatewayAlias(): string
       {
           return 'Kuberaco'; // Must match Omnipay gateway name
       }
   
       // Override methods to standardize behavior (e.g., `createPayment()`)
   }
   

3. Use the GatewayManager Inject GatewayManager into a service/controller:

   use Creatortsv\OmnipayManagerBundle\GatewayManager;
   
   class PaymentService
   {
       public function __construct(private GatewayManager $manager) {}
   
       public function processPayment(string $gatewayAlias, array $data)
       {
           $gateway = $this->manager->get($gatewayAlias);
           return $gateway->createPayment($data);
       }
   }
   

Implementation Patterns

1. Standardizing Gateway Interactions

• Unified Methods: Override adapter methods (e.g., createPayment(), completePurchase()) to abstract gateway-specific logic.

  class StripeAdapter extends OmnipayGatewayAdapter
  {
      public function createPayment(array $params)
      {
          return $this->getOmnipayGateway()
              ->purchase($params['amount'], $params['currency']);
      }
  }
  

• Parameter Normalization: Convert input data to Omnipay’s expected format in adapters.

2. Dependency Injection

• Inject Services: Use Laravel’s DI to pass services (e.g., Logger, HttpClient) to adapters:

  class PayPalAdapter extends OmnipayGatewayAdapter
  {
      public function __construct(private LoggerInterface $logger) {}
  
      public function createPayment(array $params)
      {
          $this->logger->info('Processing PayPal payment', $params);
          return $this->getOmnipayGateway()->purchase($params['amount'], $params['currency']);
      }
  }
  

• Configure via config/services.php:

  'omnipay_manager.adapters.kuberaco' => [
      'api_key' => env('KUBERACO_API_KEY'),
      'timeout' => 30,
  ],
  

3. Dynamic Gateway Selection

• Runtime Resolution: Use the GatewayManager to switch gateways dynamically:

  $gateway = $this->manager->get($request->get('gateway'));
  $response = $gateway->authorize($data);
  

4. Testing

• Mock Adapters: Replace adapters with mocks in tests:

  $this->app->instance(
      \Creatortsv\OmnipayManagerBundle\GatewayManager::class,
      $this->createMockGatewayManager()
  );
  

Gotchas and Tips

Pitfalls

1. Gateway Alias Mismatch

   • Ensure getOmnipayGatewayAlias() returns the exact Omnipay gateway name (e.g., 'Stripe' not 'stripe').
   • Fix: Check Omnipay’s supported gateways.

2. Lazy Loading Issues

   • Adapters aren’t instantiated until GatewayManager::get() is called. If you inject GatewayManager but never call get(), adapters won’t initialize.
   • Fix: Call get() early in your workflow or use dump($manager->getAvailableGateways()) to trigger initialization.

3. Omnipay Version Conflicts

   • The bundle assumes Omnipay is installed. Conflicts may arise if multiple versions are pulled in.
   • Fix: Pin Omnipay version in composer.json:

     "require": {
         "omnipay/omnipay": "^3.2"
     }
     

4. HTTP Client Overrides

   • Custom getHttpClient()/getHttpRequest() may break gateway-specific requirements (e.g., Stripe’s API expects application/x-www-form-urlencoded).
   • Fix: Test thoroughly with the target gateway’s API docs.

Debugging Tips

• Enable Omnipay Logging Configure Omnipay’s logger in your adapter:

  $this->getOmnipayGateway()->setLogger(new \Monolog\Logger('omnipay'));
  

  Or use Laravel’s logging:

  $this->getOmnipayGateway()->setLogger(new \Omnipay\Common\Logger\LoggableTrait());
  

• Inspect Raw Requests Dump the Omnipay request object before sending:

  $request = $this->getOmnipayGateway()->purchase($amount, $currency);
  \Log::debug('Omnipay Request Data', $request->getData());
  

• Gateway-Specific Errors Wrap Omnipay calls in try-catch to handle gateway-specific exceptions:

  try {
      $response = $gateway->createPayment($data);
  } catch (\Omnipay\Common\Exception\InvalidRequestException $e) {
      \Log::error('Invalid request: ' . $e->getMessage());
      throw new \RuntimeException('Payment failed: Invalid parameters');
  }
  

Extension Points

1. Custom Gateway Logic Extend OmnipayGatewayAdapter to add pre/post-processing:

   class CustomAdapter extends OmnipayGatewayAdapter
   {
       public function createPayment(array $params)
       {
           $params = $this->preProcessParams($params);
           $response = parent::createPayment($params);
           return $this->postProcessResponse($response);
       }
   }
   

2. Middleware for Requests Override getHttpRequest() to add headers/auth:

   public function getHttpRequest(\Psr\Http\Message\RequestInterface $request)
   {
       $request = parent::getHttpRequest($request);
       return $request->withHeader('X-Custom-Header', 'value');
   }
   

3. Webhook Handling Use the bundle to validate webhook signatures:

   $gateway = $this->manager->get('Stripe');
   $response = $gateway->completePurchase($webhookData);
   if ($response->isSuccessful()) {
       // Process webhook
   }