Bagisto Api Laravel Package

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

1. **Installation** (updated for v1.0.5):
   ```bash
   composer require bagisto/api-platform:^1.0.5
   php artisan bagisto-api-platform:install --force --optimize  # Added --optimize flag for production-ready setup
   php artisan migrate --seed --with-test-data  # New flag for comprehensive test data seeding

The install command now includes optimized database configurations and pre-configured queues for async operations.

2. First Use Case (updated):

   • Customer Account APIs: Test the new CustomerOrderProvider with v1.0.5's enhanced analytics:

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

   • GraphQL Playground: Access /graphiql to explore new v1.0.5 subscriptions and persisted queries:

     subscription {
       orderStatusUpdates {
         orderId
         status
         # New field: analytics
         analytics {
           lifetimeValue
           avgOrderValue
         }
       }
     }
     

   • New Seed Data: Use the /api/seed-data?comprehensive=true endpoint for full test suite data:

     curl -X GET http://your-app.test/api/seed-data?comprehensive=true
     

3. Key Configs (updated):

   • Review config/api-platform.php for new OpenAPI v3.1.1 compliance and async operation support.
   • Check config/api-platform-vendor.php for queue-based rate limit overrides (now supports delayed throttling).
   • New Locale Header: Accept-Language now supports negotiation strategies (e.g., Accept-Language: en-US;q=0.9,en;q=0.8;strategy=strict).
   • Webhook Config: Added config/api-platform-webhooks.php with retry policies and event batching.

Implementation Patterns

Core Workflows

1. Customer-Centric APIs (updated):

   • Order Analytics: Access new lifetime value metrics via CustomerOrderAnalyticsProvider:

     $analytics = $this->customerOrderAnalyticsProvider->getAnalytics($customerId);
     // Returns: { lifetimeValue: 1250.50, avgOrderValue: 75.00, orderCount: 17 }
     

   • Subscription Orders: Use SubscriptionOrderProcessor with new pause/resume logic:

     $this->subscriptionOrderProcessor->pause($subscriptionId, $customerId);
     $this->subscriptionOrderProcessor->resume($subscriptionId, $customerId);
     

   • Profile Management: Use CustomerProfileOutput with new privacy controls:

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

2. Catalog & Storefront (updated):

   • Dynamic Content: Fetch locales/categories with new includeMediaMetadata flag (v1.0.5):

     GET /api/locales?includeMediaMetadata=true
     Accept-Language: fr-CA
     

   • Booking Products: Query slots with new timezone and bufferMinutes parameters:

     query {
       bookingSlots(productId: "123", timezone: "Europe/Paris", bufferMinutes: 15) {
         availableSlots
         bufferWarning
       }
     }
     

   • CMS Pages: Look up by URL key with new version and draftMode parameters:

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

3. Cart/Wishlist/Compare (updated):

   • Smart Cart Merging: Extend CartTokenProcessor with new mergeStrategy and conflictResolver:

     $mergedCart = $this->cartTokenProcessor->merge($token1, $token2, [
         'strategy' => 'prioritize_latest',
         'conflictResolver' => 'overwrite'  // Options: 'overwrite', 'merge', 'skip'
     ]);
     

   • Wishlist-to-Cart: Use MoveWishlistToCartProcessor with new excludeOutOfStock flag:

     $this->moveWishlistToCartProcessor->execute(
         new MoveWishlistToCartInput($wishlistId, $customerId, excludeOutOfStock: true)
     );
     

   • Compare Products: New CompareProductProvider with enhanced attribute handling:

     $comparison = $this->compareProductProvider->getComparison([$productId1, $productId2], [
         'includeAttributes' => ['color', 'size', 'material']
     ]);
     

4. Infrastructure (updated):

   • Async Operations: Queue new OrderPlacementJob for background processing:

     $this->orderPlacementJob->dispatch($orderData);
     

   • Pagination: Adopt new cursor-based pagination with metadata and async loading:

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

   • Cache Management: Clear new cache groups with TTL overrides:

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

5. Webhooks (updated):

   • Subscribe to events with new retry policies:

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

   • Trigger webhooks with batch support:

     $this->webhookService->triggerBatch('order.placed', [$order1, $order2]);
     

Integration Tips

• GraphQL Subscriptions: Use new persisted queries for performance-critical subscriptions:

  subscription OrderStatusUpdate($orderId: ID!) {
    orderStatusUpdates(filter: {orderId: {eq: $orderId}}) {
      orderId
      status
    }
  }
  

• Localization: Set Accept-Language headers with new negotiation strategies:

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

• Rate Limiting: Configure queue-based throttling in api-platform-vendor.php:

  'rate_limits' => [
      'storefront/products' => ['limit' => 60, 'period' => 'minute', 'queue' => true],
  ],
  

• Webhooks: Use the new WebhookEventBatch class for bulk event handling:

  use Bagisto\ApiPlatform\Events\WebhookEventBatch;
  
  event(new WebhookEventBatch('order.placed', [$order1, $order2]));
  

Gotchas and Tips

Pitfalls

1. Breaking Changes (updated):

   • Async Operations: All order placements now default to async (v1.0.5). Use sync flag for synchronous behavior:

     $this->orderPlacementJob->dispatch($orderData, sync: true);
     

   • Webhook URLs: HTTPS enforcement is now stricter. Use http:// only in development with explicit config:

     config(['api-platform-webhooks.allow_http' => true]);
     

   • Rate Limits: Queue-based throttling may cause delays. Monitor failed_jobs table for timeouts.
   • GraphQL Subscriptions: Persisted queries are required for subscriptions. Use the new graphql-persist CLI tool:

     php artisan graphql-persist:generate
     

2. Common Bugs (updated):

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

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

   • Quantity Handling: Moving wishlist items to cart now respects excludeOutOfStock (default: