Requests_Auth: change to namespaced interface

Includes:
* Moving the namespaced version of the interface to the `src` directory.
* [Custom autoload] Adding the interface to the `$deprecated_classes` array in the `WpOrg\Requests\Autoload` class.
* [Composer autoload] Adding the interface to a new `Deprecated.php` file.
    Same as the custom autoloader when encountering deprecated classes, loading this file will also trigger a deprecation notice.
    And again, same as the custom autoloader, the deprecation notice can be silenced by setting a `REQUESTS_SILENCE_PSR0_DEPRECATIONS` constant.
* Adding the new `Deprecated.php` file to the Composer `autoload` directive to be indexed to a classmap.
* Updating all references to the interface.

composer.json

@@ -56,7 +56,8 @@
     },
     "psr-4": {
       "WpOrg\\Requests\\": "src/"
-    }
+    },
+    "classmap": ["library/Deprecated.php"]
   },
   "autoload-dev": {
     "psr-4": {

docs/authentication-custom.md

@@ -1,7 +1,7 @@
 Custom Authentication
 =====================
 Custom authentication handlers are designed to be straight-forward to write.
-In order to write a handler, you'll need to implement the `Requests_Auth`
+In order to write a handler, you'll need to implement the `WpOrg\Requests\Auth`
 interface.
 
 An instance of this handler can then be passed to Requests via the `auth`
@@ -12,7 +12,7 @@ authenticates the call if said header is set to `Yummy`. (I don't know of any
 services that do this; perhaps this is a market waiting to be tapped?)
 
 ```php
-class MySoftware_Auth_Hotdog implements Requests_Auth {
+class MySoftware_Auth_Hotdog implements WpOrg\Requests\Auth {
     protected $password;
 
     public function __construct($password) {

library/Deprecated.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * Backwards compatibility layer for Requests.
+ *
+ * Allows for Composer to autoload the old PSR-0 class names based on a classmap.
+ *
+ * All classes in this file are deprecated.
+ * Please see the Changelog for the 2.0.0 release for upgrade notes.
+ *
+ * @package Requests
+ *
+ * @deprecated 2.0.0 Use the PSR-4 class names instead.
+ */
+
+/*
+ * Integrators who cannot yet upgrade to the PSR-4 class names can silence deprecations
+ * by defining a `REQUESTS_SILENCE_PSR0_DEPRECATIONS` constant and setting it to `true`.
+ * The constant needs to be defined before the first deprecated class is requested
+ * via this Composer autoload file.
+ */
+if (!defined('REQUESTS_SILENCE_PSR0_DEPRECATIONS') || REQUESTS_SILENCE_PSR0_DEPRECATIONS !== true) {
+	// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
+	trigger_error(
+		'The PSR-0 `Requests_...` class names in the Request library are deprecated.'
+		. ' Switch to the PSR-4 `WpOrg\Requests\...` class names at your earliest convenience.',
+		E_USER_DEPRECATED
+	);
+}
+
+interface Requests_Auth extends WpOrg\Requests\Auth {}

library/Requests/Auth/Basic.php

@@ -6,6 +6,8 @@
  * @subpackage Authentication
  */
 
+use WpOrg\Requests\Auth;
+
 /**
  * Basic Authentication provider
  *
@@ -15,7 +17,7 @@
  * @package Requests
  * @subpackage Authentication
  */
-class Requests_Auth_Basic implements Requests_Auth {
+class Requests_Auth_Basic implements Auth {
 	/**
 	 * Username
 	 *

library/Requests/Auth.php → src/Auth.php

@@ -6,6 +6,10 @@
  * @subpackage Authentication
  */
 
+namespace WpOrg\Requests;
+
+use Requests_Hooks;
+
 /**
  * Authentication provider interface
  *
@@ -18,7 +22,7 @@
  * @package Requests
  * @subpackage Authentication
  */
-interface Requests_Auth {
+interface Auth {
 	/**
 	 * Register hooks as needed
 	 *

src/Autoload.php

@@ -32,7 +32,10 @@ class Autoload {
 		 *
 		 * @var array
 		 */
-		private static $deprecated_classes = array();
+		private static $deprecated_classes = array(
+			// Interfaces.
+			'requests_auth' => '\WpOrg\Requests\Auth',
+		);
 
 		/**
 		 * Whether or not a deprecation notice has been thrown for calling a deprecated class.

src/Requests.php

@@ -303,7 +303,7 @@ public static function patch($url, $headers, $data = array(), $options = array()
 	 *    (string|boolean, default: false)
 	 * - `auth`: Authentication handler or array of user/password details to use
 	 *    for Basic authentication
-	 *    (Requests_Auth|array|boolean, default: false)
+	 *    (\WpOrg\Requests\Auth|array|boolean, default: false)
 	 * - `proxy`: Proxy details to use for proxy by-passing and authentication
 	 *    (Requests_Proxy|array|string|boolean, default: false)
 	 * - `max_bytes`: Limit for the response body size.