Маршрутизация

Компонент маршрутизатора позволяет определять маршруты, которые сопоставляются с контроллерами или обработчиками, которые должны получать запрос. Маршрутизатор просто анализирует URI, чтобы определить эту информацию. Маршрутизатор имеет два режима: режим MVC и режим только соответствия. Первый режим идеально подходит для работы с приложениями MVC.

Определение маршрутов

Phalcon\Mvc\Router предоставляет расширенные возможности маршрутизации. В режиме MVC вы можете определять маршруты и сопоставлять их с необходимыми контроллерами/действиями. Маршрут определяется следующим образом:

use Phalcon\Mvc\Router;

// Create the router
$router = new Router();

// Define a route
$router->add(
    "/admin/users/my-profile",
    [
        "controller" => "users",
        "action"     => "profile",
    ]
);

// Another route
$router->add(
    "/admin/users/change-password",
    [
        "controller" => "users",
        "action"     => "changePassword",
    ]
);

$router->handle();

Первый параметр метода add() — это шаблон, который вы хотите сопоставить, а второй параметр (необязательный) — это набор путей. В данном случае, если URI равен /admin/users/my-profile, то будет выполнен контроллер «users» с действием «profile». Важно помнить, что маршрутизатор не выполняет контроллер и действие, он только собирает эту информацию, чтобы уведомить соответствующий компонент (например, Phalcon\Mvc\Dispatcher), что это контроллер/действие, которое он должен выполнить.

Приложения могут иметь множество путей, и определение маршрутов по одному может быть затруднительным. В таких случаях мы можем создать более гибкие маршруты:

use Phalcon\Mvc\Router;

// Create the router
$router = new Router();

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

В приведенном примере мы используем подстановки, чтобы сделать маршрут допустимым для многих URI. Например, доступ к следующему URL-адресу (/admin/users/a/delete/dave/301) приведет к:

Метод add() получает шаблон, который может (необязательно) содержать предварительно определенные плейсхолдеры и модификаторы регулярных выражений. Все шаблоны маршрутизации должны начинаться с символа косой черты (/). Синтаксис регулярных выражений совпадает с регулярными выражениями PCRE. Обратите внимание, что не нужно добавлять разделители регулярных выражений. Все шаблоны маршрутов нечувствительны к регистру.

Второй параметр определяет, как сопоставленные части должны связываться с контроллером/действием/параметрами. Сопоставляемые части — это плейсхолдеры или подшаблоны, ограниченные круглыми скобками. В приведенном выше примере первая подстрока, которая соответствует (:controller) — это часть контроллера маршрута, вторая — действие и так далее.

Эти плейсхолдеры помогают писать регулярные выражения, которые более понятны разработчикам и легче поддаются пониманию. Поддерживаются следующие плейсхолдеры:

Имена контроллеров написаны в стиле camelCase, это означает, что символы (-) и (_) удаляются, а следующий символ записывается с большой буквы. Например, some_controller преобразуется в SomeController.

Поскольку вы можете добавлять необходимые маршруты с помощью метода add(), порядок добавления маршрутов указывает на их важность, добавленные в последнюю очередь имеют большее значение, чем добавленные в первую очередь. Внутренне все определенные маршруты проходят обход в обратном порядке, пока Phalcon\Mvc\Router не найдет тот, который соответствует заданному URI, и не обработает его, проигнорировав остальные.

Параметры с именами

Приведенный ниже пример демонстрирует, как задавать имена параметрам маршрута:

$router->add(
    "/news/([0-9]{4})/([0-9]{2})/([0-9]{2})/:params",
    [
        "controller" => "posts",
        "action"     => "show",
        "year"       => 1, // ([0-9]{4})
        "month"      => 2, // ([0-9]{2})
        "day"        => 3, // ([0-9]{2})
        "params"     => 4, // :params
    ]
);

В приведенном выше примере маршрут не определяет часть «контроллера» или «действия». Эти части заменяются фиксированными значениями («posts» и «show»). Пользователь не будет знать контроллер, который фактически отправляется запросом. Внутри контроллера эти именованные параметры можно получить следующим образом:

use Phalcon\Mvc\Controller;

class PostsController extends Controller
{
    public function indexAction()
    {

    }

    public function showAction()
    {
        // Get "year" parameter
        $year = $this->dispatcher->getParam("year");

        // Get "month" parameter
        $month = $this->dispatcher->getParam("month");

        // Get "day" parameter
        $day = $this->dispatcher->getParam("day");

        // ...
    }
}

Обратите внимание, что значения параметров получаются из диспетчера. Это происходит потому, что именно он в конечном итоге взаимодействует с драйверами вашего приложения. Кроме того, существует еще один способ создания именованных параметров как части шаблона:

$router->add(
    "/documentation/{chapter}/{name}.{type:[a-z]+}",
    [
        "controller" => "documentation",
        "action"     => "show",
    ]
);

Значения можно получить аналогичным образом:

use Phalcon\Mvc\Controller;

class DocumentationController extends Controller
{
    public function showAction()
    {
        // Get "name" parameter
        $name = $this->dispatcher->getParam("name");

        // Get "type" parameter
        $type = $this->dispatcher->getParam("type");

        // ...
    }
}

Краткая запись

Если вам не нравится использовать массив для определения путей маршрута, доступен альтернативный синтаксис. Следующие примеры дают тот же результат:

// Short form
$router->add(
    "/posts/{year:[0-9]+}/{title:[a-z\-]+}",
    "Posts::show"
);

// Array form
$router->add(
    "/posts/([0-9]+)/([a-z\-]+)",
    [
       "controller" => "posts",
       "action"     => "show",
       "year"       => 1,
       "title"      => 2,
    ]
);

Смешанный синтаксис массива и короткой записи

Массивы и короткую запись можно смешивать для определения маршрута. В этом случае обратите внимание, что именованные параметры автоматически добавляются к путям маршрута в соответствии с позицией, в которой они были определены:

// First position must be skipped because it is used for
// the named parameter 'country'
$router->add(
    "/news/{country:[a-z]{2}}/([a-z+])/([a-z\-+])",
    [
        "section" => 2, // Positions start with 2
        "article" => 3,
    ]
);

Маршрутизация к модулям

Вы можете определить маршруты, пути которых включают модули. Это особенно подходит для приложений с несколькими модулями. Можно определить маршрут по умолчанию, который включает подстановку модуля:

use Phalcon\Mvc\Router;

$router = new Router(false);

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

В этом случае имя модуля обязательно должно присутствовать в URL-адресе. Например, следующий URL: /admin/users/edit/sonny, будет обработан как:

Или вы можете привязать определенные маршруты к определенным модулям:

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

$router->add(
    "/products/:action",
    [
        "module"     => "frontend",
        "controller" => "products",
        "action"     => 1,
    ]
);

Или привязать их к определённым пространствам имён:

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

Пространства имён/имена классов должны передаваться раздельно:

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

Ограничения по методам HTTP

При добавлении маршрута с помощью простого add(), маршрут будет активирован для любого метода HTTP. Иногда необходимо ограничить маршрут определённым методом, это особенно полезно при создании RESTful-приложений:

// This route only will be matched if the HTTP method is GET
$router->addGet(
    "/products/edit/{id}",
    "Products::edit"
);

// This route only will be matched if the HTTP method is POST
$router->addPost(
    "/products/save",
    "Products::save"
);

// This route will be matched if the HTTP method is POST or PUT
$router->add(
    "/products/update",
    "Products::update"
)->via(
    [
        "POST",
        "PUT",
    ]
);

Использование конвертеров

Конвертеры позволяют свободно преобразовывать параметры маршрута перед передачей их в диспетчер. Следующие примеры показывают, как их использовать:

// The action name allows dashes, an action can be: /products/new-ipod-nano-4-generation
$route = $router->add(
    "/products/{slug:[a-z\-]+}",
    [
        "controller" => "products",
        "action"     => "show",
    ]
);

$route->convert(
    "slug",
    function ($slug) {
        // Transform the slug removing the dashes
        return str_replace("-", "", $slug);
    }
);

Другой случай использования конвертеров — привязка модели к маршруту. Это позволяет передать модель непосредственно в определённое действие:

// This example works off the assumption that the ID is being used as parameter in the url: /products/4
$route = $router->add(
    "/products/{id}",
    [
        "controller" => "products",
        "action"     => "show",
    ]
);

$route->convert(
    "id",
    function ($id) {
        // Fetch the model
        return Product::findFirstById($id);
    }
);

Группы маршрутов

Если у набора маршрутов есть общие пути, их можно сгруппировать для облегчения их обслуживания:

use Phalcon\Mvc\Router;
use Phalcon\Mvc\Router\Group as RouterGroup;

$router = new Router();

// Create a group with a common module and controller
$blog = new RouterGroup(
    [
        "module"     => "blog",
        "controller" => "index",
    ]
);

// All the routes start with /blog
$blog->setPrefix("/blog");

// Add a route to the group
$blog->add(
    "/save",
    [
        "action" => "save",
    ]
);

// Add another route to the group
$blog->add(
    "/edit/{id}",
    [
        "action" => "edit",
    ]
);

// This route maps to a controller different than the default
$blog->add(
    "/blog",
    [
        "controller" => "blog",
        "action"     => "index",
    ]
);

// Add the group to the router
$router->mount($blog);

Вы можете переместить группы маршрутов в отдельные файлы, чтобы улучшить организацию и повторное использование кода в приложении:

use Phalcon\Mvc\Router\Group as RouterGroup;

class BlogRoutes extends RouterGroup
{
    public function initialize()
    {
        // Default paths
        $this->setPaths(
            [
                "module"    => "blog",
                "namespace" => "Blog\\Controllers",
            ]
        );

        // All the routes start with /blog
        $this->setPrefix("/blog");

        // Add a route to the group
        $this->add(
            "/save",
            [
                "action" => "save",
            ]
        );

        // Add another route to the group
        $this->add(
            "/edit/{id}",
            [
                "action" => "edit",
            ]
        );

        // This route maps to a controller different than the default
        $this->add(
            "/blog",
            [
                "controller" => "blog",
                "action"     => "index",
            ]
        );
    }
}

Затем подключить группу к маршрутизатору:

// Add the group to the router
$router->mount(
    new BlogRoutes()
);

Сопоставление маршрутов

Для обработки URI и поиска соответствующего маршрута в маршрутизатор должен быть передан допустимый URI. По умолчанию URI маршрутизации берется из переменной $_GET["_url"], которая создается модулем перенаправления. Несколько правил перенаправления, которые отлично работают с Phalcon:

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

В этой конфигурации все запросы к файлам или папкам, которые не существуют, будут отправлены в index.php.

Следующий пример показывает, как использовать этот компонент в автономном режиме:

use Phalcon\Mvc\Router;

// Creating a router
$router = new Router();

// Define routes here if any
// ...

// Taking URI from $_GET["_url"]
$router->handle();

// Or Setting the URI value directly
$router->handle("/employees/edit/17");

// Getting the processed controller
echo $router->getControllerName();

// Getting the processed action
echo $router->getActionName();

// Get the matched route
$route = $router->getMatchedRoute();

Именование маршрутов

Каждый маршрут, который добавляется в маршрутизатор, хранится в виде объекта Phalcon\Mvc\Router\Route. Этот класс обобщает все детали каждого маршрута. Например, мы можем присвоить имя пути для его уникальной идентификации в нашем приложении. Это особенно полезно, если вы хотите создать URL-адреса на его основе.

$route = $router->add(
    "/posts/{year}/{title}",
    "Posts::show"
);

$route->setName("show-posts");

Затем, используя, например, компонент Phalcon\Mvc\Url, мы можем создать маршруты по их имени:

// Returns /posts/2012/phalcon-1-0-released
echo $url->get(
    [
        "for"   => "show-posts",
        "year"  => "2012",
        "title" => "phalcon-1-0-released",
    ]
);

Примеры использования

Ниже приведены примеры пользовательских маршрутов:

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

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

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

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

// Matches "/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,
    ]
);

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

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

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

Будьте осторожны с символами, разрешенными в регулярных выражениях для контроллеров и пространств имен. Поскольку они становятся именами классов, и в свою очередь они передаются через файловую систему, их можно использовать злоумышленниками для чтения несанкционированных файлов. Безопасное регулярное выражение: /([a-zA-Z0-9\_\-]+)

Поведение по умолчанию

Phalcon\Mvc\Router имеет поведение по умолчанию, которое обеспечивает очень простую маршрутизацию, которая всегда ожидает URI, соответствующего следующему шаблону: /:controller/:action/:params

Например, для URL-адреса http://phalconphp.com/documentation/show/about.html этот маршрутизатор переведет его следующим образом:

Если вы не хотите, чтобы маршрутизатор имел это поведение, вы должны создать маршрутизатор, передавая false в качестве первого параметра:

use Phalcon\Mvc\Router;

// Create the router without default routes
$router = new Router(false);

Установление маршрута по умолчанию

Когда к вашему приложению обращаются без какого-либо маршрута, используется маршрут «/» для определения путей, которые должны быть использованы для отображения начальной страницы вашего веб-сайта/приложения:

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

Пути, не найденные

Если ни один из указанных в маршрутизаторе маршрутов не соответствует, вы можете определить группу путей, используемых в этом случае:

// Set 404 paths
$router->notFound(
    [
        "controller" => "index",
        "action"     => "route404",
    ]
);

Это обычно используется для страницы ошибки 404.

Установка путей по умолчанию

Можно определить значения по умолчанию для модуля, контроллера или действия. Когда в маршруте отсутствует любой из этих путей, они могут быть автоматически заполнены маршрутизатором:

// Setting a specific default
$router->setDefaultModule("backend");
$router->setDefaultNamespace("Backend\\Controllers");
$router->setDefaultController("index");
$router->setDefaultAction("index");

// Using an array
$router->setDefaults(
    [
        "controller" => "index",
        "action"     => "index",
    ]
);

Обработка дополнительных/завершающих косых черт

Иногда к маршруту можно получить доступ с дополнительными/завершающими косыми чертами. Эти дополнительные косые черты приведут к статусу «не найдено» в диспетчере. Вы можете настроить маршрутизатор на автоматическое удаление косых черт из конца обработанного маршрута:

use Phalcon\Mvc\Router;

$router = new Router();

// Remove trailing slashes automatically
$router->removeExtraSlashes(true);

Или вы можете изменить определённые маршруты, чтобы необязательно принимать конечные слэши:

// The [/]{0,1} allows this route to have optionally have a trailing slash
$router->add(
    "/{language:[a-z]{2}}/:controller[/]{0,1}",
    [
        "controller" => 2,
        "action"     => "index",
    ]
);

Обработка совпадений

Иногда маршруты должны соответствовать только при выполнении определённых условий. Вы можете добавить произвольные условия к маршрутам, используя beforeMatch() обработчик. Если эта функция вернёт false, маршрут будет считаться несоответствующим:

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

$route->beforeMatch(
    function ($uri, $route) {
        // Check if the request was made with Ajax
        if (isset($_SERVER["HTTP_X_REQUESTED_WITH"]) && $_SERVER["HTTP_X_REQUESTED_WITH"] === "XMLHttpRequest") {
            return false;
        }

        return true;
    }
);

Вы можете повторно использовать эти дополнительные условия в классах:

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

И использовать этот класс вместо анонимной функции:

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

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

Начиная с Phalcon 3, есть другой способ проверки этого:

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

$route->beforeMatch(
    function ($uri, $route) {
        /**
         * @var string $uri
         * @var \Phalcon\Mvc\Router\Route $route
         * @var \Phalcon\DiInterface $this
         * @var \Phalcon\Http\Request $request
         */
        $request = $this->getShared("request");

        // Check if the request was made with Ajax
        return $request->isAjax();
    }
);

Ограничения по имени хоста

Маршрутизатор позволяет задавать ограничения по имени хоста, это означает, что конкретные маршруты или группа маршрутов могут быть ограничены, чтобы соответствовать только в том случае, если маршрут также соответствует ограничению по имени хоста:

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

$route->setHostName("admin.company.com");

Имя хоста также может быть передано в виде регулярного выражения:

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

$route->setHostName("([a-z]+).company.com");

В группах маршрутов вы можете настроить ограничение по имени хоста, которое применяется ко всем маршрутам в группе:

use Phalcon\Mvc\Router\Group as RouterGroup;

// Create a group with a common module and controller
$blog = new RouterGroup(
    [
        "module"     => "blog",
        "controller" => "posts",
    ]
);

// Hostname restriction
$blog->setHostName("blog.mycompany.com");

// All the routes start with /blog
$blog->setPrefix("/blog");

// Default route
$blog->add(
    "/",
    [
        "action" => "index",
    ]
);

// Add a route to the group
$blog->add(
    "/save",
    [
        "action" => "save",
    ]
);

// Add another route to the group
$blog->add(
    "/edit/{id}",
    [
        "action" => "edit",
    ]
);

// Add the group to the router
$router->mount($blog);

Источники URI

По умолчанию информация о URI извлекается из переменной $_GET["_url"], которая передаётся модулем Rewrite-Engine в Phalcon. Вы также можете использовать $_SERVER["REQUEST_URI"], если это необходимо:

use Phalcon\Mvc\Router;

// ...

// Use $_GET["_url"] (default)
$router->setUriSource(
    Router::URI_SOURCE_GET_URL
);

// Use $_SERVER["REQUEST_URI"]
$router->setUriSource(
    Router::URI_SOURCE_SERVER_REQUEST_URI
);

Или вы можете вручную передать URI методу handle():

$router->handle("/some/route/to/handle");

Тестирование ваших маршрутов

Поскольку этот компонент не зависит от других, вы можете создать файл, как показано ниже, для проверки ваших маршрутов:

use Phalcon\Mvc\Router;

// These routes simulate real URIs
$testRoutes = [
    "/",
    "/index",
    "/index/index",
    "/index/test",
    "/products",
    "/products/index/",
    "/products/show/101",
];

$router = new Router();

// Add here your custom routes
// ...

// Testing each route
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>";
}

Маршрутизатор аннотаций

Этот компонент предоставляет вариант, интегрированный со службой аннотаций. Используя эту стратегию, вы можете писать маршруты непосредственно в контроллерах вместо добавления их в регистрацию сервисов:

use Phalcon\Mvc\Router\Annotations as RouterAnnotations;

$di["router"] = function () {
    // Use the annotations router. We're passing false as we don't want the router to add its default patterns
    $router = new RouterAnnotations(false);

    // Read the annotations from ProductsController if the URI starts with /api/products
    $router->addResource("Products", "/api/products");

    return $router;
};

Аннотации можно определить следующим образом:

/**
 * @RoutePrefix("/api/products")
 */
class ProductsController
{
    /**
     * @Get(
     *     "/"
     * )
     */
    public function indexAction()
    {

    }

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

    }

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

    }

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

    }

    public function infoAction($id)
    {

    }
}

Используются только методы, помеченные допустимыми аннотациями. Список поддерживаемых аннотаций:

Для аннотаций, добавляющих маршруты, поддерживаются следующие параметры:

Если вы используете модули в своем приложении, лучше использовать метод addModuleResource():

use Phalcon\Mvc\Router\Annotations as RouterAnnotations;

$di["router"] = function () {
    // Use the annotations router
    $router = new RouterAnnotations(false);

    // Read the annotations from Backend\Controllers\ProductsController if the URI starts with /api/products
    $router->addModuleResource("backend", "Products", "/api/products");

    return $router;
};

Регистрация экземпляра маршрутизатора

Вы можете зарегистрировать маршрутизатор во время регистрации сервисов с помощью инжектора зависимостей Phalcon, чтобы сделать его доступным внутри контроллеров.

Вам нужно добавить код ниже в ваш файл инициализации (например, index.php или app/config/services.php, если вы используете Phalcon Developer Tools)

/**
 * Add routing capabilities
 */
$di->set(
    "router",
    function () {
        require __DIR__ . "/../app/config/routes.php";

        return $router;
    }
);

Вам нужно создать app/config/routes.php и добавить код инициализации маршрутизатора, например:

use Phalcon\Mvc\Router;

$router = new Router();

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

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

return $router;

Реализация собственного маршрутизатора

Для создания собственного маршрутизатора, заменяющего предоставленный Phalcon, необходимо реализовать интерфейс Phalcon\Mvc\RouterInterface.