Skip to content

Reworded and improved the routing/external_resources article #9102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 25, 2018
Merged

Reworded and improved the routing/external_resources article #9102

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 46 additions & 53 deletions routing/external_resources.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just a question. having values of this keys aligned by column is by convention or something?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes ... but we only do that for the docs, to improve readability. In code we never align code like this.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


.. code-block:: xml

Expand All @@ -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">

<!-- the type is required to enable the annotation reader for this resource -->
<import resource="@AppBundle/Controller/" type="annotation"/>
<!-- loads routes from the given routing file stored in some bundle -->
<import resource="@AcmeOtherBundle/Resources/config/routing.yml" />

<!-- loads routes from the PHP annotations of the controllers found in that directory -->
<import resource="@AppBundle/Controller/" type="annotation" />

<!-- loads routes from the YAML or XML files found in that directory -->
<import resource="../legacy/routing/" type="directory" />

<!-- loads routes from the YAML or XML files found in some bundle directory -->
<import resource="@AppBundle/Resources/config/routing/public/" type="directory" />
</routes>

.. code-block:: php
Expand All @@ -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

<!-- app/config/routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/routing
http://symfony.com/schema/routing/routing-1.0.xsd">

<import resource="@AcmeOtherBundle/Resources/config/routing.xml" />
</routes>

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

Expand Down