Deprecate ResultPager::postFetch method

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/" }
@@ -50,7 +52,7 @@
     "extra": {
         "branch-alias": {
             "dev-2.x": "2.19.x-dev",
-            "dev-master": "3.1.x-dev"
+            "dev-master": "3.2.x-dev"
         }
     }
 }

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 <[email protected]>
@@ -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();
+    }
 }