From efecf6fa405f38441efcc7620ac1a75b9d3cde5c Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Sun, 26 Jul 2026 19:19:08 +0200 Subject: [PATCH 1/5] Use newer Github API & deprecate non-functioning APIs --- src/AbstractGithubObject.php | 30 ++++++++++++++++++++++---- src/Package/Authorization.php | 9 ++++++-- src/Package/Repositories/Downloads.php | 5 ++++- 3 files changed, 37 insertions(+), 7 deletions(-) diff --git a/src/AbstractGithubObject.php b/src/AbstractGithubObject.php index 80fa942a..ddcc43d6 100644 --- a/src/AbstractGithubObject.php +++ b/src/AbstractGithubObject.php @@ -109,22 +109,42 @@ public function __construct(Registry $options = null, BaseHttp $client = null) * @return Uri * * @since 1.0 + * @since __DEPLOY_VERSION__ Sets a default `Accept: application/vnd.github+json` header and pins + * `X-GitHub-Api-Version` (overridable via the `api.version` option, or by + * setting either header on the HTTP client before the request). The + * `gh.token.scheme` option (default `token`, unchanged) may be set to + * `Bearer` for fine-grained PATs / GitHub App installation tokens. */ protected function fetchUrl($path, $page = 0, $limit = 0) { // Get a new Uri object focusing the api url and given path. $uri = new Uri($this->options->get('api.url') . $path); + $headers = $this->client->getOption('headers', []); + + // Pin the REST API media type and version unless the consumer already set their own. + if (!isset($headers['Accept'])) { + $headers['Accept'] = 'application/vnd.github+json'; + } + + if (!isset($headers['X-GitHub-Api-Version'])) { + $headers['X-GitHub-Api-Version'] = $this->options->get('api.version', '2022-11-28'); + } + if ($this->options->get('gh.token', false)) { // Use oAuth authentication - $headers = $this->client->getOption('headers', []); - if (!isset($headers['Authorization'])) { - $headers['Authorization'] = 'token ' . $this->options->get('gh.token'); - $this->client->setOption('headers', $headers); + // 'token' is the classic scheme; set gh.token.scheme to 'Bearer' for fine-grained + // PATs or GitHub App installation tokens, both of which GitHub also accepts as 'token'. + $scheme = $this->options->get('gh.token.scheme', 'token'); + + $headers['Authorization'] = $scheme . ' ' . $this->options->get('gh.token'); } } else { // Use basic authentication + // Note: GitHub removed username/password Basic authentication for the API in + // November 2020; this path is kept only for compatibility with Enterprise Server + // instances that may still accept it. Use gh.token for github.com. if ($this->options->get('api.username', false)) { $uri->setUser($this->options->get('api.username')); } @@ -134,6 +154,8 @@ protected function fetchUrl($path, $page = 0, $limit = 0) } } + $this->client->setOption('headers', $headers); + // If we have a defined page number add it to the JUri object. if ($page > 0) { $uri->setVar('page', (int) $page); diff --git a/src/Package/Authorization.php b/src/Package/Authorization.php index 10b881f2..a0300e3c 100644 --- a/src/Package/Authorization.php +++ b/src/Package/Authorization.php @@ -19,8 +19,13 @@ * @documentation http://developer.github.com/v3/oauth/ * @documentation http://developer.github.com/v3/oauth_authorizations/ * - * @note The methods in this class are only accessible with Basic Authentication - * @since 1.0 + * @note The methods in this class are only accessible with Basic Authentication + * @since 1.0 + * @deprecated __DEPLOY_VERSION__ will be removed in 5.0. GitHub removed the OAuth + * Authorizations API (and Basic Authentication for the API) in November 2020; + * every method in this class now fails against github.com. Kept only so + * existing `$github->authorization` call sites don't fatal. Use GitHub Apps / OAuth + * device flow (Package\Apps) or a personal access token via the `gh.token` option instead. */ class Authorization extends AbstractPackage { diff --git a/src/Package/Repositories/Downloads.php b/src/Package/Repositories/Downloads.php index 4e23ea1a..93d79211 100644 --- a/src/Package/Repositories/Downloads.php +++ b/src/Package/Repositories/Downloads.php @@ -21,7 +21,10 @@ * @documentation https://developer.github.com/v3/repos/downloads * * @since 1.0 - * @deprecated The Releases API should be used instead + * @deprecated __DEPLOY_VERSION__ GitHub removed the Repository Downloads API entirely in + * 2020; every method in this class now 404s against github.com. Kept only so + * existing `$github->repositories->downloads` call sites don't fatal. Use + * Package\Repositories\Releases (release assets) instead. */ class Downloads extends AbstractPackage { From 770267d82711466160649cf9ba44ae04185f5832 Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Sun, 26 Jul 2026 19:29:19 +0200 Subject: [PATCH 2/5] Update Downloads.php --- src/Package/Repositories/Downloads.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Package/Repositories/Downloads.php b/src/Package/Repositories/Downloads.php index 93d79211..b8168deb 100644 --- a/src/Package/Repositories/Downloads.php +++ b/src/Package/Repositories/Downloads.php @@ -21,7 +21,7 @@ * @documentation https://developer.github.com/v3/repos/downloads * * @since 1.0 - * @deprecated __DEPLOY_VERSION__ GitHub removed the Repository Downloads API entirely in + * @deprecated __DEPLOY_VERSION__ will be removed in 5.0. GitHub removed the Repository Downloads API entirely in * 2020; every method in this class now 404s against github.com. Kept only so * existing `$github->repositories->downloads` call sites don't fatal. Use * Package\Repositories\Releases (release assets) instead. From cb2712048da0a730712c16407002f3b5325d28ad Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Sun, 26 Jul 2026 19:31:13 +0200 Subject: [PATCH 3/5] Document changes in 4.1 --- docs/v3-to-v4-update.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/v3-to-v4-update.md b/docs/v3-to-v4-update.md index 1098ef1e..c02e73e5 100644 --- a/docs/v3-to-v4-update.md +++ b/docs/v3-to-v4-update.md @@ -5,3 +5,42 @@ The following changes were made to the Github API package between v3 and v4. ### Minimum supported PHP version raised All Framework packages now require PHP 8.3 or newer. + +### Modern API headers and authentication (since 4.1) + +Starting with version 4.1, `fetchUrl()` automatically sends `Accept: application/vnd.github+json` and pins +`X-GitHub-Api-Version` to `2022-11-28` on every request, matching GitHub's currently recommended REST API +conventions. Both headers are only added if you haven't already set them yourself on the HTTP client, so +existing code that manages its own headers is unaffected. + +If you need a different API version, set the `api.version` option: + +```php +$options->set('api.version', '2022-11-28'); +``` + +A new `gh.token.scheme` option (default `token`, unchanged) lets you send the `Authorization` header using the +`Bearer` scheme instead, which some fine-grained personal access tokens and GitHub App installation tokens +require: + +```php +$options->set('gh.token', $token); +$options->set('gh.token.scheme', 'Bearer'); +``` + +HTTP Basic Authentication (`api.username` / `api.password`) against `https://api.github.com` no longer works — +GitHub removed it in November 2020. Use `gh.token` instead. The `api.username` / `api.password` options remain +available for GitHub Enterprise Server instances that still accept them. + +### `Authorization` and `Repositories\Downloads` are deprecated (since 4.1) + +`Package\Authorization` wrapped GitHub's OAuth Authorizations API, and `Package\Repositories\Downloads` wrapped +the Repository Downloads API. GitHub has removed both endpoints from github.com (OAuth Authorizations in +November 2020; Downloads years earlier), so every method on these two classes now fails against live GitHub. +The classes are kept so existing `$github->authorization` and `$github->repositories->downloads` call sites +don't fatal, but they are marked `@deprecated`; `Authorization` is scheduled for removal in 5.0. + +* Replace `$github->authorization` usage with a personal access token passed via the `gh.token` option, or the + GitHub Apps / OAuth device flow once supported. +* Replace `$github->repositories->downloads` usage with `$github->repositories->releases`, which manages + release assets. From 2e4723690bfa2a3db866beaa7dd50ccc0e7a77dd Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Thu, 12 Nov 2026 23:36:16 +0100 Subject: [PATCH 4/5] Send the GitHub headers per request instead of storing them on the client The Authorization header was written into the HTTP client's options and only when it was not set yet. A rotated token was never used, and every later request through a shared client carried the token, including requests to other hosts. Basic auth credentials were put unencoded into the URL. Wrap the client so that the headers (Accept, X-GitHub-Api-Version, Authorization) are computed from the options on every request and put on the client only for that request. Send Basic auth as an Authorization header. Default api.url to api.github.com for packages built without Github. Rename gh.token.scheme to gh.token_scheme, because a Registry cannot hold gh.token and gh.token.scheme at the same time. Deprecate only the dead methods of Authorization (getRateLimit(), getAuthorizationLink() and requestToken() still work) and trigger runtime deprecations for them and for Downloads. Document the options in overview.md instead of the v3 to v4 update guide. Co-Authored-By: Claude Opus 5.5 --- Tests/GithubObjectTest.php | 180 +++++++++++++++- Tests/Package/AuthorizationsTest.php | 4 + Tests/Package/Repositories/DownloadsTest.php | 4 + Tests/Stub/GitHubTestCase.php | 3 + Tests/Stub/ObjectMock.php | 12 ++ Tests/Stub/RecordingTransport.php | 42 ++++ composer.json | 3 +- docs/overview.md | 38 ++++ docs/v3-to-v4-update.md | 39 ---- src/AbstractGithubObject.php | 83 ++++---- src/Package/Authorization.php | 82 ++++++- src/Package/Repositories/Downloads.php | 50 ++++- src/RequestHeadersHttp.php | 213 +++++++++++++++++++ 13 files changed, 650 insertions(+), 103 deletions(-) create mode 100644 Tests/Stub/RecordingTransport.php create mode 100644 src/RequestHeadersHttp.php diff --git a/Tests/GithubObjectTest.php b/Tests/GithubObjectTest.php index de9d5129..3e4dcdbe 100755 --- a/Tests/GithubObjectTest.php +++ b/Tests/GithubObjectTest.php @@ -7,8 +7,12 @@ namespace Joomla\Github\Tests; +use Joomla\Github\Github; use Joomla\Github\Tests\Stub\GitHubTestCase; use Joomla\Github\Tests\Stub\ObjectMock; +use Joomla\Github\Tests\Stub\RecordingTransport; +use Joomla\Http\Http; +use Joomla\Registry\Registry; use PHPUnit\Framework\Attributes\DataProvider; /** @@ -105,11 +109,9 @@ public function testFetchUrl($apiUrl, $path, $page, $limit, $expected) } /** - * Tests the fetchUrl method with basic authentication data + * Tests that fetchUrl() does not put Basic auth credentials into the URL * * @return void - * - * @since 1.0 */ public function testFetchUrlBasicAuth() { @@ -119,12 +121,24 @@ public function testFetchUrlBasicAuth() $this->options->set('api.password', 'MyTestPass'); $this->assertThat( - $this->object->fetchUrl('/gists', 0, 0), - $this->equalTo('https://MyTestUser:MyTestPass@api.github.com/gists'), + (string) $this->object->fetchUrl('/gists', 0, 0), + $this->equalTo('https://api.github.com/gists'), 'URL is not as expected.' ); } + /** + * Tests that fetchUrl() uses api.github.com when the api.url option is not set + * + * @return void + */ + public function testFetchUrlDefaultApiUrl() + { + $object = new ObjectMock(new Registry(), $this->client); + + $this->assertSame('https://api.github.com/user', (string) $object->fetchUrl('/user')); + } + /** * Tests the fetchUrl method using an oAuth token. * @@ -142,4 +156,160 @@ public function testFetchUrlToken() 'URL is not as expected.' ); } + + /** + * Tests that the token is sent with each request and read again for every request + * + * @return void + */ + public function testTokenIsSentPerRequestAndCanBeRotated() + { + $transport = new RecordingTransport(); + $object = new ObjectMock($this->options, new Http([], $transport)); + + $this->options->set('gh.token', 'AAA'); + $object->request('/user'); + + $this->options->set('gh.token', 'BBB'); + $object->request('/user'); + + $this->assertSame('token AAA', $transport->requests[0]['headers']['Authorization']); + $this->assertSame('token BBB', $transport->requests[1]['headers']['Authorization']); + } + + /** + * Tests that the GitHub headers are not left on a shared HTTP client + * + * @return void + */ + public function testHeadersAreNotStoredOnTheClient() + { + $transport = new RecordingTransport(); + $client = new Http([], $transport); + $object = new ObjectMock($this->options, $client); + + $this->options->set('gh.token', 'MyTestToken'); + $object->request('/user'); + + $this->assertNull($client->getOption('headers')); + + // Another request through the same client, e.g. to a different host, does not carry the token + $client->get('https://example.com/'); + + $this->assertSame('token MyTestToken', $transport->requests[0]['headers']['Authorization']); + $this->assertArrayNotHasKey('Authorization', $transport->requests[1]['headers']); + } + + /** + * Tests that the GitHub headers are not written into an options registry the client was built from + * + * @return void + */ + public function testHeadersAreNotStoredInTheOptions() + { + $transport = new RecordingTransport(); + $object = new ObjectMock($this->options, new Http($this->options, $transport)); + + $this->options->set('gh.token', 'MyTestToken'); + $object->request('/user'); + + $this->assertSame('token MyTestToken', $transport->requests[0]['headers']['Authorization']); + $this->assertNull($this->options->get('headers')); + } + + /** + * Tests the default media type and API version headers and the api.version and gh.token_scheme options + * + * @return void + */ + public function testDefaultHeadersAndOptions() + { + $transport = new RecordingTransport(); + $object = new ObjectMock($this->options, new Http([], $transport)); + + $object->request('/zen'); + + $this->options->set('api.version', '2026-03-10'); + $this->options->set('gh.token', 'MyTestToken'); + $this->options->set('gh.token_scheme', 'Bearer'); + $object->request('/zen'); + + $this->assertSame( + ['Accept' => 'application/vnd.github+json', 'X-GitHub-Api-Version' => '2022-11-28'], + $transport->requests[0]['headers'] + ); + $this->assertSame( + [ + 'Accept' => 'application/vnd.github+json', + 'X-GitHub-Api-Version' => '2026-03-10', + 'Authorization' => 'Bearer MyTestToken', + ], + $transport->requests[1]['headers'] + ); + } + + /** + * Tests that headers set on the client take precedence and are left as they were + * + * @return void + */ + public function testClientHeadersTakePrecedence() + { + $transport = new RecordingTransport(); + $client = new Http( + ['headers' => ['authorization' => 'token Custom', 'Accept' => 'application/vnd.github.raw+json']], + $transport + ); + $object = new ObjectMock($this->options, $client); + + $this->options->set('gh.token', 'MyTestToken'); + $object->request('/user'); + + $headers = $transport->requests[0]['headers']; + + $this->assertSame('token Custom', $headers['authorization']); + $this->assertArrayNotHasKey('Authorization', $headers); + $this->assertSame('application/vnd.github.raw+json', $headers['Accept']); + $this->assertSame( + ['authorization' => 'token Custom', 'Accept' => 'application/vnd.github.raw+json'], + $client->getOption('headers') + ); + } + + /** + * Tests that Basic auth credentials are sent in the Authorization header, not in the URL + * + * @return void + */ + public function testBasicAuthIsSentAsHeader() + { + $transport = new RecordingTransport(); + $object = new ObjectMock($this->options, new Http([], $transport)); + + $this->options->set('api.url', 'https://api.github.com'); + $this->options->set('api.username', 'bob'); + $this->options->set('api.password', 'p@ss:w/rd'); + $object->request('/user'); + + $this->assertSame('https://api.github.com/user', $transport->requests[0]['uri']); + $this->assertSame('Basic ' . base64_encode('bob:p@ss:w/rd'), $transport->requests[0]['headers']['Authorization']); + } + + /** + * Tests that sub-packages send the headers once + * + * @return void + */ + public function testSubPackagesSendTheHeaders() + { + $transport = new RecordingTransport(); + $options = new Registry(); + $options->set('gh.token', 'MyTestToken'); + + $github = new Github($options, new Http([], $transport)); + $github->repositories->forks->getList('joomla', 'joomla-framework'); + + $this->assertSame('https://api.github.com/repos/joomla/joomla-framework/forks', $transport->requests[0]['uri']); + $this->assertSame('token MyTestToken', $transport->requests[0]['headers']['Authorization']); + } } diff --git a/Tests/Package/AuthorizationsTest.php b/Tests/Package/AuthorizationsTest.php index f5746fc5..93d4c19b 100644 --- a/Tests/Package/AuthorizationsTest.php +++ b/Tests/Package/AuthorizationsTest.php @@ -9,6 +9,7 @@ use Joomla\Github\Package\Authorization; use Joomla\Github\Tests\Stub\GitHubTestCase; +use PHPUnit\Framework\Attributes\IgnoreDeprecations; /** * Test class for Authorization. @@ -430,8 +431,11 @@ public function testGetGrantFailure() * * @since 1.0 */ + #[IgnoreDeprecations] public function testGetList() { + $this->expectUserDeprecationMessageMatches('/' . preg_quote('Joomla\Github\Package\Authorization::getList() is deprecated and will be removed in 5.0', '/') . '/'); + $this->client->expects($this->once()) ->method('get') ->with('/authorizations') diff --git a/Tests/Package/Repositories/DownloadsTest.php b/Tests/Package/Repositories/DownloadsTest.php index 189a7c5d..ae60def3 100644 --- a/Tests/Package/Repositories/DownloadsTest.php +++ b/Tests/Package/Repositories/DownloadsTest.php @@ -9,6 +9,7 @@ use Joomla\Github\Package\Repositories\Downloads; use Joomla\Github\Tests\Stub\GitHubTestCase; +use PHPUnit\Framework\Attributes\IgnoreDeprecations; /** * Test class for Downloads. @@ -42,8 +43,11 @@ protected function setUp(): void * * @return void */ + #[IgnoreDeprecations] public function testGetList() { + $this->expectUserDeprecationMessageMatches('/' . preg_quote('Joomla\Github\Package\Repositories\Downloads::getList() is deprecated and will be removed in 5.0', '/') . '/'); + $this->client->expects($this->once()) ->method('get') ->with('/repos/joomla/joomla-platform/downloads') diff --git a/Tests/Stub/GitHubTestCase.php b/Tests/Stub/GitHubTestCase.php index e0eba3de..e25ce04b 100644 --- a/Tests/Stub/GitHubTestCase.php +++ b/Tests/Stub/GitHubTestCase.php @@ -62,6 +62,9 @@ protected function setUp(): void $this->options = new Registry(); + // An empty API URL keeps the request paths relative, so the tests can assert on the path alone. + $this->options->set('api.url', ''); + $this->client = $this->createMock(Http::class); $this->response = $this->getResponseObject($this->sampleString); diff --git a/Tests/Stub/ObjectMock.php b/Tests/Stub/ObjectMock.php index fe40373e..ead50961 100644 --- a/Tests/Stub/ObjectMock.php +++ b/Tests/Stub/ObjectMock.php @@ -33,5 +33,17 @@ public function fetchUrl($path, $page = 0, $limit = 0) { return parent::fetchUrl($path, $page, $limit); } + + /** + * Send a GET request for the given path. + * + * @param string $path The API path. + * + * @return mixed + */ + public function request($path) + { + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } // @codingStandardsIgnoreEnd } diff --git a/Tests/Stub/RecordingTransport.php b/Tests/Stub/RecordingTransport.php new file mode 100644 index 00000000..4a4122c4 --- /dev/null +++ b/Tests/Stub/RecordingTransport.php @@ -0,0 +1,42 @@ +requests[] = [ + 'method' => $method, + 'uri' => (string) $uri, + 'data' => $data, + 'headers' => $headers, + ]; + + return new Response('data://text/plain,[]', 200, []); + } + + public static function isSupported() + { + return true; + } +} diff --git a/composer.json b/composer.json index 49ad2e0a..d44c9b57 100644 --- a/composer.json +++ b/composer.json @@ -9,7 +9,8 @@ "php": "^8.3.0", "joomla/http": "^4.0", "joomla/registry": "^4.0", - "joomla/uri": "^4.0" + "joomla/uri": "^4.0", + "symfony/deprecation-contracts": "^2|^3" }, "require-dev": { "phpunit/phpunit": "^12.2.7", diff --git a/docs/overview.md b/docs/overview.md index cfd53634..347c924b 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,3 +1,41 @@ # Github API package TODO + +## Authentication and request headers + +The options are read on every request, so a changed token is used from the next request on. The headers are added +to each request only; they are not stored on the HTTP client, so a client shared with other code never sends the +GitHub credentials elsewhere. + +| Option | Default | Meaning | +|---|---|---| +| `api.url` | `https://api.github.com` | API root; for GitHub Enterprise Server `https:///api/v3` | +| `api.version` | `2022-11-28` | Sent as `X-GitHub-Api-Version` | +| `gh.token` | | Token sent as `Authorization: token ` | +| `gh.token_scheme` | `token` | Scheme of the `Authorization` header, e.g. `Bearer` for GitHub App tokens | +| `api.username`, `api.password` | | Sent as `Authorization: Basic` when no token is set (GitHub Enterprise Server only) | + +```php +$options = new Registry(); +$options->set('gh.token', getenv('GITHUB_TOKEN')); +$options->set('gh.token_scheme', 'Bearer'); + +$github = new Github($options); +``` + +Every request also sends `Accept: application/vnd.github+json`. A header set on the HTTP client (its `headers` +option) or passed with a request takes precedence over these defaults. + +GitHub removed password authentication for the API in November 2020; `api.username` and `api.password` only work +against GitHub Enterprise Server instances that still accept it. They are sent in the `Authorization` header, not in +the URL. + +## Deprecated endpoints + +GitHub has removed some of the endpoints this package wraps. Calling these methods triggers a deprecation notice; +they will be removed in 5.0. + +* `Authorization`: everything except `getRateLimit()`, `getAuthorizationLink()` and `requestToken()` (the OAuth + Authorizations API). Use a token (`gh.token`) instead. +* `Repositories\Downloads`: the whole class. Use `Repositories\Releases` and its assets instead. diff --git a/docs/v3-to-v4-update.md b/docs/v3-to-v4-update.md index c02e73e5..1098ef1e 100644 --- a/docs/v3-to-v4-update.md +++ b/docs/v3-to-v4-update.md @@ -5,42 +5,3 @@ The following changes were made to the Github API package between v3 and v4. ### Minimum supported PHP version raised All Framework packages now require PHP 8.3 or newer. - -### Modern API headers and authentication (since 4.1) - -Starting with version 4.1, `fetchUrl()` automatically sends `Accept: application/vnd.github+json` and pins -`X-GitHub-Api-Version` to `2022-11-28` on every request, matching GitHub's currently recommended REST API -conventions. Both headers are only added if you haven't already set them yourself on the HTTP client, so -existing code that manages its own headers is unaffected. - -If you need a different API version, set the `api.version` option: - -```php -$options->set('api.version', '2022-11-28'); -``` - -A new `gh.token.scheme` option (default `token`, unchanged) lets you send the `Authorization` header using the -`Bearer` scheme instead, which some fine-grained personal access tokens and GitHub App installation tokens -require: - -```php -$options->set('gh.token', $token); -$options->set('gh.token.scheme', 'Bearer'); -``` - -HTTP Basic Authentication (`api.username` / `api.password`) against `https://api.github.com` no longer works — -GitHub removed it in November 2020. Use `gh.token` instead. The `api.username` / `api.password` options remain -available for GitHub Enterprise Server instances that still accept them. - -### `Authorization` and `Repositories\Downloads` are deprecated (since 4.1) - -`Package\Authorization` wrapped GitHub's OAuth Authorizations API, and `Package\Repositories\Downloads` wrapped -the Repository Downloads API. GitHub has removed both endpoints from github.com (OAuth Authorizations in -November 2020; Downloads years earlier), so every method on these two classes now fails against live GitHub. -The classes are kept so existing `$github->authorization` and `$github->repositories->downloads` call sites -don't fatal, but they are marked `@deprecated`; `Authorization` is scheduled for removal in 5.0. - -* Replace `$github->authorization` usage with a personal access token passed via the `gh.token` option, or the - GitHub Apps / OAuth device flow once supported. -* Replace `$github->repositories->downloads` usage with `$github->repositories->releases`, which manages - release assets. diff --git a/src/AbstractGithubObject.php b/src/AbstractGithubObject.php index a3e645b5..c2ab186e 100644 --- a/src/AbstractGithubObject.php +++ b/src/AbstractGithubObject.php @@ -93,6 +93,9 @@ public function __construct(Registry $options = null, BaseHttp $client = null) $this->options = $options ?: new Registry(); $this->client = $client ?: (new HttpFactory())->getHttp($this->options); + // Add the GitHub headers per request instead of storing them on the (possibly shared) client. + $this->client = new RequestHeadersHttp($this->client, fn (): array => $this->getRequestHeaders()); + $this->package = \get_class($this); $this->package = substr($this->package, strrpos($this->package, '\\') + 1); } @@ -102,6 +105,8 @@ public function __construct(Registry $options = null, BaseHttp $client = null) * add appropriate pagination details if necessary and also prepend the API url * to have a complete URL for the request. * + * When the `api.url` option is not set, `https://api.github.com` is used. + * * @param string $path URL to inflect * @param integer $page Page to request * @param integer $limit Number of results to return per page @@ -109,52 +114,12 @@ public function __construct(Registry $options = null, BaseHttp $client = null) * @return Uri * * @since 1.0 - * @since __DEPLOY_VERSION__ Sets a default `Accept: application/vnd.github+json` header and pins - * `X-GitHub-Api-Version` (overridable via the `api.version` option, or by - * setting either header on the HTTP client before the request). The - * `gh.token.scheme` option (default `token`, unchanged) may be set to - * `Bearer` for fine-grained PATs / GitHub App installation tokens. */ protected function fetchUrl($path, $page = 0, $limit = 0) { // Get a new Uri object focusing the api url and given path. - $uri = new Uri($this->options->get('api.url') . $path); - - $headers = $this->client->getOption('headers', []); - - // Pin the REST API media type and version unless the consumer already set their own. - if (!isset($headers['Accept'])) { - $headers['Accept'] = 'application/vnd.github+json'; - } - - if (!isset($headers['X-GitHub-Api-Version'])) { - $headers['X-GitHub-Api-Version'] = $this->options->get('api.version', '2022-11-28'); - } - - if ($this->options->get('gh.token', false)) { - // Use oAuth authentication - if (!isset($headers['Authorization'])) { - // 'token' is the classic scheme; set gh.token.scheme to 'Bearer' for fine-grained - // PATs or GitHub App installation tokens, both of which GitHub also accepts as 'token'. - $scheme = $this->options->get('gh.token.scheme', 'token'); - - $headers['Authorization'] = $scheme . ' ' . $this->options->get('gh.token'); - } - } else { - // Use basic authentication - // Note: GitHub removed username/password Basic authentication for the API in - // November 2020; this path is kept only for compatibility with Enterprise Server - // instances that may still accept it. Use gh.token for github.com. - if ($this->options->get('api.username', false)) { - $uri->setUser($this->options->get('api.username')); - } - - if ($this->options->get('api.password', false)) { - $uri->setPass($this->options->get('api.password')); - } - } - - $this->client->setOption('headers', $headers); + $apiUrl = $this->options->exists('api.url') ? $this->options->get('api.url', '') : 'https://api.github.com'; + $uri = new Uri($apiUrl . $path); // If we have a defined page number add it to the JUri object. if ($page > 0) { @@ -169,6 +134,40 @@ protected function fetchUrl($path, $page = 0, $limit = 0) return $uri; } + /** + * Get the headers to send with each request. + * + * The options are read on every request, so a changed token is used on the next request. The headers are added + * to the request only; headers set on the HTTP client or passed with a request take precedence. + * + * - `Accept: application/vnd.github+json` + * - `X-GitHub-Api-Version`, set with the `api.version` option (default `2022-11-28`) + * - `Authorization: token `; the scheme can be changed with the `gh.token_scheme` option, e.g. to `Bearer` + * - Without a token, `Authorization: Basic` from the `api.username` and `api.password` options. GitHub removed + * password authentication for the API in November 2020; it is kept only for GitHub Enterprise Server. + * + * @return array + * + * @since __DEPLOY_VERSION__ + */ + protected function getRequestHeaders(): array + { + $headers = [ + 'Accept' => 'application/vnd.github+json', + 'X-GitHub-Api-Version' => (string) $this->options->get('api.version', '2022-11-28'), + ]; + + if ($this->options->get('gh.token', false)) { + $headers['Authorization'] = $this->options->get('gh.token_scheme', 'token') . ' ' . $this->options->get('gh.token'); + } elseif ($this->options->get('api.username', false)) { + $headers['Authorization'] = 'Basic ' . base64_encode( + $this->options->get('api.username') . ':' . $this->options->get('api.password', '') + ); + } + + return $headers; + } + /** * Process the response and decode it. * diff --git a/src/Package/Authorization.php b/src/Package/Authorization.php index ef040570..7c98341a 100644 --- a/src/Package/Authorization.php +++ b/src/Package/Authorization.php @@ -19,13 +19,9 @@ * @documentation http://developer.github.com/v3/oauth/ * @documentation http://developer.github.com/v3/oauth_authorizations/ * - * @note The methods in this class are only accessible with Basic Authentication - * @since 1.0 - * @deprecated __DEPLOY_VERSION__ will be removed in 5.0. GitHub removed the OAuth - * Authorizations API (and Basic Authentication for the API) in November 2020; - * every method in this class now fails against github.com. Kept only so - * existing `$github->authorization` call sites don't fatal. Use GitHub Apps / OAuth - * device flow (Package\Apps) or a personal access token via the `gh.token` option instead. + * @note GitHub has removed the OAuth Authorizations API and password authentication for the API. Only + * getRateLimit(), getAuthorizationLink() and requestToken() still work; the other methods are deprecated. + * @since 1.0 */ class Authorization extends AbstractPackage { @@ -40,9 +36,17 @@ class Authorization extends AbstractPackage * * @since 1.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function create(array $scopes = [], $note = '', $url = '') { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Build the request path. $path = '/authorizations'; @@ -63,9 +67,17 @@ public function create(array $scopes = [], $note = '', $url = '') * * @since 1.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function delete($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Build the request path. $path = '/authorizations/' . $id; @@ -84,9 +96,17 @@ public function delete($id) * * @since 1.5.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function deleteGrant($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Build the request path. $path = '/authorizations/grants/' . $id; @@ -109,9 +129,17 @@ public function deleteGrant($id) * @since 1.0 * @throws \DomainException * @throws \RuntimeException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function edit($id, array $scopes = [], array $addScopes = [], array $removeScopes = [], $note = '', $url = '') { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Check if more than one scopes array contains data $scopesCount = 0; $scope = ''; @@ -164,9 +192,17 @@ public function edit($id, array $scopes = [], array $addScopes = [], array $remo * * @since 1.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function get($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Build the request path. $path = '/authorizations/' . $id; @@ -183,9 +219,17 @@ public function get($id) * * @since 1.5.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function getGrant($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Build the request path. $path = '/authorizations/grants/' . $id; @@ -200,9 +244,17 @@ public function getGrant($id) * * @since 1.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function getList() { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Build the request path. $path = '/authorizations'; @@ -219,9 +271,17 @@ public function getList() * * @since 1.5.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead. */ public function getListGrants() { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the OAuth Authorizations API. Use a token (gh.token) instead.', + __METHOD__ + ); + // Build the request path. $path = '/authorizations/grants'; @@ -363,9 +423,17 @@ public function requestToken($clientId, $clientSecret, $code, $redirectUri = '', * * @since 1.5.0 * @throws \DomainException + * @deprecated 5.0 GitHub has removed this endpoint. Use DELETE /applications/{client_id}/grant instead. */ public function revokeGrantForApplication($clientId, $accessToken) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed this endpoint. Use DELETE /applications/{client_id}/grant instead.', + __METHOD__ + ); + // Build the request path. $path = "/applications/$clientId/grants/$accessToken"; diff --git a/src/Package/Repositories/Downloads.php b/src/Package/Repositories/Downloads.php index b8168deb..c522e59e 100644 --- a/src/Package/Repositories/Downloads.php +++ b/src/Package/Repositories/Downloads.php @@ -21,10 +21,7 @@ * @documentation https://developer.github.com/v3/repos/downloads * * @since 1.0 - * @deprecated __DEPLOY_VERSION__ will be removed in 5.0. GitHub removed the Repository Downloads API entirely in - * 2020; every method in this class now 404s against github.com. Kept only so - * existing `$github->repositories->downloads` call sites don't fatal. Use - * Package\Repositories\Releases (release assets) instead. + * @deprecated 5.0 GitHub has removed the Downloads API. Use the Releases API instead. */ class Downloads extends AbstractPackage { @@ -37,10 +34,17 @@ class Downloads extends AbstractPackage * @return object * * @since 1.0 - * @deprecated The Releases API should be used instead + * @deprecated 5.0 GitHub has removed the Downloads API. Use the Releases API instead. */ public function getList($owner, $repo) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the Downloads API. Use the Releases API instead.', + __METHOD__ + ); + // Build the request path. $path = '/repos/' . $owner . '/' . $repo . '/downloads'; @@ -60,10 +64,17 @@ public function getList($owner, $repo) * @return object * * @since 1.0 - * @deprecated The Releases API should be used instead + * @deprecated 5.0 GitHub has removed the Downloads API. Use the Releases API instead. */ public function get($owner, $repo, $id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the Downloads API. Use the Releases API instead.', + __METHOD__ + ); + // Build the request path. $path = '/repos/' . $owner . '/' . $repo . '/downloads/' . $id; @@ -90,10 +101,17 @@ public function get($owner, $repo, $id) * @note This API endpoint no longer exists at GitHub * @since 1.0 * @throws \RuntimeException - * @deprecated The Releases API should be used instead + * @deprecated 5.0 GitHub has removed the Downloads API. Use the Releases API instead. */ public function create($owner, $repo, $name, $size, $description = '', $contentType = '') { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the Downloads API. Use the Releases API instead.', + __METHOD__ + ); + throw new \RuntimeException('The GitHub API no longer supports creating downloads. The Releases API should be used instead.'); } @@ -140,10 +158,17 @@ public function create($owner, $repo, $name, $size, $description = '', $contentT * @note This API endpoint no longer exists at GitHub * @since 1.0 * @throws \RuntimeException - * @deprecated The Releases API should be used instead + * @deprecated 5.0 GitHub has removed the Downloads API. Use the Releases API instead. */ public function upload($key, $acl, $successActionStatus, $filename, $awsAccessKeyId, $policy, $signature, $contentType, $file) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the Downloads API. Use the Releases API instead.', + __METHOD__ + ); + throw new \RuntimeException('The GitHub API no longer supports creating downloads. The Releases API should be used instead.'); } @@ -157,10 +182,17 @@ public function upload($key, $acl, $successActionStatus, $filename, $awsAccessKe * @return object * * @since 1.0 - * @deprecated The Releases API should be used instead + * @deprecated 5.0 GitHub has removed the Downloads API. Use the Releases API instead. */ public function delete($owner, $repo, $id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the Downloads API. Use the Releases API instead.', + __METHOD__ + ); + // Build the request path. $path = '/repos/' . $owner . '/' . $repo . '/downloads/' . (int) $id; diff --git a/src/RequestHeadersHttp.php b/src/RequestHeadersHttp.php new file mode 100644 index 00000000..2b188bdb --- /dev/null +++ b/src/RequestHeadersHttp.php @@ -0,0 +1,213 @@ +getClient(); + } + + $this->client = $client; + $this->headers = $headers; + } + + /** + * Get the wrapped HTTP client. + * + * @return Http + * + * @since __DEPLOY_VERSION__ + */ + public function getClient(): Http + { + return $this->client; + } + + /** + * Get an option from the wrapped HTTP client. + * + * @param string $key The name of the option to get. + * @param mixed $default The default value if the option is not set. + * + * @return mixed The option value. + * + * @since __DEPLOY_VERSION__ + */ + public function getOption($key, $default = null) + { + return $this->client->getOption($key, $default); + } + + /** + * Set an option on the wrapped HTTP client. + * + * @param string $key The name of the option to set. + * @param mixed $value The option value to set. + * + * @return $this + * + * @since __DEPLOY_VERSION__ + */ + public function setOption($key, $value) + { + $this->client->setOption($key, $value); + + return $this; + } + + /** + * {@inheritdoc} + */ + public function options($url, array $headers = [], $timeout = null) + { + return $this->withHeaders(fn () => $this->client->options($url, $headers, $timeout)); + } + + /** + * {@inheritdoc} + */ + public function head($url, array $headers = [], $timeout = null) + { + return $this->withHeaders(fn () => $this->client->head($url, $headers, $timeout)); + } + + /** + * {@inheritdoc} + */ + public function get($url, array $headers = [], $timeout = null) + { + return $this->withHeaders(fn () => $this->client->get($url, $headers, $timeout)); + } + + /** + * {@inheritdoc} + */ + public function post($url, $data, array $headers = [], $timeout = null) + { + return $this->withHeaders(fn () => $this->client->post($url, $data, $headers, $timeout)); + } + + /** + * {@inheritdoc} + */ + public function put($url, $data, array $headers = [], $timeout = null) + { + return $this->withHeaders(fn () => $this->client->put($url, $data, $headers, $timeout)); + } + + /** + * {@inheritdoc} + */ + public function delete($url, array $headers = [], $timeout = null, $data = null) + { + return $this->withHeaders(fn () => $this->client->delete($url, $headers, $timeout, $data)); + } + + /** + * {@inheritdoc} + */ + public function trace($url, array $headers = [], $timeout = null) + { + return $this->withHeaders(fn () => $this->client->trace($url, $headers, $timeout)); + } + + /** + * {@inheritdoc} + */ + public function patch($url, $data, array $headers = [], $timeout = null) + { + return $this->withHeaders(fn () => $this->client->patch($url, $data, $headers, $timeout)); + } + + /** + * {@inheritdoc} + */ + public function sendRequest(RequestInterface $request): ResponseInterface + { + return $this->withHeaders(fn () => $this->client->sendRequest($request)); + } + + /** + * Run a request with the GitHub headers added to the wrapped client, and restore its headers afterwards. + * + * The headers are put on the client's options rather than passed with the request, so that request headers + * passed by the caller keep precedence, as they do for the client's own headers. + * + * @param callable $request Callback sending the request. + * + * @return mixed The response. + * + * @since __DEPLOY_VERSION__ + */ + private function withHeaders(callable $request) + { + $original = $this->client->getOption('headers'); + $headers = (array) ($original ?? []); + $existing = array_change_key_case($headers, \CASE_LOWER); + + foreach (($this->headers)() as $name => $value) { + if (!isset($existing[strtolower($name)])) { + $headers[$name] = $value; + } + } + + $this->client->setOption('headers', $headers); + + try { + return $request(); + } finally { + $this->client->setOption('headers', $original); + } + } +} From 59b6c6978b3e8282c7b293ac99458fab08e77f92 Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Thu, 12 Nov 2026 23:51:50 +0100 Subject: [PATCH 5/5] Send JSON request bodies with Content-Type application/json The packages send JSON strings as request bodies, but without a content type joomla/http labels them application/x-www-form-urlencoded. Add Content-Type: application/json for string bodies unless a content type is set on the client or passed with the request. Co-Authored-By: Claude Opus 5.5 --- Tests/GithubObjectTest.php | 19 +++++++++++++++++++ docs/overview.md | 5 +++-- src/RequestHeadersHttp.php | 21 ++++++++++++++------- 3 files changed, 36 insertions(+), 9 deletions(-) diff --git a/Tests/GithubObjectTest.php b/Tests/GithubObjectTest.php index 3e4dcdbe..2e01d27c 100755 --- a/Tests/GithubObjectTest.php +++ b/Tests/GithubObjectTest.php @@ -312,4 +312,23 @@ public function testSubPackagesSendTheHeaders() $this->assertSame('https://api.github.com/repos/joomla/joomla-framework/forks', $transport->requests[0]['uri']); $this->assertSame('token MyTestToken', $transport->requests[0]['headers']['Authorization']); } + + /** + * Tests that a JSON body is sent as application/json, and a form body keeps the transport's content type + * + * @return void + */ + public function testJsonBodyContentType() + { + $transport = new RecordingTransport(); + $client = new Http([], $transport); + $github = new Github($this->options, $client); + + $github->markdown->render('Hello'); + $github->authorization->requestToken('{id}', '{secret}', '{code}', '', 'json'); + + $this->assertSame('application/json', $transport->requests[0]['headers']['Content-Type']); + $this->assertArrayNotHasKey('Content-Type', $transport->requests[1]['headers']); + $this->assertNull($client->getOption('headers')); + } } diff --git a/docs/overview.md b/docs/overview.md index 347c924b..ff208c00 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -24,8 +24,9 @@ $options->set('gh.token_scheme', 'Bearer'); $github = new Github($options); ``` -Every request also sends `Accept: application/vnd.github+json`. A header set on the HTTP client (its `headers` -option) or passed with a request takes precedence over these defaults. +Every request also sends `Accept: application/vnd.github+json`, and a JSON request body is sent with +`Content-Type: application/json`. A header set on the HTTP client (its `headers` option) or passed with a request +takes precedence over these defaults. GitHub removed password authentication for the API in November 2020; `api.username` and `api.password` only work against GitHub Enterprise Server instances that still accept it. They are sent in the `Authorization` header, not in diff --git a/src/RequestHeadersHttp.php b/src/RequestHeadersHttp.php index 2b188bdb..2d7cb4c3 100644 --- a/src/RequestHeadersHttp.php +++ b/src/RequestHeadersHttp.php @@ -135,7 +135,7 @@ public function get($url, array $headers = [], $timeout = null) */ public function post($url, $data, array $headers = [], $timeout = null) { - return $this->withHeaders(fn () => $this->client->post($url, $data, $headers, $timeout)); + return $this->withHeaders(fn () => $this->client->post($url, $data, $headers, $timeout), $data); } /** @@ -143,7 +143,7 @@ public function post($url, $data, array $headers = [], $timeout = null) */ public function put($url, $data, array $headers = [], $timeout = null) { - return $this->withHeaders(fn () => $this->client->put($url, $data, $headers, $timeout)); + return $this->withHeaders(fn () => $this->client->put($url, $data, $headers, $timeout), $data); } /** @@ -151,7 +151,7 @@ public function put($url, $data, array $headers = [], $timeout = null) */ public function delete($url, array $headers = [], $timeout = null, $data = null) { - return $this->withHeaders(fn () => $this->client->delete($url, $headers, $timeout, $data)); + return $this->withHeaders(fn () => $this->client->delete($url, $headers, $timeout, $data), $data); } /** @@ -167,7 +167,7 @@ public function trace($url, array $headers = [], $timeout = null) */ public function patch($url, $data, array $headers = [], $timeout = null) { - return $this->withHeaders(fn () => $this->client->patch($url, $data, $headers, $timeout)); + return $this->withHeaders(fn () => $this->client->patch($url, $data, $headers, $timeout), $data); } /** @@ -182,21 +182,28 @@ public function sendRequest(RequestInterface $request): ResponseInterface * Run a request with the GitHub headers added to the wrapped client, and restore its headers afterwards. * * The headers are put on the client's options rather than passed with the request, so that request headers - * passed by the caller keep precedence, as they do for the client's own headers. + * passed by the caller keep precedence, as they do for the client's own headers. A string body is sent as JSON + * unless a content type is given. * * @param callable $request Callback sending the request. + * @param mixed $data The request body. * * @return mixed The response. * * @since __DEPLOY_VERSION__ */ - private function withHeaders(callable $request) + private function withHeaders(callable $request, $data = null) { $original = $this->client->getOption('headers'); $headers = (array) ($original ?? []); $existing = array_change_key_case($headers, \CASE_LOWER); + $added = ($this->headers)(); - foreach (($this->headers)() as $name => $value) { + if (\is_string($data)) { + $added['Content-Type'] = 'application/json'; + } + + foreach ($added as $name => $value) { if (!isset($existing[strtolower($name)])) { $headers[$name] = $value; }