Update to newer Github API

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {

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.

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);

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
 {

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__ 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.
  */
 class Downloads extends AbstractPackage
 {