Commerce Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ekyna/commerce-bundle
   

   Add to config/bundles.php:

   Ekyna\CommerceBundle\EkynaCommerceBundle::class => ['all' => true],
   

2. Database Migrations: Run migrations to set up required tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case: Create a basic product entity and integrate it with the bundle’s product repository:

   use Ekyna\CommerceBundle\Entity\Product;
   
   $product = new Product();
   $product->setName('Test Product');
   $product->setPrice(19.99);
   $em->persist($product);
   $em->flush();
   

4. Configuration: Check config/packages/ekyna_commerce.yaml (auto-generated) for default settings. Override as needed:

   ekyna_commerce:
       cart_lifetime: 2592000 # 30 days in seconds
       payment_watch_interval: 86400 # 24 hours in seconds
   

Implementation Patterns

Core Workflows

1. Product Management: Use the ProductRepository to fetch/products:

   $repository = $entityManager->getRepository(Product::class);
   $products = $repository->findBy(['category' => 'electronics']);
   

2. Cart Operations: Attach carts to users or sessions:

   $cart = $cartManager->createCart();
   $cart->addProduct($product, 2);
   $cartManager->saveCart($cart);
   

3. Order Processing: Convert carts to orders and trigger payment workflows:

   $order = $orderManager->createOrderFromCart($cart);
   $payment = $paymentManager->processOrder($order);
   

4. Payment Handling: Use the PaymentManager to track statuses:

   $paymentManager->watchPayments(); // Manually trigger cron logic
   

Integration Tips

• Symfony Events: Listen to ekyna_commerce.order.created or ekyna_commerce.payment.status_changed for custom logic.

  // src/EventListener/OrderListener.php
  public function onOrderCreated(OrderCreatedEvent $event) {
      $this->sendNotification($event->getOrder());
  }
  

• Custom Entities: Extend bundle entities (e.g., Product, Order) via inheritance or traits for domain-specific fields.

• API Layer: Expose cart/order endpoints using Symfony’s JsonResponse or API Platform:

  #[Route('/api/cart', methods: ['GET'])]
  public function getCart(CartManager $cartManager): JsonResponse {
      return new JsonResponse($cartManager->getCurrentCart()->toArray());
  }
  

• Testing: Use Ekyna\CommerceBundle\Tests\* as a reference for unit/integration tests. Mock the PaymentGateway interface for isolated tests.

Gotchas and Tips

Pitfalls

1. Cron Dependency:

   • The payment:watch and cart:purge commands must run daily. Schedule them via:

     0 0 * * * cd /path/to/project && php bin/console ekyna_commerce:payment:watch -e prod >> /dev/null 2>&1
     

   • Gotcha: Forgetting to run these leads to stale carts/payments. Test locally with:

     php bin/console ekyna_commerce:payment:watch --env=dev
     

2. Entity Lifecycle:

   • Cart/orders are not automatically deleted. Use cart:purge to clean up abandoned carts (configurable via cart_lifetime).
   • Tip: Override Cart::isExpired() to implement custom expiration logic.

3. Payment Gateways:

   • The bundle expects a PaymentGateway service implementing Ekyna\CommerceBundle\Payment\PaymentGatewayInterface.
   • Gotcha: If the gateway fails silently, check Ekyna\CommerceBundle\Event\PaymentFailedEvent listeners.

4. Database Schema:

   • Migrations may conflict if you’ve customized the bundle’s entities. Tip: Use doctrine:schema:update --force cautiously.

Debugging

• Enable Debug Mode: Set EKYNA_COMMERCE_DEBUG=true in .env to log payment/cart operations to var/log/ekyna_commerce.log.

• Common Issues:

  • Cart Not Found: Ensure the cart ID is correctly stored in the session (ekyna_commerce.cart_id).
  • Payment Stuck: Manually trigger payment:watch or check the payment_status column in the database.
  • Price Calculation Errors: Override Product::getFinalPrice() if using dynamic pricing.

Extension Points

1. Custom Fields: Add fields to entities via Doctrine extensions or traits:

   // src/Entity/ProductExtension.php
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class ProductExtension {
       #[ORM\Column(type: 'string', nullable: true)]
       private ?string $sku = null;
   
       // Getters/setters...
   }
   

2. Payment Strategies: Implement Ekyna\CommerceBundle\Payment\PaymentStrategyInterface for custom payment logic (e.g., subscriptions).

3. Shipping Methods: Extend ShippingMethod entity or create a ShippingCalculator service to integrate with third-party APIs.

4. Event Subscribers: Subscribe to bundle events for real-time actions:

   // config/services.yaml
   Ekyna\CommerceBundle\EventSubscriber\YourSubscriber::class:
       tags:
           - { name: kernel.event_subscriber }