Order Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require sylius/order
   

   Publish the migration (if using Doctrine):

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

2. First Use Case: Creating an Order

   use Sylius\Component\Order\Model\OrderInterface;
   use Sylius\Component\Order\Model\OrderItemInterface;
   
   // Create an order
   $order = $orderFactory->createNew();
   $order->setCurrencyCode('USD');
   
   // Add an item
   $item = $orderFactory->createOrderItem();
   $item->setProductVariant($variant);
   $item->setQuantity(2);
   $order->addItem($item);
   
   // Persist (via Doctrine or your ORM)
   $entityManager->persist($order);
   $entityManager->flush();
   

3. Where to Look First

   • Core Classes: Sylius\Component\Order\Model\Order, OrderItem, Adjustment
   • Factories: Sylius\Component\Order\Factory\OrderFactoryInterface
   • Documentation: Sylius Order Component Docs
   • Tests: tests/ directory for usage examples.

Implementation Patterns

Core Workflows

1. Order Creation & Management

   • Use OrderFactory to create orders and items.
   • Attach metadata (e.g., customer, shipping address) via setters:

     $order->setCustomer($customer);
     $order->setShippingAddress($shippingAddress);
     

2. Adjustments (Fees/Discounts)

   • Apply adjustments to orders or items:

     $adjustment = $adjustmentFactory->createShippingAdjustment();
     $adjustment->setAmount(5.99);
     $order->addAdjustment($adjustment);
     

   • Use AdjustmentType (e.g., Sylius\Component\Order\Model\AdjustmentInterface::TYPE_SHIPPING) for categorization.

3. Order States & Transitions

   • Leverage state machines (e.g., Sylius\Component\Order\Model\OrderStates) for workflows:

     $order->setState(OrderInterface::STATE_CART);
     $order->setState(OrderInterface::STATE_COMPLETED);
     

   • Integrate with Symfony Workflow Component for complex transitions.

4. Order Numbering

   • Customize numbering via OrderNumberGenerator:

     # config/packages/sylius_order.yaml
     sylius_order:
         order_number_generator:
             pattern: 'ORD-{year}-{sequence}'
     

5. API/Serialization

   • Use Symfony Serializer or API Platform for exposing orders:

     use Sylius\Component\Order\Serializer\OrderSerializer;
     
     $serializer = new OrderSerializer();
     $data = $serializer->serialize($order, 'json');
     

Integration Tips

• Event-Driven: Listen to OrderEvents (e.g., OrderCreated, OrderStateChanged) for side effects.
• Validation: Use Symfony Validator constraints (e.g., @Assert\GreaterThan(0) for quantities).
• Testing: Mock OrderFactory and OrderRepository in unit tests:

  $this->orderFactory = $this->createMock(OrderFactoryInterface::class);
  $this->orderFactory->method('createNew')->willReturn($order);
  

Gotchas and Tips

Pitfalls

1. Adjustment Precision

   • Floating-point arithmetic can cause rounding errors. Use bcmath or gmp for financial calculations:

     $total = bcadd($order->getSubtotal(), $order->getTotalAdjustments(), 2);
     

2. State Transitions

   • Ensure state transitions are validated (e.g., prevent CART → SHIPPED directly). Use Symfony Workflow for constraints:

     # config/workflows/order_workflow.yaml
     supports:
         - Sylius\Component\Order\Model\OrderInterface
     places:
         cart:
             initial: true
             transitions:
                 checkout: completed
     

3. Order Number Collisions

   • Default generators (e.g., sequential) may collide in high-concurrency environments. Use UUIDs or database sequences:

     // Custom generator example
     $generator = new UuidOrderNumberGenerator();
     $order->setNumber($generator->generate());
     

4. Lazy-Loading Pitfalls

   • Avoid N+1 queries when accessing collections (e.g., order->getItems()). Use DQL or repository methods:

     $items = $orderRepository->findItemsByOrder($order);
     

Debugging

• Adjustment Calculation Issues

  • Log intermediate values:

    foreach ($order->getAdjustments() as $adjustment) {
        $this->logger->debug('Adjustment: ', [
            'type' => $adjustment->getType(),
            'amount' => $adjustment->getAmount(),
        ]);
    }
    

  • Verify AdjustmentType constants match your use case.

• State Machine Errors

  • Check OrderStates for valid transitions. Use:

    $this->order->getStateMachine()->can($order, 'transition_name');
    

Extension Points

1. Custom Adjustment Types

   • Extend AdjustmentInterface or create subclasses:

     class LoyaltyDiscountAdjustment implements AdjustmentInterface
     {
         public function getType(): string
         {
             return self::TYPE_LOYALTY_DISCOUNT;
         }
     }
     

2. Order Number Generators

   • Implement OrderNumberGeneratorInterface:

     class CustomOrderNumberGenerator implements OrderNumberGeneratorInterface
     {
         public function generate(): string
         {
             return 'CUST-' . Str::upper(Random::string(8));
         }
     }
     

3. Order Factories

   • Override OrderFactory to inject custom logic:

     class CustomOrderFactory implements OrderFactoryInterface
     {
         public function createNew(): OrderInterface
         {
             $order = parent::createNew();
             $order->setChannel($this->channelResolver->resolve());
             return $order;
         }
     }
     

4. Event Subscribers

   • Extend order behavior via events (e.g., send email on OrderCompleted):

     use Sylius\Component\Order\Event\OrderCompletedEvent;
     
     $eventDispatcher->addListener(OrderCompletedEvent::NAME, function (OrderCompletedEvent $event) {
         $this->mailer->send(new OrderConfirmationEmail($event->getOrder()));
     });
     

Configuration Quirks

• Doctrine Mappings
  • Ensure Order and OrderItem entities are properly mapped. Example:

    # config/packages/doctrine.yaml
    orm:
        mappings:
            SyliusOrder:
                type: attribute
                prefix: 'Sylius\Component\Order\Model'
                dir: '%kernel.project_dir%/vendor/sylius/order/src/Model'
    

• Symfony Workflow
  • If using Symfony Workflow, register the order workflow in config/packages/framework.yaml:

    framework:
        workflows:
            order_workflow: '@sylius_order.workflow.order'