Literato Payment Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require dkrasilnikov/literato-payment-bundle
   

   Publish the bundle configuration (if needed):

   php artisan vendor:publish --provider="LiteratoPaymentBundle\LiteratoPaymentBundleServiceProvider"
   

2. Service Provider & Facade Ensure the bundle is registered in config/app.php under providers:

   LiteratoPaymentBundle\LiteratoPaymentBundleServiceProvider::class,
   

   Use the facade for quick access:

   use LiteratoPaymentBundle\Facades\LiteratoPayment;
   

3. First Use Case: Processing a Payment Initialize a payment gateway (e.g., Stripe) in config/literato_payment.php:

   'gateways' => [
       'stripe' => [
           'key' => env('STRIPE_KEY'),
           'secret' => env('STRIPE_SECRET'),
       ],
   ],
   

   Process a payment in a controller:

   $payment = LiteratoPayment::gateway('stripe')
       ->charge(1000, 'user@example.com', [
           'description' => 'Premium Subscription',
       ]);
   

Implementation Patterns

Core Workflows

1. Gateway Abstraction Use the LiteratoPayment facade to switch between gateways dynamically:

   // Charge via Stripe
   $result = LiteratoPayment::gateway('stripe')->charge(2000, 'user@example.com');
   
   // Charge via PayPal (if configured)
   $result = LiteratoPayment::gateway('paypal')->charge(2000, 'user@example.com');
   

2. Webhook Handling Register a route in routes/web.php:

   Route::post('/payment/webhook', [PaymentWebhookController::class, 'handle']);
   

   Process webhooks in a controller:

   public function handle(Request $request) {
       $event = LiteratoPayment::gateway('stripe')->webhook($request->all());
       // Handle $event (e.g., 'charge.succeeded', 'charge.failed')
   }
   

3. Subscription Management Create a subscription:

   $subscription = LiteratoPayment::gateway('stripe')
       ->subscribe('user@example.com', 1000, [
           'interval' => 'month',
           'trial_days' => 7,
       ]);
   

4. Middleware for Authenticated Payments Protect payment routes with middleware:

   Route::middleware(['auth', 'verified'])->group(function () {
       Route::post('/pay', [PaymentController::class, 'process']);
   });
   

Integration Tips

• Environment Variables: Store sensitive keys (e.g., STRIPE_SECRET) in .env.
• Logging: Enable debug logging in config/literato_payment.php:

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

• Testing: Use mock gateways in tests:

  $this->mock(LiteratoPayment::class)->shouldReceive('gateway')->andReturnSelf();
  

Gotchas and Tips

Pitfalls

1. Missing Configuration

   • Issue: Forgetting to publish the config or set gateway keys in .env.
   • Fix: Run php artisan vendor:publish and verify config/literato_payment.php.

2. Webhook Signature Validation

   • Issue: Unverified webhook payloads may cause security risks.
   • Fix: Enable signature validation in config:

     'webhook' => [
         'validate_signature' => true,
         'secret' => env('STRIPE_WEBHOOK_SECRET'),
     ],
     

3. Currency Mismatch

   • Issue: Charging in incorrect currency (e.g., cents vs. dollars).
   • Fix: Standardize amounts (e.g., always use cents) and document this in your codebase.

4. Idempotency Keys

   • Issue: Duplicate payments if idempotency keys aren’t handled.
   • Fix: Use unique keys for critical operations:

     $payment = LiteratoPayment::gateway('stripe')
         ->charge(1000, 'user@example.com', [
             'idempotency_key' => uniqid(),
         ]);
     

Debugging

• Enable Debug Mode: Set 'debug' => true in config to log raw API responses.
• Check Raw Responses: Access the underlying response object:

  $response = LiteratoPayment::gateway('stripe')->charge(...);
  dd($response->getRawResponse());
  

Extension Points

1. Custom Gateways Extend the AbstractGateway class to support new providers:

   namespace App\Providers;
   
   use LiteratoPaymentBundle\Contracts\GatewayInterface;
   use LiteratoPaymentBundle\AbstractGateway;
   
   class CustomGateway extends AbstractGateway implements GatewayInterface {
       // Implement charge(), webhook(), etc.
   }
   

   Register the gateway in config/literato_payment.php:

   'gateways' => [
       'custom' => [
           'class' => App\Providers\CustomGateway::class,
           'config' => [...],
       ],
   ],
   

2. Event Listeners Listen for payment events (e.g., PaymentCharged, SubscriptionCreated):

   // In EventServiceProvider
   protected $listen = [
       'LiteratoPaymentBundle\Events\PaymentCharged' => [
          'App\Listeners\LogPayment',
      ],
   ];
   

3. Overriding Services Bind custom implementations in AppServiceProvider:

   $this->app->bind(GatewayInterface::class, function ($app) {
       return new App\Providers\CustomGateway();
   });