Routing

• Creating a Route
  • Routing files
  • Writing a Route
    • Standard RESTful Request Methods
    • Any Request Method
    • Mixed Request Methods
  • Naming the target controller
  • Adding additional context information to route
  • Placeholder routing
  • Routing with Path Params / Variables
• Working with Routes
  • Get all routes
    • Get routes array
    • Get array stacked by request methods
  • Get a route
    • Get current route
    • Get any route
  • Accessing additional context information
    • Get the additional context information of the current route
    • Get the additional context information of any route

Creating a Route

Routing files

All routing information are written in php files in your module's routing folder. All *.php files in the routing folder will be load at start.

Schema

modules/{Module}/etc/routing/

If your module is Foo, then this is your routing folder

modules/Foo/etc/routing/;

per default you see these contents

modules/Foo/etc/routing/
└── frontend.php

individual routing files
you can create you own *.php routing file, for example foo.php and edit your route in that file.

If you want to create routes for an API, it then makes sense to create a file called api.php and write all your api routes inside that file.

Writing a Route

TLDR; Examples

\MVC\Route::get     ('/', '\Foo\Controller\Index::index'); // expecting GET
\MVC\Route::post    ('/', '\Foo\Controller\Index::index'); // expecting POST
\MVC\Route::put     ('/', '\Foo\Controller\Index::index'); // expecting PUT
\MVC\Route::delete  ('/', '\Foo\Controller\Index::index'); // expecting DELETE

\MVC\Route::any     ('/', '\Foo\Controller\Index::index');  // be open for any request method
\MVC\Route::mix     (['GET', 'POST'], '/',    '\Foo\Controller\Index::index'); // expecting GET or POST

Standard RESTful Request Methods

You declare a route with Command \MVC\Route:

\MVC\Route::{METHOD}(string path, string targetController, mixed additionalInformation)

• {METHOD}: one of the RESTful request methods GET, POST, PUT, DELETE; you declare which RESTful request method is expected for this route
• path: url path
• targetController: the Module, Controller and method the route leads to
• additionalInformation [optional]: any information you may need to process in your target controller (or elsewhere). You can pass string, array, object, bool or whatever you like.

Example

\MVC\Route::get('/foo/', '\Foo\Controller\Index::index');

Assuming you are running Emvicy's local development server, you can then call the url http://127.0.0.1:1969/foo/

Any Request Method

Using ANY you leave it open which request method should apply

\MVC\Route::any('/foo/', '\Foo\Controller\Index::index');

Mixed Request Methods

Assign more than one request method to the route with MIX

\MVC\Route::mix(['GET', 'POST'], '/foo/', '\Foo\Controller\Index::index');

Naming the target controller

You name the target controller and method info by its class and method names itself.
⚠ Requirement: It has to be a MVC Controller.

\MVC\Route::get('/foo/', '\Foo\Controller\Index::index');

• request method here is GET
• path is /foo/
• targetController: leads to Class::method \Foo\Controller\Index::index

Adding additional context information to route

You can add any information of any type to the route.

Simple Examples

\MVC\Route::get('/foo/', '\Foo\Controller\Index::index', 'Hello World'); # passing string

\MVC\Route::get('/foo/', '\Foo\Controller\Index::index', [1, 'foo', 'bar']); # passing array

\MVC\Route::get('/foo/', '\Foo\Controller\Index::index', DTRoutingAdditional::create()->set_sTitle('Foo')); # passing object

Get the additional context

you can get the additonal context via the Route object.

example: get additonal context in Controller method

public function index(DTRequestCurrent $oDTRequestCurrent, DTRoute $oDTRoute)
{
    $oDTRoutingAdditional = $oDTRoute->get_additional()
    ...
}

You can also get the additional context by requesting Route class directly

$oDTRoutingAdditional = Route::getCurrent()->get_additional()

see also: Accessing additional context information

More complex Example

In the example frontend.php you see a DataType Class $oDTRoutingAdditional of Type \Foo\DataType\DTRoutingAdditional. This class is generated by Emvicy's DataType Generator; see /1.x/generating-datatype-classes for more Information.
The information stored in this DataType Class will be accessed by the View Class as they are necessary for setting up the View correctly.

Example object DTRoutingAdditional

$oDTRoutingAdditional = \Foo\DataType\DTRoutingAdditional::create()
    ->set_sTitle('Foo')
    ->set_sLayout('Frontend/layout/index.tpl')
    ->set_sMainmenu('Frontend/layout/menu.tpl')
    ->set_sContent('Frontend/content/index.tpl')
    ->set_sHeader('Frontend/layout/header.tpl')
    ->set_sNoscript('Frontend/content/_noscript.tpl')
    ->set_sCookieConsent('Frontend/content/_cookieConsent.tpl')
    ->set_sFooter('Frontend/layout/footer.tpl')
    ->set_aStyle(array (
        '/Emvicy/assets/bootstrap-4.6.2-dist/css/bootstrap.min.css',
        '/Emvicy/assets/font-awesome-4.7.0/css/font-awesome.min.css',
        '/Emvicy/styles/Emvicy.min.css',
    ))
    ->set_aScript(array (
        '/Emvicy/assets/jquery/3.7.0/jquery-3.7.0.min.js',
        '/Emvicy/assets/jquery-cookie/1.4.1/jquery.cookie.min.js',
        '/Emvicy/assets/bootstrap-4.6.2-dist/js/bootstrap.min.js',
        '/Emvicy/scripts/cookieConsent.min.js',
    ));

Example routes using $oDTRoutingAdditional

/*
 * Routes
 */
\MVC\Route::mix(
    ['GET', 'POST'],
    '/',
    '\Foo\Controller\Index::index',
    clone $oDTRoutingAdditional // copy from above object
);
\MVC\Route::get(
    '/404/',
    '\Foo\Controller\Index::notFound',
    clone $oDTRoutingAdditional // copy from above object; but set different title, content
        ->set_sTitle('404')
        ->set_sContent('Frontend/content/404.tpl')
);

Placeholder routing

per default all routings are restricitv

Example

\MVC\Route::get('/foo/', '\Foo\Controller\Index::foo');

you can only request

• /foo/

you cannot request e.g.

• /foo/bar/

activating Placeholder routing
therefore, just add * after the path: '/foo/*'.

\MVC\Route::get('/foo/*', '\Foo\Controller\Index::foo');

now you can call the route with further paths

• e.g. /foo/bar/baz/

You can get the tailing path after /foo/ by accessing Path Params _tail.

$aPathParam = \MVC\Request::getPathParam()['_tail'];

this will give you

bar/baz/

• see Request: Accessing Path Params / Variables

Routing with Path Params / Variables

You can define Routes with Variables.
This you can do in one of two ways:

1. :var notation: e.g. '/api/:id/:name/:address/'
2. {var} notation: e.g. '/api/{id}/{name}/{address}/'

You cannot mix these notations; Use one or the other for defining your routes.
All variables you declare in your route are accessible by name.

Examples

# :var notation
\MVC\Route::get('/api/:id/:name/:address/', '\Foo\Controller\Api::index');
# {var} notation
\MVC\Route::get('/api/{id}/{name}/{address}/', '\Foo\Controller\Api::index');

Valid Requests:

• /api/1/Foo/Bar/
• /api/1969/FooBar/Somwhere%20else/

Example with activating wildcard routing

\MVC\Route::get('/api/:id/:name/:address/*', '\Foo\Controller\Api::index');

Valid Requests:

• /api/1/Foo/Bar/what/else/
• /api/1969/FooBar/Somwhere%20else/what/else/

Access the Variables

• see Request: Accessing Path Params / Variables

Working with Routes

Get all routes

Get routes array

Simply access the public property $aRoute of class Route. It will give you an associative array where its values are objects of type MVC\DataType\DTRoute.

Command

/** @var MVC\DataType\DTRoute[] $aRoute */
$aRoute = Route::$aRoute;

Example Result of $aRoute (shortened)

array(2) {
  ["/"]=>
  object(MVC\DataType\DTRoute)#15 (9) {
    ["path":protected]=>string(1) "/"
    ["method":protected]=>string(3) "GET"
    ["methodsAssigned":protected]=>array(1) {[0]=> string(3) "GET"}
    ["query":protected]=>string(30) "module=Foo&c=Index&m=index"
    ["class":protected]=>string(24) "Foo\Controller\Index"
    ["classFile":protected]=>string(128) "/var/www/Emvicy/modules/Foo/Controller/Index.php"
    ["module":protected]=>string(7) "Foo"
    ["c":protected]=>string(5) "Index"
    ["m":protected]=>string(5) "index"
    ["additional":protected]=>string(733) "{"sTitle":"Foo","sLayout":"Frontend\/layout\/index.tpl","sMainmenu":"Frontend\/layout\/menu.tpl","sContent":"Frontend\/content\/index.tpl","sHeader":"Frontend\/layout\/header.tpl","sNoscript":"Frontend\/content\/_noscript.tpl","sCookieConsent":"Frontend\/content\/_cookieConsent.tpl","sFooter":"Frontend\/layout\/footer.tpl","aStyle":["\/Emvicy\/assets\/bootstrap-4.6.2-dist\/css\/bootstrap.min.css","\/Emvicy\/assets\/font-awesome-4.7.0\/css\/font-awesome.min.css","\/Emvicy\/styles\/Emvicy.min.css"],"aScript":["\/Emvicy\/assets\/jquery\/3.4.1\/jquery-3.4.1.min.js","\/Emvicy\/assets\/jquery-cookie\/1.4.1\/jquery.cookie.min.js","\/Emvicy\/assets\/bootstrap-4.6.2-dist\/js\/bootstrap.min.js","\/Emvicy\/scripts\/cookieConsent.min.js"]}"
  }
  ["/404/"]=>
  object(MVC\DataType\DTRoute)#17 (9) {
   ...
 }
}

Get array stacked by request methods

Access the public property $aMethod to get an array of route indeces stacked by request method.

Command

$aMethod = Route::$aMethod;

Example Result of $aMethod

array(2) {
  ["put"]=>array(1) {
    [0]=>string(20) "/api/1.0.0/user/:id/"
  }
  ["get"]=>array(3) {
    [0]=>string(1) "/"
    [1]=>string(5) "/404/"
    [2]=>string(25) "/api/:id/:name/:address/*"
  }
}

Get a route

Get current route

this will give you the current route object to the requested url path.

Example request

• /api/1/Foo/Bar/what/else/

Command

$oDTRoute = \MVC\Route::getCurrent();

Example Result of $oDTRoute

object(MVC\DataType\DTRoute)#19 (9) {
  ["path":protected]=>string(25) "/api/:id/:name/:address/*"
  ["method":protected]=>string(3) "GET"
  ["methodsAssigned":protected]=>array(1) {[0]=>string(3) "GET"}
  ["query":protected]=>string(30) "module=Foo&c=Api&m=index"
  ["class":protected]=>string(24) "Foo\Controller\Api"
  ["classFile":protected]=>string(128) "/var/www/Emvicy/modules/Foo/Controller/Api.php"
  ["module":protected]=>string(7) "Foo"
  ["c":protected]=>string(5) "Index"
  ["m":protected]=>string(5) "index"
  ["additional":protected]=>string(727) "{"sTitle":"API","sLayout":"Frontend\/layout\/index.tpl","sMainmenu":"Frontend\/layout\/menu.tpl","sContent":"Frontend\/content\/foo.tpl","sHeader":"Frontend\/layout\/header.tpl","sNoscript":"Frontend\/content\/_noscript.tpl","sCookieConsent":"Frontend\/content\/_cookieConsent.tpl","sFooter":"Frontend\/layout\/footer.tpl","aStyle":["\/Emvicy\/assets\/bootstrap-4.6.2-dist\/css\/bootstrap.min.css","\/Emvicy\/assets\/font-awesome-4.7.0\/css\/font-awesome.min.css","\/Emvicy\/styles\/Emvicy.min.css"],"aScript":["\/Emvicy\/assets\/jquery\/3.4.1\/jquery-3.4.1.min.js","\/Emvicy\/assets\/jquery-cookie\/1.4.1\/jquery.cookie.min.js","\/Emvicy\/assets\/bootstrap-4.6.2-dist\/js\/bootstrap.min.js","\/Emvicy\/scripts\/cookieConsent.min.js"]}"
}

As the Result is an object of type MVC\DataType\DTRoute you can access all its properties by getter.

Example

$sClass = \MVC\Route::getCurrent()->get_methodsAssigned();

Example Result of $sClass

array(1) {
  [0]=>
  string(3) "GET"
}

Get any route

you can get any route object by accessing public $aRoute from class Route.

Command

// we want the route object of route /404/
$oRoute = \MVC\Route::$aRoute['/404/'];

Example Result of $oRoute

object(MVC\DataType\DTRoute)#17 (9) {
  ["path":protected]=>string(5) "/404/"
  ["method":protected]=>string(3) "GET"
  ["methodsAssigned":protected]=>array(1) {[0]=>string(3) "GET"}  
  ["query":protected]=>string(33) "module=Foo&c=Index&m=notFound"
  ["class":protected]=>string(24) "Foo\Controller\Index"
  ["classFile":protected]=>string(128) "/var/www/Emvicy/modules/Foo/Controller/Index.php"
  ["module":protected]=>string(7) "Foo"
  ["c":protected]=>string(5) "Index"
  ["m":protected]=>string(8) "notFound"
  ["additional":protected]=>string(727) "{"sTitle":"404","sLayout":"Frontend\/layout\/index.tpl","sMainmenu":"Frontend\/layout\/menu.tpl","sContent":"Frontend\/content\/404.tpl","sHeader":"Frontend\/layout\/header.tpl","sNoscript":"Frontend\/content\/_noscript.tpl","sCookieConsent":"Frontend\/content\/_cookieConsent.tpl","sFooter":"Frontend\/layout\/footer.tpl","aStyle":["\/Emvicy\/assets\/bootstrap-4.6.2-dist\/css\/bootstrap.min.css","\/Emvicy\/assets\/font-awesome-4.7.0\/css\/font-awesome.min.css","\/Emvicy\/styles\/Emvicy.min.css"],"aScript":["\/Emvicy\/assets\/jquery\/3.4.1\/jquery-3.4.1.min.js","\/Emvicy\/assets\/jquery-cookie\/1.4.1\/jquery.cookie.min.js","\/Emvicy\/assets\/bootstrap-4.6.2-dist\/js\/bootstrap.min.js","\/Emvicy\/scripts\/cookieConsent.min.js"]}"
}

As the Result is an object of type MVC\DataType\DTRoute you can access all its properties by getter.

Example

$sClass = \MVC\Route::$aRoute['/404/']->get_class();

Example Result of $sClass

Foo\Controller\Index

Accessing additional context information

Get the additional context information of the current route

Command

/** @var \MVC\DataType\DTRoutingAdditional $oDTRoutingAdditional */
$oDTRoutingAdditional = \MVC\Route::getCurrent()->get_additional();

Example Result of $oDTRoutingAdditional

// type: object
\Foo\DataType\DTRoutingAdditional::__set_state(array(
      'sTitle' => 'Foo',
      'sLayout' => 'Frontend/layout/index.tpl',
      'sMainmenu' => 'Frontend/layout/menu.tpl',
      'sContent' => 'Frontend/content/index.tpl',
      'sHeader' => 'Frontend/layout/header.tpl',
      'sNoscript' => 'Frontend/content/_noscript.tpl',
      'sCookieConsent' => 'Frontend/content/_cookieConsent.tpl',
      'sFooter' => 'Frontend/layout/footer.tpl',
      'aStyle' =>    array (
        0 => '/Emvicy/assets/bootstrap-5.3.2-dist/css/bootstrap.min.css',
        1 => '/Emvicy/assets/fontawesome-free-6.4.2-web/css/all.min.css',
        2 => '/Emvicy/styles/Emvicy.min.css',
    ),
      'aScript' =>    array (
        0 => '/Emvicy/assets/jquery-3.7.1/jquery-3.7.1.min.js',
        1 => '/Emvicy/assets/jquery-cookie-1.4.1/jquery.cookie.min.js',
        2 => '/Emvicy/assets/bootstrap-5.3.2-dist/js/bootstrap.min.js',
        3 => '/Emvicy/scripts/cookieConsent.min.js',
    ),
))

Get the additional context information of any route

Therefore access the public property $aRoute directly with the path of the route of your interest. It will give you an object of Type MVC\DataType\DTRoute, which allows you to access its method get_additional().

Command

/** @var \MVC\DataType\DTRoutingAdditional $oDTRoutingAdditional */
$oDTRoutingAdditional = \MVC\Route::$aRoute['/404/']->get_additional();

Example Result of $oDTRoutingAdditional

// type: object
\Foo\DataType\DTRoutingAdditional::__set_state(array(
      'sTitle' => '404',
      'sLayout' => 'Frontend/layout/index.tpl',
      'sMainmenu' => 'Frontend/layout/menu.tpl',
      'sContent' => 'Frontend/content/404.tpl',
      'sHeader' => 'Frontend/layout/header.tpl',
      'sNoscript' => 'Frontend/content/_noscript.tpl',
      'sCookieConsent' => 'Frontend/content/_cookieConsent.tpl',
      'sFooter' => 'Frontend/layout/footer.tpl',
      'aStyle' =>    array (
        0 => '/Emvicy/assets/bootstrap-5.3.2-dist/css/bootstrap.min.css',
        1 => '/Emvicy/assets/fontawesome-free-6.4.2-web/css/all.min.css',
        2 => '/Emvicy/styles/Emvicy.min.css',
    ),
      'aScript' =>    array (
        0 => '/Emvicy/assets/jquery-3.7.1/jquery-3.7.1.min.js',
        1 => '/Emvicy/assets/jquery-cookie-1.4.1/jquery.cookie.min.js',
        2 => '/Emvicy/assets/bootstrap-5.3.2-dist/js/bootstrap.min.js',
        3 => '/Emvicy/scripts/cookieConsent.min.js',
    ),
))