Added Porter::importOne and accompanying test.

Fixed old referneces to Resource in docblocks.
Optimized PorterTest.

Author: Bilge

src/Porter/Collection/CountableProviderRecords.php

@@ -10,7 +10,7 @@ class CountableProviderRecords extends ProviderRecords implements \Countable
     /**
      * @param \Iterator $providerRecords
      * @param int $count
-     * @param Resource $resource
+     * @param ProviderResource $resource
      */
     public function __construct(\Iterator $providerRecords, $count, ProviderResource $resource)
     {

src/Porter/Collection/ProviderRecords.php

@@ -15,7 +15,7 @@ public function __construct(\Iterator $providerRecords, ProviderResource $resour
     }
 
     /**
-     * @return Resource
+     * @return ProviderResource
      */
     public function getResource()
     {

src/Porter/ImportException.php

@@ -0,0 +1,10 @@
+<?php
+namespace ScriptFUSION\Porter;
+
+/**
+ * The exception that is thrown when an import fails.
+ */
+class ImportException extends \RuntimeException
+{
+    // Intentionally empty.
+}

src/Porter/Porter.php

@@ -62,6 +62,32 @@ public function import(ImportSpecification $specification)
         return $this->createPorterRecords($records, clone $specification);
     }
 
+    /**
+     * Imports one record according to the design of the specified import specification.
+     *
+     * @param ImportSpecification $specification Import specification.
+     *
+     * @return mixed Data.
+     *
+     * @throws ImportException More than one record was imported.
+     */
+    public function importOne(ImportSpecification $specification)
+    {
+        $results = $this->import($specification);
+
+        if (!$results->valid()) {
+            return;
+        }
+
+        $one = $results->current();
+
+        if ($results->next() || $results->valid()) {
+            throw new ImportException('Cannot import one: more than one record imported.');
+        }
+
+        return $one;
+    }
+
     private function createPorterRecords(RecordCollection $records, ImportSpecification $specification)
     {
         if ($records instanceof \Countable) {

src/Porter/Provider/AbstractProvider.php

@@ -16,7 +16,7 @@ public function __construct(Connector $connector)
     }
 
     /**
-     * @param Resource $resource
+     * @param ProviderResource $resource
      *
      * @return \Iterator
      *

src/Porter/Specification/ImportSpecification.php

@@ -7,7 +7,7 @@
 
 class ImportSpecification
 {
-    /** @var Resource */
+    /** @var ProviderResource */
     private $resource;
 
     /** @var Mapping */
@@ -35,7 +35,7 @@ public function __clone()
     }
 
     /**
-     * @return Resource
+     * @return ProviderResource
      */
     final public function getResource()
     {

test/Integration/Porter/PorterTest.php

@@ -14,8 +14,10 @@
 use ScriptFUSION\Porter\Collection\MappedRecords;
 use ScriptFUSION\Porter\Collection\PorterRecords;
 use ScriptFUSION\Porter\Collection\ProviderRecords;
+use ScriptFUSION\Porter\ImportException;
 use ScriptFUSION\Porter\Porter;
 use ScriptFUSION\Porter\Provider\Provider;
+use ScriptFUSION\Porter\Provider\Resource\ProviderResource;
 use ScriptFUSION\Porter\Provider\StaticDataProvider;
 use ScriptFUSION\Porter\ProviderAlreadyRegisteredException;
 use ScriptFUSION\Porter\ProviderNotFoundException;
@@ -33,9 +35,12 @@ final class PorterTest extends \PHPUnit_Framework_TestCase
     /** @var Provider|MockInterface */
     private $provider;
 
-    /** @var Resource */
+    /** @var ProviderResource */
     private $resource;
 
+    /** @var ImportSpecification */
+    private $specification;
+
     protected function setUp()
     {
         $this->porter = (new Porter)->registerProvider(
@@ -48,6 +53,7 @@ protected function setUp()
         );
 
         $this->resource = MockFactory::mockResource($this->provider);
+        $this->specification = new ImportSpecification($this->resource);
     }
 
     public function testGetProvider()
@@ -85,14 +91,14 @@ public function testGetInvalidProvider()
     {
         $this->setExpectedException(ProviderNotFoundException::class);
 
-        (new Porter)->getProvider('foo');
+        $this->porter->getProvider('foo');
     }
 
     public function testGetInvalidTag()
     {
         $this->setExpectedException(ProviderNotFoundException::class);
 
-        (new Porter)->getProvider(get_class($this->provider), 'foo');
+        $this->porter->getProvider(get_class($this->provider), 'foo');
     }
 
     public function testGetStaticProviderTag()
@@ -102,26 +108,6 @@ public function testGetStaticProviderTag()
         $this->porter->getProvider(StaticDataProvider::class, 'foo');
     }
 
-    public function testImportTaggedResource()
-    {
-        $this->porter->registerProvider(
-            $provider = \Mockery::mock(Provider::class)
-                ->shouldReceive('fetch')
-                ->andReturn(new \ArrayIterator([$output = 'bar']))
-                ->getMock(),
-            $tag = 'foo'
-        );
-
-        $records = $this->porter->import(MockFactory::mockImportSpecification(
-            MockFactory::mockResource($provider)
-                ->shouldReceive('getProviderTag')
-                ->andReturn($tag)
-                ->getMock()
-        ));
-
-        self::assertSame($output, $records->current());
-    }
-
     public function testHasProvider()
     {
         self::assertTrue($this->porter->hasProvider(get_class($this->provider)));
@@ -131,10 +117,10 @@ public function testHasProvider()
 
     public function testImport()
     {
-        $records = $this->porter->import($specification = new ImportSpecification($this->resource));
+        $records = $this->porter->import($this->specification);
 
         self::assertInstanceOf(PorterRecords::class, $records);
-        self::assertNotSame($specification, $records->getSpecification());
+        self::assertNotSame($this->specification, $records->getSpecification());
         self::assertInstanceOf(ProviderRecords::class, $records->getPreviousCollection());
         self::assertSame('foo', $records->current());
     }
@@ -194,12 +180,57 @@ public function testImportAndFilterCountableRecords()
         self::assertNotInstanceOf(\Countable::class, $records);
     }
 
+    public function testImportOne()
+    {
+        $result = $this->porter->importOne($this->specification);
+
+        self::assertSame('foo', $result);
+    }
+
+    public function testImportOneOfNone()
+    {
+        $this->provider->shouldReceive('fetch')->andReturn(new \EmptyIterator);
+
+        $result = $this->porter->importOne($this->specification);
+
+        self::assertNull($result);
+    }
+
+    public function testImportOneOfMany()
+    {
+        $this->setExpectedException(ImportException::class);
+
+        $this->provider->shouldReceive('fetch')->andReturn(new \ArrayIterator(['foo', 'bar']));
+
+        $this->porter->importOne($this->specification);
+    }
+
+    public function testImportTaggedResource()
+    {
+        $this->porter->registerProvider(
+            $provider = \Mockery::mock(Provider::class)
+                ->shouldReceive('fetch')
+                ->andReturn(new \ArrayIterator([$output = 'bar']))
+                ->getMock(),
+            $tag = 'foo'
+        );
+
+        $records = $this->porter->import(MockFactory::mockImportSpecification(
+            MockFactory::mockResource($provider)
+                ->shouldReceive('getProviderTag')
+                ->andReturn($tag)
+                ->getMock()
+        ));
+
+        self::assertSame($output, $records->current());
+    }
+
     public function testFilter()
     {
         $this->provider->shouldReceive('fetch')->andReturn(new \ArrayIterator(range(1, 10)));
 
         $records = $this->porter->import(
-            (new ImportSpecification($this->resource))
+            $this->specification
                 ->setFilter(function ($record) {
                     return $record % 2;
                 })
@@ -219,9 +250,7 @@ public function testMap()
                 ->once()
                 ->andReturn(new \ArrayIterator($result = ['foo' => 'bar']))
                 ->getMock()
-        )->import(
-            (new ImportSpecification($this->resource))->setMapping(\Mockery::mock(Mapping::class))
-        );
+        )->import($this->specification->setMapping(\Mockery::mock(Mapping::class)));
 
         self::assertInstanceOf(PorterRecords::class, $records);
         self::assertInstanceOf(MappedRecords::class, $records->getPreviousCollection());
@@ -246,6 +275,6 @@ public function testCacheUnavailable()
     {
         $this->setExpectedException(CacheUnavailableException::class);
 
-        $this->porter->import((new ImportSpecification($this->resource))->setCacheAdvice(CacheAdvice::MUST_CACHE()));
+        $this->porter->import($this->specification->setCacheAdvice(CacheAdvice::MUST_CACHE()));
     }
 }

test/MockFactory.php

@@ -19,7 +19,7 @@ public static function mockImportSpecification(ProviderResource $resource = null
     /**
      * @param Provider $provider
      *
-     * @return MockInterface|Resource
+     * @return MockInterface|ProviderResource
      */
     public static function mockResource(Provider $provider)
     {

test/Unit/Porter/ImportSpecificationTest.php

@@ -11,7 +11,7 @@ final class ImportSpecificationTest extends \PHPUnit_Framework_TestCase
     /** @var ImportSpecification */
     private $specification;
 
-    /** @var Resource */
+    /** @var ProviderResource */
     private $resource;
 
     protected function setUp()