Commerce Laravel Package

Getting Started

Minimal Setup

1. Install OroCommerce Application Clone and install the full OroCommerce application from orocommerce-application (this package is a dependency, not standalone).

   git clone https://github.com/orocrm/orocommerce-application.git
   cd orocommerce-application
   composer install
   php bin/console oro:install
   

2. First Use Case: Basic Product Management

   • Access the admin panel (/app_dev.php/admin) and navigate to Products > Products.
   • Use the Product entity to create a B2B product with attributes like SKU, price, and inventory.
   • Leverage Oro’s built-in Product Association (e.g., bundles, kits) via the UI or API.

3. Key Entry Points

   • Entities: OroCommerce\Bundle\ProductBundle\Entity/Product (core product model).
   • Services: oro_product.product_manager (for programmatic product operations).
   • Commands: oro:product:import (for bulk imports via CSV/Excel).
   • API: Enable REST API (oro_api) to expose products via /api/products.

Implementation Patterns

Core Workflows

1. Product-Centric Extensions

• Extend Product Attributes: Add custom fields via Doctrine extensions or Oro’s Attribute system.

  # config/oro/product.yml
  oro_product:
      product_attributes:
          custom_field:
              type: string
              label: 'Custom Field'
  

  • Use oro_product.product_attribute_manager to fetch/update attributes dynamically.

• Custom Product Types: Subclass Oro\Bundle\ProductBundle\Entity\Product and override behaviors (e.g., validation).

  namespace App\Entity;
  use Oro\Bundle\ProductBundle\Entity\Product as BaseProduct;
  
  class CustomProduct extends BaseProduct {
      // Add custom logic (e.g., dynamic pricing)
  }
  

2. B2B-Specific Features

• Customer Groups & Pricing: Use Oro\Bundle\CustomerBundle\Entity\CustomerGroup to assign tiered pricing.

  $product->setPrice($price->setCustomerGroup($group));
  

• Quotes & Orders: Leverage Oro’s Quote and Order entities (Oro\Bundle\OrderBundle\Entity\Quote) for B2B workflows.
  • Extend quote validation with oro_order.order_manager.

3. Integration Patterns

• ERP/CRM Sync: Use Oro’s Integration bundles (e.g., oro_integration) to connect with external systems via:

  • API Platform: Expose entities as GraphQL/REST endpoints.
  • Webhooks: Trigger actions on order events (e.g., order.create).

  // Example: Subscribe to order events
  $eventDispatcher->addListener(
      'oro_order.order.create',
      [$this, 'onOrderCreate']
  );
  

• Payment Gateways: Integrate with oro_payment bundle for custom payment methods.

  # config/oro/payment.yml
  oro_payment:
      gateways:
          custom_gateway:
              class: App\Payment\Gateway\CustomGateway
  

4. Performance Optimization

• Caching: Cache product collections with oro_product.product_manager:

  $products = $productManager->getProducts(['sku' => 'ABC123'], ['cache' => true]);
  

• Batch Processing: Use oro_batch for large imports/exports (e.g., product updates).

Gotchas and Tips

Pitfalls

1. Entity Inheritance Quirks

   • Avoid direct subclassing of Oro’s core entities (e.g., Product) without overriding the getNewEntityName() method in your EntityManager.
   • Fix: Use composition or Oro’s Entity Extension system instead.

2. Database Schema Conflicts

   • OroCommerce uses Doctrine Extensions (e.g., Gedmo\Timestampable). Ensure your migrations account for these.
   • Tip: Run php bin/console doctrine:schema:update --dump-sql after adding custom fields.

3. Event Dispatching Order

   • Oro’s events (e.g., oro_product.product.update) may fire before/after your expectations.
   • Debug: Use oro_event_dispatcher to log event priorities:

     $dispatcher->addListener('oro_product.product.update', function() {
         \Oro\Bundle\LogBundle\Logger\Logger::info('Event fired!');
     }, -100); // Lower priority = earlier execution
     

4. API Versioning

   • Oro’s REST API is versioned (/api/{version}/products). Ensure your clients target the correct version.

Debugging Tips

• Enable Debug Mode:

  # config/packages/dev/oro_logging.yml
  oro_logging:
      channels:
          oro_product: true
  

• Dump Entities: Use Oro’s Data Auditor (/admin/system/data-auditor) to inspect entity changes.
• Command-Line Tools:

  # List all installed bundles
  php bin/console debug:container --tags="oro.bundle"
  
  # Check product associations
  php bin/console oro:product:association:list
  

Extension Points

1. Custom Business Rules

   • Extend Oro\Bundle\RuleBundle to add dynamic product visibility/pricing:

     namespace App\Rule\Condition;
     use Oro\Bundle\RuleBundle\Condition\AbstractCondition;
     
     class CustomProductCondition extends AbstractCondition {
         // Implement logic (e.g., "Show product if customer group is VIP")
     }
     

2. Frontend Customization

   • Override Twig templates in templates/OroProduct/ (e.g., product/view.html.twig).
   • Use Symfony UX for React/Vue integrations.

3. Testing Strategies

   • Functional Tests: Extend Oro\Bundle\TestFrameworkBundle\Test\WebTestCase.
   • Unit Tests: Mock oro_product.product_manager:

     $this->productManager = $this->createMock(ProductManager::class);
     $this->productManager->method('getProduct')->willReturn($product);
     

4. Localization

   • Oro supports multi-language via oro_locale. Extend translations in translations/messages.en.yml:

     Oro\Bundle\ProductBundle:
         product: 'My Custom Product Name'