Added docblock documentation to Transformer.

Split transformation in Porter into separate method.

Author: Bilge

src/Porter.php

@@ -15,6 +15,7 @@
 use ScriptFUSION\Porter\Provider\ProviderFactory;
 use ScriptFUSION\Porter\Provider\Resource\ProviderResource;
 use ScriptFUSION\Porter\Specification\ImportSpecification;
+use ScriptFUSION\Porter\Transform\Transformer;
 use ScriptFUSION\Retry\ExceptionHandler\ExponentialBackoffExceptionHandler;
 
 /**
@@ -72,13 +73,7 @@ public function import(ImportSpecification $specification)
             $records = $this->createProviderRecords($records, $specification->getResource());
         }
 
-        foreach ($specification->getTransformers() as $transformer) {
-            if ($transformer instanceof PorterAware) {
-                $transformer->setPorter($this);
-            }
-
-            $records = $transformer->transform($records, $specification->getContext());
-        }
+        $records = $this->transformRecords($records, $specification->getTransformers(), $specification->getContext());
 
         return $this->createPorterRecords($records, $specification);
     }
@@ -109,27 +104,10 @@ public function importOne(ImportSpecification $specification)
         return $one;
     }
 
-    private function createProviderRecords(\Iterator $records, ProviderResource $resource)
-    {
-        if ($records instanceof \Countable) {
-            return new CountableProviderRecords($records, count($records), $resource);
-        }
-
-        return new ProviderRecords($records, $resource);
-    }
-
-    private function createPorterRecords(RecordCollection $records, ImportSpecification $specification)
-    {
-        if ($records instanceof \Countable) {
-            return new CountablePorterRecords($records, count($records), $specification);
-        }
-
-        return new PorterRecords($records, $specification);
-    }
-
     private function fetch(ProviderResource $resource, CacheAdvice $cacheAdvice = null)
     {
         $provider = $this->getProvider($resource->getProviderClassName(), $resource->getProviderTag());
+
         $this->applyCacheAdvice($provider, $cacheAdvice ?: $this->defaultCacheAdvice);
 
         if (($records = \ScriptFUSION\Retry\retry(
@@ -152,6 +130,44 @@ function (\Exception $exception) {
         throw new ImportException(get_class($provider) . '::fetch() did not return an Iterator.');
     }
 
+    /**
+     * @param RecordCollection $records
+     * @param Transformer[] $transformers
+     * @param mixed $context
+     *
+     * @return RecordCollection
+     */
+    private function transformRecords(RecordCollection $records, array $transformers, $context)
+    {
+        foreach ($transformers as $transformer) {
+            if ($transformer instanceof PorterAware) {
+                $transformer->setPorter($this);
+            }
+
+            $records = $transformer->transform($records, $context);
+        }
+
+        return $records;
+    }
+
+    private function createProviderRecords(\Iterator $records, ProviderResource $resource)
+    {
+        if ($records instanceof \Countable) {
+            return new CountableProviderRecords($records, count($records), $resource);
+        }
+
+        return new ProviderRecords($records, $resource);
+    }
+
+    private function createPorterRecords(RecordCollection $records, ImportSpecification $specification)
+    {
+        if ($records instanceof \Countable) {
+            return new CountablePorterRecords($records, count($records), $specification);
+        }
+
+        return new PorterRecords($records, $specification);
+    }
+
     private function applyCacheAdvice(Provider $provider, CacheAdvice $cacheAdvice)
     {
         try {
@@ -223,7 +239,7 @@ public function getProvider($name, $tag = null)
                 return $provider;
             }
         } catch (ObjectNotCreatedException $exception) {
-            // Intentionally empty.
+            // We will throw our own exception.
         }
 
         throw new ProviderNotFoundException(

src/Transform/Transformer.php

@@ -3,11 +3,16 @@
 
 use ScriptFUSION\Porter\Collection\RecordCollection;
 
+/**
+ * Provides a method to transform imported data.
+ */
 interface Transformer
 {
     /**
-     * @param RecordCollection $records
-     * @param mixed $context
+     * Transforms the specified record collection decorated with the specified context data.
+     *
+     * @param RecordCollection $records Record collection.
+     * @param mixed $context Context data.
      *
      * @return RecordCollection
      */