Shopify Services Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require clrz/shopify-services
   

   Ensure shopify/php-api is also installed (this package depends on it).

2. Configure Shopify Credentials Add your Shopify API credentials to .env:

   SHOPIFY_STORE_URL=https://your-store.myshopify.com
   SHOPIFY_API_KEY=your_api_key
   SHOPIFY_API_SECRET=your_api_secret
   SHOPIFY_ACCESS_TOKEN=your_access_token
   

3. Initialize the Client In a service provider (e.g., AppServiceProvider):

   use Clrz\ShopifyServices\ShopifyClient;
   
   public function register()
   {
       $this->app->singleton(ShopifyClient::class, function ($app) {
           return new ShopifyClient(
               config('shopify.store_url'),
               config('shopify.api_key'),
               config('shopify.api_secret'),
               config('shopify.access_token')
           );
       });
   }
   

4. First Use Case: Fetch Products

   use Clrz\ShopifyServices\Services\ProductService;
   
   $productService = app(ProductService::class);
   $products = $productService->getProducts(['limit' => 5]);
   

Implementation Patterns

Common Workflows

1. Service Layer Abstraction Use the pre-built services (ProductService, CustomerService, OrderService, etc.) to encapsulate API calls:

   $orderService = app(OrderService::class);
   $order = $orderService->createOrder([
       'line_items' => [
           ['variant_id' => 12345, 'quantity' => 2],
       ],
       'email' => 'customer@example.com',
   ]);
   

2. Bulk Operations Leverage batch methods for efficiency (e.g., updating multiple products):

   $productService->updateProducts([
       ['id' => 1, 'title' => 'Updated Product 1'],
       ['id' => 2, 'title' => 'Updated Product 2'],
   ]);
   

3. Webhook Handling Use the WebhookService to validate and process incoming Shopify webhooks:

   $webhookService = app(WebhookService::class);
   $isValid = $webhookService->validateWebhook(
       $request->input(),
       config('shopify.webhook_topic'),
       config('shopify.webhook_secret')
   );
   

4. Custom API Calls For unsupported endpoints, use the raw client:

   $client = app(ShopifyClient::class);
   $response = $client->get('/admin/api/2023-01/custom_collections.json');
   

Integration Tips

• Laravel Events: Trigger events after Shopify operations (e.g., OrderCreated):

  event(new OrderCreated($order));
  

• Queues: Offload long-running tasks (e.g., bulk product imports) to queues.
• Caching: Cache frequent reads (e.g., product lists) using Laravel’s cache:

  $products = Cache::remember('shopify_products', now()->addHours(1), function () {
      return $productService->getProducts();
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated SDK The package relies on shopify/php-api, which may lag behind Shopify’s latest API versions. Check compatibility:

   composer show shopify/php-api
   

   • Fix: Manually patch API calls or fork the package if needed.

2. Rate Limiting Shopify enforces rate limits (e.g., 2 calls/second for most endpoints). Handle throttling:

   try {
       $productService->getProducts();
   } catch (RateLimitExceededException $e) {
       sleep(1); // Retry after delay
   }
   

3. Webhook Secrets Ensure SHOPIFY_WEBHOOK_SECRET matches the HMAC secret in your Shopify store settings. Mismatches will invalidate webhooks.

4. Idempotency Some operations (e.g., order creation) lack built-in idempotency. Use custom headers or database checks:

   $client->setHeader('X-Request-Id', uniqid());
   

Debugging

• Enable Debugging Configure the Shopify client to log requests:

  $client = new ShopifyClient(..., true); // Enable debug mode
  

  Logs appear in storage/logs/shopify.log.

• Common Errors

  • Invalid API Key: Verify .env credentials.
  • 404 Not Found: Check endpoint URLs (e.g., /admin/api/2023-01/products.json).
  • 429 Too Many Requests: Implement exponential backoff.

Extension Points

1. Custom Services Extend existing services or create new ones by implementing ShopifyServiceInterface:

   class CustomService implements ShopifyServiceInterface {
       public function __construct(ShopifyClient $client) {}
       public function customMethod() {}
   }
   

2. Middleware Add middleware to the client for logging, auth, or retries:

   $client->addMiddleware(new CustomMiddleware());
   

3. Testing Mock the ShopifyClient in tests:

   $mock = Mockery::mock(ShopifyClient::class);
   $mock->shouldReceive('get')->andReturn(['data' => []]);
   $this->app->instance(ShopifyClient::class, $mock);