セクション

Routing Component


概要

Phalcon\Mvc\Router コンポーネントを使用することで、コントローラやハンドラに紐づくルートを定義し、リクエストを受け取って処理することが出来ます。 ルータには「MVCモード」と「マッチオンリーモード」の2つのモードがあります。 前者のモードはMVCアプリケーションに最適です。

<?php

use Phalcon\Mvc\Router;

$router = new Router();

$router->add(
    '/admin/invoices/list',
    [
        'controller' => 'invoices',
        'action'     => 'list',
    ]
);

$router->handle(
    $_SERVER["REQUEST_URI"]
);

Constants

There are two constants available for the [Phalcon\Mvc\Router][mvc-router] component that are used to define the position of the route in the processing stack.

  • POSITION_FIRST
  • POSITION_LAST

Methods

public function __construct(
    bool $defaultRoutes = true
)

Phalcon\Mvc\Router constructor

public function add(
    string $pattern, 
    mixed $paths = null, 
    mixed $httpMethods = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTPメソッドの制約のないルーターに追加します

use Phalcon\Mvc\Router;

$router->add("/about", "About::index");

$router->add(
    "/about",
    "About::index",
    ["GET", "POST"]
);

$router->add(
    "/about",
    "About::index",
    ["GET", "POST"],
    Router::POSITION_FIRST
);
public function addConnect(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが CONNECT の場合にのみ一致するルータに追加します。

public function addDelete(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが DELETE の場合にのみ一致するルータに追加します。

public function addGet(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが GET の場合にのみ一致するルータに追加します。

public function addHead(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが HEAD の場合にのみ一致するルータに追加します。

public function addOptions(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが OPTIONS の場合にのみ一致するルータに追加します。

public function addPatch(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが PATCH の場合にのみ一致するルータに追加します。

public function addPost(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが POST の場合にのみ一致するルータに追加します。

public function addPurge(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが PURGE である場合にのみ一致するルーターに追加します。(Squid と Varnish のサポート)

public function addPut(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが PUT の場合にのみ一致するルータに追加します。

public function addTrace(
    string $pattern, 
    mixed $paths = null, 
    mixed $position = Router::POSITION_LAST
): RouteInterface

ルートをHTTP メソッドが TRACE の場合にのみ一致するルータに追加します。

public function attach(
    RouteInterface $route, 
    mixed $position = Router::POSITION_LAST
): RouterInterface

ルートオブジェクトをルートスタックに付与します。

```php use Phalcon\Mvc\Router; use Phalcon\Mvc\Router\Route;

class CustomRoute extends Route { // … }

$router = new Router();

$router->attach( new CustomRoute( “/about”, “About::index”, [“GET”, “HEAD”] ), Router::POSITION_FIRST );

<br />```php
public function clear(): void

Removes all the pre-defined routes

public function getActionName(): string

Returns the processed action name

public function getControllerName(): string

Returns the processed controller name

public function getMatchedRoute(): RouteInterface

Returns the route that matches the handled URI

public function getMatches(): array

Returns the sub expressions in the regular expression matched

public function getModuleName(): string

Returns the processed module name

public function getNamespaceName(): string

Returns the processed namespace name

public function getParams(): array

Returns the processed parameters

public function getRouteById(
    mixed $id
): RouteInterface | bool

Returns a route object by its id

public function getRouteByName(
    string $name
): RouteInterface | bool

Returns a route object by its name

public function getRoutes(): RouteInterface[]

Returns all the routes defined in the router

public function handle(string $uri): void

Handles routing information received from the rewrite engine

$router->handle("/posts/edit/1");
public function isExactControllerName(): bool

Returns whether controller name should not be mangled

public function mount(
    GroupInterface $group
): RouterInterface

Mounts a group of routes in the router

public function notFound(
    mixed $paths
): RouterInterface

Set a group of paths to be returned when none of the defined routes are matched

public function removeExtraSlashes(
    bool $remove
): RouterInterface

Set whether router must remove the extra slashes in the handled routes

public function setDefaultAction(
    string $actionName
): RouterInterface

Sets the default action name

public function setDefaultController(
    string $controllerName
): RouterInterface

Sets the default controller name

public function setDefaultModule(
    string $moduleName
): RouterInterface

Sets the name of the default module

public function setDefaultNamespace(
    string $namespaceName
): RouterInterface

Sets the name of the default namespace

public function setDefaults(
    array $defaults
): RouterInterface

Sets an array of default paths. If a route is missing a path the router will use the defined here. This method must not be used to set a 404 route

$router->setDefaults(
    [
        "module" => "common",
        "action" => "index",
    ]
);
public function getDefaults(): array

Returns an array of default parameters

public function wasMatched(): bool

Checks if the router matches any of the defined routes

ルートの定義

Phalcon\Mvc\Router は高度なルーティング機能を提供します。 MVC モードでは、ルートを定義して、必要なコントローラー/アクションに紐づけできます。 ルートは以下のように定義されます:

<?php

use Phalcon\Mvc\Router;

$router = new Router();

$router->add(
    '/admin/invoices/list',
    [
        'controller' => 'invoices',
        'action'     => 'list',
    ]
);

$router->add(
    '/admin/customers/list',
    [
        'controller' => 'customers',
        'action'     => 'list',
    ]
);

$router->handle(
    $_SERVER["REQUEST_URI"]
);

The first parameter of the add() method is the pattern you want to match and, optionally, the second parameter is a set of paths. In the above example, for the URI /admin/invoices/list, the InvoicesController will be loaded and the listAction will be called. It is important to remember that the router does not execute the controller and action, it only collects this information and then forwards it to the Phalcon\Mvc\Dispatcher which executes them.

An application can have many paths and defining routes one by one can be a cumbersome task. [Phalcon\Mvc\Router][mvc-router] offers an easier way to register routes.

<?php

use Phalcon\Mvc\Router;

$router = new Router();

$router->add(
    '/admin/:controller/:action/:params',
    [
        'controller' => 1,
        'action'     => 2,
        'params'     => 3,
    ]
);

In the example above, we are using wildcards to make a route valid for many URIs. For example, by accessing the following URL (/admin/customers/view/12345/1) would produce:

Controller Action Parameter Parameter
customers view 12345 1

The add() method receives a pattern that can optionally have predefined placeholders and regular expression modifiers. All the routing patterns must start with a forward slash character (/). The regular expression syntax used is the same as the PCRE regular expressions.

NOTE: It is not necessary to add regular expression delimiters. All route patterns are case-insensitive.

The second parameter defines how the matched parts should bind to the controller/action/parameters. Matching parts are placeholders or subpatterns delimited by parentheses (round brackets). In the example given above, the first subpattern matched (:controller) is the controller part of the route, the second the action (:action) and after that any parameters passed (:params).

These placeholders make the route expressions more readable and easier to understand. The following placeholders are supported:

Placeholder Regular Expression Matches
/:module /([a-zA-Z0-9\_\-]+) Valid module name with alpha-numeric characters only
/:controller /([a-zA-Z0-9\_\-]+) Valid controller name with alpha-numeric characters only
/:action /([a-zA-Z0-9_-]+) Valid action name with alpha-numeric characters only
/:params (/.*)* List of optional words separated by slashes. Only use this placeholder at the end of a route
/:namespace /([a-zA-Z0-9\_\-]+) Single level namespace name
/:int /([0-9]+) Integer parameter

Controller names are camelized, this means that characters (-) and (_) are removed and the next character is uppercased. For instance, some_controller is converted to SomeController.

Since you can add as many routes as needed using the add() method, the order in which routes are added indicates their relevance. The routes added last have more relevance than the ones added above them. Internally, all defined routes are traversed in reverse order until Phalcon\Mvc\Router finds the one that matches the given URI and processes it, while ignoring the rest.

Named Parameters

The example below demonstrates how to define names to route parameters:

<?php

$router->add(
    //         1     /     2    /    3     /   4
    '/admin/([0-9]{4})/([0-9]{2})/([0-9]{2})/:params',
    [
        'controller' => 'invoices',
        'action'     => 'view',
        'year'       => 1, // ([0-9]{4})
        'month'      => 2, // ([0-9]{2})
        'day'        => 3, // ([0-9]{2})
        'params'     => 4, // :params
    ]
);

In the above example, the route does not define a controller or action. Those are replaced with fixed values (invoices and view). The user will never know the underlying controller that is dispatched by the request. In the controller, those named parameters can be accessed as follows:

<?php

use Phalcon\Mvc\Controller;
use Phalcon\Mvc\Dispatcher;

/**
 * @property Dispatcher $dispatcher
 */
class InvoicesController extends Controller
{
    public function viewAction()
    {
        // year
        $year = $this->dispatcher->getParam('year');

        // month
        $month = $this->dispatcher->getParam('month');

        // day
        $day = $this->dispatcher->getParam('day');

        // ...
    }
}

Note that the values of the parameters are obtained from the dispatcher. There is also another way to create named parameters as part of the pattern:

<?php

$router->add(
    '/admin/{year}/{month}/{day}/{invoiceNo:[0-9]+}',
    [
        'controller' => 'invoices',
        'action'     => 'view',
    ]
);

You can access their values in the same way as before:

<?php

use Phalcon\Mvc\Controller;
use Phalcon\Mvc\Dispatcher;

/**
 * @property Dispatcher $dispatcher
 */
class InvoicesController extends Controller
{
    public function viewAction()
    {
        // year
        $year = $this->dispatcher->getParam('year');

        // month
        $month = $this->dispatcher->getParam('month');

        // day 
        $day = $this->dispatcher->getParam('day');

        // invoiceNo
        $invoicNo = $this->dispatcher->getParam('invoiceNo');

        // ...
    }
}

Short Syntax

Phalcon\Mvc\Router also offers an alternative, shorter syntax. The following examples produce the same result:

<?php

$router->add(
    '/admin/{year:[0-9]{4}}/{month:[0-9]{2}}/{day:[0-9]{2}}/:params',
    'Invoices::view'
);

$router->add(
    '/admin/([0-9]{4})/([0-9]{2})/([0-9]{2})/:params',
    [
        'controller' => 'invoices',
        'action'     => 'view',
        'year'       => 1, // ([0-9]{4})
        'month'      => 2, // ([0-9]{2})
        'day'        => 3, // ([0-9]{2})
        'params'     => 4, // :params
    ]
);

Array and Short Syntax

Array and short syntax can be mixed to define a route, in this case note that named parameters automatically are added to the route paths according to the position on which they were defined:

<?php

$router->add(
    '/admin/{year:[0-9]{4}}/([0-9]{2})/([0-9]{2})/:params',
    [
        'controller' => 'invoices',
        'action'     => 'view',
        'month'      => 2, // ([0-9]{2}) // 2
        'day'        => 3, // ([0-9]{2}) // 3
        'params'     => 4, // :params    // 4
    ]
);

The first position must be skipped because it is used for the named parameter year.

Modules

You can define routes with modules in the path. This is specially suitable to multi-module applications. You can define a default route that includes a module wildcard.

<?php

use Phalcon\Mvc\Router;

$router = new Router(false);

$router->add(
    '/:module/:controller/:action/:params',
    [
        'module'     => 1,
        'controller' => 2,
        'action'     => 3,
        'params'     => 4,
    ]
);

With the above route, you need to always have the module name as part of your URL. For example, for the following URL: /admin/invoices/view/12345, will be processed as:

Module Controller Action Parameter
admin invoices view 12345

Or you can bind specific routes to specific modules:

<?php

$router->add(
    '/login',
    [
        'module'     => 'session',
        'controller' => 'login',
        'action'     => 'index',
    ]
);

$router->add(
    '/invoices/:action',
    [
        'module'     => 'admin',
        'controller' => 'invoices',
        'action'     => 1,
    ]
);

Or bind them to specific namespaces:

<?php

$router->add(
    '/:namespace/login',
    [
        'namespace'  => 1,
        'controller' => 'login',
        'action'     => 'index',
    ]
);

The full namespace needs to be passed separately:

<?php

$router->add(
    '/login',
    [
        'namespace'  => 'Admin\Controllers',
        'controller' => 'login',
        'action'     => 'index',
    ]
);

HTTP Methods

When you add a route using simply add(), the route will be enabled for any HTTP method. Sometimes we can restrict a route to a specific method. This is particularly useful when creating RESTful applications.

<?php

// GET
$router->addGet(
    '/invoices/edit/{id}',
    'Invoices::edit'
);

// POST
$router->addPost(
    '/invoices/save',
    'Invoices::save'
);

// POST/PUT
$router->add(
    '/invoices/update',
    'Invoices::update'
)->via(
    [
        'POST',
        'PUT',
    ]
);

Converters

Converters are snippets of code that allow you to convert the parameters of a route prior to it being sent to the

<?php

$route = $router->add(
    '/products/{slug:[a-z\-]+}',
    [
        'controller' => 'products',
        'action'     => 'show',
    ]
);

$route->convert(
    'slug',
    function ($slug) {
        return str_replace('-', '', $slug);
    }
);

In the above example, the action name allows dashes, therefore an action can be /products/new-ipod-nano-4-generation. The convert method will change the action to newipodnano4generation

Another use case for converters is when binding a model to a route. This allows the model to be passed into the defined action directly.

<?php

$route = $router->add(
    '/products/{id}',
    [
        'controller' => 'products',
        'action'     => 'show',
    ]
);

$route->convert(
    'id',
    function ($id) {
        return Product::findFirstById($id);
    }
);

In the above example the ID is passed in the URL and our converter gets the record from the database, passing it back.

Groups

If a set of routes have common paths they can be grouped for easier maintenance. To achieve this, we utilize the Phalcon\Mvc\Router\Group component

<?php

use Phalcon\Mvc\Router;
use Phalcon\Mvc\Router\Group;

$router   = new Router();
$invoices = new RouterGroup(
    [
        'module'     => 'admin',
        'controller' => 'invoices',
    ]
);

$invoices->setPrefix('/invoices');

$invoices->add(
    '/list',
    [
        'action' => 'list',
    ]
);

$invoices->add(
    '/edit/{id}',
    [
        'action' => 'edit',
    ]
);

$invoices->add(
    '/view',
    [
        'controller' => 'common',
        'action'     => 'index',
    ]
);

$router->mount($invoices);

In the above example, we first create a group with a common module and controller. We then add the prefix for the group to be /invoices. We then add more routes to the group, some without parameters and some with. The last route allows us to use a different controller than the default one (common). Finally, we add the group to the router.

We can extend the Phalcon\Mvc\Router\Group component and register our routes in it on a per group basis. This allows us to better organize the routes of our application.

<?php

use Phalcon\Mvc\Router\Group;

class InvoicesRoutes extends Group
{
    public function initialize()
    {
        $this->setPaths(
            [
                'module'    => 'invoices',
                'namespace' => 'Invoices\Controllers',
            ]
        );

        $this->setPrefix('/invoices');

        $this->add(
            '/list',
            [
                'action' => 'list',
            ]
        );

        $this->add(
            '/edit/{id}',
            [
                'action' => 'edit',
            ]
        );

        $this->add(
            '/view',
            [
                'controller' => 'common',
                'action'     => 'index',
            ]
        );
    }
}

Now we can mount the custom group class in the router:

<?php

$router->mount(
    new InvoicesRoutes()
);

Matching Routes

A valid URI must be passed to the Router so that it can process it and find a matching route. By default, the routing URI is taken from the $_GET['_url'] variable that is created by the rewrite engine module. A couple of rewrite rules that work very well with Phalcon are:

RewriteEngine On
RewriteCond   %{REQUEST_FILENAME} !-d
RewriteCond   %{REQUEST_FILENAME} !-f
RewriteRule   ^((?s).*)$ index.php?_url=/$1 [QSA,L]

In this configuration, any requests to files or folders that do not exist will be sent to index.php. The following example shows how to use this as a stand alone component:

<?php

use Phalcon\Mvc\Router;

$router = new Router();

// ...

$router->handle(
    $_GET["_url"]
);

echo $router->getControllerName();
echo $router->getActionName();

$route = $router->getMatchedRoute();

In the above example, we first create a router object. We can have some code after that, such as defining services, routes etc.. We then take the _url element from the $_GET superglobal and after that we can get the controller name or the action name or even get back the matched route.

Naming Routes

Each route that is added to the router is stored internally as a Phalcon\Mvc\Router\Route object. That class encapsulates all the details of each route. For instance, we can give a name to a path to identify it uniquely in our application. This is especially useful if you want to create URLs from it.

<?php

$route = $router->add(
    '/admin/{year:[0-9]{4}}/{month:[0-9]{2}}/{day:[0-9]{2}}/{id:[0-9]{4}',
    'Invoices::view'
);

$route->setName('invoices-view');

Then, using for example the component Phalcon\Url we can build routes from the defined name:

<?php

// /admin/2019/12/25/1234
echo $url->get(
    [
        'for'   => 'invoices-view',
        'year'  => '2019',
        'month' => '12',
        'day'   => '25',
        'id'    => '1234',
    ]
);

デフォルトの動作

Phalcon\Mvc\Router にはデフォルトの動作があります。これは、次のURIのパターンに一致するシンプルなルーティングを提供します。:

/:controller/:action/:params

例えば、このような URL の場合、 https://dev.phalcon.od/download/linux/ubuntu.html このルータは以下のように解釈されます:

Controller Action Parameter
DownloadController linuxAction ubuntu.html

このルーターの動作が期待にそぐわない場合は、次のようにコンストラクタで false を渡すルーターを作成しましょう。

<?php

use Phalcon\Mvc\Router;

$router = new Router(false);

デフォルトのルート

アプリケーションがルートなしでアクセスされた場合 / ルートは、アプリケーションの最初のページを表示するために使用されるパスを決定するために使用されます

<?php

$router->add(
    '/',
    [
        'controller' => 'index',
        'action'     => 'index',
    ]
);

Not Found (404)

ルーターで指定されたルートがいずれにも一致しない場合、 notFound メソッドを使用して404 controller/actionを定義できます。

<?php

$router->notFound(
    [
        'controller' => 'index',
        'action'     => 'fourOhFour',
    ]
);

注意: これはルーターがデフォルトのルートなしで作成された場合にのみ動作します: $router = Phalcon\Mvc\Router(false);

Defaults

modulecontroller 、および `action のデフォルト値を定義できます。 パスにこれらの要素のいずれかを欠落している場合、ルータは自動的にデフォルト値を使用します。

<?php

$router->setDefaultModule('admin');
$router->setDefaultNamespace('Admin\Controllers');
$router->setDefaultController('index');
$router->setDefaultAction('index');

$router->setDefaults(
    [
        'controller' => 'index',
        'action'     => 'index',
    ]
);

末尾のスラッシュ

末尾に余分なスラッシュがついていても、場合によってはルートにアクセスすることができます。 余分なスラッシュは予期せぬ動作として、送出時にnot-found ステータスを生成してしまうことがあります。 ルーターの設定により、処理中のルート末尾からスラッシュを自動的に削除することができます。

<?php

use Phalcon\Mvc\Router;

$router = new Router();

$router->removeExtraSlashes(true);

または、任意で末尾のスラッシュを受け入れるように特定のルートを変更することもできます。:

<?php

$route = $router->add(
    '/admin/:controller/status[/]{0,1}',
    [
        'controller' => 2,
        'action'     => 'status',
    ]
);

上記の場合、 [/]{0,1} は追加されている末尾のスラッシュを許可します

Callbacks

場合によっては、特定の条件を満たす場合にのみルートを一致させたいことがあります。 beforeMatch コールバックを使用することで、任意の条件をルートに追加できます。 この関数が falseを返す場合、ルートは一致しなかったものとして扱われます。

<?php

$route = $router->add(
    '/login',
    [
        'module'     => 'admin',
        'controller' => 'session',
    ]
);

$route->beforeMatch(
    function ($uri, $route) {
        if (true === isset($_SERVER['HTTP_X_REQUESTED_WITH']) && 
            $_SERVER['HTTP_X_REQUESTED_WITH'] === 'XMLHttpRequest'
        ) {
            return false;
        }

        return true;
    }
);

上記は、AJAXでリクエストが行われたかどうかを確認し、そうでない場合は false を返します。

フィルタークラスを作成して、異なるルートで同じ機能を組み込むこともできます。

<?php

class AjaxFilter
{
    public function check()
    {
        return $_SERVER['HTTP_X_REQUESTED_WITH'] === 'XMLHttpRequest';
    }
}

これを設定するには、クラスを beforeMatch 呼び出しに追加します。

<?php

$route = $router->add(
    '/login',
    [
        'module'     => 'admin',
        'controller' => 'session',
    ]
);

$route->beforeMatch(
    [
        new AjaxFilter(),
        'check'
    ]
);

最後に、 beforeMatch メソッド (またはイベント) を使用して、これが AJAX によるリクエストかを確認します。

<?php

use Phalcon\Di\DiInterface;
use Phalcon\Http\Request;
use Phalcon\Mvc\Router\Route;

$route = $router->add(
    '/login',
    [
        'module'     => 'admin',
        'controller' => 'session',
    ]
);

$route->beforeMatch(
    function ($uri, $route) {
        /**
         * @var string     $uri
         * @var Route       $route
         * @var DiInterface $this
         * @var Request     $request
         */
        $request = $this->getShared('request');

        return $request->isAjax();
    }
);

Hostname

Phalcon\Mvc\Router コンポーネントはホスト名による制約も許可します。 つまり、特定のルートやルートのグループは、特定のホスト名に由来する場合にのみ、そのルートと一致するように制限することができます。

<?php

$route = $router->add(
    '/admin/invoices/:action/:params',
    [
        'module'     => 'admin',
        'controller' => 'invoices',
        'action'     => 1,
        'params'     => 2,
    ]
);

$route->setHostName('dev.phalcon.ld');

ホスト名は正規表現として渡すこともできます。

<?php

$route = $router->add(
    '/admin/invoices/:action/:params',
    [
        'module'     => 'admin',
        'controller' => 'invoices',
        'action'     => 1,
        'params'     => 2,
    ]
);

$route->setHostName('([a-z]+).phalcon.ld');

ルートのグループを使用する場合は、グループ内のすべてのルートに適用されるホスト名制約を設定できます。

<?php

use Phalcon\Mvc\Router\Group;

$invoices = new Group(
    [
        'module'     => 'admin',
        'controller' => 'invoices',
    ]
);

$invoices->setHostName('dev.phalcon.ld');
$invoices->setPrefix('/invoices');

$invoices->add(
    '/',
    [
        'action' => 'index',
    ]
);

$invoices->add(
    '/list',
    [
        'action' => 'list',
    ]
);

$invoices->add(
    '/view/{id}',
    [
        'action' => 'view',
    ]
);

$router->mount($invoices);

Testing

このコンポーネントには依存関係はありません。 そのため、ルートをテストするための単体テストを作成できます。

<?php

use Phalcon\Mvc\Router;

$testRoutes = [
    '/',
    '/index',
    '/index/index',
    '/index/test',
    '/products',
    '/products/index/',
    '/products/show/101',
];

$router = new Router();

foreach ($testRoutes as $testRoute) {
    // Handle the route
    $router->handle($testRoute);

    echo 'Testing ', $testRoute, '<br>';

    // Check if some route was matched
    if ($router->wasMatched()) {
        echo 'Controller: ', $router->getControllerName(), '<br>';
        echo 'Action: ', $router->getActionName(), '<br>';
    } else {
        echo "The route wasn't matched by any route<br>";
    }

    echo '<br>';
}

イベント

他のPhalconコンポーネントと同様に、 Phalcon\Mvc\Router にもイベントがあり、 Events Manager が存在します。 利用可能なイベントは次のとおりです。:

Event Fired when
router:afterCheckRoutes After checking all the routes
router:beforeCheckRoute Before checking a route
router:beforeCheckRoutes Before checking all loaded routes
router:beforeMount Before mounting a new route
router:matchedRoute When a route is matched
router:notMatchedRoute When a route is not matched

アノテーション

このコンポーネントは、 サービスと統合されたバリアントを提供します。 この手法を採用すると、ルータコンポーネントに直接追加する代わりに、コントローラに直接ルートを書くことができます。

<?php

use Phalcon\Mvc\Router\Annotations;

$container['router'] = function () {
    $router = new Annotations(false);

    $router->addResource('Invoices', '/admin/invoices');

    return $router;
};

上の例では、 Phalcon\Mvc\Router\Annotations コンポーネントを使用してルートを設定しています。 デフォルトの動作を削除するには、 false を渡します。 その後、URI が /admin/invoices と一致する場合、 InvoicesController からアノテーションを読み取るようコンポーネントに指示します。

InvoicesController には以下の実装が必要です:

<?php

/**
 * @RoutePrefix('/admin/invoices')
 */
class InvoicesController
{
    /**
     * @Get(
     *     '/'
     * )
     */
    public function indexAction()
    {

    }

    /**
     * @Get(
     *     '/edit/{id:[0-9]+}',
     *     name='invoice-edit'
     * )
     */
    public function editAction($id)
    {

    }

    /**
     * @Route(
     *     '/save',
     *     methods={'POST', 'PUT'},
     *     name='invoice-save'
     * )
     */
    public function saveAction()
    {

    }

    /**
     * @Route(
     *     '/delete/{id:[0-9]+}',
     *     methods='DELETE',
     *     converters={
     *         id='MyConverters::checkId'
     *     }
     * )
     */
    public function deleteAction($id)
    {

    }
}

ルートとしては、有効なアノテーションでマークされたメソッドのみが使用されます。 使用可能なアノテーションは次のとおりです:

Annotation Description 使い方
Delete Restrict the HTTP method to DELETE @Delete('/invoices/delete/{id}')
Get Restrict the HTTP method to GET @Get('/invoices/search')
Options Restrict the HTTP method to OPTIONS @Option('/invoices/info')
Post Restrict the HTTP method to POST @Post('/invoices/save')
Put Restrict the HTTP method to PUT @Put('/invoices/save')
Route メソッドをルートとしてマークします。 メソッドのdocblockに配置する必要があります @Route('/invoices/show')
RoutePrefix 各ルート URI の前に prefix を追加します。 クラスの docblock に配置する必要があります。 @RoutePrefix('/invoices')

ルートを追加するアノテーションの場合、次のパラメータがサポートされます。

Name Description 使い方
converters A hash of converters for the parameters @Route('/posts/{id}/{slug}', converter={id='MyConverter::getId'})
methods One or more HTTP methods allowed for the route @Route('/api/products', methods={'GET', 'POST'})
name The name for the route @Route('/api/products', name='get-products')
paths Paths array for the route @Route('/invoices/view/{id}/{slug}', paths={module='backend'})

アプリケーションでモジュールを使用している場合は、 次のようにaddModuleResource() メソッドを使用することをお勧めします。:

<?php

use Phalcon\Mvc\Router\Annotations;

$container['router'] = function () {
    $router = new Annotations(false);

    $router->addModuleResource(
        'admin', 
        'Invoices', 
        '/admin/invoices'
    );

    return $router;
};

上記では、URI が /admin/invoices で始まる場合、 Admin\Controllers\InvoicesController からアノテーションを読みます。

ルータは、最速でルートが解決されるようにプレフィックスを解釈します。 例えば、以下のルート:

/clients/{clientId:[0-9]+}/
/clients/{clientId:[0-9]+}/robots
/clients/{clientId:[0-9]+}/parts

/clients プレフィックスのみがすべてのコントローラで使用でき、これにより検索を高速化します。

依存性の注入

You can register the router component during the container setup, to make it available inside the controllers or any other components that extend the Phalcon\Di\Injectable component.

You can use the example below in your bootstrap file (for example index.php or app/config/services.php if you use Phalcon Developer Tools).

<?php

$container->set(
    'router',
    function () {
        require __DIR__ . '/app/config/routes.php';

        return $router;
    }
);

You need to create app/config/routes.php and add the router initialization code:

<?php

use Phalcon\Mvc\Router;

$router = new Router();

$router->add(
    '/login',
    [
        'controller' => 'login',
        'action'     => 'index',
    ]
);

$router->add(
    '/invoices/:action',
    [
        'controller' => 'invoices',
        'action'     => 1,
    ]
);

return $router;

Custom

You can create your own components by implementing the supplied interfaces: - Phalcon\Mvc\Router\GroupInterface - Phalcon\Mvc\Router\RouteInterface - Phalcon\Mvc\RouterInterface

Examples

The following are examples of custom routes:

<?php

// '/system/admin/a/edit/7001'
$router->add(
    '/system/:controller/a/:action/:params',
    [
        'controller' => 1,
        'action'     => 2,
        'params'     => 3,
    ]
);

// '/en/news'
$router->add(
    '/([a-z]{2})/:controller',
    [
        'controller' => 2,
        'action'     => 'index',
        'language'   => 1,
    ]
);

// '/en/news'
$router->add(
    '/{language:[a-z]{2}}/:controller',
    [
        'controller' => 2,
        'action'     => 'index',
    ]
);

// '/admin/posts/edit/100'
$router->add(
    '/admin/:controller/:action/:int',
    [
        'controller' => 1,
        'action'     => 2,
        'id'         => 3,
    ]
);

// '/posts/2015/02/some-cool-content'
$router->add(
    '/posts/([0-9]{4})/([0-9]{2})/([a-z\-]+)',
    [
        'controller' => 'posts',
        'action'     => 'show',
        'year'       => 1,
        'month'      => 2,
        'title'      => 3,
    ]
);

// '/manual/en/translate.adapter.html'
$router->add(
    '/manual/([a-z]{2})/([a-z\.]+)\.html',
    [
        'controller' => 'manual',
        'action'     => 'show',
        'language'   => 1,
        'file'       => 2,
    ]
);

// /feed/fr/hot-news.atom
$router->add(
    '/feed/{lang:[a-z]+}/{blog:[a-z\-]+}\.{type:[a-z\-]+}',
    'Feed::get'
);

// /api/v1/users/peter.json
$router->add(
    '/api/(v1|v2)/{method:[a-z]+}/{param:[a-z]+}\.(json|xml)',
    [
        'controller' => 'api',
        'version'    => 1,
        'format'     => 4,
    ]
);

NOTE: Be careful when allowing characters in regular expressions for controllers and namespaces. These will become class names and in turn they will interact with the file system. As such, it is possible that an attacker can access unauthorized files. A safe regular expression is: /([a-zA-Z0-9\_\-]+)