Changed Connector and AsyncConnector fetch() method parameter order.

Although this seems at first glance like a pointless BC break, we
already broke BC with connectors when retry() was removed from
ConnectionContext. Typical Connector implementations should no longer be
concerned with the ConnectionContext at all, so we'd rather move it to
the secondary position, since the source is always needed and thus
should be the primary parameter.

Author: Bilge

src/Connector/AsyncConnector.php

@@ -11,10 +11,10 @@ interface AsyncConnector
     /**
      * Fetches data from the specified source.
      *
-     * @param ConnectionContext $context Runtime connection settings and methods.
      * @param string $source Source.
+     * @param ConnectionContext $context Runtime connection settings and methods.
      *
      * @return \Closure Closure that returns a Promise or raw data.
      */
-    public function fetchAsync(ConnectionContext $context, string $source): \Closure;
+    public function fetchAsync(string $source, ConnectionContext $context): \Closure;
 }

src/Connector/CachingConnector.php

@@ -50,14 +50,14 @@ public function __clone()
     }
 
     /**
-     * @param ConnectionContext $context
      * @param string $source
+     * @param ConnectionContext $context
      *
      * @return mixed
      *
-     * @throws InvalidCacheKeyException
+     * @throws InvalidCacheKeyException Cache key contains invalid data.
      */
-    public function fetch(ConnectionContext $context, string $source)
+    public function fetch(string $source, ConnectionContext $context)
     {
         if ($context->mustCache()) {
             $options = $this->connector instanceof ConnectorOptions ? $this->connector->getOptions()->copy() : [];
@@ -70,7 +70,7 @@ public function fetch(ConnectionContext $context, string $source)
             }
         }
 
-        $data = $this->connector->fetch($context, $source);
+        $data = $this->connector->fetch($source, $context);
 
         isset($key) && $this->cache->save($this->cache->getItem($key)->set($data));
 

src/Connector/Connector.php

@@ -11,10 +11,10 @@ interface Connector
     /**
      * Fetches data from the specified source optionally augmented by the specified options.
      *
-     * @param ConnectionContext $context Runtime connection settings and methods.
      * @param string $source Source.
+     * @param ConnectionContext $context Runtime connection settings and methods.
      *
      * @return mixed Data.
      */
-    public function fetch(ConnectionContext $context, string $source);
+    public function fetch(string $source, ConnectionContext $context);
 }

src/Connector/ImportConnector.php

@@ -66,7 +66,7 @@ public function fetch(string $source)
         return \ScriptFUSION\Retry\retry(
             $this->maxFetchAttempts,
             function () use ($source) {
-                return $this->connector->fetch($this->connectionContext, $source);
+                return $this->connector->fetch($source, $this->connectionContext);
             },
             $this->createExceptionHandler()
         );
@@ -77,7 +77,7 @@ public function fetchAsync(string $source): Promise
         return \ScriptFUSION\Retry\retryAsync(
             $this->maxFetchAttempts,
             function () use ($source): Promise {
-                return \Amp\call($this->connector->fetchAsync($this->connectionContext, $source));
+                return \Amp\call($this->connector->fetchAsync($source, $this->connectionContext));
             },
             $this->createExceptionHandler()
         );

src/Connector/NullConnector.php

@@ -5,7 +5,7 @@
 
 final class NullConnector implements Connector
 {
-    public function fetch(ConnectionContext $context, string $source)
+    public function fetch(string $source, ConnectionContext $context)
     {
         // Intentionally empty.
     }

test/Integration/Porter/Connector/CachingConnectorTest.php

@@ -69,8 +69,8 @@ protected function setUp(): void
      */
     public function testCacheEnabled(): void
     {
-        self::assertSame('foo', $this->connector->fetch($this->context, 'baz'));
-        self::assertSame('foo', $this->connector->fetch($this->context, 'baz'));
+        self::assertSame('foo', $this->connector->fetch('baz', $this->context));
+        self::assertSame('foo', $this->connector->fetch('baz', $this->context));
     }
 
     /**
@@ -81,35 +81,35 @@ public function testCacheDisabled(): void
         // The default connection context has caching disabled.
         $context = FixtureFactory::buildConnectionContext();
 
-        self::assertSame('foo', $this->connector->fetch($context, 'baz'));
-        self::assertSame('bar', $this->connector->fetch($context, 'baz'));
+        self::assertSame('foo', $this->connector->fetch('baz', $context));
+        self::assertSame('bar', $this->connector->fetch('baz', $context));
     }
 
     /**
      * Tests that when sources are the same but options are different, the cache is not reused.
      */
     public function testCacheBypassedForDifferentOptions(): void
     {
-        self::assertSame('foo', $this->connector->fetch($this->context, 'baz'));
+        self::assertSame('foo', $this->connector->fetch('baz', $this->context));
 
         $this->options->setFoo('bar');
-        self::assertSame('bar', $this->connector->fetch($this->context, 'baz'));
+        self::assertSame('bar', $this->connector->fetch('baz', $this->context));
     }
 
     /**
      * Tests that when the same options are specified by two different object instances, the cache is reused.
      */
     public function testCacheUsedForDifferentOptionsInstance(): void
     {
-        self::assertSame('foo', $this->connector->fetch($this->context, 'baz'));
+        self::assertSame('foo', $this->connector->fetch('baz', $this->context));
 
         $this->wrappedConnector->shouldReceive('getOptions')->andReturn($options = clone $this->options);
         self::assertNotSame($this->options, $options);
-        self::assertSame('foo', $this->connector->fetch($this->context, 'baz'));
+        self::assertSame('foo', $this->connector->fetch('baz', $this->context));
 
         // Ensure new options have really taken effect by changing option. Cache should no longer be used.
         $options->setFoo('bar');
-        self::assertSame('bar', $this->connector->fetch($this->context, 'baz'));
+        self::assertSame('bar', $this->connector->fetch('baz', $this->context));
     }
 
     public function testNullAndEmptyOptionsAreEquivalent(): void
@@ -119,8 +119,8 @@ public function testNullAndEmptyOptionsAreEquivalent(): void
         $this->wrappedConnector->shouldReceive('getOptions')->andReturn($options);
         self::assertEmpty($this->wrappedConnector->getOptions()->copy());
 
-        self::assertSame('foo', $this->connector->fetch($this->context, 'baz'));
-        self::assertSame('foo', $this->connector->fetch($this->context, 'baz'));
+        self::assertSame('foo', $this->connector->fetch('baz', $this->context));
+        self::assertSame('foo', $this->connector->fetch('baz', $this->context));
     }
 
     /**
@@ -145,7 +145,7 @@ function ($key) use ($reservedCharacters): void {
             ->shouldReceive('set')->andReturn(\Mockery::mock(CacheItemInterface::class))
         ;
 
-        $connector->fetch($this->context, $reservedCharacters);
+        $connector->fetch($reservedCharacters, $this->context);
     }
 
     /**
@@ -163,9 +163,9 @@ public function testCacheKeyGenerator(): void
                 ->getMock()
         );
 
-        self::assertSame('foo', $connector->fetch($this->context, $source));
-        self::assertSame('foo', $connector->fetch($this->context, $source));
-        self::assertSame('bar', $connector->fetch($this->context, $source));
+        self::assertSame('foo', $connector->fetch($source, $this->context));
+        self::assertSame('foo', $connector->fetch($source, $this->context));
+        self::assertSame('bar', $connector->fetch($source, $this->context));
     }
 
     public function testFetchThrowsInvalidCacheKeyExceptionOnNonPSR6CompliantCacheKey(): void
@@ -180,7 +180,7 @@ public function testFetchThrowsInvalidCacheKeyExceptionOnNonPSR6CompliantCacheKe
 
         $this->expectException(InvalidCacheKeyException::class);
         $this->expectExceptionMessage('contains one or more reserved characters');
-        $connector->fetch($this->context, 'baz');
+        $connector->fetch('baz', $this->context);
     }
 
     /**

test/Unit/Porter/Connector/ImportConnectorTest.php

@@ -32,8 +32,8 @@ public function testCallGraph(): void
             \Mockery::mock(Connector::class)
                 ->shouldReceive('fetch')
                 ->with(
-                    $context = FixtureFactory::buildConnectionContext(),
-                    $source = 'bar'
+                    $source = 'bar',
+                    $context = FixtureFactory::buildConnectionContext()
                 )->once()
                 ->andReturn($output = 'foo')
                 ->getMock(),

test/Unit/Porter/Connector/NullConnectorTest.php

@@ -14,6 +14,6 @@ final class NullConnectorTest extends TestCase
 {
     public function test(): void
     {
-        self::assertNull((new NullConnector)->fetch(FixtureFactory::buildConnectionContext(), 'foo'));
+        self::assertNull((new NullConnector)->fetch('foo', FixtureFactory::buildConnectionContext()));
     }
 }