Payment Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ekyna/payment-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+):

   Ekyna\PaymentBundle\EkynaPaymentBundle::class => ['all' => true],
   

2. Publish Config:

   php artisan vendor:publish --provider="Ekyna\PaymentBundle\EkynaPaymentBundle" --tag=config
   

   This generates config/payment.php with default gateways (e.g., PayPal, Stripe).

3. First Use Case: Define a payment method in your controller:

   use Ekyna\PaymentBundle\Payment\PaymentGatewayInterface;
   
   public function processPayment(Request $request, PaymentGatewayInterface $gateway)
   {
       $payment = $gateway->createPayment([
           'amount' => 100.00,
           'currency' => 'USD',
           'description' => 'Order #12345',
           'method' => 'paypal', // Configured in payment.php
       ]);
       return $payment->execute();
   }
   

Implementation Patterns

Core Workflows

1. Gateway Integration:

   • Configure gateways in config/payment.php:

     'gateways' => [
         'paypal' => [
             'class' => 'Ekyna\PaymentBundle\Payment\Gateway\PayPalGateway',
             'options' => [
                 'api_username' => env('PAYPAL_API_USERNAME'),
                 // ... other PayPal credentials
             ],
         ],
     ],
     

   • Inject PaymentGatewayInterface into services/controllers for flexibility.

2. Payment Lifecycle:

   • Create: $gateway->createPayment($data) → Returns a Payment object.
   • Execute: $payment->execute() → Triggers the gateway’s logic.
   • Refund: $payment->refund($amount) → If supported by the gateway.

3. Event-Driven Extensions:

   • Listen to payment.created, payment.succeeded, or payment.failed events:

     // In a service provider
     $this->app->booted(function () {
         event(new PaymentCreated($payment));
     });
     

4. Form Integration:

   • Use the bundle’s payment_form Twig helper to generate gateway-specific forms:

     {{ payment_form('paypal', payment) }}
     

Advanced Patterns

• Custom Gateways: Implement PaymentGatewayInterface and register it in config/payment.php:

  'custom_gateway' => [
      'class' => 'App\Payment\CustomGateway',
      'options' => [...],
  ],
  

• Payment Models: Extend Ekyna\PaymentBundle\Model\Payment to add domain-specific fields:

  class OrderPayment extends Payment
  {
      protected $orderId;
  }
  

• Webhook Handling: Use the PaymentWebhookListener to process gateway callbacks:

  $listener = new PaymentWebhookListener($gateway);
  $listener->handle($request->getContent());
  

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • Last release in 2015—expect missing PHP 8+ compatibility. Test thoroughly or fork.
   • No active maintenance; verify gateways (e.g., PayPal/Stripe APIs) aren’t deprecated.

2. Configuration Quirks:

   • Missing TODO in README: Assume config/payment.php requires manual setup (no defaults for credentials).
   • Gateway Auto-Wiring: If using Symfony’s autowiring, explicitly bind interfaces to implementations in config/services.php:

     PaymentGatewayInterface::class => \Ekyna\PaymentBundle\Payment\Gateway\PayPalGateway::class,
     

3. Event System:

   • Events are not documented. Inspect src/Event/ for available events (e.g., PaymentEvent).

4. Database Schema:

   • The bundle expects a payments table. Run migrations manually if not auto-generated:

     php artisan vendor:publish --provider="Ekyna\PaymentBundle\EkynaPaymentBundle" --tag=migrations
     

Debugging Tips

• Gateway Failures: Enable debug mode in config/payment.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Webhook Testing: Use the PaymentWebhookListener with a test payload:

  $listener->handle(json_encode([
      'ipn_track_id' => '123', // PayPal example
      'mc_gross' => '100.00',
  ]));
  

Extension Points

1. Override Payment Model: Bind your custom model in config/payment.php:

   'model' => App\Models\OrderPayment::class,
   

2. Add Custom Fields: Extend the Payment entity and update the migration:

   class OrderPayment extends Payment
   {
       protected $userId;
   }
   

3. Gateway-Specific Logic: Override gateway methods (e.g., execute()) by creating a decorator:

   class CustomPayPalGateway extends PayPalGateway
   {
       public function execute(Payment $payment)
       {
           // Add custom logic
           return parent::execute($payment);
       }
   }
   

   Register it in config/payment.php.

4. Testing: Use the PaymentGatewayInterface mock in PHPUnit:

   $mockGateway = $this->createMock(PaymentGatewayInterface::class);
   $mockGateway->method('createPayment')->willReturn(new Payment());