markzero/wp-on-routes

WordPress plugin that adds API-like functionality by allowing you to add custom routes

dev-master 2015-10-13 09:47 UTC

Requires

• php: >=5.3.0
• composer/installers: ~1.0

Requires (Dev)

• phpunit/phpunit: 4.0.*

MIT

• Marko Jakic

• route
• rest
• api
• restful
• wordpress
• params

README

WordPress on Routes is a plugin for WordPress, inspired mainly by Ruby micro-frameworks. It adds ability to add custom routes to your WordPress instance. Useful for form submissions, API-like features, etc.

It's also hosted under Plugins repo: https://wordpress.org/plugins/wp-on-routes/.

Installation

Good old plugin installation applies here too - download it / clone it to plugins/ dir, activate.

No UI involved.

Basic Usage

In your functions.php:

$routing = \WoR\Main::get_instance();

$routing->add_routes(
  array(
    'get' => array(
      'path' => '/foo/bar',
      'body' => 'Hello Buz!',
      'headers' => array(
        'Content-Type' => 'text/html; charset=UTF-8',
        'exclude' => array(
          'x-powered-by', 'x-pingback'
        )
      )
    )
  )
);

Naturally, you have to check for class existence (e.g. in lib/routes.php file):

if (!class_exists('\WoR\Main')) {
  return;
}

And use it in functions.php:

require_once('lib/routes.php');

Remember, because of using namespaces your PHP installation version must be >= 5.3.0.

Extended Usage

function wor_dump() {
  var_dump($_GET);
}

add_action('wor_action', 'wor_dump');

$routing = \WoR\Main::get_instance();

$routing->add_routes(
  array(
    'get' => array(
      'path' => '/foo/*/bar/:p1?',
      'action' => 'wor_action',
      'agent' => '/Firefox/',
      'include_template' => true
    )
  )
);

In example above, if you target /foo/a/b/c/bar/test, browser will answer with HTTP status 200, with following code, with header and footer included, only in Firefox browser:

array (size=2)
  'p1' => string 'test' (length=4)
  'splats' => 
    array (size=1)
      0 => string 'a/b/c' (length=5)

Details

At this point there are several capabilities:

1. Add custom routes to your WordPress installation
2. Set method GET/POST/DELETE etc.
3. Set body (as text, or template) or action (using add/do_action). If both are defined, action takes precedence over body.
4. Set header (e.g. 'Content-Type' => 'text/html; charset=UTF-8')
5. Exclude header (e.g. 'Set-Cookie')
6. Set parameters like /my/route/:param1/:param2 or as splats /foo/*/bar
7. Add agents or filter by agents, using regular expressions
8. Agent filter for negative logic (e.g. /^((?!Firefox).)*$/, which tells "every browser except Firefox")
9. Include header and footer

Options you can set:

1. path (string)
2. body OR action (string)
3. agent (string/regex)
4. include_template (boolean; default: false)
5. headers (array)

• exclude (array)

Tests

Reference to tests/instructions.txt to read how to test output of your WordPress website.

I am using wp-cli to generate testing environment: https://github.com/wp-cli/wp-cli/wiki/Plugin-Unit-Tests.

So, before any testing run similar command: bash bin/install-wp-tests.sh wor_test_db root root localhost latest.