From cf7ca9a2652d76dc4c395f3b5db3dd2d5f387cac Mon Sep 17 00:00:00 2001
From: Jeroen Thora <jeroenthora@gmail.com>
Date: Sun, 28 Mar 2021 13:06:32 +0200
Subject: [PATCH] Deprecate ResultPager::postFetch method

---
 UPGRADE-4.0.md                        |  5 +++++
 composer.json                         |  8 +++++---
 lib/Github/ResultPager.php            | 17 +++++++++++++----
 lib/Github/ResultPagerInterface.php   |  2 ++
 phpunit.xml.dist                      |  4 ++++
 test/Github/Tests/ResultPagerTest.php | 17 +++++++++++++++++
 6 files changed, 46 insertions(+), 7 deletions(-)
 create mode 100644 UPGRADE-4.0.md

diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md
new file mode 100644
index 00000000000..9192a02a726
--- /dev/null
+++ b/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.
diff --git a/composer.json b/composer.json
index 864d25c0219..ef03d2e3d64 100644
--- a/composer.json
+++ b/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"
         }
     }
 }
diff --git a/lib/Github/ResultPager.php b/lib/Github/ResultPager.php
index 5f9c40d0911..cfd1d605e4f 100644
--- a/lib/Github/ResultPager.php
+++ b/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());
+    }
 }
diff --git a/lib/Github/ResultPagerInterface.php b/lib/Github/ResultPagerInterface.php
index 350f8453e05..bf7618ee411 100644
--- a/lib/Github/ResultPagerInterface.php
+++ b/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;
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
index 3b6dc204b03..98d2e51cc8f 100644
--- a/phpunit.xml.dist
+++ b/phpunit.xml.dist
@@ -27,4 +27,8 @@
             <directory suffix=".php">./lib/Github/</directory>
         </whitelist>
     </filter>
+
+    <listeners>
+        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
+    </listeners>
 </phpunit>
diff --git a/test/Github/Tests/ResultPagerTest.php b/test/Github/Tests/ResultPagerTest.php
index 41327c5d9d1..2839e16f3df 100644
--- a/test/Github/Tests/ResultPagerTest.php
+++ b/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();
+    }
 }