# 路由（Routing） # 路由（Routing） The router component allows defining routes that are mapped to controllers or handlers that should receivethe request. A router simply parses a URI to determine this information. The router has two modes: MVCmode and match-only mode. The first mode is ideal for working with MVC applications. 路由器組件用來定義處理接收到的請求的路由，指向相應的控制器或者處理程序。路由器只是簡單解析一個URI獲取這些信息。路由器有兩種模式：MVC模式以及匹配模式。第一種模式主要適合MVC應用。 ### 定義路由（Defining Routes） [*Phalcon\\Mvc\\Router*](#) provides advanced routing capabilities. In MVC mode,you can define routes and map them to controllers/actions that you require. A route is defined as follows: [*Phalcon\\Mvc\\Router*](#) 提供高級路由支持。在MVC模式下，你可以定義路由并映射向需要的控制器/動作。一個路由定義方法如下所示： ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; // Create the router $router = new Router(); // Define a route $router->add( "/admin/users/my-profile", array( "controller" => "users", "action" => "profile" ) ); // Another route $router->add( "/admin/users/change-password", array( "controller" => "users", "action" => "changePassword" ) ); $router->handle(); ``` ``` add() 方法接受一個匹配模式作為第一個參數，一組可選的路徑作為第二個參數。如上，如果URI就是/admin/users/my-profile的話，那么 “users” 控制的 “profile” 方法將被調用。當然路由器并不馬上就調用這個方法，它只是收集這些信息并且通知相應的組件（比如 [*Phalcon\\Mvc\\Dispatcher*](#) ）應該調用這個控制器的這個動作。 一個應用程序可以由很多路徑，一個一個定義是一個非常笨重的工作。這種情況下我們可以創建一個更加靈活的路由： ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; // Create the router $router = new Router(); // Define a route $router->add( "/admin/:controller/a/:action/:params", array( "controller" => 1, "action" => 2, "params" => 3 ) ); ``` ``` 在上面的例子中我們通過使用通配符定義了一個可以匹配多個URI的路由，比如，訪問這個URL（/admin/users/a/delete/dave/301），那么： ControllerusersActiondeleteParameterdaveParameter301The method add() receives a pattern that optionally could have predefined placeholders and regular expressionmodifiers. All the routing patterns must start with a slash character (/). The regular expression syntax usedis the same as the [PCRE regular expressions](http://www.php.net/manual/en/book.pcre.php). Note that, it is not necessary to add regular expressiondelimiters. All routes patterns are case-insensitive. The second parameter defines how the matched parts should bind to the controller/action/parameters. Matchingparts are placeholders or subpatterns delimited by parentheses (round brackets). In the example given above, thefirst subpattern matched (:controller) is the controller part of the route, the second the action and so on. These placeholders help writing regular expressions that are more readable for developers and easierto understand. The following placeholders are supported: PlaceholderRegular ExpressionUsage/:module/(\[a-zA-Z0-9\_-\]+)Matches a valid module name with alpha-numeric characters only/:controller/(\[a-zA-Z0-9\_-\]+)Matches a valid controller name with alpha-numeric characters only/:action/(\[a-zA-Z0-9\_\]+)Matches a valid action name with alpha-numeric characters only/:params(/.*)*Matches a list of optional words separated by slashes. Use only this placeholder at the end of a route/:namespace/(\[a-zA-Z0-9\_-\]+)Matches a single level namespace name/:int/(\[0-9\]+)Matches an integer parameterController names are camelized, this means that characters (-) and (\_) are removed and the next characteris uppercased. For instance, some\_controller is converted to SomeController. Since you can add many routes as you need using add(), the order in which routes are added indicatetheir relevance, latest routes added have more relevance than first added. Internally, all defined routesare traversed in reverse order until [*Phalcon\\Mvc\\Router*](#) finds theone that matches the given URI and processes it, while ignoring the rest. ### 參數名稱（Parameters with Names） The example below demonstrates how to define names to route parameters: ``` <pre class="calibre14">``` <?php $router->add( "/news/([0-9]{4})/([0-9]{2})/([0-9]{2})/:params", array( "controller" => "posts", "action" => "show", "year" => 1, // ([0-9]{4}) "month" => 2, // ([0-9]{2}) "day" => 3, // ([0-9]{2}) "params" => 4 // :params ) ); ``` ``` In the above example, the route doesn't define a “controller” or “action” part. These parts are replacedwith fixed values (“posts” and “show”). The user will not know the controller that is really dispatchedby the request. Inside the controller, those named parameters can be accessed as follows: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Controller; class PostsController extends Controller { public function indexAction() { } public function showAction() { // Return "year" parameter $year = $this->dispatcher->getParam("year"); // Return "month" parameter $month = $this->dispatcher->getParam("month"); // Return "day" parameter $day = $this->dispatcher->getParam("day"); } } ``` ``` Note that the values of the parameters are obtained from the dispatcher. This happens because it is thecomponent that finally interacts with the drivers of your application. Moreover, there is also anotherway to create named parameters as part of the pattern: ``` <pre class="calibre14">``` <?php $router->add( "/documentation/{chapter}/{name}.{type:[a-z]+}", array( "controller" => "documentation", "action" => "show" ) ); ``` ``` You can access their values in the same way as before: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Controller; class DocumentationController extends Controller { public function showAction() { // Returns "name" parameter $name = $this->dispatcher->getParam("name"); // Returns "type" parameter $type = $this->dispatcher->getParam("type"); } } ``` ``` ### 短語法（Short Syntax） If you don't like using an array to define the route paths, an alternative syntax is also available.The following examples produce the same result: ``` <pre class="calibre14">``` <?php // Short form $router->add("/posts/{year:[0-9]+}/{title:[a-z\-]+}", "Posts::show"); // Array form $router->add( "/posts/([0-9]+)/([a-z\-]+)", array( "controller" => "posts", "action" => "show", "year" => 1, "title" => 2 ) ); ``` ``` ### 混合使用數組和短語法（Mixing Array and Short Syntax） Array and short syntax can be mixed to define a route, in this case note that named parameters automaticallyare added to the route paths according to the position on which they were defined: ``` <pre class="calibre14">``` <?php // 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\-+])', array( 'section' => 2, // Positions start with 2 'article' => 3 ) ); ``` ``` ### 路由到模塊（Routing to Modules） You can define routes whose paths include modules. This is specially suitable to multi-module [applications.It](http://applications.It)'s possible define a default route that includes a module wildcard: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; $router = new Router(false); $router->add('/:module/:controller/:action/:params', array( 'module' => 1, 'controller' => 2, 'action' => 3, 'params' => 4 )); ``` ``` In this case, the route always must have the module name as part of the URL. For example, the followingURL: /admin/users/edit/sonny, will be processed as: ModuleadminControllerusersActioneditParametersonnyOr you can bind specific routes to specific modules: ``` <pre class="calibre14">``` <?php $router->add( "/login", array( 'module' => 'backend', 'controller' => 'login', 'action' => 'index' ) ); $router->add( "/products/:action", array( 'module' => 'frontend', 'controller' => 'products', 'action' => 1 ) ); ``` ``` Or bind them to specific namespaces: ``` <pre class="calibre14">``` <?php $router->add( "/:namespace/login", array( 'namespace' => 1, 'controller' => 'login', 'action' => 'index' ) ); ``` ``` Namespaces/class names must be passed separated: ``` <pre class="calibre14">``` <?php $router->add( "/login", array( 'namespace' => 'Backend\Controllers', 'controller' => 'login', 'action' => 'index' ) ); ``` ``` ### 限制 HTTP 請求傳入方式（HTTP Method Restrictions） 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 especially useful when creating RESTful applications: ``` <pre class="calibre14">``` <?php // 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(array("POST", "PUT")); ``` ``` ### 使用轉換（Using convertions） Convertions allow to freely transform the route's parameters before passing them to the dispatcher, the following examples show how to use them: ``` <pre class="calibre14">``` <?php // The action name allows dashes, an action can be: /products/new-ipod-nano-4-generation $router ->add('/products/{slug:[a-z\-]+}', array( 'controller' => 'products', 'action' => 'show' )) ->convert('slug', function ($slug) { // Transform the slug removing the dashes return str_replace('-', '', $slug); }); ``` ``` ### 路由分組（Groups of Routes） If a set of routes have common paths they can be grouped to easily maintain them: ``` <pre class="calibre14">``` <?php 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( array( 'module' => 'blog', 'controller' => 'index' ) ); // All the routes start with /blog $blog->setPrefix('/blog'); // Add a route to the group $blog->add('/save', array( 'action' => 'save' )); // Add another route to the group $blog->add('/edit/{id}', array( 'action' => 'edit' )); // This route maps to a controller different than the default $blog->add('/blog', array( 'controller' => 'blog', 'action' => 'index' )); // Add the group to the router $router->mount($blog); ``` ``` You can move groups of routes to separate files in order to improve the organization and code reusing in the application: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router\Group as RouterGroup; class BlogRoutes extends RouterGroup { public function initialize() { // Default paths $this->setPaths( array( 'module' => 'blog', 'namespace' => 'Blog\Controllers' ) ); // All the routes start with /blog $this->setPrefix('/blog'); // Add a route to the group $this->add( '/save', array( 'action' => 'save' ) ); // Add another route to the group $this->add( '/edit/{id}', array( 'action' => 'edit' ) ); // This route maps to a controller different than the default $this->add( '/blog', array( 'controller' => 'blog', 'action' => 'index' ) ); } } ``` ``` Then mount the group in the router: ``` <pre class="calibre14">``` <?php // Add the group to the router $router->mount(new BlogRoutes()); ``` ``` ### 匹配路由（Matching Routes） A valid URI must be passed to Router in order to let it checks the route that matches that given [URI.By](http://URI.By) default, the routing URI is taken from the $\_GET\[‘\_url'\] variable that is created by the rewrite enginemodule. A couple of rewrite rules that work very well with Phalcon are: ``` <pre class="calibre14">``` RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^((?s).*)$ index.php?_url=/$1 [QSA,L] ``` ``` The following example shows how to use this component in stand-alone mode: ``` <pre class="calibre14">``` <?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(); ``` ``` ### 路由命名（Naming Routes） Each route that is added to the router is stored internally as an object [*Phalcon\\Mvc\\Router\\Route*](#).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. ``` <pre class="calibre14">``` <?php $route = $router->add("/posts/{year}/{title}", "Posts::show"); $route->setName("show-posts"); // Or just $router->add("/posts/{year}/{title}", "Posts::show")->setName("show-posts"); ``` ``` Then, using for example the component [*Phalcon\\Mvc\\Url*](#) we can build routes from its name: ``` <pre class="calibre14">``` <?php // Returns /posts/2012/phalcon-1-0-released echo $url->get( array( "for" => "show-posts", "year" => "2012", "title" => "phalcon-1-0-released" ) ); ``` ``` ### 范例（Usage Examples） The following are examples of custom routes: ``` <pre class="calibre14">``` <?php // Matches "/system/admin/a/edit/7001" $router->add( "/system/:controller/a/:action/:params", array( "controller" => 1, "action" => 2, "params" => 3 ) ); // Matches "/es/news" $router->add( "/([a-z]{2})/:controller", array( "controller" => 2, "action" => "index", "language" => 1 ) ); // Matches "/es/news" $router->add( "/{language:[a-z]{2}}/:controller", array( "controller" => 2, "action" => "index" ) ); // Matches "/admin/posts/edit/100" $router->add( "/admin/:controller/:action/:int", array( "controller" => 1, "action" => 2, "id" => 3 ) ); // Matches "/posts/2015/02/some-cool-content" $router->add( "/posts/([0-9]{4})/([0-9]{2})/([a-z\-]+)", array( "controller" => "posts", "action" => "show", "year" => 1, "month" => 2, "title" => 4 ) ); // Matches "/manual/en/translate.adapter.html" $router->add( "/manual/([a-z]{2})/([a-z\.]+)\.html", array( "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)', array( 'controller' => 'api', 'version' => 1, 'format' => 4 ) ); ``` ``` > Beware of characters allowed in regular expression for controllers and namespaces. As thesebecome class names and in turn they're passed through the file system could be used by attackers toread unauthorized files. A safe regular expression is: /(\[a-zA-Z0-9\_-\]+) ### 默認行為（Default Behavior） [*Phalcon\\Mvc\\Router*](#) has a default behavior providing a very simple routing thatalways expects a URI that matches the following pattern: /:controller/:action/:params For example, for a URL like this *<http://phalconphp.com/documentation/show/about.html>*, this router will translate it as follows: ControllerdocumentationActionshowParameterabout.htmlIf you don't want use this routes as default in your application, you must create the router passing false as parameter: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; // Create the router without default routes $router = new Router(false); ``` ``` ### 設置默認路由（Setting the default route） When your application is accessed without any route, the ‘/' route is used to determine what paths must be used to show the initial pagein your website/application: ``` <pre class="calibre14">``` <?php $router->add( "/", array( 'controller' => 'index', 'action' => 'index' ) ); ``` ``` ### 沒有找到路徑（Not Found Paths） If none of the routes specified in the router are matched, you can define a group of paths to be used in this scenario: ``` <pre class="calibre14">``` <?php // Set 404 paths $router->notFound( array( "controller" => "index", "action" => "route404" ) ); ``` ``` ### 設置默認路徑（Setting default paths） It's possible to define default values for common paths like module, controller or action. When a route is missing any ofthose paths they can be automatically filled by the router: 可以為通用路徑中的 module, controller, action 定義默認值。當一個路由缺少其中任何一項時，路由器可以自動用默認值填充： ``` <pre class="calibre14">``` <?php // Setting a specific default $router->setDefaultModule('backend'); $router->setDefaultNamespace('Backend\Controllers'); $router->setDefaultController('index'); $router->setDefaultAction('index'); // Using an array $router->setDefaults( array( 'controller' => 'index', 'action' => 'index' ) ); ``` ``` ### 處理結尾額外的斜桿（Dealing with extra/trailing slashes） Sometimes a route could be accessed with extra/trailing slashes and the end of the route, those extra slashes would lead to producea not-found status in the dispatcher. You can set up the router to automatically remove the slashes from the end of handled route: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; $router = new Router(); // Remove trailing slashes automatically $router->removeExtraSlashes(true); ``` ``` Or, you can modify specific routes to optionally accept trailing slashes: ``` <pre class="calibre14">``` <?php $router->add( '/{language:[a-z]{2}}/:controller[/]{0,1}', array( 'controller' => 2, 'action' => 'index' ) ); ``` ``` ### 匹配回調函數（Match Callbacks） Sometimes, routes must be matched if they meet specific conditions, you can add arbitrary conditions to routes using the‘beforeMatch' callback, if this function return false, the route will be treaded as non-matched: ``` <pre class="calibre14">``` <?php $router->add('/login', array( 'module' => 'admin', 'controller' => 'session' ))->beforeMatch(function ($uri, $route) { // Check if the request was made with Ajax if ($_SERVER['HTTP_X_REQUESTED_WITH'] == 'xmlhttprequest') { return false; } return true; }); ``` ``` You can re-use these extra conditions in classes: ``` <pre class="calibre14">``` <?php class AjaxFilter { public function check() { return $_SERVER['HTTP_X_REQUESTED_WITH'] == 'xmlhttprequest'; } } ``` ``` And use this class instead of the anonymous function: ``` <pre class="calibre14">``` <?php $router->add('/get/info/{id}', array( 'controller' => 'products', 'action' => 'info' ))->beforeMatch(array(new AjaxFilter(), 'check')); ``` ``` ### 限制主機名（Hostname Constraints） The router allow to set hostname constraints, this means that specific routes or a group of routes can be restrictedto only match if the route also meets the hostname constraint: ``` <pre class="calibre14">``` <?php $router->add('/login', array( 'module' => 'admin', 'controller' => 'session', 'action' => 'login' ))->setHostName('admin.company.com'); ``` ``` Hostname can also be regular expressions: ``` <pre class="calibre14">``` <?php $router->add('/login', array( 'module' => 'admin', 'controller' => 'session', 'action' => 'login' ))->setHostName('([a-z+]).company.com'); ``` ``` In groups of routes you can set up a hostname constraint that apply for every route in the group: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router\Group as RouterGroup; // Create a group with a common module and controller $blog = new RouterGroup( array( 'module' => 'blog', 'controller' => 'posts' ) ); // Hostname restriction $blog->setHostName('blog.mycompany.com'); // All the routes start with /blog $blog->setPrefix('/blog'); // Default route $blog->add('/', array( 'action' => 'index' )); // Add a route to the group $blog->add('/save', array( 'action' => 'save' )); // Add another route to the group $blog->add('/edit/{id}', array( 'action' => 'edit' )); // Add the group to the router $router->mount($blog); ``` ``` ### URI 來源（URI Sources） By default the URI information is obtained from the $\_GET\[‘\_url'\] variable, this is passed by the Rewrite-Engine toPhalcon, you can also use $\_SERVER\[‘REQUEST\_URI'\] if required: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; // ... $router->setUriSource(Router::URI_SOURCE_GET_URL); // Use $_GET['_url'] (default) $router->setUriSource(Router::URI_SOURCE_SERVER_REQUEST_URI); // Use $_SERVER['REQUEST_URI'] (default) ``` ``` Or you can manually pass a URI to the ‘handle' method: ``` <pre class="calibre14">``` <?php $router->handle('/some/route/to/handle'); ``` ``` ### 測試路由（Testing your routes） Since this component has no dependencies, you can create a file as shown below to test your routes: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; // These routes simulate real URIs $testRoutes = array( '/', '/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>'; } ``` ``` ### 注解路由（Annotations Router） 這個組件利用集成的注解服務 [*annotations*](#) 提供了一個路由定義的變體。通過這個策略，你可以直接在書寫控制器的時候編寫路由，而不需要一個一個在服務注冊的時候添加。 ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router\Annotations as RouterAnnotations; $di['router'] = function () { // Use the annotations router $router = new RouterAnnotations(false); // Read the annotations from ProductsController if the URI starts with /api/products $router->addResource('Products', '/api/products'); return $router; }; ``` ``` 注解通過如下的方式定義： ``` <pre class="calibre14">``` <?php /** * @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) { } } ``` ``` 只有標記了格式正確的注解的方法才能被用作路由。Phalcon支持如下注解： 名稱描述用法RoutePrefixA prefix to be prepended to each route URI. This annotation must be placed at the class' docblock@RoutePrefix(“/api/products”)RouteThis annotation marks a method as a route. This annotation must be placed in a method docblock@Route(“/api/products/show”)GetThis annotation marks a method as a route restricting the HTTP method to GET@Get(“/api/products/search”)PostThis annotation marks a method as a route restricting the HTTP method to POST@Post(“/api/products/save”)PutThis annotation marks a method as a route restricting the HTTP method to PUT@Put(“/api/products/save”)DeleteThis annotation marks a method as a route restricting the HTTP method to DELETE@Delete(“/api/products/delete/{id}”)OptionsThis annotation marks a method as a route restricting the HTTP method to OPTIONS@Option(“/api/products/info”)用來添加路由的注解支持如下參數： 名稱描述用法methodsDefine one or more HTTP method that route must meet with@Route(“/api/products”, methods={“GET”, “POST”})nameDefine a name for the route@Route(“/api/products”, name=”get-products”)pathsAn array of paths like the one passed to Phalcon\\Mvc\\Router::add@Route(“/posts/{id}/{slug}”, paths={module=”backend”})conversorsA hash of conversors to be applied to the parameters@Route(“/posts/{id}/{slug}”, conversors={id=”MyConversor::getId”})如果路由對應的控制器屬于一個模塊，使用 addModuleResource 效果更佳： ``` <pre class="calibre14">``` <?php 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; }; ``` ``` ### 注冊路由實例（Registering Router instance） You can register router during service registration with Phalcon dependency injector to make it available inside controller. You need to add code below in your bootstrap file (for example index.php or app/config/services.php if you use [Phalcon Developer Tools](http://phalconphp.com/en/download/tools)) ``` <pre class="calibre14">``` <?php /** * Add routing capabilities */ $di->set('router', function () { require __DIR__.'/../app/config/routes.php'; return $router; }); ``` ``` You need to create app/config/routes.php and add router initialization code, for example: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Router; $router = new Router(); $router->add("/login", array( 'controller' => 'login', 'action' => 'index' )); $router->add("/products/:action", array( 'controller' => 'products', 'action' => 1 )); return $router; ``` ``` ### 自定義路由（Implementing your own Router） The [*Phalcon\\Mvc\\RouterInterface*](#) interface must be implemented to create your own router replacingthe one provided by Phalcon. | - [索引](# "總目錄") - [下一頁](# "調度控制器（Dispatching Controllers）") | - [上一頁](# "MVC 應用（MVC Applications）") |