Dzangocart Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dzangocart/dzangocart-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       DzangoCart\DzangoCartBundle\DzangoCartBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console dzango-cart:install
   

   Update config/packages/dzango_cart.yaml with your DzangoCart API credentials (e.g., api_key, base_uri).

3. First Use Case Fetch a product in a controller:

   use DzangoCart\DzangoCartBundle\Service\DzangoCartClient;
   
   class ProductController extends AbstractController
   {
       public function show(Product $product)
       {
           $client = $this->container->get(DzangoCartClient::class);
           $dzangoProduct = $client->getProduct($product->dzangoId);
   
           return $this->render('product/show.html.twig', [
               'dzangoProduct' => $dzangoProduct,
           ]);
       }
   }
   

Implementation Patterns

Common Workflows

1. Product Management

   • Fetching: Use DzangoCartClient::getProduct($id) for single products or getProducts() for collections.
   • Syncing: Implement a cron job with syncProducts() to mirror DzangoCart inventory to your DB.

     $this->get('dzango_cart.client')->syncProducts();
     

2. Cart Integration

   • Guest Carts: Use createGuestCart() and addToGuestCart() for anonymous users.
   • Authenticated Carts: Link user accounts via linkUserToCart($user, $cartId).

     $cart = $this->get('dzango_cart.client')->getCart($user->dzangoCartId);
     

3. Order Processing

   • Create Orders: Use createOrder() with user/cart data.
   • Webhooks: Configure dzango_cart.yaml to listen for order.created events:

     dzango_cart:
         webhooks:
             order_created: 'App\EventListener\OrderWebhookListener'
     

4. Twig Integration

   • Access cart data in templates:

     {% set cart = app.service('dzango_cart.client').getCart(user.dzangoCartId) %}
     {% for item in cart.items %}
         {{ item.product.name }} - {{ item.quantity }}
     {% endfor %}
     

Best Practices

• Caching: Cache DzangoCart responses (e.g., getProduct()) with Symfony’s cache system:

  $product = $this->get('dzango_cart.client')->getProduct($id, 3600); // Cache for 1 hour
  

• Error Handling: Wrap API calls in try-catch blocks:

  try {
      $client->getProduct($id);
  } catch (\DzangoCart\Exception\ApiException $e) {
      $this->addFlash('error', 'Failed to fetch product: ' . $e->getMessage());
  }
  

• Event-Driven Syncs: Use Symfony events to trigger DzangoCart actions (e.g., kernel.request to update cart on page load).

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • DzangoCart may throttle requests. Implement exponential backoff in custom clients:

     $client = $this->get('dzango_cart.client');
     $client->setRetryPolicy(new RetryPolicy(3, 1000)); // Retry 3 times with 1s delay
     

   • Monitor usage via getRateLimitStatus().

2. ID Mismatches

   • Ensure your local product IDs (product.id) match DzangoCart’s (product.dzangoId). Use a migration to sync them:

     // In a Doctrine migration
     $product->setDzangoId($dzangoProduct->getId());
     $entityManager->persist($product);
     

3. Webhook Delays

   • Webhooks may arrive out of order. Use a queue (e.g., Symfony Messenger) to process them asynchronously:

     # config/packages/messenger.yaml
     framework:
         messenger:
             transports:
                 dzango_cart: '%env(MESSENGER_TRANSPORT_DSN)%'
     

4. Deprecated Methods

   • The bundle lacks a changelog. Check src/Service/DzangoCartClient.php for deprecated methods (e.g., getCartItems() → getCart()->getItems()).

Debugging Tips

• Enable API Logging Add to config/packages/dzango_cart.yaml:

  dzango_cart:
      debug: true
  

  Logs appear in var/log/dev.log.

• Test Locally Use DzangoCart’s sandbox environment (configure base_uri in dzango_cart.yaml):

  dzango_cart:
      base_uri: 'https://sandbox.dzangocart.com/api/v1'
  

• Validate Responses DzangoCart’s API may return partial data. Always check response structure:

  $product = $client->getProduct($id);
  if (!$product->getId()) {
      throw new \RuntimeException('Invalid product data from DzangoCart');
  }
  

Extension Points

1. Custom Clients Extend DzangoCartClient to add methods:

   class CustomDzangoCartClient extends DzangoCartClient
   {
       public function getProductWithReviews($productId)
       {
           $product = parent::getProduct($productId);
           $reviews = $this->get('/products/' . $productId . '/reviews');
           return array_merge($product->toArray(), ['reviews' => $reviews]);
       }
   }
   

   Register as a service:

   services:
       App\Service\CustomDzangoCartClient:
           arguments:
               - '@http_client'
               - '%dzango_cart.api_key%'
           tags: ['dzango_cart.client']
   

2. Event Listeners Subscribe to DzangoCart events (e.g., dzango_cart.product.updated):

   use DzangoCart\Event\ProductEvent;
   
   class ProductSyncListener
   {
       public function onProductUpdated(ProductEvent $event)
       {
           // Sync local product data
       }
   
       public static function getSubscribedEvents()
       {
           return [
               'dzango_cart.product.updated' => 'onProductUpdated',
           ];
       }
   }
   

3. Override Templates The bundle uses Twig templates in Resources/views/. Override them in your app’s templates/bundles/dzangocart/ directory.

4. Add Custom Fields Extend DzangoCart’s product model by adding custom attributes to your local Product entity and sync them via a custom sync method:

   $client->syncProduct($localProduct, ['custom_field' => $localProduct->getCustomField()]);