README

Starter package for working with the WordPress REST API in an object-oriented fashion.

Introduction

Since both the infrastructure and the first set of endpoints of the WordPress REST API got merged into Core, it’s obvious for plugin and even theme authors to jump on the bandwagon.
This package provides you with virtually anything you need to start feeling RESTful.

WP REST Starter consists of several interfaces for both data types and business logic, and it comes with straightforward implementations suitable for the common needs.
All you have to do is configure your REST routes and data structures, and implement the according request handlers.

Installation

Requirements

This package requires PHP 7 or higher.

Adding custom fields to existing resources requires WordPress 4.7 or higher, or the WP REST API plugin.
If all you want to do is define custom REST routes, you're already good to go with WordPress 4.4 or higher.

Usage

The following sections will help you get started with the WordPress REST API in an object-oriented fashion.
If you're new to working with the WordPress REST API in general, please refer to the REST API handbook.

Actions

In order to inform about certain events, some of the shipped classes provide you with custom actions.
For each of these, a short description as well as a code example on how to take action is given below.

Registering a Complex Custom Route

What follows is a more complete (and thus complex) example of registering a custom route.
The nature of the resource is described by using an according schema object.
Both the endpoint schema object and the request handlers are aware of additional fields registered by other parties for their individual resource.
The response objects also contain links (compact, if supported).

Adding Custom Fields to the Response of Existing Endpoints

The below example shows how to register two additional fields to all response objects of the targeted resource.
Of course, the according code that creates the response has to be aware of additional fields.
This is the case when the code uses either the WP_REST_Controller class or a (custom) implementation of the field processor interfaces provided in this package.

<?phpuseInpsyde\WPRESTStarter\Core\Field\Collection;useInpsyde\WPRESTStarter\Core\Field\Field;useInpsyde\WPRESTStarter\Core\Field\Registry;add_action( 'rest_api_init', function() {// Create a new field collection.$fields=newCollection();// Optional: Set up the field reader./** @var $reader Inpsyde\WPRESTStarter\Common\Field\Reader */$reader=newSome\Field\Reader();// Optional: Set up the field updater./** @var $updater Inpsyde\WPRESTStarter\Common\Field\Updater */$updater=newSome\Field\Updater();// Optional: Create a field schema./** @var $schema Inpsyde\WPRESTStarter\Common\Schema */$schema=newSome\Field\Schema();// Create a readable and updatable field for some resource.$field=newField( 'has_explicit_content' );$field->set_get_callback( $reader );$field->set_update_callback( $updater );$field->set_schema( $schema );// Add the field.$fields->add( 'some-data-type', $field );// Set up the field reader./** @var $reader Inpsyde\WPRESTStarter\Common\Field\Reader */$reader=newOther\Field\Reader();// Create another read-only field for some resource.$field=newField( 'is_long_read' );$field->set_get_callback( $reader );// Add the field.$fields->add( 'some-data-type', $field );// Register all fields. ( newRegistry() )->register_fields( $fields );} );

Example Endpoint Schema Implementation

The below endpoint schema implementation is aware of fields registered by other parties for the current resource.
By means of an injected (or defaulted) endpoint schema field processor object, the data of all registered schema-aware fields is added to the schema properties.

Example Endpoint Arguments Implementation

An endpoint arguments implementation is straightforward, and in most cases only a single method returning a hard-coded array.
The below code also contains a validate callback that returns a WP_Error object on failure.

Example Field Updater Implementation

The below field updater implementation uses a global callback to update the field value.
You could also inject an API object and use provided methods.
The injected permission callback, if any, is used to check permission prior to updating the field.

PSR-7

In the PHP world in general, there is a standard (recommendation) when it comes to HTTP messages: PSR-7.
Despite things like Calypso, Gutenberg and the growing JavaScript codebase in general, WordPress is written in PHP.
Thus, wouldn’t it be nice to do what the rest of the PHP world is doing?
Isn’t there some way to leverage all the existing PSR-7 middleware?

Well, there is!
Since version 3.1.0, WP REST Starter comes with enhanced, PSR-7-compliant WordPress REST request and response classes, each implementing the according PSR-7 HTTP message interface.
Using these classes enables you to integrate existing PSR-7 middleware into your RESTful WordPress project.

Creating a PSR-7-compliant WordPress REST Request

If you are interested in a PSR-7-compliant WordPress REST request object, you can, of course, create a new instance yourself.
You can do this like so, with all arguments being optional:

However, it is rather unlikely, because you usually do not want to define any request-based data on your own, ... since it is already included in the current request. :)
More likely is that you want to make an existing WordPress request object PSR-7-compliant, like so: