Download the PHP package / without Composer

WP Route

A Route Service for WordPress that uses the WordPress rewrite engine and adds Laravel syntax to it.

Table of Contents

• Introduction
• Getting Started
  • Installation
• Dependencies
  • morningtrain/php-loader
  • illuminate/pipeline
  • Symfony HTTP Foundation
• Usage
  • Setup
  • Adding a route
  • A route with arguments
  • Using named routes
  • Grouping Routes
  • Accessing WP Query Vars
• Middleware
  • A quick example
• REST
  • Options
  • Public
  • Expose
  • Changing the namespace
• Credits
• Testing
• License

Introduction

A Route is an address or endpoint in the application. Routes are defined in the /routes directory of your project, unless otherwise specified.

All files in this directory are loaded by the framework while it is booting up.

Note that the Route API imitates Laravel Route

Routes MUST call a Controller as callback!

Getting Started

To get started install the package as described below in Installation.

To use the tool have a look at Usage

Installation

Install with composer

Dependencies

morningtrain/php-loader

PHP Loader is used to load and initialize all Hooks

illuminate/pipeline

Illuminate Pipeline

Symfony HTTP Foundation

Symfony Http Foundation

Usage

Setup

Initialize the package with Route::setup($path) or, if the package is already initialized, load a directory of routes with Route::loadDir($path)

Adding a route

A route with arguments

Using named routes

Grouping Routes

You may group a set of routes to apply a shared prefix to all of them or to apply shared middleware.

With prefix

With middleware

With both prefix and middleware

Accessing WP Query Vars

WordPress query vars are added to the Request class as query data. So you can access them like so:

Middleware

Middleware are functions called for a route after it has been matched against a url, but before its callback is called.

Middleware are useful for validating a group of routes, validating a users permissions or hijacking a request.

Read more about them here: Laravel Docs - Middleware

A quick example

Middleware are function that receive a request object and a closure that represents the next middleware in the pipeline. It is important to always return $next($request); at the end of a valid middleware.

In the example below we create a middleware that stops the pipeline if the current user is not logged in and returns a response with status 404. If the user is logged in the middleware pipeline continues and eventually lets the route call its controller.

A middleware is allowed to either continue the pipeline, return a Response or throw an exception. Responses must be \Symfony\Component\HttpFoundation\Response and will be sent automatically. Exceptions are caught and converted into custom \Morningtrain\WP\Route\Responses\WPErrorResponse that are then displayed using wp_die()

Rest

You can also register rest endpoints using the same syntax! Behind the scenes all Rest routes are registered using register_rest_route

Options

You can use middleware, prefix, groups and names on Rest routes the same way as you can on rewrite routes!!

Note: Middleware is applied AFTER WordPress has identified the route and passed through all other verifications such as permission_callback, but before the controller or supplied callback is called.

Public

To make an endpoint public chain public() on either the route or its group. This simply sets the permission_callback to __return_true. This defaults to __return_false.

Expose

You can expose the endpoint URL to the DOM by chaining expose() onto the route or its group. This outputs the url to a JavaScript object similar to the way localize_script would.

The exposed url can be accessed like so:

Note: to expose an endpoint it has to be named.

Changing the namespace

You can set the namespace the same way you would a prefix.

This can be combined with prefixes

Credits

• Mathias Munk
• All Contributors

Testing

License

The MIT License (MIT). Please see License File for more information.