Public API

Plugin Hooks

Hook ID	Description	Support
front-route	Called when front router is registering the routes	0.1+

Public Methods

addFrontRoute(string $route, function $action) : void

Adds a front route with a given $route and $action. Use with the front-route hook during plugin registration to register the route.

// your_plugin.php

// ...
register_plugin(
  /* */
);

// ...

add_action('front-route', 'addFrontRoute', array(
  // Route
  'your/desired/regex/route/(.*)',

  // Action
  // Parameters passed are the same as the ones passed to the 'content' action
  function($url) {
    return array(
      'title'   => 'Your Desired Page Title',
      'content' => function($url) {
        echo 'You are on your/desired/regex/route/' . $url;
      }
    );
  }
));

You can write lightweight (read: single file) plugins whose job is only to set up the routes for functionality existing on your installation (e.g. tying together functionality for a specific configuration of plugins).

Route Actions

Actions are functions that return an array of information. This information will modify the page's content in the event of a successful route match. For example:

// Route
test

// Action
<?php
return array(
  'title'   => 'Test'
  'content' => 'Test page',
);

Basic Action Options

title

• Type: string
• Optional
• Since: v0.1

The page title. If it matches an existing page it will use that title. Otherwise it will have the 404 error title.

content

• Type: string|function
• Mandatory
• Since: v0.1

The content to be displayed. If it is a string, the page content will just be the string. If it is a function, the router will execute the function, and pass the matched strings as arguments. The echoed output will be buffered into a string and used for the new page content.

// Route
test/([a-z0-9-]+)

// Action
<?php

return array(
  'title'   => 'Test with example slug',
  'content' => function($slug) {
    echo 'You are currently on page ' . $slug;
  }
);

template

• Type: string
• Optional
• Since: v0.4.2

The template file for the active theme, which renders the rest of the page. This defaults to template.php.

REST API Options

The following properties are to be used for RESTful API services. These will completely overwrite the original page's HTML output.

content

• Type: function
• Mandatory
• Since: v0.5.0

The content for RESTful services must return their data, rather than echo it. The data should be the kind that can be transformed into the corresponding type (described below). This usually means returning an array or an object.

// Route
api/v1/item/([a-z0-9-]+)

// Action
<?php

return array(
  'type'    => 'json', // Formats the output as JSON
  'content' => function($slug) {
    // Assuming there are functions for getting item data...
    $success = item_exists($slug);

    if ($success) {
      $item = get_item($slug);
    } else {
      $item = null;
    }

    // Result object data
    $result = array(
      'version' => '1.0',
      'item'    => $item,
      'success' => $success,
    );

    // Return the data - the plugin will transform it into a valid JSON
    return $result;
  }
);

type

• Type: string
• Mandatory if you want the route to be a RESTful endpoint
• Since: v0.5.0

Specify the output type of your API's endpoint (json or xml).

If you use xml:

• If you want an XML node to have attributes, then have a key for that node called @attributes:

  /// Produces XML: <item name="Item 1" price="£3.99">
  $result = array(
    'item' => array(
      '@attributes' => array(
        'name'  => 'Item 1',
        'price' => '£3.99',
      )
    ),
  );

• If you want to have multiple nodes with the same name, the data should be passed as an array:

  // Produces XML:
  //   <item>Item 1</item>
  //   <item>Item 2</item>
  //   <item>Item 3</item>
  $result = array(
    'item' => array(
      'Item 1',
      'Item 2',
      'Item 3',
    )
  );

method

• Type: string
• Optional
• Since: v0.5.0

Specify the response type (e.g. get, post). If the response type does not match this, the route will fail. Leave empty to match any response type.