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
~~~~~~~~~~~~~~~~~~~~~~~~~