Economic Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require clubmaster/economic
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Clubmaster\EconomicBundle\ClubAccountEconomicBundle::class => ['all' => true],
   ];
   

2. Configuration Configure the bundle in config/packages/clubmaster_economic.yaml:

   clubmaster_economic:
       gateway: 'your_gateway_name'  # e.g., 'stripe', 'paypal', or custom
       api_key: '%env(ECONOMIC_API_KEY)%'
       # Other gateway-specific settings
   

3. First Use Case: Payment Processing Inject the EconomicGateway service and use it to create a payment:

   use Clubmaster\EconomicBundle\Service\EconomicGateway;
   
   class PaymentController extends AbstractController
   {
       public function __construct(private EconomicGateway $economicGateway) {}
   
       public function processPayment(Request $request)
       {
           $payment = $this->economicGateway->createPayment(
               amount: 1000, // 10.00 USD (in cents)
               currency: 'USD',
               description: 'Membership fee',
               metadata: ['user_id' => 123]
           );
   
           return new JsonResponse($payment);
       }
   }
   

4. Where to Look First

   • Documentation: Check the src/Service/EconomicGateway.php for available methods.
   • Gateway Implementations: Look in src/DependencyInjection/Configuration.php or src/Resources/config/services.yaml for supported gateways.
   • Events: Review src/Event/ for dispatchable events (e.g., PaymentCreatedEvent).

Implementation Patterns

Core Workflows

1. Payment Processing

   • Create a Payment:

     $payment = $economicGateway->createPayment($amount, $currency, $description, $metadata);
     

   • Capture a Payment:

     $economicGateway->capturePayment($paymentId);
     

   • Refund a Payment:

     $economicGateway->refundPayment($paymentId, $amount);
     

2. Webhook Handling Subscribe to events in your controller or event listener:

   use Clubmaster\EconomicBundle\Event\PaymentSucceededEvent;
   
   public function onPaymentSucceeded(PaymentSucceededEvent $event)
   {
       // Update your database or trigger follow-up actions
   }
   

   Register the listener in config/services.yaml:

   services:
       App\EventListener\PaymentListener:
           tags:
               - { name: 'kernel.event_listener', event: 'clubmaster.economic.payment.succeeded', method: 'onPaymentSucceeded' }
   

3. Gateway-Specific Logic Extend or override default gateways by creating a custom service:

   # config/services.yaml
   services:
       App\Service\CustomEconomicGateway:
           decorates: 'clubmaster_economic.gateway'
           arguments: ['@App\Service\CustomEconomicGateway.inner']
   

4. Testing Use the TestGateway for unit tests:

   $testGateway = new \Clubmaster\EconomicBundle\Service\TestGateway();
   $testGateway->setExpectedResponse(['success' => true]);
   $this->container->set('clubmaster_economic.gateway', $testGateway);
   

Integration Tips

• Symfony Forms: Bind payment fields to a form for user input:

  $builder->add('amount', MoneyType::class, [
      'currency' => 'USD',
      'scale' => 2,
  ]);
  

• Doctrine Entities: Map payments to an entity for persistence:

  /**
   * @ORM\Entity
   */
  class Payment
  {
      // ...
      #[ORM\Column(type: 'json')]
      private array $economicData;
  }
  

• API Clients: Use the bundle’s HttpClient for direct API calls if needed:

  $client = $economicGateway->getHttpClient();
  $response = $client->request('GET', '/payments');
  

Gotchas and Tips

Common Pitfalls

1. Gateway Configuration Mismatch

   • Issue: Forgetting to set the correct gateway in clubmaster_economic.yaml or providing invalid API keys.
   • Fix: Validate configuration in a CompilerPass or use Symfony’s ParameterBag validation:

     if (empty($this->getParameter('clubmaster_economic.api_key'))) {
         throw new \RuntimeException('API key is required.');
     }
     

2. Currency/Amount Handling

   • Issue: Passing amounts as floats (e.g., 10.00) instead of integers (e.g., 1000 for cents).
   • Fix: Use the Money component or enforce integer amounts in the gateway:

     $amount = (int) round($request->request->get('amount') * 100);
     

3. Webhook Verification

   • Issue: Unverified webhook payloads leading to security risks.
   • Fix: Implement HMAC verification in a custom gateway or use Symfony’s HttpFoundation utilities:

     $expectedSignature = hash_hmac('sha256', $payload, $this->apiKey);
     if (!hash_equals($expectedSignature, $request->headers->get('X-Signature'))) {
         throw new \RuntimeException('Invalid signature');
     }
     

4. Idempotency

   • Issue: Duplicate payments due to retries or failed transactions.
   • Fix: Use the idempotency_key parameter in createPayment():

     $payment = $economicGateway->createPayment(..., ['idempotency_key' => uniqid()]);
     

Debugging Tips

• Enable Debug Mode: Set debug: true in clubmaster_economic.yaml to log raw API responses:

  clubmaster_economic:
      debug: true
  

• Check Events: Use Symfony’s EventDispatcher debug tool to inspect dispatched events:

  bin/console debug:event-dispatcher
  

• Gateway-Specific Logs: Override the log() method in a custom gateway to write to Monolog:

  public function log(string $message, array $context = [])
  {
      $this->logger->info($message, $context);
  }
  

Extension Points

1. Custom Gateways Implement the GatewayInterface to add support for new payment providers:

   use Clubmaster\EconomicBundle\Service\GatewayInterface;
   
   class CustomGateway implements GatewayInterface
   {
       public function createPayment(array $data): array
       {
           // Custom logic for your gateway
       }
       // Implement other required methods
   }
   

   Register it in config/services.yaml:

   services:
       App\Service\CustomGateway:
           tags:
               - { name: 'clubmaster_economic.gateway', alias: 'custom' }
   

2. Event Subscribers Extend functionality by subscribing to events (e.g., PaymentFailedEvent):

   use Clubmaster\EconomicBundle\Event\PaymentFailedEvent;
   
   public static function getSubscribedEvents()
   {
       return [
           PaymentFailedEvent::class => 'onPaymentFailed',
       ];
   }
   
   public function onPaymentFailed(PaymentFailedEvent $event)
   {
       // Send a notification or retry logic
   }
   

3. HTTP Client Overrides Replace the default HttpClient for custom retries or middleware:

   services:
       App\Client\CustomHttpClient:
           decorates: 'clubmaster_economic.http_client'
           arguments: ['@App\Client\CustomHttpClient.inner']
   

4. Configuration Overrides Dynamically override configuration per environment:

   # config/packages/dev/clubmaster_economic.yaml
   clubmaster_economic:
       debug: true
       api_key: '%env(ECONOMIC_API_KEY_DEV)%'