Shopbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alpixel/shopbundle
   

   Ensure your project uses Symfony 2.8 (as per composer.json).

2. Enable the Bundle: Add to app/AppKernel.php:

   new Alpixel\Bundle\ShopBundle\AlpixelShopBundle(),
   new Happyr\GoogleAnalyticsBundle\HappyrGoogleAnalyticsBundle(), // Required if using GA
   new Http\HttplugBundle\HttplugBundle(), // Required if using GA
   

3. Basic Configuration (config.yml):

   alpixel_shop:
       customer_class: AppBundle\Entity\Customer # Extend Alpixel's base Customer entity
       stock:
           strategy: soft # Default: 'soft' (allows over-selling)
       use_google_analytics: false # Set to true if using GA
   

4. First Use Case: Create a custom Customer entity extending Alpixel\Bundle\ShopBundle\Entity\Customer:

   // src/AppBundle/Entity/Customer.php
   namespace AppBundle\Entity;
   use Alpixel\Bundle\ShopBundle\Entity\Customer as BaseCustomer;
   
   class Customer extends BaseCustomer { /* Add custom fields */ }
   

Implementation Patterns

Core Workflows

1. Product Management:

   • Use Alpixel\Bundle\ShopBundle\Entity\Product or extend via product_inheritance:

     alpixel_shop:
         product_inheritance:
             - { key: 'custom_product', class: AppBundle\Entity\CustomProduct }
     

   • Stock strategies (soft, tolerant, strict) control order validation:

     // Soft: Allow orders regardless of stock
     $order->validate(); // Always passes
     

2. Cart Functionality:

   • Save carts for reuse (v0.1.2+):

     $cart = $this->get('alpixel_shop.cart_manager')->createCart();
     $cart->addProduct($product, 2);
     $cartManager->saveCart($cart); // Persist to reuse later
     

   • Admin access to user carts (v0.1.5+):

     $userCart = $this->get('alpixel_shop.cart_manager')->getCartByUser($user);
     

3. Order Processing:

   • Shipments (v0.2.0+):

     $order->addShipment($address, $carrier);
     $order->setStatus('shipped');
     

4. Google Analytics Integration:

   • Enable tracking in config.yml and use events:

     $this->get('ga.tracker')->sendEvent('ecommerce', 'purchase', $order->getId());
     

Integration Tips

• Doctrine Extensions: Leverage stof/doctrine-extensions for behaviors like timestamps.
• Events: Listen to alpixel_shop.order.created or alpixel_shop.cart.saved for custom logic.
• APIs: Use Http\HttplugBundle for external services (e.g., payment gateways).

Gotchas and Tips

Pitfalls

1. Stock Strategy Misconfiguration:

   • strict mode blocks orders with insufficient stock. Test thoroughly in staging.
   • soft mode risks over-selling; monitor stock levels post-order.

2. Entity Inheritance:

   • Ensure custom Customer/Product entities are properly mapped in Doctrine:

     # AppBundle/Resources/config/doctrine/Customer.orm.yml
     AppBundle\Entity\Customer:
         type: entity
         extends: Alpixel\Bundle\ShopBundle\Entity\Customer
     

3. Google Analytics Dependency:

   • If use_google_analytics: true, ensure HappyrGoogleAnalyticsBundle and HttplugBundle are installed and configured.

4. Deprecated Symfony Version:

   • The bundle targets Symfony 2.8. Upgrade paths may not be documented for newer versions.

Debugging

• Cart Persistence Issues:

  • Verify CartManager is autowired and the cart table exists in your database.
  • Check Doctrine events for prePersist/preUpdate issues.

• Stock Updates:

  • If stock.update: false, stock quantities won’t auto-decrement. Manually update via:

    $product->decrementStock($quantity);
    $em->flush();
    

Extension Points

1. Custom Order Statuses:

   • Extend Alpixel\Bundle\ShopBundle\Entity\Order and add transitions:

     // src/AppBundle/Entity/Order.php
     public function setStatus($status)
     {
         if ($status === 'custom_status') {
             $this->fireEvent('custom_status_transition');
         }
         parent::setStatus($status);
     }
     

2. Payment Gateways:

   • Create a service to integrate with third-party APIs:

     // src/AppBundle/Service/PaymentGateway.php
     class PaymentGateway
     {
         public function process(Order $order) {
             // Use HttplugBundle to call external API
         }
     }
     

3. Custom Validation:

   • Override OrderValidator to add rules:

     // src/AppBundle/Validator/OrderValidator.php
     class OrderValidator extends \Alpixel\Bundle\ShopBundle\Validator\OrderValidator
     {
         public function validate(Order $order) {
             parent::validate($order);
             // Add custom checks
         }
     }
     

   • Register as a service with a higher priority than the default validator.