From a22235b555f1c01ff0ce0118ef19b477213578ee Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 22 Jan 2018 14:55:01 +0100 Subject: [PATCH] Reworded and improved the routing/external_resources article --- routing/external_resources.rst | 99 ++++++++++++++++------------------ 1 file changed, 46 insertions(+), 53 deletions(-) diff --git a/routing/external_resources.rst b/routing/external_resources.rst index b3246bb9d8a..37242053b6c 100644 --- a/routing/external_resources.rst +++ b/routing/external_resources.rst @@ -4,19 +4,37 @@ How to Include External Routing Resources ========================================= -All routes are loaded via a single configuration file - usually ``app/config/routing.yml`` -(see :ref:`routing-creating-routes`). However, if you use routing annotations, -you'll need to point the router to the controllers with the annotations. -This can be done by "importing" directories into the routing configuration: +Simple applications can define all their routes in a single configuration file - +usually ``app/config/routing.yml`` (see :ref:`routing-creating-routes`). +However, in most applications it's common to import routes definitions from +different resources: PHP annotations in controller files, YAML or XML files +stored in some directory, etc. + +This can be done by importing routing resources from the main routing file: .. configuration-block:: .. code-block:: yaml # app/config/routing.yml - app: + app_file: + # loads routes from the given routing file stored in some bundle + resource: '@AcmeOtherBundle/Resources/config/routing.yml' + + app_annotations: + # loads routes from the PHP annotations of the controllers found in that directory resource: '@AppBundle/Controller/' - type: annotation # required to enable the Annotation reader for this resource + type: annotation + + app_directory: + # loads routes from the YAML or XML files found in that directory + resource: '../legacy/routing/' + type: directory + + app_bundle: + # loads routes from the YAML or XML files found in some bundle directory + resource: '@AppBundle/Resources/config/routing/public/' + type: directory .. code-block:: xml @@ -27,8 +45,17 @@ This can be done by "importing" directories into the routing configuration: xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - - + + + + + + + + + + + .. code-block:: php @@ -38,60 +65,26 @@ This can be done by "importing" directories into the routing configuration: $collection = new RouteCollection(); $collection->addCollection( - // second argument is the type, which is required to enable - // the annotation reader for this resource + // loads routes from the given routing file stored in some bundle + $loader->import("@AcmeOtherBundle/Resources/config/routing.yml") + + // loads routes from the PHP annotations of the controllers found in that directory $loader->import("@AppBundle/Controller/", "annotation") + + // loads routes from the YAML or XML files found in that directory + $loader->import("../legacy/routing/", "directory") + + // loads routes from the YAML or XML files found in some bundle directory + $loader->import("@AppBundle/Resources/config/routing/public/", "directory") ); return $collection; .. note:: - When importing resources from YAML, the key (e.g. ``app``) is meaningless. + When importing resources from YAML, the key (e.g. ``app_file``) is meaningless. Just be sure that it's unique so no other lines override it. -The ``resource`` key loads the given routing resource. In this example the -resource is a directory, where the ``@AppBundle`` shortcut syntax resolves -to the full path of the AppBundle. When pointing to a directory, all files -in that directory are parsed and put into the routing. - -.. note:: - - You can also include other routing configuration files, this is often - used to import the routing of third party bundles: - - .. configuration-block:: - - .. code-block:: yaml - - # app/config/routing.yml - app: - resource: '@AcmeOtherBundle/Resources/config/routing.yml' - - .. code-block:: xml - - - - - - - - - .. code-block:: php - - // app/config/routing.php - use Symfony\Component\Routing\RouteCollection; - - $collection = new RouteCollection(); - $collection->addCollection( - $loader->import("@AcmeOtherBundle/Resources/config/routing.php") - ); - - return $collection; - Prefixing Imported Routes ~~~~~~~~~~~~~~~~~~~~~~~~~