Merge pull request #430 from symfony-cmf/routing-configuration

documentation for cleaned up routing

Author: wouterj

book/simplecms.rst

@@ -37,6 +37,9 @@ The SimpleCmsBundle provides a class called ``Page`` which extends from the core
 ``NodeInterface``, so you can use inside the menu. This three-in-one approach is
 the key concept behind the bundle.
 
+The mapping of the ``Page`` to a template and controller works as explained in
+the :doc:`previous chapter <routing>`.
+
 Creating a new Page
 ~~~~~~~~~~~~~~~~~~~
 
@@ -49,7 +52,7 @@ To create a page, use the
     use Symfony\Cmf\Bundle\SimpleCmsBundle\Doctrine\Phpcr\Page;
     use Doctrine\ODM\PHPCR\DocumentManager;
 
-    class LoadRoutingData implements FixtureInterface
+    class LoadSimpleCms implements FixtureInterface
     {
         /**
          * @param DocumentManager $dm
@@ -79,7 +82,7 @@ have the following tree structure:
 
 .. code-block:: text
 
-    /cmf/simple/
+    /cms/simple/
         about/
         blog/
             symfony-cmf-is-great/
@@ -97,7 +100,7 @@ structure, you would do::
     use Symfony\Cmf\Bundle\SimpleCmsBundle\Doctrine\Phpcr\Page;
     use Doctrine\ODM\PHPCR\DocumentManager;
 
-    class LoadRoutingData implements FixtureInterface
+    class LoadSimpleCms implements FixtureInterface
     {
         /**
          * @param DocumentManager $dm
@@ -130,11 +133,11 @@ structure, you would do::
 
 Every PHPCR-ODM document must have a parent document. Parents are never
 created automatically, so we use the PHPCR NodeHelper to ensure we have
-the root element (``/cmf/simple`` in this case).
+the root element (``/cms/simple`` in this case).
 
 .. note::
 
-    The Page at ``/cmf/simple`` is created by an
+    The Page at ``/cms/simple`` is created by an
     :ref:`initializer <phpcr-odm-repository-initializers>` of the
     SimpleCmsBundle.
 

bundles/routing/dynamic.rst

@@ -263,15 +263,20 @@ need content, you can just not set it in the route document.
     from content instances. When resolving the route, the ``_locale`` gets
     into the request and is picked up by the Symfony2 locale system.
 
+    Make sure you configure the valid locales in the configuration so that the
+    bundle can optimally handle locales. The
+    :ref:`configuration reference <reference-config-routing-locales>` lists
+    some options to tweak behaviour and performance.
+
 .. note::
 
-    Under PHPCR-ODM, Routes should never be translatable documents, as one
+    Under PHPCR-ODM, Routes should not be translatable documents, as one
     Route document represents one single url, and serving several translations
     under the same url is not recommended.
 
-    If you need translated URLs, make the locale part of the route name and use
-    several routes for the same content. The route generator will pick the
-    correct route if available.
+    If you need translated URLs, make the ``locale`` part of the route name and
+    create one route per language for the same content. The route generator will
+    pick the correct route if available.
 
 Sonata Doctrine PHPCR-ODM Admin classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -288,6 +293,10 @@ get an error if Sonata becomes unavailable.
 Sonata admin is using the ``content_basepath`` to show the tree of content to
 select the route target.
 
+The root path to add Routes defaults to the first entry in ``route_basepaths``,
+but you can overwrite this with the ``admin_basepath`` if you need a different
+base path.
+
 .. configuration-block::
 
     .. code-block:: yaml

bundles/routing/dynamic_customize.rst

@@ -24,7 +24,9 @@ You can add your own :ref:`RouteEnhancerInterface <bundles-routing-dynamic_route
 implementations if you have a case not handled by the
 :ref:`provided enhancers <component-routing-enhancers>`. Simply define services
 for your enhancers and tag them with ``dynamic_router_route_enhancer`` to have
-them added to the routing.
+them added to the routing. You can specify an optional ``priority`` parameter
+on the tag to control the order in which enhancers are executed. The higher the
+priority, the earlier the enhancer is executed.
 
 .. index:: Route Provider
 .. _bundle-routing-custom_provider:

bundles/simple_cms/multilang.rst

@@ -4,7 +4,7 @@
 Multi-Language Support
 ----------------------
 
-Setting ``addLocalePattern`` to ``true`` in a
+Setting the option ``add_locale_pattern`` to ``true`` in a
 ``Symfony\Cmf\Bundle\SimpleCmsBundle\Doctrine\Phpcr\Page`` document will
 result in prefixing the associated route with ``/{_locale}``. Using the native
 translation capabilities of PHPCR ODM it is now possible to create different
@@ -42,10 +42,8 @@ For example::
     will have the same node name for all languages. So a url
     ``http://foo.com/en/hello-world`` for english content will look like
     ``http://foo.com/de/hello-world`` for german content.
-    
-    At times it might be most feasible to use integers as the node names and
-    simple append the title of the node in the given locale as an anchor. So
-    for example ``http://foo.com/de/1#my title`` and
-    ``http://foo.com/de/1#mein title``. If you need language specific URLs,
-    you want to use the CMF RoutingBundle and ContentBundle directly to have
-    a separate route document per language.
+
+    If you need language specific URLs, you can either add Route documents for
+    the other locales and configure the dynamic router to look for routes under
+    both prefixes. You can also completely separate routing and content by using
+    the separate documents from the RoutingBundle and ContentBundle.

bundles/simple_cms/rendering.rst

@@ -4,11 +4,11 @@
 Rendering
 ---------
 
-You can specify the template to render a page by setting the
-``_template`` default or by specifying the controller by setting the
-``_controller`` default in the page instance. Alternatively one can
-configure the template and controller also via the SimpleCmsBundle
-:ref:`routing configuration <config-simple-cms-routing>`.
+You can configure a mapping of document class to template and/or controller
+by configuring the :ref:`RoutingBundle <reference-config-routing-dynamic>`.
+When you need specific settings for a single page, you can call
+``setDefault()`` for the key ``_template`` or ``_controller`` default in the
+page instance.
 
 A simple example for such a template could look like this:
 

components/routing/nested_matcher.rst

@@ -37,6 +37,12 @@ do any elaborate matching operations yet - this will be done in the later steps.
     implementations for everything needed to get this component running with
     Doctrine PHPCR-ODM as well as with the Doctrine ORM.
 
+.. tip::
+
+    This component provides the ``Candidates`` implementation for the very
+    first step of splitting the URL on the ``/`` to allow matching with
+    variable patterns.
+
 To create and register your own Route Provider, create a class implementing
 ``Symfony\Cmf\Component\Routing\RouteProviderInterface`` which will have the
 following methods::

reference/configuration/routing.rst

@@ -305,8 +305,11 @@ phpcr
                     phpcr:
                         enabled: false
                         manager_name: ~
-                        route_basepath: /cms/routes
+                        route_basepaths:
+                            - /cms/routes
+                            - /cms/simple
                         content_basepath: /cms/content
+                        admin_basepath: /cms/routes
                         use_sonata_admin: auto
 
     .. code-block:: xml
@@ -320,10 +323,13 @@ phpcr
                         <phpcr
                             enabled="false"
                             manager-name="null"
-                            route-basepath="/cms/routes"
                             content-basepath="/cms/content"
+                            admin-basepath="/cms/routes"
                             use-sonata-admin="auto"
-                        />
+                        >
+                            <route-basepath>/cms/routes</route-basepath>
+                            <route-basepath>/cms/simple</route-basepath>
+                        </phpcr>
                     </persistence>
                 </dynamic>
             </config>
@@ -337,8 +343,12 @@ phpcr
                     'phpcr' => array(
                         'enabled' => false,
                         'manager_name' => null,
-                        'route_basepath' => '/cms/routes',
+                        'route_basepaths' => array(
+                            '/cms/routes',
+                            '/cms/simple',
+                        )
                         'content_basepath' => '/cms/content',
+                        'admin_basepath' => '/cms/routes',
                         'use_sonata_admin' => 'auto',
                     ),
                 ),
@@ -356,27 +366,37 @@ manager_name
 
 .. include:: partials/persistence_phpcr_manager_name.rst.inc
 
-route_basepath
-**************
+route_basepaths
+***************
 
-**type**: ``string`` **default**: ``/cms/routes``
+**type**: ``array`` **default**: ``array('/cms/routes')``
 
-The basepath for routes in the PHPCR tree.
+The basepaths where to look for routes in the PHPCR tree.
 
-If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to
-``%cmf_core.persistence.phpcr.basepath%/routes``.
+If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will
+default to ``%cmf_core.persistence.phpcr.basepath%/routes``. If the
+:doc:`SimpleCmsBundle <../../bundles/simple_cms/index>` is registered as well,
+this will additionally default to ``%cmf_core.persistence.phpcr.basepath%/simple``.
 
 content_basepath
 ****************
 
-**type**: ``content_basepath`` **default**: ``/cms/content``
+**type**: ``string`` **default**: ``/cms/content``
 
 The basepath for content objects in the PHPCR tree. This information is used
 with the sonata admin to offer the correct subtree to select content documents.
 
 If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to
 ``%cmf_core.persistence.phpcr.basepath%/content``.
 
+admin_basepath
+**************
+
+**type**: ``string`` **default**: first value of route_basepaths
+
+The path at which to create routes with Sonata admin. There can be additional
+route basepaths, but you will need your own tools to edit those.
+
 use_sonata_admin
 ****************
 
@@ -487,12 +507,62 @@ content repository service.
     This can be overriden by this option. ORM doesn't have a content
     repository at the moment.
 
+.. _reference-config-routing-locales:
+
 locales
 ~~~~~~~
 
-**type**: ``array`` **default**:
+**type**: ``array`` **default**: ``array()``
 
 To enable multilanguage, set the valid locales in this option.
 
-If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to the value
-of ``cmf_core.locales``.
+If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will
+default to the value of ``cmf_core.locales``.
+
+limit_candidates
+~~~~~~~~~~~~~~~~
+
+**type**: ``integer`` **default**: ``20``
+
+With this flag you can tune the routing behaviour when using the dynamic
+pattern part of routes stored in the database. If you do never use the variable
+pattern field of the Route model, you can set this to 1 as a small performance
+optimization. If you have very complex URLs with patterns, you might need to
+increase the limit.
+
+.. caution::
+
+    Setting this to a higher makes your site more vulnerable to load attacks
+    when someone visits your site with URLs with lots of slashes in them, since
+    every slash will lead to a document being tried to be loaded.
+
+match_implicit_locale
+~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true``
+
+Whether the route provider should look for routes without the locale.
+
+For example, when the ``locales`` are ``de`` and ``en`` and the request has the
+url ``de/my/path``, the route provider will not only look for ``de/my/path``,
+``de/my`` and ``de`` but also for ``my/path`` and ``my``. This allows to use a
+single route for multiple languages. This is used for example by the
+:doc:`SimpleCms <../../bundles/simple_cms/index>`.
+
+If you do not need this, disabling the option will gain some performance.
+
+auto_locale_pattern
+~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+If you enable this option, the LocaleListener will ensure that routes that have
+no locale in their static pattern get the ``auto_locale_pattern`` option set.
+
+.. note::
+
+    Enabling this option will prevent you from having any CMF Routes that match
+    URL without a locale in it.
+
+This is ignored if there are no ``locales`` configured. It makes no sense to
+enable this option when ``match_implicit_locale`` is disabled.