Added SingleRecordResource interface that resources must implement to be used with Porter::importOne().

Author: Bilge

src/IncompatibleResourceException.php

@@ -0,0 +1,18 @@
+<?php
+declare(strict_types=1);
+
+namespace ScriptFUSION\Porter;
+
+use ScriptFUSION\Porter\Provider\Resource\SingleRecordResource;
+
+/**
+ * The exception that is throw when a resource is incompatible with an importOne operation because it is not marked
+ * with the single record interface.
+ */
+final class IncompatibleResourceException extends \LogicException
+{
+    public function __construct()
+    {
+        parent::__construct('Cannot import one: resource does not implement ' . SingleRecordResource::class . '.');
+    }
+}

src/Porter.php

@@ -21,6 +21,7 @@
 use ScriptFUSION\Porter\Provider\Provider;
 use ScriptFUSION\Porter\Provider\ProviderFactory;
 use ScriptFUSION\Porter\Provider\Resource\ProviderResource;
+use ScriptFUSION\Porter\Provider\Resource\SingleRecordResource;
 use ScriptFUSION\Porter\Specification\AsyncImportSpecification;
 use ScriptFUSION\Porter\Specification\ImportSpecification;
 use ScriptFUSION\Porter\Transform\AsyncTransformer;
@@ -86,6 +87,10 @@ public function import(ImportSpecification $specification): PorterRecords
      */
     public function importOne(ImportSpecification $specification): ?array
     {
+        if (!$specification->getResource() instanceof SingleRecordResource) {
+            throw new IncompatibleResourceException;
+        }
+
         $results = $this->import($specification);
 
         if (!$results->valid()) {
@@ -162,6 +167,10 @@ public function importAsync(AsyncImportSpecification $specification): AsyncRecor
     public function importOneAsync(AsyncImportSpecification $specification): Promise
     {
         return call(function () use ($specification) {
+            if (!$specification->getAsyncResource() instanceof SingleRecordResource) {
+                throw new IncompatibleResourceException;
+            }
+
             $results = $this->importAsync($specification);
 
             yield $results->advance();

src/Provider/Resource/SingleRecordResource.php

@@ -0,0 +1,13 @@
+<?php
+declare(strict_types=1);
+
+namespace ScriptFUSION\Porter\Provider\Resource;
+
+/**
+ * Marker interface that specifies a resource that only fetches a single record and whose iterator is thus only valid
+ * for one iteration. Such resources are intended to be used with Porter::importOne() rather than import().
+ */
+interface SingleRecordResource
+{
+    // Marker interface.
+}

test/Integration/PorterAsyncTest.php

@@ -12,9 +12,12 @@
 use ScriptFUSION\Porter\ForeignResourceException;
 use ScriptFUSION\Porter\ImportException;
 use ScriptFUSION\Porter\IncompatibleProviderException;
+use ScriptFUSION\Porter\IncompatibleResourceException;
 use ScriptFUSION\Porter\Porter;
 use ScriptFUSION\Porter\PorterAware;
 use ScriptFUSION\Porter\Provider\Provider;
+use ScriptFUSION\Porter\Provider\Resource\AsyncResource;
+use ScriptFUSION\Porter\Provider\Resource\SingleRecordResource;
 use ScriptFUSION\Porter\Specification\AsyncImportSpecification;
 use ScriptFUSION\Porter\Transform\AsyncTransformer;
 use ScriptFUSION\Porter\Transform\FilterTransformer;
@@ -51,6 +54,17 @@ public function testImportOneAsync(): \Generator
         self::assertSame(['foo'], yield $this->porter->importOneAsync($this->specification));
     }
 
+    /**
+     * Tests that when importing one from a resource not marked with SingleRecordResource, an exception is thrown.
+     */
+    public function testImportOneNonSingleAsync(): \Generator
+    {
+        $this->expectException(IncompatibleResourceException::class);
+        $this->expectExceptionMessage(SingleRecordResource::class);
+
+        yield $this->porter->importOneAsync(new AsyncImportSpecification(\Mockery::mock(AsyncResource::class)));
+    }
+
     /**
      * Tests that when the resource is countable, the count is propagated to the outermost collection and the records
      * are intact.

test/Integration/PorterSyncTest.php

@@ -16,8 +16,11 @@
 use ScriptFUSION\Porter\ForeignResourceException;
 use ScriptFUSION\Porter\ImportException;
 use ScriptFUSION\Porter\IncompatibleProviderException;
+use ScriptFUSION\Porter\IncompatibleResourceException;
 use ScriptFUSION\Porter\PorterAware;
 use ScriptFUSION\Porter\Provider\AsyncProvider;
+use ScriptFUSION\Porter\Provider\Resource\ProviderResource;
+use ScriptFUSION\Porter\Provider\Resource\SingleRecordResource;
 use ScriptFUSION\Porter\ProviderNotFoundException;
 use ScriptFUSION\Porter\Specification\ImportSpecification;
 use ScriptFUSION\Porter\Specification\StaticDataImportSpecification;
@@ -209,6 +212,17 @@ public function testImportOneOfMany(): void
         $this->porter->importOne($this->specification);
     }
 
+    /**
+     * Tests that when importing one from a resource not marked with SingleRecordResource, an exception is thrown.
+     */
+    public function testImportOneNonSingleAsync(): \Generator
+    {
+        $this->expectException(IncompatibleResourceException::class);
+        $this->expectExceptionMessage(SingleRecordResource::class);
+
+        yield $this->porter->importOne(new ImportSpecification(\Mockery::mock(ProviderResource::class)));
+    }
+
     #endregion
 
     #region Durability

test/MockFactory.php

@@ -16,6 +16,7 @@
 use ScriptFUSION\Porter\Provider\Provider;
 use ScriptFUSION\Porter\Provider\Resource\AsyncResource;
 use ScriptFUSION\Porter\Provider\Resource\ProviderResource;
+use ScriptFUSION\Porter\Provider\Resource\SingleRecordResource;
 use ScriptFUSION\StaticClass;
 
 final class MockFactory
@@ -54,7 +55,7 @@ public static function mockProvider()
      */
     public static function mockResource(Provider $provider, \Iterator $return = null)
     {
-        $resource = \Mockery::mock(ProviderResource::class, AsyncResource::class)
+        $resource = \Mockery::mock(ProviderResource::class, AsyncResource::class, SingleRecordResource::class)
             ->shouldReceive('getProviderClassName')
                 ->andReturn(\get_class($provider))
             ->shouldReceive('fetch')