Bagisto Api Laravel Package

## Getting Started
This package is now a **fully-fledged eCommerce API platform** built on Laravel, API Platform, and GraphQL. For new developers, start with:

1. **Installation** (updated for v1.0.4):
   ```bash
   composer require bagisto/api-platform:^1.0.4
   php artisan bagisto-api-platform:install --force  # Added --force flag for safer upgrades
   php artisan migrate --seed  # New seeders for sample data

The install command now includes database seeders for pre-populated test data (customers, products, orders).

2. First Use Case (updated):

   • Customer Account APIs: Test the new CustomerOrderProvider with v1.0.4's enhanced filtering:

     $orders = $this->customerOrderProvider->getOrders($customerId, [
         'filter' => ['status' => ['eq' => 'completed']],
         'sort' => ['-created_at']
     ]);
     

   • GraphQL Playground: Access /graphiql (fixed typo in docs) to explore new v1.0.4 queries:

     query {
       customerOrders(filter: {status: {eq: "completed"}}) {
         edges {
           node {
             id
             orderNumber
             total
             # New field: paymentStatus
             paymentStatus
           }
         }
       }
     }
     

   • New Seed Data: Use the /api/seed-data endpoint to fetch sample payloads for testing:

     curl -X GET http://your-app.test/api/seed-data
     

3. Key Configs (updated):

   • Review config/api-platform.php for new OpenAPI/Swagger v3.1.0 compliance.
   • Check config/api-platform-vendor.php for rate limit overrides (now supports per-endpoint limits).
   • New Locale Header: Accept-Language now supports region-specific fallbacks (e.g., en-US,en;q=0.9).
   • Webhook Config: Added config/api-platform-webhooks.php for event-driven integrations.

Implementation Patterns

Core Workflows

1. Customer-Centric APIs (updated):

   • Order Lifecycle: Use CancelOrderProcessor with new cancellation reasons (v1.0.4):

     $processor = new CancelOrderProcessor();
     $result = $processor->process(new CancelOrderInput(
         $orderId,
         $customerId,
         reason: 'customer_request'  // New enum: 'customer_request', 'stock_unavailable', 'fraud'
     ));
     

   • Reordering: Leverage ReorderProcessor with new includeTaxes flag:

     $this->reorderProcessor->execute(new ReorderInput(
         $orderId,
         $customerId,
         includeTaxes: true
     ));
     

   • Profile Management: Use CustomerProfileOutput with new address validation:

     $profile = $this->customerProfileHelper->getProfile($customerId, validateAddresses: true);
     

2. Catalog & Storefront (updated):

   • Dynamic Content: Fetch locales/categories with new includeMedia flag:

     GET /api/locales?includeMedia=true
     Accept-Language: fr_FR
     

   • Booking Products: Query slots with new timezone parameter (v1.0.4):

     query {
       bookingSlots(productId: "123", timezone: "America/New_York") {
         availableSlots
       }
     }
     

   • CMS Pages: Look up by URL key with new version parameter:

     $page = $this->pageProvider->getByUrlKey('about-us', version: 'draft');
     

3. Cart/Wishlist/Compare (updated):

   • Merge Carts: Extend CartTokenProcessor with new mergeStrategy option:

     $mergedCart = $this->cartTokenProcessor->merge($token1, $token2, strategy: 'prioritize_latest');
     

     Strategies: prioritize_latest, prioritize_first, merge_quantities.
   • Wishlist-to-Cart: Use MoveWishlistToCartProcessor with new preserveQuantities flag:

     $this->moveWishlistToCartProcessor->execute(
         new MoveWishlistToCartInput($wishlistId, $customerId, preserveQuantities: false)
     );
     

   • Compare Products: New CompareProductProvider for multi-product comparisons:

     $comparison = $this->compareProductProvider->getComparison([$productId1, $productId2]);
     

4. Infrastructure (updated):

   • Pagination: Adopt new cursor-based pagination with metadata:

     $orders = $this->customerOrderProvider->getOrders($customerId, [
         'pagination' => [
             'type' => 'cursor',
             'pageSize' => 20,
             'includeMetadata' => true
         ]
     ]);
     

   • Cache Management: Clear new cache groups explicitly:

     php artisan bagisto-api-platform:cache:clear --group=orders
     

     Groups: orders, products, customers, all.

5. Webhooks (new in v1.0.4):

   • Subscribe to events via the new WebhookService:

     $webhook = $this->webhookService->create([
         'url' => 'https://your-webhook-endpoint.com',
         'events' => ['order.placed', 'inventory.low'],
     ]);
     

   • Trigger webhooks manually:

     $this->webhookService->trigger('order.placed', $order);
     

Integration Tips

• GraphQL vs. REST: Prefer GraphQL for nested queries with new include directives (v1.0.4):

  query {
    customerOrders(include: [shipments, invoices, items]) {
      edges {
        node {
          id
          shipments { trackingNumber }
          invoices { pdfUrl }
        }
      }
    }
  }
  

• Localization: Always set Accept-Language headers for catalog data. Use new region-specific fallbacks:

  Accept-Language: en-US,en;q=0.9,fr;q=0.8
  

• Rate Limiting: Storefront endpoints are now per-endpoint rate-limited. Configure in api-platform-vendor.php:

  'rate_limits' => [
      'storefront/products' => '60|minute',
      'storefront/cart' => '120|minute',
  ],
  

• Webhooks: Use the new WebhookEvent class for type-safe event handling:

  use Bagisto\ApiPlatform\Events\WebhookEvent;
  
  event(new WebhookEvent('order.placed', $order));
  

Gotchas and Tips

Pitfalls

1. Breaking Changes (updated):

   • Cart Merging: Configurable products now require explicit quantity handling in CartTokenProcessor extensions. Use the new mergeStrategy to avoid silent failures.
   • Disabled Products: Wishlists now reject disabled products by default (fixed in v1.0.3, but v1.0.4 adds stricter validation). Use:

     $this->wishlistProvider->addItem($wishlistId, $productId, skipValidation: true);
     

   • Rate Limits: Tightened enforcement may break local testing. Use .env overrides:

     API_PLATFORM_RATE_LIMIT_STOREFRONT_PRODUCTS=100|minute
     API_PLATFORM_RATE_LIMIT_STOREFRONT_CART=200|minute
     

   • Webhook URLs: URLs are now validated against HTTPS by default. Use http:// only in development:

     $webhook = $this->webhookService->create(['url' => 'http://localhost:3000']);
     

2. Common Bugs (updated):

   • Translation Fallbacks: Products/variants may show null translations if active status isn’t set. Use:

     $product->setTranslationFallback(true)->setActive(true);
     

   • Quantity Increment: Moving a wishlist item to cart now respects preserveQuantities (default: true). Reset cart first if needed:

     $this->cartService->clear($customerId);
     

   • GraphQL Playground: Clear browser cache after updates. The new v1.0.4 playground includes schema validation:

     # Example of a validated query
     query {
       customerOrders(filter: {