Commerce Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/commerce
   

   Add to composer.json under require if not using Composer directly.

2. Basic Usage Initialize a Commerce instance (check for updated class names post-rename):

   use Ekyna\Commerce\Commerce;
   
   $commerce = new Commerce();
   

3. First Use Case: Product Creation

   $product = $commerce->createProduct('Laptop', 999.99);
   $product->addAttribute('color', 'black');
   $product->addVariant(['size' => '15"']);
   

4. Key Files to Explore

   • src/Ekyna/Commerce/ – Core classes (e.g., Product, Order, Customer).
   • tests/ – Real-world usage examples (if tests exist).
   • README.md – TODO list hints at active development (e.g., Doctrine integration).

Implementation Patterns

Core Workflows

1. Product Management

   • CRUD: Use createProduct(), addAttribute(), addVariant().
   • Bulk Operations: Chain methods or loop through collections.

     $products = [];
     foreach ($skus as $sku) {
         $products[] = $commerce->createProduct($sku, $price);
     }
     

2. Order Processing

   • Cart → Order: Convert cart to order with tax/resolver logic.

     $order = $commerce->createOrder($customer);
     $order->addItem($product, 2);
     $order->calculateTax(); // Hypothetical; check for `TaxResolver`
     

3. Customer Segmentation

   • Groups: Assign customers to groups (post-implementation of ManyToOne).

     $customer->setGroup($commerce->createCustomerGroup('Premium'));
     

4. Doctrine Integration (Future)

   • Embeddables: Use Doctrine\Common\Collections for nested objects (e.g., addresses).

     // Example (post-rename to `is` getters)
     $address = $commerce->createAddress();
     $address->setStreet('123 Main St');
     $product->setShippingAddress($address);
     

Integration Tips

• Event-Driven: Extend with listeners for OrderCreated, InventoryUpdated.
• API Layer: Wrap methods in a DTO layer for API responses.

  class ProductResource extends JsonResource {
      public function toArray($request) {
          return [
              'name' => $this->resource->getName(),
              'price' => $this->resource->getPrice(),
              'attributes' => $this->resource->getAttributes()->toArray(),
          ];
      }
  }
  

• Testing: Mock Commerce for unit tests (e.g., createProduct() returns stubs).

Gotchas and Tips

Pitfalls

1. Naming Inconsistencies

   • Boolean Getters: Rename getIsActive() → isActive() (see TODO).
   • Collections: setXXXs() clears existing items; use addXXX() for appends.

2. Doctrine Quirks

   • Missing Mappings: No ORM constraints (e.g., position indexes for variants).
   • Embeddables: Addresses may need manual Doctrine setup (see TODO).

3. Tax Logic

   • Resolver Dependency: No built-in tax resolver; implement TaxResolverInterface.

     $order->setTaxResolver(new EuTaxResolver());
     

4. Attribute Sets

   • Undefined Slots: Warn if variants lack required attributes (see TODO).

Debugging Tips

• Collection Methods: Use dump($product->getAttributes()) to inspect collections.
• Validation: Add custom validation for setXXXs() to prevent silent overwrites.

  public function setAttributes(array $attributes) {
      if (!empty($this->attributes)) {
          throw new \RuntimeException('Use addAttribute() to modify collections.');
      }
      $this->attributes = $attributes;
  }
  

Extension Points

1. Custom Resolvers

   • Implement TaxResolverInterface for region-specific rules.

   class UsTaxResolver implements TaxResolverInterface {
       public function resolve(Order $order) { ... }
   }
   

2. Attribute Types

   • Extend Attribute class for custom validation (e.g., ColorAttribute).

   class ColorAttribute extends Attribute {
       public function isValid($value) {
           return in_array($value, ['red', 'green', 'blue']);
       }
   }
   

3. Print Catalog

   • Override Product::toString() or create a CatalogPrinter service.

   $catalog = new CatalogPrinter();
   echo $catalog->render($products);
   

Configuration Quirks

• No Default Config: Package is library-only; configure via DI (e.g., Laravel’s bind()).

  $app->bind(TaxResolverInterface::class, function ($app) {
      return new EuTaxResolver();
  });