Paypalbridgebundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require alessandrolandim/paypalbridgebundle
   

   (Note: The package name in the README is outdated; use alessandrolandim/paypalbridgebundle as per composer.json.)

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 2/3):

   // config/bundles.php
   return [
       // ...
       Alessandrolandim\PayPalBridgeBundle\AlessandrolandimPayPalBridgeBundle::class => ['all' => true],
   ];
   

3. Configure: Create config/packages/kmj_paypal_bridge.yaml (Symfony 4+) or app/config/config.yml (Symfony 2/3):

   kmj_pay_pal_bridge:
       environment: sandbox  # or 'production'
       sandbox:
           clientId: "%env(PAYPAL_SANDBOX_CLIENT_ID)%"
           secret: "%env(PAYPAL_SANDBOX_SECRET)%"
       production:
           clientId: "%env(PAYPAL_PROD_CLIENT_ID)%"
           secret: "%env(PAYPAL_PROD_SECRET)%"
       logs:
           enabled: true
           filename: "%kernel.logs_dir%/paypal.log"
           level: fine
   

4. First Use Case: Inject the service and create a payment:

   use PayPal\Api\Amount;
   use PayPal\Api\Transaction;
   use PayPal\Api\Payer;
   use PayPal\Api\Payment;
   
   class PaymentController extends AbstractController
   {
       public function createPayment(Alessandrolandim\PayPalBridgeBundle\Service\PayPalService $paypal)
       {
           $amount = new Amount();
           $amount->setCurrency('USD')->setTotal('10.00');
   
           $transaction = new Transaction();
           $transaction->setAmount($amount)->setDescription('Test Payment');
   
           $payer = new Payer();
           $payer->setPaymentMethod('paypal');
   
           $payment = new Payment();
           $payment->setIntent('sale')->setPayer($payer)->setTransactions([$transaction]);
   
           $createdPayment = $paypal->createPayment($payment);
           return $this->json($createdPayment);
       }
   }
   

Implementation Patterns

Common Workflows

1. Environment-Aware Operations: Use the bundle’s auto-switching between sandbox/production:

   // Automatically uses sandbox/production based on config
   $paypal->getApiContext()->getConfig()->getMode();
   

2. Payment Creation & Execution:

   // Create a payment
   $payment = $paypal->createPayment($paymentObj);
   
   // Execute payment (redirect to PayPal)
   $approvalUrl = $paypal->getApprovalUrl($payment->getId());
   

3. Webhook Handling:

   // Verify webhook signatures
   $verified = $paypal->verifyWebhook($request->getContent(), $request->headers->get('PAYPAL-WEBHOOK-SIGNATURE'));
   

4. Refunds & Captures:

   // Capture a payment
   $capture = $paypal->capturePayment($paymentId, $amount);
   
   // Refund a payment
   $refund = $paypal->refundPayment($saleId, $amount);
   

Integration Tips

• Use Dependency Injection: Prefer injecting PayPalService over manually instantiating the SDK.

  public function __construct(private PayPalService $paypal) {}
  

• Leverage Events: Extend the bundle by subscribing to PayPal events (e.g., paypal.payment.created).

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

• Logging: Enable logging for debugging:

  kmj_pay_pal_bridge:
      logs:
          enabled: true
          level: debug  # or 'info', 'warning', 'error'
  

• Testing: Mock the PayPalService in tests:

  $this->mock(PayPalService::class)
       ->shouldReceive('createPayment')
       ->andReturn($mockPayment);
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle Name: The original README references KMJPayPalBridgeBundle, but the package is now AlessandrolandimPayPalBridgeBundle. Ensure your composer.json and bundles.php match the correct namespace.

2. Environment Mismatch:

   • Issue: Forgetting to update environment in config when switching between sandbox/production.
   • Fix: Validate the environment in logs or add a pre-action check:

     $mode = $paypal->getApiContext()->getConfig()->getMode();
     if ($mode !== 'sandbox' && $this->getParameter('kernel.environment') === 'dev') {
         throw new \RuntimeException('Production API called in dev environment!');
     }
     

3. Webhook Verification:

   • Issue: Webhook signatures failing due to incorrect headers or payloads.
   • Fix: Use the bundle’s verifyWebhook() method and log raw headers/payloads for debugging:

     $verified = $paypal->verifyWebhook($rawBody, $signature);
     if (!$verified) {
         $this->logger->error('Webhook verification failed', [
             'headers' => $request->headers->all(),
             'body' => $rawBody,
         ]);
     }
     

4. Rate Limiting:

   • Issue: PayPal’s API rate limits (e.g., 200 calls/100ms in sandbox).
   • Fix: Implement exponential backoff in retries:

     $paypal->setHttpConfig([
         'retry' => true,
         'timeout' => 30,
         'backoff' => true, // Add this if supported (check bundle version)
     ]);
     

5. Legacy SDK Compatibility:

   • Issue: The underlying paypal/rest-api-sdk-php may have breaking changes.
   • Fix: Pin the SDK version in composer.json:

     "paypal/rest-api-sdk-php": "~1.14.0"  // Use a stable version
     

Debugging Tips

• Enable SDK Logging: Add this to your config to debug SDK-level issues:

  kmj_pay_pal_bridge:
      logs:
          enabled: true
          level: debug
  

  Check logs at %kernel.logs_dir%/paypal.log.

• Inspect API Context: Dump the ApiContext to verify settings:

  $context = $paypal->getApiContext();
  dump([
      'mode' => $context->getConfig()->getMode(),
      'clientId' => $context->getConfig()->getClientId(),
      'credentials' => $context->getConfig()->getCredential(),
  ]);
  

• Test with Sandbox First: Always test payments in the PayPal Sandbox before going live. Use sandbox credentials:

  sandbox:
      clientId: "YOUR_SANDBOX_CLIENT_ID"
      secret: "YOUR_SANDBOX_SECRET"
  

Extension Points

1. Customize HTTP Client: Override the default HTTP client (e.g., for proxies or custom headers):

   kmj_pay_pal_bridge:
       http:
           timeout: 60
           headers:
               X-Custom-Header: "value"
   

2. Add Custom PayPal Objects: Extend the bundle’s service to support custom PayPal objects (e.g., Disbursement):

   // src/Service/PayPalService.php
   public function createDisbursement($disbursement)
   {
       return $this->getPayPalClient()->disbursement->create($disbursement);
   }
   

3. Event Dispatching: Trigger custom events for PayPal actions:

   // In PayPalService
   $this->dispatchEvent('paypal.payment.created', ['payment' => $payment]);
   

   Listen in your app:

   services:
       App\EventListener\PaymentListener:
           tags:
               - { name: kernel.event_listener, event: paypal.payment.created, method: onPaymentCreated }
   

4. Override Templates: If the bundle includes views (e.g., for approval URLs), override them in templates/bundles/KMJPayPalBridge/.