Porter 4.0 release candidate

.travis.yml

@@ -10,6 +10,7 @@ php:
   - 5.6
   - 7.0
   - 7.1
+  - 7.2
 
 env:
   matrix:
@@ -21,7 +22,7 @@ matrix:
 
 cache:
   directories:
-    - .composer/cache
+    - vendor
 
 install:
   - alias composer=composer\ -n && composer selfupdate
@@ -32,5 +33,4 @@ script:
   - composer test -- --coverage-clover=build/logs/clover.xml
 
 after_success:
-  - composer require satooshi/php-coveralls
-  - vendor/bin/coveralls -v
+  - bash <(curl -s https://codecov.io/bash)

composer.json

@@ -10,20 +10,19 @@
   "license": "LGPL-3.0",
   "require": {
     "php": "^5.5|^7",
-    "connectors/http": "^1",
-    "connectors/soap": "^1",
     "scriptfusion/static-class": "^1",
     "scriptfusion/retry": "^1.1",
-    "scriptfusion/retry-exception-handlers": "^1",
-    "eloquent/enumeration": "^5",
+    "scriptfusion/retry-exception-handlers": "^1.1",
+    "psr/container": "^1",
     "psr/cache": "^1"
   },
   "require-dev": {
     "phpunit/phpunit": "^4.8",
     "mockery/mockery": "^0.9.4"
   },
   "suggest" : {
-    "transformers/mapping": "Transforms array collections using Mappings."
+    "connectors/http": "Provides an HTTP connector for Porter providers.",
+    "transformers/mapping-transformer": "Transforms records using Mappings."
   },
   "autoload": {
     "psr-4": {
@@ -37,10 +36,5 @@
   },
   "scripts": {
     "test": "phpunit -c test"
-  },
-  "extra": {
-    "branch-alias": {
-      "dev-master": "3-dev"
-    }
   }
 }

src/Cache/CacheKeyGenerator.php

@@ -3,6 +3,8 @@
 
 interface CacheKeyGenerator
 {
+    const RESERVED_CHARACTERS = '{}()/\@:';
+
     /**
      * @param string $source
      * @param array $sortedOptions Options sorted by key.

src/Cache/CacheUnavailableException.php

@@ -6,10 +6,10 @@
 /**
  * The exception that is thrown when cache is unavailable.
  */
-class CacheUnavailableException extends \RuntimeException implements CacheException
+final class CacheUnavailableException extends \RuntimeException implements CacheException
 {
-    public static function modify()
+    public static function createUnsupported()
     {
-        return new self('Cannot modify cache: cache unavailable.');
+        return new self('Cannot cache: connector does not support caching.');
     }
 }

src/Cache/JsonCacheKeyGenerator.php

@@ -1,14 +1,12 @@
 <?php
 namespace ScriptFUSION\Porter\Cache;
 
-use ScriptFUSION\Porter\Connector\CachingConnector;
-
 class JsonCacheKeyGenerator implements CacheKeyGenerator
 {
     public function generateCacheKey($source, array $sortedOptions)
     {
         return str_replace(
-            str_split(CachingConnector::RESERVED_CHARACTERS),
+            str_split(self::RESERVED_CHARACTERS),
             '.',
             json_encode([$source, $sortedOptions], JSON_UNESCAPED_SLASHES)
         );

src/Collection/RecordCollection.php

@@ -10,32 +10,54 @@ abstract class RecordCollection implements \Iterator
 
     private $previousCollection;
 
-    public function __construct(\Iterator $records, RecordCollection $previousCollection = null)
+    public function __construct(\Iterator $records, self $previousCollection = null)
     {
         $this->records = $records;
         $this->previousCollection = $previousCollection;
     }
 
+    /**
+     * @return array
+     */
     public function current()
     {
-        return $this->records->current();
+        $current = $this->records->current();
+
+        // TODO: Consider removing when dropping PHP 5 support (replace with type hint).
+        if (!is_array($current)) {
+            throw new \RuntimeException('Record collection did not return an array.');
+        }
+
+        return $current;
     }
 
+    /**
+     * @return void
+     */
     public function next()
     {
         $this->records->next();
     }
 
+    /**
+     * @return mixed
+     */
     public function key()
     {
         return $this->records->key();
     }
 
+    /**
+     * @return bool
+     */
     public function valid()
     {
         return $this->records->valid();
     }
 
+    /**
+     * @return void
+     */
     public function rewind()
     {
         $this->records->rewind();

src/Connector/CachingConnector.php

@@ -3,127 +3,101 @@
 
 use Psr\Cache\CacheItemPoolInterface;
 use ScriptFUSION\Porter\Cache\CacheKeyGenerator;
-use ScriptFUSION\Porter\Cache\CacheToggle;
 use ScriptFUSION\Porter\Cache\InvalidCacheKeyException;
 use ScriptFUSION\Porter\Cache\JsonCacheKeyGenerator;
 use ScriptFUSION\Porter\Cache\MemoryCache;
-use ScriptFUSION\Porter\Options\EncapsulatedOptions;
 
 /**
- * Caches remote data using PSR-6-compliant objects.
+ * Wraps a connector to cache fetched data using PSR-6-compliant objects.
  */
-abstract class CachingConnector implements Connector, CacheToggle
+class CachingConnector implements Connector, ConnectorWrapper
 {
-    const RESERVED_CHARACTERS = '{}()/\@:';
-
     /**
-     * @var CacheItemPoolInterface
+     * @var Connector
      */
-    private $cache;
+    private $connector;
 
     /**
-     * @var bool
+     * @var CacheItemPoolInterface
      */
-    private $cacheEnabled = true;
+    private $cache;
 
     /**
      * @var CacheKeyGenerator
      */
     private $cacheKeyGenerator;
 
-    public function __construct(CacheItemPoolInterface $cache = null, CacheKeyGenerator $cacheKeyGenerator = null)
-    {
+    public function __construct(
+        Connector $connector,
+        CacheItemPoolInterface $cache = null,
+        CacheKeyGenerator $cacheKeyGenerator = null
+    ) {
+        $this->connector = $connector;
         $this->cache = $cache ?: new MemoryCache;
         $this->cacheKeyGenerator = $cacheKeyGenerator ?: new JsonCacheKeyGenerator;
     }
 
+    public function __clone()
+    {
+        $this->connector = clone $this->connector;
+
+        /* It doesn't make sense to clone the cache because we want cache state to be shared between imports.
+           We're also not cloning the CacheKeyGenerator because they're expected to be stateless algorithms. */
+    }
+
     /**
+     * @param ConnectionContext $context
      * @param string $source
-     * @param EncapsulatedOptions|null $options
      *
      * @return mixed
      *
      * @throws InvalidCacheKeyException
      */
-    public function fetch($source, EncapsulatedOptions $options = null)
+    public function fetch(ConnectionContext $context, $source)
     {
-        if ($this->isCacheEnabled()) {
-            $optionsCopy = $options ? $options->copy() : [];
-
-            ksort($optionsCopy);
+        if ($context->mustCache()) {
+            $options = $this->connector instanceof ConnectorOptions ? $this->connector->getOptions()->copy() : [];
+            ksort($options);
 
-            $key = $this->validateCacheKey($this->getCacheKeyGenerator()->generateCacheKey($source, $optionsCopy));
+            $this->validateCacheKey($key = $this->cacheKeyGenerator->generateCacheKey($source, $options));
 
             if ($this->cache->hasItem($key)) {
                 return $this->cache->getItem($key)->get();
             }
         }
 
-        $data = $this->fetchFreshData($source, $options);
+        $data = $this->connector->fetch($context, $source);
 
         isset($key) && $this->cache->save($this->cache->getItem($key)->set($data));
 
         return $data;
     }
 
-    abstract public function fetchFreshData($source, EncapsulatedOptions $options = null);
-
-    public function getCache()
-    {
-        return $this->cache;
-    }
-
-    public function setCache(CacheItemPoolInterface $cache)
-    {
-        $this->cache = $cache;
-    }
-
-    public function enableCache()
-    {
-        $this->cacheEnabled = true;
-    }
-
-    public function disableCache()
-    {
-        $this->cacheEnabled = false;
-    }
-
-    public function isCacheEnabled()
-    {
-        return $this->cacheEnabled;
-    }
-
-    public function getCacheKeyGenerator()
-    {
-        return $this->cacheKeyGenerator;
-    }
-
-    public function setCacheKeyGenerator(CacheKeyGenerator $cacheKeyGenerator)
-    {
-        $this->cacheKeyGenerator = $cacheKeyGenerator;
-    }
-
     /**
      * @param mixed $key
      *
-     * @return string
+     * @return void
      *
      * @throws InvalidCacheKeyException Cache key contains invalid data.
      */
     private function validateCacheKey($key)
     {
+        // TODO: Remove when PHP 5 support dropped and replace with string hint.
         if (!is_string($key)) {
             throw new InvalidCacheKeyException('Cache key must be a string.');
         }
 
-        if (strpbrk($key, self::RESERVED_CHARACTERS) !== false) {
+        if (strpbrk($key, CacheKeyGenerator::RESERVED_CHARACTERS) !== false) {
             throw new InvalidCacheKeyException(sprintf(
                 'Cache key "%s" contains one or more reserved characters: "%s".',
                 $key,
-                self::RESERVED_CHARACTERS
+                CacheKeyGenerator::RESERVED_CHARACTERS
             ));
         }
+    }
 
-        return $key;
+    public function getWrappedConnector()
+    {
+        return $this->connector;
     }
 }