Order Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dywee/order-bundle
   

   Ensure knplabs/knp-paginator-bundle is also installed (required dependency).

2. Register the Bundle Add to config/bundles.php:

   Dywee\OrderBundle\DyweeOrderBundle::class => ['all' => true],
   

3. Basic Configuration Configure in config/packages/dywee_order.yaml (or config/services.yaml):

   parameters:
     order_bundle.is_price_ttc: true
     order_bundle.sell_type: both  # 'buy', 'rent', or 'both'
     order_bundle.order_connexion_permission: anon  # 'anon', 'registered', or 'both'
   

4. First Use Case: Create an Order Inject the OrderManager service and use its methods:

   use Dywee\OrderBundle\Manager\OrderManager;
   
   public function createOrder(OrderManager $orderManager) {
       $order = $orderManager->createOrder();
       $order->setCustomer($customerEntity);
       $order->setItems([$product1, $product2]);
       $orderManager->saveOrder($order);
   }
   

Implementation Patterns

Core Workflows

1. Order Creation & Management

   • Use OrderManager to handle CRUD operations:

     $order = $orderManager->findOrder($orderId);
     $orderManager->updateOrder($order);
     $orderManager->cancelOrder($order);
     

   • Leverage OrderItemManager for line-item operations:

     $orderItem = $orderManager->addItemToOrder($order, $product, $quantity);
     

2. Paginated Order Lists

   • Integrate with KNP Paginator for listing orders:

     use Knp\Component\Pager\PaginatorInterface;
     
     public function listOrders(PaginatorInterface $paginator, OrderManager $orderManager) {
         $orders = $orderManager->getAllOrders();
         return $this->render('order/list.html.twig', [
             'orders' => $paginator->paginate($orders, $request->query->getInt('page', 1))
         ]);
     }
     

3. Permission-Based Access

   • Use order_connexion_permission to control visibility:
     • anon: Public access (e.g., guest checkout).
     • registered: Requires authentication.
     • both: Hybrid logic (e.g., anonymous view, registered edit).

4. Price Handling

   • Configure is_price_ttc to toggle tax-inclusive pricing:

     order_bundle.is_price_ttc: false  # Defaults to excluding tax
     

   • Use OrderManager::calculateTotal() to compute totals dynamically.

5. Sell Type Logic

   • Customize behavior for buy, rent, or both modes:

     if ($orderManager->getSellType() === 'rent') {
         $order->setRentalTerms($terms);
     }
     

Gotchas and Tips

Pitfalls

1. Missing KNP Paginator

   • Error: Class 'Knp\Component\Pager\PaginatorInterface' not found.
   • Fix: Install knplabs/knp-paginator-bundle and register it in bundles.php.

2. Configuration Overrides

   • Issue: Parameters in services.yaml may not apply if the bundle expects them in parameters:.
   • Fix: Use the exact key structure from the README (e.g., order_bundle.is_price_ttc).

3. Sell Type Mismatches

   • Gotcha: Hardcoding buy/rent logic without checking getSellType() can break features.
   • Tip: Always validate the sell type before processing orders:

     if ($orderManager->getSellType() !== 'both' && $order->isRental()) {
         throw new \LogicException('Rental orders not supported in current mode.');
     }
     

4. Permission Logic

   • Edge Case: anon mode may expose sensitive data (e.g., order IDs) to guests.
   • Mitigation: Use order_connexion_permission: registered for admin dashboards and anon for public-facing pages.

5. Price TTC Quirks

   • Behavior: is_price_ttc: true affects all price calculations, including discounts.
   • Workaround: Apply tax logic manually if granular control is needed:

     $subtotal = $orderManager->calculateSubtotal($order);
     $total = $orderManager->isPriceTtc() ? $subtotal : $subtotal + ($subtotal * $taxRate);
     

Debugging Tips

1. Order State Inspection Use var_dump($order->getState()) to debug workflows (e.g., pending, cancelled).

2. Event Listeners The bundle may dispatch events (e.g., order.created). Override them in your EventSubscriber:

   public static function getSubscribedEvents() {
       return [
           'order.created' => 'onOrderCreated',
       ];
   }
   

3. Database Schema

   • Tip: Dump the order and order_item tables to understand relationships:

     php bin/console doctrine:schema:dump
     

   • Common Fields:
     • order: id, customer_id, state, created_at, total_ttc.
     • order_item: order_id, product_id, quantity, unit_price.

Extension Points

1. Custom Order States Extend the OrderState enum or add a state_machine configuration to support workflows like:

   # config/packages/workflow.yaml
   dywee_order:
       supports_markers: true
       markers:
           payment_required: { label: 'Payment Required' }
   

2. Validation Rules Override the OrderValidator service to add constraints:

   # config/services.yaml
   Dywee\OrderBundle\Validator\OrderValidator:
       arguments:
           $constraints: ['@validator.constraint_collection']
       tags: [validator]
   

3. API Integration Use the bundle’s entities with API Platform or Symfony’s Serializer:

   # config/packages/api_platform.yaml
   resources:
       Dywee\OrderBundle\Entity\Order:
           collectionOperations:
               get:
                   security: "is_granted('ROLE_ADMIN')"