corpus/router

Simple Router

v1.1.0 2022-12-15 05:19 UTC

Requires

• php: >=7.1

Requires (Dev)

• corpus/coding-standard: ^0.6.0
• friendsofphp/php-cs-fixer: ^2.19
• phpunit/phpunit: ~7.5 | ~9.5
• squizlabs/php_codesniffer: ^3.7

MIT

• Jesse Donat

README

A Simple Collection of Routers

Requirements

• php: >=7.1

Installing

Install the latest version with:

composer require 'corpus/router'

Usage

HttpRouter

<?php

require __DIR__ . '/../vendor/autoload.php';

// $_SERVER => ['REQUEST_METHOD' => [ 'method' => 'POST' ]]
$router = new \Corpus\Router\HttpRouter('\\Corpus\\Controllers', $_SERVER);

$route = $router->match('test/controller:action');

// $route =
//	[
//		'controller' => '\\Corpus\\Controllers\\test\\controller',
//		'action'     => 'action',
//		'options'    => [],
//		'request'    => [ 'method' => 'POST' ],
//	]

// ----------------

$route = $router->match('test/controller?query=whatwhat');

// $route =
//	[
//		'controller' => '\\Corpus\\Controllers\\test\\controller',
//		'action'     => NULL,
//		'options'    => [ 'query'  => 'whatwhat' ],
//		'request'    => [ 'method' => 'POST' ],
//	]

// ----------------

$route = $router->match($_SERVER['REQUEST_URI']);

// $route = Current Request

// ----------------

$url = $router->generate('myNamespace\\admin', 'index');

// $url = '/myNamespace/admin:index'

// ----------------

$url = $router->generate('\\Corpus\\Controllers\\myNamespace\\admin', 'index');

// $url = '/myNamespace/admin:index'

// ----------------

try {
	$url = $router->generate('\\Invalid\\Absolute\\Controller', 'index');
}catch (\Corpus\Router\Exceptions\NonRoutableException $e) {
	$url = 'fail';
}

// $url = 'fail'

Documentation

Class: \Corpus\Router\HttpRouter

<?php
namespace Corpus\Router;

class HttpRouter {
	public const ACTION = 'action';
	public const CONTROLLER = 'controller';
	public const OPTIONS = 'options';
}

Method: HttpRouter->__construct

function __construct(string $rootNamespace [, array $server = []])

Parameters:

• array $server - The $_SERVER array - optional

Method: HttpRouter->match

function match(string $path) : ?array

Match given path to a route array.

A non-null route is not guaranteed to exist - just to be well formed.
It is up the implementations dispatch mechanism to decide it the route exists

The returned route array the the a shape of

[  
    // The controller action. Definition varies by router.  
    RouterInterface:ACTION     => 'action',  
  
    // An expected class name based on given rules. Not guaranteed to exist.  
    RouterInterface:CONTROLLER => '\Controller\www\index',  
  
    // Router specific but akin to $_GET - may contain additional options  
    RouterInterface:OPTIONS    => ['key' => 'value'],  
]  

Match given path to a route array.

A non-null route is not guaranteed to exist - just to be well formed.
It is up the implementations dispatch mechanism to decide it the route exists

The returned route array the the a shape of

[  
    // The controller action. Definition varies by router.  
    RouterInterface:ACTION     => 'action',  
  
    // An expected class name based on given rules. Not guaranteed to exist.  
    RouterInterface:CONTROLLER => '\Controller\www\index',  
  
    // Router specific but akin to $_GET - may contain additional options  
    RouterInterface:OPTIONS    => ['key' => 'value'],  
]  

Parameters:

• string $path - The path to match against including query string ala foo/bar.html?param=woo

Returns:

• array | null - route array or null on failure to route

Method: HttpRouter->generate

function generate($controller [, ?string $action = null [, array $options = []]]) : string

Generate a URL for the given controller, action and options

Parameters:

• object | string $controller - Instance or Relative 'admin\index' or absolute '\Controllers\www\admin\index'

Method: HttpRouter->getNamespace

function getNamespace() : string

Returns:

• string - The canonical namespace prefix

Class: \Corpus\Router\CliRouter

<?php
namespace Corpus\Router;

class CliRouter {
	public const ARGUMENTS = 'arguments';
	public const ACTION = 'action';
	public const CONTROLLER = 'controller';
	public const OPTIONS = 'options';
}

Method: CliRouter->__construct

function __construct($rootNamespace [, array $arguments = []])

Parameters:

• string $rootNamespace - The namespace prefix the controllers will be under

Method: CliRouter->match

function match(string $path) : ?array

Match given path to a route array.

A non-null route is not guaranteed to exist - just to be well formed.
It is up the implementations dispatch mechanism to decide it the route exists

The returned route array the the a shape of

[  
    // The controller action. Definition varies by router.  
    RouterInterface:ACTION     => 'action',  
  
    // An expected class name based on given rules. Not guaranteed to exist.  
    RouterInterface:CONTROLLER => '\Controller\www\index',  
  
    // Router specific but akin to $_GET - may contain additional options  
    RouterInterface:OPTIONS    => ['key' => 'value'],  
]  

Parameters:

• string $path - The path to match against including query string ala foo/bar.html?param=woo

Returns:

• array | null - route array or null on failure to route

Method: CliRouter->getNamespace

function getNamespace() : string

Returns:

• string - The canonical namespace prefix