Add failed() logging and event to ProductImport (#326)

Author: ryanmitchell

docs/content/en/CMS/importing-data.md

@@ -62,6 +62,29 @@ In multi-store mode you can specify the store the product belongs to:
 php artisan shopify:import:product ID_HERE --store=uk
 ```
 
+## Import Failures
+
+When an import job fails after all retries are exhausted, two things happen automatically:
+
+1. The error is written to your Laravel log with the product ID and, in multi-store mode, the store handle.
+2. A `ProductImportFailed` event is fired, which you can listen for to add your own handling (notifications, alerts, etc.).
+
+```php
+use StatamicRadPack\Shopify\Events\ProductImportFailed;
+
+class AppServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        Event::listen(ProductImportFailed::class, function (ProductImportFailed $event) {
+            // $event->productId   — the Shopify product ID
+            // $event->storeHandle — the store handle (null in single-store mode)
+            // $event->exception   — the Throwable that caused the failure
+        });
+    }
+}
+```
+
 ## API Rate Limiting
 
 The importer automatically handles Shopify's GraphQL API throttling. After each query, it inspects the `extensions.cost.throttleStatus` returned by Shopify. If the available query budget drops below 500 points, the importer pauses briefly (calculated from Shopify's restore rate) before continuing.

docs/content/en/CMS/webhooks.md

@@ -120,3 +120,5 @@ StatamicRadPack\Shopify\Events\OrderCreate
 ```
 
 Each event has one property `$data` with the payload data decoded to a `stdClass`.
+
+For import job failures, see `ProductImportFailed` documented in [Importing Data](/CMS/importing-data#import-failures).

src/Events/ProductImportFailed.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace StatamicRadPack\Shopify\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+use Throwable;
+
+class ProductImportFailed
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(
+        public int $productId,
+        public ?string $storeHandle,
+        public Throwable $exception,
+    ) {}
+}

src/Jobs/ImportSingleProductJob.php

@@ -3,6 +3,7 @@
 namespace StatamicRadPack\Shopify\Jobs;
 
 use Carbon\Carbon;
+use Throwable;
 use Illuminate\Bus\Queueable;
 use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Foundation\Bus\Dispatchable;
@@ -14,6 +15,7 @@
 use Statamic\Facades\Term;
 use Statamic\Support\Arr;
 use Statamic\Support\Str;
+use StatamicRadPack\Shopify\Events\ProductImportFailed;
 use StatamicRadPack\Shopify\Support\StoreConfig;
 use StatamicRadPack\Shopify\Traits\SavesImagesAndMetafields;
 use StatamicRadPack\Shopify\Traits\ThrottlesShopifyRequests;
@@ -700,6 +702,21 @@ private function removeOldVariants(array $variants, string $productSlug)
             });
     }
 
+    /**
+     * Handle a job failure — log the error and fire an event.
+     */
+    public function failed(Throwable $exception): void
+    {
+        $context = array_filter([
+            'product_id' => $this->productId,
+            'store' => $this->storeHandle,
+        ]);
+
+        Log::error('Shopify: ImportSingleProductJob failed for product '.$this->productId.': '.$exception->getMessage(), $context);
+
+        ProductImportFailed::dispatch($this->productId, $this->storeHandle, $exception);
+    }
+
     /**
      * Update the purchase history for this item
      */

src/ServiceProvider.php

@@ -18,11 +18,11 @@ class ServiceProvider extends AddonServiceProvider
     protected $publishAfterInstall = false;
 
     protected $commands = [
+        Commands\ShopifyImportCollections::class,
         Commands\ShopifyImportProducts::class,
         Commands\ShopifyImportSingleProduct::class,
-        Commands\ShopifyImportCollections::class,
-        Commands\ShopifyMultistoreEnable::class,
         Commands\ShopifyMultistoreDisable::class,
+        Commands\ShopifyMultistoreEnable::class,
         Commands\ShopifyWebhooksRegister::class,
     ];
 

tests/Unit/ProductImportFailedTest.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace StatamicRadPack\Shopify\Tests\Unit;
+
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\Log;
+use PHPUnit\Framework\Attributes\Test;
+use RuntimeException;
+use StatamicRadPack\Shopify\Events\ProductImportFailed;
+use StatamicRadPack\Shopify\Jobs\ImportSingleProductJob;
+use StatamicRadPack\Shopify\Tests\TestCase;
+
+class ProductImportFailedTest extends TestCase
+{
+    #[Test]
+    public function logs_error_on_failure()
+    {
+        Log::shouldReceive('error')
+            ->once()
+            ->withArgs(function (string $message, array $context) {
+                return str_contains($message, '12345')
+                    && $context['product_id'] === 12345;
+            });
+
+        $job = new ImportSingleProductJob(12345);
+        $job->failed(new RuntimeException('Something went wrong'));
+    }
+
+    #[Test]
+    public function includes_store_handle_in_log_context_when_present()
+    {
+        Log::shouldReceive('error')
+            ->once()
+            ->withArgs(function (string $message, array $context) {
+                return $context['product_id'] === 12345
+                    && $context['store'] === 'uk';
+            });
+
+        $job = new ImportSingleProductJob(12345, [], 'uk');
+        $job->failed(new RuntimeException('Something went wrong'));
+    }
+
+    #[Test]
+    public function omits_store_from_log_context_in_single_store_mode()
+    {
+        Log::shouldReceive('error')
+            ->once()
+            ->withArgs(function (string $message, array $context) {
+                return ! array_key_exists('store', $context);
+            });
+
+        $job = new ImportSingleProductJob(12345);
+        $job->failed(new RuntimeException('Something went wrong'));
+    }
+
+    #[Test]
+    public function fires_product_import_failed_event()
+    {
+        Event::fake();
+        Log::shouldReceive('error')->once();
+
+        $exception = new RuntimeException('Something went wrong');
+
+        $job = new ImportSingleProductJob(12345);
+        $job->failed($exception);
+
+        Event::assertDispatched(ProductImportFailed::class, function ($event) use ($exception) {
+            return $event->productId === 12345
+                && $event->storeHandle === null
+                && $event->exception === $exception;
+        });
+    }
+
+    #[Test]
+    public function event_carries_store_handle_in_multi_store_mode()
+    {
+        Event::fake();
+        Log::shouldReceive('error')->once();
+
+        $job = new ImportSingleProductJob(99, [], 'uk');
+        $job->failed(new RuntimeException('Timeout'));
+
+        Event::assertDispatched(ProductImportFailed::class, function ($event) {
+            return $event->productId === 99
+                && $event->storeHandle === 'uk';
+        });
+    }
+}