feature #986 Deprecate ResultPager::postFetch method (acrobat)

This PR was merged into the 3.2.x-dev branch.

Discussion
----------

We don't see any real usecases for the method to be called from the outside. Therefor we prepare this method for removal in 4.0. If you have any valid usecases, please open an issue to discuss this.

Fixes #951

Commits
-------

cf7ca9a Deprecate ResultPager::postFetch method

Author: acrobat

UPGRADE-4.0.md

@@ -0,0 +1,5 @@
+## UPGRADE from 3.x to 4.0
+
+### ResultPager
+
+* `\Github\ResultPagerInterface::postFetch` is deprecated, and the method will be removed from the ResultPager interface/class.

composer.json

@@ -28,7 +28,8 @@
         "psr/http-client-implementation": "^1.0",
         "psr/http-factory-implementation": "^1.0",
         "psr/http-message": "^1.0",
-        "symfony/polyfill-php80": "^1.17"
+        "symfony/polyfill-php80": "^1.17",
+        "symfony/deprecation-contracts": "^2.2"
     },
     "require-dev": {
         "symfony/cache": "^5.1.8",
@@ -39,7 +40,8 @@
         "phpstan/phpstan": "^0.12.57",
         "phpstan/extension-installer": "^1.0.5",
         "phpstan/phpstan-deprecation-rules": "^0.12.5",
-        "phpunit/phpunit": "^8.5 || ^9.4"
+        "phpunit/phpunit": "^8.5 || ^9.4",
+        "symfony/phpunit-bridge": "^5.2"
     },
     "autoload": {
         "psr-4": { "Github\\": "lib/Github/" }

lib/Github/ResultPager.php

@@ -86,7 +86,7 @@ public function fetch(AbstractApi $api, string $method, array $parameters = []):
         $api = $closure($api);
         $result = $api->$method(...$parameters);
 
-        $this->postFetch();
+        $this->postFetch(true);
 
         return $result;
     }
@@ -130,9 +130,13 @@ public function fetchAllLazy(AbstractApi $api, string $method, array $parameters
     /**
      * {@inheritdoc}
      */
-    public function postFetch(): void
+    public function postFetch(/* $skipDeprecation = false */): void
     {
-        $this->pagination = ResponseMediator::getPagination($this->client->getLastResponse());
+        if (func_num_args() === 0 || (func_num_args() > 0 && false === func_get_arg(0))) {
+            trigger_deprecation('KnpLabs/php-github-api', '3.2', 'The "%s" method is deprecated and will be removed.', __METHOD__);
+        }
+
+        $this->setPagination();
     }
 
     /**
@@ -196,8 +200,13 @@ protected function get(string $key): array
 
         $result = $this->client->getHttpClient()->get($this->pagination[$key]);
 
-        $this->postFetch();
+        $this->postFetch(true);
 
         return ResponseMediator::getContent($result);
     }
+
+    private function setPagination(): void
+    {
+        $this->pagination = ResponseMediator::getPagination($this->client->getLastResponse());
+    }
 }

lib/Github/ResultPagerInterface.php

@@ -54,6 +54,8 @@ public function fetchAllLazy(AbstractApi $api, string $method, array $parameters
     /**
      * Method that performs the actual work to refresh the pagination property.
      *
+     * @deprecated since 3.2 and will be removed in 4.0.
+     *
      * @return void
      */
     public function postFetch(): void;

phpunit.xml.dist

@@ -27,4 +27,8 @@
             <directory suffix=".php">./lib/Github/</directory>
         </whitelist>
     </filter>
+
+    <listeners>
+        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
+    </listeners>
 </phpunit>

test/Github/Tests/ResultPagerTest.php

@@ -13,6 +13,7 @@
 use GuzzleHttp\Psr7\Utils;
 use Http\Client\HttpClient;
 use Psr\Http\Client\ClientInterface;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 
 /**
  * @author Ramon de la Fuente <ramon@future500.nl>
@@ -21,6 +22,8 @@
  */
 class ResultPagerTest extends \PHPUnit\Framework\TestCase
 {
+    use ExpectDeprecationTrait;
+
     public function provideFetchCases()
     {
         return [
@@ -197,4 +200,18 @@ public function testFetchAllWithoutKeys()
 
         $this->assertCount(9, $result);
     }
+
+    /**
+     * @group legacy
+     */
+    public function testPostFetchDeprecation()
+    {
+        $this->expectDeprecation('Since KnpLabs/php-github-api 3.2: The "Github\ResultPager::postFetch" method is deprecated and will be removed.');
+
+        $clientMock = $this->createMock(Client::class);
+        $clientMock->method('getLastResponse')->willReturn(new PaginatedResponse(3, []));
+
+        $paginator = new ResultPager($clientMock);
+        $paginator->postFetch();
+    }
 }