63946: Add "resolvable" routes for the REST API

src/wp-includes/rest-api.php

@@ -92,67 +92,88 @@ function register_rest_route( $route_namespace, $route, $args = array(), $overri
 		);
 	}
 
-	if ( isset( $args['args'] ) ) {
+	if ( ! is_callable( $args ) && isset( $args['args'] ) ) {
 		$common_args = $args['args'];
 		unset( $args['args'] );
 	} else {
 		$common_args = array();
 	}
 
-	if ( isset( $args['callback'] ) ) {
+	if ( is_callable( $args ) || isset( $args['callback'] ) ) {
 		// Upgrade a single set to multiple.
 		$args = array( $args );
 	}
 
-	$defaults = array(
-		'methods'  => 'GET',
-		'callback' => null,
-		'args'     => array(),
-	);
-
 	foreach ( $args as $key => &$arg_group ) {
 		if ( ! is_numeric( $key ) ) {
 			// Route option, skip here.
 			continue;
 		}
 
-		$arg_group         = array_merge( $defaults, $arg_group );
-		$arg_group['args'] = array_merge( $common_args, $arg_group['args'] );
+		if ( is_callable( $arg_group ) ) {
+			// Just-in-time resolvable callback, we'll normalize it later.
+			$arg_group = new WP_REST_Resolvable_Route( $clean_namespace, $route, $arg_group );
+			continue;
+		}
+
+		$arg_group = normalize_rest_endpoint_options( $clean_namespace, $route, $arg_group, $common_args );
+	}
+
+	$full_route = '/' . $clean_namespace . '/' . trim( $route, '/' );
+	rest_get_server()->register_route( $clean_namespace, $full_route, $args, $override );
+	return true;
+}
+
+/**
+ * Normalize the options for a single REST API endpoint.
+ *
+ * @since X.X.0
+ *
+ * @param string $namespace The route namespace.
+ * @param string $route     The route.
+ * @param array  $endpoint  The endpoint options.
+ * @param array  $common_args Common arguments to merge with endpoint-specific arguments.
+ */
+function normalize_rest_endpoint_options( string $namespace, string $route, array $endpoint, array $common_args = array() ) {
+	$defaults = array(
+		'methods'  => 'GET',
+		'callback' => null,
+		'args'     => array(),
+	);
+	$endpoint         = array_merge( $defaults, $endpoint );
+	$endpoint['args'] = array_merge( $common_args, $endpoint['args'] );
+
+	if ( ! isset( $endpoint['permission_callback'] ) ) {
+		_doing_it_wrong(
+			'register_rest_route',
+			sprintf(
+				/* translators: 1: The REST API route being registered, 2: The argument name, 3: The suggested function name. */
+				__( 'The REST API route definition for %1$s is missing the required %2$s argument. For REST API routes that are intended to be public, use %3$s as the permission callback.' ),
+				'<code>' . $namespace . '/' . trim( $route, '/' ) . '</code>',
+				'<code>permission_callback</code>',
+				'<code>__return_true</code>'
+			),
+			'5.5.0'
+		);
+	}
 
-		if ( ! isset( $arg_group['permission_callback'] ) ) {
+	foreach ( $endpoint['args'] as $arg ) {
+		if ( ! is_array( $arg ) ) {
 			_doing_it_wrong(
-				__FUNCTION__,
+				'register_rest_route',
 				sprintf(
-					/* translators: 1: The REST API route being registered, 2: The argument name, 3: The suggested function name. */
-					__( 'The REST API route definition for %1$s is missing the required %2$s argument. For REST API routes that are intended to be public, use %3$s as the permission callback.' ),
-					'<code>' . $clean_namespace . '/' . trim( $route, '/' ) . '</code>',
-					'<code>permission_callback</code>',
-					'<code>__return_true</code>'
+					/* translators: 1: $args, 2: The REST API route being registered. */
+					__( 'REST API %1$s should be an array of arrays. Non-array value detected for %2$s.' ),
+					'<code>$args</code>',
+					'<code>' . $namespace . '/' . trim( $route, '/' ) . '</code>'
 				),
-				'5.5.0'
+				'6.1.0'
 			);
-		}
-
-		foreach ( $arg_group['args'] as $arg ) {
-			if ( ! is_array( $arg ) ) {
-				_doing_it_wrong(
-					__FUNCTION__,
-					sprintf(
-						/* translators: 1: $args, 2: The REST API route being registered. */
-						__( 'REST API %1$s should be an array of arrays. Non-array value detected for %2$s.' ),
-						'<code>$args</code>',
-						'<code>' . $clean_namespace . '/' . trim( $route, '/' ) . '</code>'
-					),
-					'6.1.0'
-				);
-				break; // Leave the foreach loop once a non-array argument was found.
-			}
+			break; // Leave the foreach loop once a non-array argument was found.
 		}
 	}
 
-	$full_route = '/' . $clean_namespace . '/' . trim( $route, '/' );
-	rest_get_server()->register_route( $clean_namespace, $full_route, $args, $override );
-	return true;
+	return $endpoint;
 }
 
 /**

src/wp-includes/rest-api/class-wp-rest-resolvable-route.php

@@ -0,0 +1,147 @@
+<?php
+/**
+ * REST API: WP_REST_Resolvable_Route class
+ *
+ * @package WordPress
+ * @subpackage REST_API
+ * @since X.X.0
+ */
+
+/**
+ * Just-in-time resolvable route for REST API routes.
+ *
+ * @since X.X.0
+ */
+class WP_REST_Resolvable_Route implements ArrayAccess, IteratorAggregate, Countable {
+	protected $namespace;
+	protected $route;
+
+	/**
+	 * The callable used to resolve the route.
+	 *
+	 * @since X.X.0
+	 * @var callable
+	 */
+	protected $callable;
+
+	/**
+	 * The resolved route definition.
+	 *
+	 * @since X.X.0
+	 * @var array|null
+	 */
+	protected $resolved = null;
+
+	/**
+	 * Constructor.
+	 *
+	 * @since X.X.0
+	 *
+	 * @param callable $closure The callable used to resolve the route. Returns a single route definition.
+	 */
+	public function __construct( string $namespace, string $route, callable $closure ) {
+		$this->namespace = $namespace;
+		$this->route = $route;
+		$this->callable = $closure;
+	}
+
+	/**
+	 * Invokes the callable to resolve, if needed.
+	 *
+	 * Routes can only be resolved once, the first time they're used. Any
+	 * subsequent calls will return the same resolved definition, which may
+	 * be modified by reference if needed.
+	 *
+	 * @since X.X.0
+	 *
+	 * @return array The resolved route definition.
+	 */
+	public function __invoke() {
+		if ( ! $this->resolved ) {
+			$this->resolved = call_user_func( $this->callable );
+
+			// Normalize the result.
+			$this->resolved = normalize_rest_endpoint_options( $this->namespace, $this->route, $this->resolved );
+		}
+		return $this->resolved;
+	}
+
+	/**
+	 * Checks a single array key exists in the resolved route definition.
+	 *
+	 * @since X.X.0
+	 *
+	 * @param string $key The key to check.
+	 * @return bool True if the key exists, false otherwise.
+	 */
+	#[ReturnTypeWillChange]
+	public function offsetExists( $k ) {
+		$this->__invoke();
+		return isset( $this->resolved[ $k ] );
+	}
+
+	/**
+	 * Gets a single array key from the resolved route definition.
+	 *
+	 * @since X.X.0
+	 *
+	 * @param string $key The key to retrieve.
+	 * @return mixed The value of the key, or null if not set. Returns by reference, so it can be modified if needed.
+	 */
+	#[ReturnTypeWillChange]
+	public function &offsetGet( $k ) {
+		$this->__invoke();
+		return $this->resolved[ $k ];
+	}
+
+	/**
+	 * Sets a single array key in the resolved route definition.
+	 *
+	 * @since X.X.0
+	 *
+	 * @param string $key The key to set.
+	 * @param mixed $value The value to set.
+	 */
+	#[ReturnTypeWillChange]
+	public function offsetSet( $k, $v ) {
+		$this->__invoke();
+		$this->resolved[ $k ] = $v;
+	}
+
+	/**
+	 * Unsets a single array key in the resolved route definition.
+	 *
+	 * @since X.X.0
+	 *
+	 * @param string $key The key to unset.
+	 */
+	#[ReturnTypeWillChange]
+	public function offsetUnset( $k ) {
+		$this->__invoke();
+		unset( $this->resolved[ $k ] );
+	}
+
+	/**
+	 * Gets an iterator for the resolved route definition.
+	 *
+	 * @since X.X.0
+	 *
+	 * @return Traversable An iterator for the resolved route definition.
+	 */
+	public function getIterator(): Traversable {
+		$this->__invoke();
+		return new ArrayIterator( $this->resolved );
+	}
+
+	/**
+	 * Counts the number of elements in the resolved route definition.
+	 *
+	 * @since X.X.0
+	 *
+	 * @return int The number of elements in the resolved route definition.
+	 */
+	public function count(): int {
+		$this->__invoke();
+		return count( $this->resolved );
+	}
+}