Product Inventory Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bajomodavid/product-inventory-bundle
   

   Add to config/bundles.php:

   BajomoDavid\ProductInventoryBundle\ProductInventoryBundle::class => ['all' => true],
   

2. Database Migration Run these commands in sequence:

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

3. First Use Case Import stock via CLI:

   php bin/console inventory:import-stock public/stock.csv
   

   Verify stock records in the database via doctrine:query:sql or a simple API endpoint.

Implementation Patterns

Core Workflows

1. Stock Management

   • CLI Imports: Use inventory:import-stock for bulk CSV uploads. Ideal for nightly batch jobs or initial data seeding.
   • API Endpoints: Send POST requests with x-action: inventory-import header to dynamically update stock. Example:

     // Controller
     public function updateStock(Request $request) {
         $request->headers->set('x-action', 'inventory-import');
         $validator = $this->get('validator');
         $data = $request->request->all();
         // Validate and process
     }
     

2. Integration with Product Entities

   • Extend the bundle’s Stock entity to include product relationships:

     // src/Entity/Product.php
     #[ORM\OneToMany(targetEntity: Stock::class, mappedBy: 'product')]
     private Collection $stocks;
     

   • Use events to trigger inventory updates post-product creation:

     // src/EventListener/ProductListener.php
     public function postPersist(Product $product) {
         $stock = new Stock();
         $stock->setProduct($product);
         $stock->setBranch('default');
         $stock->setQuantity(0);
         $em->persist($stock);
     }
     

3. Multi-Branch Inventory

   • Use the branch field to segment stock by location. Example query:

     $stocks = $entityManager->getRepository(Stock::class)
         ->findBy(['branch' => 'nyc-store']);
     

4. Validation Layer

   • Customize validation in config/packages/bajomo_product_inventory.yaml:

     inventory:
         validation:
             min_stock: 0
             max_stock: 1000
     

Gotchas and Tips

Pitfalls

1. CSV Format Strictness

   • The inventory:import-stock command expects exact column names: sku, branch, stock. Missing or misnamed columns will silently fail. Validate files pre-import:

     // Custom validator for CSV
     public function validateCsv(array $data): bool {
         return isset($data['sku'], $data['branch'], $data['stock']);
     }
     

2. Race Conditions

   • Concurrent stock updates (e.g., via API + CLI) may cause inconsistencies. Use database transactions:

     $entityManager->beginTransaction();
     try {
         $stock->setQuantity($stock->getQuantity() + $delta);
         $entityManager->flush();
         $entityManager->commit();
     } catch (\Exception $e) {
         $entityManager->rollBack();
         throw $e;
     }
     

3. Migration Dependencies

   • The bundle assumes a Stock table with columns id, sku, branch, quantity. Custom migrations may break compatibility. Check the bundle’s Migration class for schema details.

Debugging

• Log Imports: Add logging to the ImportStockCommand:

  $this->logger->info('Importing stock for SKU: ' . $sku, ['branch' => $branch]);
  

• Validate API Headers: Ensure x-action: inventory-import is set; missing headers may route requests to default controllers.

Extension Points

1. Custom Stock Events

   • Subscribe to StockUpdatedEvent to trigger actions (e.g., notifications):

     // config/services.yaml
     BajomoDavid\ProductInventoryBundle\EventListener\StockListener:
         tags:
             - { name: kernel.event_listener, event: stock.updated, method: onStockUpdated }
     

2. Override Default Behavior

   • Extend the Stock entity to add fields (e.g., reserved_quantity):

     #[ORM\Column(type: 'integer', nullable: true)]
     private ?int $reservedQuantity = null;
     

   • Update the bundle’s StockType form class to include new fields.

3. API Security

   • Restrict inventory-import actions to trusted IPs or roles:

     # config/packages/security.yaml
     access_control:
         - { path: ^/api/inventory, roles: ROLE_INVENTORY_MANAGER }