Add more docs & clean array args

Author: valendesigns

wp-includes/rest-api/auth/class-wp-rest-key-pair.php

@@ -103,10 +103,7 @@ public function register_routes() {
 					'validate_callback' => 'rest_validate_request_arg',
 				),
 			),
-			'schema'   => array(
-				$this,
-				'get_item_schema',
-			),
+			'schema'   => array( $this, 'get_item_schema' ),
 		);
 		register_rest_route( self::_NAMESPACE_, '/' . self::_REST_BASE_ . '/(?P<user_id>[\d]+)', $args );
 
@@ -306,7 +303,9 @@ public function require_token( $require_token, $request_uri, $request_method ) {
 	 * Authenticate the key-pair if API key and API secret is provided and return the user.
 	 *
 	 * If not authenticated, send back the original $user value to allow other authentication
-	 * methods to attempt authentication.
+	 * methods to attempt authentication. If the initial value of `$user` is false this method
+	 * will return a `WP_User` object on success or a `WP_Error` object on failure. However,
+	 * if the value is not `false` it will return that value, which could be any type of object.
 	 *
 	 * @filter rest_authentication_user
 	 *
@@ -383,6 +382,11 @@ public function authenticate( $user, WP_REST_Request $request ) {
 	/**
 	 * Filters the JWT Payload.
 	 *
+	 * Due to the fact that `$user` could have been filtered the object type is technically
+	 * unknown. However, likely a `WP_User` object if auth has not been filtered. In any
+	 * case, the object must have the `$user->data->api_key` property in order to connect
+	 * the API key to the JWT payload and allow for token invalidation.
+	 *
 	 * @filter rest_authentication_token_private_claims
 	 *
 	 * @param array          $payload The payload used to generate the token.

wp-includes/rest-api/auth/class-wp-rest-token.php

@@ -89,43 +89,35 @@ public static function get_rest_uri() {
 	 */
 	public function register_routes() {
 		$args = array(
-			array(
-				'methods'  => WP_REST_Server::CREATABLE,
-				'callback' => array(
-					$this,
-					'generate_token',
+			'methods'  => WP_REST_Server::CREATABLE,
+			'callback' => array( $this, 'generate_token' ),
+			'args'     => array(
+				'username'   => array(
+					'description'       => __( 'The username of the user; requires also setting the password argument.', 'jwt-auth' ),
+					'type'              => 'string',
+					'sanitize_callback' => 'sanitize_user',
+					'validate_callback' => 'rest_validate_request_arg',
 				),
-				'args'     => array(
-					'username'   => array(
-						'description'       => __( 'The username of the user; requires also setting the password argument.', 'jwt-auth' ),
-						'type'              => 'string',
-						'sanitize_callback' => 'sanitize_user',
-						'validate_callback' => 'rest_validate_request_arg',
-					),
-					'password'   => array(
-						'description'       => __( 'The password of the user; requires also setting the username argument.', 'jwt-auth' ),
-						'type'              => 'string',
-						'sanitize_callback' => 'sanitize_text_field',
-						'validate_callback' => 'rest_validate_request_arg',
-					),
-					'api_key'    => array(
-						'description'       => __( 'The API key of the user; requires also setting the api_secret.', 'jwt-auth' ),
-						'type'              => 'string',
-						'sanitize_callback' => 'sanitize_text_field',
-						'validate_callback' => 'rest_validate_request_arg',
-					),
-					'api_secret' => array(
-						'description'       => __( 'The API secret of the user; requires also setting the api_key.', 'jwt-auth' ),
-						'type'              => 'string',
-						'sanitize_callback' => 'sanitize_text_field',
-						'validate_callback' => 'rest_validate_request_arg',
-					),
+				'password'   => array(
+					'description'       => __( 'The password of the user; requires also setting the username argument.', 'jwt-auth' ),
+					'type'              => 'string',
+					'sanitize_callback' => 'sanitize_text_field',
+					'validate_callback' => 'rest_validate_request_arg',
+				),
+				'api_key'    => array(
+					'description'       => __( 'The API key of the user; requires also setting the api_secret.', 'jwt-auth' ),
+					'type'              => 'string',
+					'sanitize_callback' => 'sanitize_text_field',
+					'validate_callback' => 'rest_validate_request_arg',
+				),
+				'api_secret' => array(
+					'description'       => __( 'The API secret of the user; requires also setting the api_key.', 'jwt-auth' ),
+					'type'              => 'string',
+					'sanitize_callback' => 'sanitize_text_field',
+					'validate_callback' => 'rest_validate_request_arg',
 				),
 			),
-			'schema' => array(
-				$this,
-				'get_item_schema',
-			),
+			'schema'   => array( $this, 'get_item_schema' ),
 		);
 		register_rest_route( self::_NAMESPACE_, '/' . self::_REST_BASE_, $args );
 	}