Route

Defines a single route and its properties.

Methods (Setters)

namespace

public function namespace( string $namespace )

@param string $namespace
@return \PinkCrab\Route\Route\Route

Sets the namespace for the defined route, this is required (unless creating the route via the Route_Factory). This should be done in the same fashion as core WP Rest Registration my_thing/v1

Example

$route = new Route('GET', '/some_route');
$route->namespace('my_thing/v1');

The above would create an endpoint on https://www.url.com/wp-json/my_thing/v1/some_route for GET requests.

authentication

public function authentication( callable $auth_callback )

@param callable(WP_REST_Request $request):bool $auth_callback
@return \PinkCrab\Route\Route\Route

You can assign multiple authentication methods to a route, this allows you to have a global set of rules you apply to every route, and then some additional checks on a route by route basis.

Example

$route = new Route('GET', '/some_route');
$route->authentication( function( WP_REST_Request $request ):bool {
    // Do some checks (api key in header etc)
    return true;
});
$route->authentication('some_other_auth_callback');

When passing more than 1 auth callback, they are compiled into an ALL TRUE function. If any of them return false, the whole chain ends and returns false. All must return true.

callback

public function callback( callable $callback )

@param callable(WP_REST_Request $request):WP_REST_Response|WP_Error $auth_callback
@return \PinkCrab\Route\Route\Route

You can either return a WP_REST_Response with the response code defined, or a WP_Error if you wish to denote an error (500 response). Your callback will receive the current WP_REST_Request object, which you can use to run your code, ready to return.

$route = new Route('GET', '/some_route');
$route->callback( function( WP_REST_Request $request ) {
    // Do your logic here and then either return error or success.
    if('something' === 'something'){
        return new WP_REST_Response(['data' => 'Your data'], 200, ['optional' => 'headers']);
    } else {
        return new WP_Error(500, 'Something went wrong', ['data' => 'Your data']);
    }
});

You can always return using WP_REST_Response if you wish and just set the response code, but using WP_Error will ensure all call error handling takes place. Please see the WP_Codex for more information on populating either Response or WP_Error.

argument

public function argument( Argument $argument )

@param PinkCrab\WP_Rest_Schema\Argument\Argument $argument
@return \PinkCrab\Route\Route\Route

As per the WordPress API for routes, you will need to define all arguments used in the route URL. These should be passed to the route as a compiled Argument object, but as this uses a fluent API, it can be done inline.

$route = new Route('GET', '/some_route/{foo}');
$route->argument( String_Type::on('foo')->required() );

If you have more than one argument, you can pass as many as you need.

See below for more details on Arguemnts.

with_method

public function with_method( string $method )

@param string $argument
@return \PinkCrab\Route\Route\Route

If you would like to create a copy of an existing route, but with a different method, you can call this useful method. It will just clone the initial route but with an alternative method.

$route_post = new Route('POST', '/some_route');
// Your other setup. $route->authentication(....);

// Create a PUT route using the same setup, but with a different callback.
$route_put = $route_post->with_method('put');
$route_put->callback('some_other_callback');

If you are planning to create a route with multiple methods, please consider using the Route_Group (detailed below)

Methods (Getters)

Most of the Getter methods are primarily used internally, but you have access to them if you wish to create conditional logic around existing routes.

public function get_namespace()

@return string

Returns the currently defined namespace.

public function get_route()

@return string

Returns the currently defined route.

public function get_method()

@return string

Returns the currently defined route method.

public function get_arguments()

@return Argument[]

Returns an array of all defined arguments.

public function get_authentication()

@return callable[]

Returns an array of all defined authentication callbacks.