[component][routing] Proofreading and tweaking the bootstrap for the routing component docs by @blogsh

Author: weaverryan

book/security.rst

@@ -1,3 +1,6 @@
+.. index::
+   single: Security
+
 Security
 ========
 

components/routing.rst

@@ -1,10 +1,11 @@
 .. index::
    single: Routing
+   single: Components; Routing
 
 The Routing Component
-====================
+=====================
 
-   The Routing Component maps a HTTP request to a set of configuration 
+   The Routing Component maps an HTTP request to a set of configuration 
    variables.
 
 Installation
@@ -25,8 +26,9 @@ In order to set up a basic routing system you need three parts:
 * A :class:`Symfony\\Component\\Routing\\RequestContext`, which has information about the request
 * A :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher`, which performs the mapping of the request to a single route
 
-.. code-block:: php
-    
+Let's see a quick example. Notice that this assumes that you've already configured
+your autoloader to load the Routing component::
+
     use Symfony\Component\Routing\Matcher\UrlMatcher;
     use Symfony\Component\Routing\RequestContext;
     use Symfony\Component\Routing\RouteCollection;
@@ -35,140 +37,165 @@ In order to set up a basic routing system you need three parts:
     $routes = new RouteCollection();
     $routes->add('route_name', new Route('/foo', array('controller' => 'MyController')));
 
-    $context = new RequestContext();
+    $context = new RequestContext($_SERVER['REQUEST_URI']);
 
     $matcher = new UrlMatcher($routes, $context);
 
     $parameters = $matcher->match( '/foo' ); 
     // array('controller' => 'MyController', '_route' => 'route_name')
 
+.. note::
+
+    Be careful when using ``$_SERVER['REQUEST_URI']``, as it may include
+    any query parameters on the URL, which will cause problems with route
+    matching. An easy way to solve this is to use the HTTPFoundation component
+    as explained :ref:`below<components-routing-http-foundation>`.
+
 You can add as many routes as you like to a 
-:class:`Symfony\\Component\\Routing\\RouteCollection`. The first argument you have to
-provide to the :method:`Symfony\\Component\\Routing\\RouteCollection::add` method is 
-the name of the Route. The constructor of the :class:`Symfony\\Component\\Routing\\Route` 
-class expects an url path and an array of custom variables. These are returned by the 
-Matcher if the route matches the request.
+:class:`Symfony\\Component\\Routing\\RouteCollection`.
+
+The :method:`RouteCollection::add()<Symfony\\Component\\Routing\\RouteCollection::add>`
+method takes two arguments. The first is the name of the route, The second
+is a :class:`Symfony\\Component\\Routing\\Route` object, which expects a
+URL path and some array of custom variables in its constructor. This array
+of custom variables can be *anything* that's significant to your application,
+and is returned when that route is matched.
 
 If no matching route can be found a 
 :class:`Symfony\\Component\\Routing\\Exception\\ResourceNotFoundException` will be thrown.
 
-Additionally to the custom variables the name of the route is added with the 
-key "_route".
+In addition to your array of custom variables, a ``_route`` key is added,
+which holds the name of the matched route.
 
 Defining routes
 ~~~~~~~~~~~~~~~
 
-A route contains:
+A full route definition can contain up to four parts:
+
+1) The URL pattern route. This is matched against the URL passed to the `RequestContext`,
+    and can contain named wildcard placeholders (e.g. ``{placeholders}``)
+    to match dynamic parts in the URL.
+
+2) An array of default values. This contains an array of arbitrary values
+    that will be returned when the request matches the route.
 
-* The path the of route, which shall be recognized by the matcher. You can use ``{placeholders}`` to match dynamic parts in the url.
-* The default values. These contain the values that will be returned when the request matches the route.
-* The requirements. These define constraints for the values of the placeholders as regular expressions.
-* The options. These contain internal settings for the route
+3) An array of requirements. These define constraints for the values of the
+    placeholders as regular expressions.
+
+4) An array of options. These contain internal settings for the route
+
+Take the following route, which combines several of these ideas::
 
-.. code-block:: php
-    
    $route = new Route(
        '/archive/{month}', // path
        array('controller' => 'showArchive'), // default values
        array('month' => '[0-9]{4}-[0-9]{2}'), // requirements
        array() // options
    );
-   
+
    // ...
-   
+
    $parameters = $matcher->match('/archive/2012-01');
    // array('controller' => 'showArchive', 'month' => 2012-01'', '_route' => '...')
-   
+
    $parameters = $matcher->match('/archive/foo');
    // throws ResourceNotFoundException
 
+In this case, the route is matched by ``/archive/2012/01``, because the ``{month}``
+wildcard matches the regular expression wildcard given. However, ``/archive/foo``
+does *not* match, because "foo" fails the month wildcard.
+
 Besides the regular expression constraints there are two special requirements 
 you can define:
 
 * ``_method`` enforces a certain HTTP request method (``HEAD``, ``GET``, ``POST``, ...)
 * ``_scheme`` enforces a certain HTTP scheme (``http``, ``https``) 
 
-.. code-block:: php
-    
-   // Only accepts requests to /foo with the POST method and a secure connection.
+For example, the following route would only accept requests to /foo with
+the POST method and a secure connection::
+
    $route = new Route('/foo', array('_method' => 'post', '_scheme' => 'https' ));
 
-Using prefixes
+Using Prefixes
 ~~~~~~~~~~~~~~
 
 You can add routes or other instances of 
-:class:`Symfony\\Component\\Routing\\RouteCollection` to a collection. This way 
-you can build a tree of routes. Additionally you can define a prefix, default 
-requirements and default options to all routes of a subtree:
+:class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection.
+This way you can build a tree of routes. Additionally you can define a prefix,
+default requirements and default options to all routes of a subtree::
 
-.. code-block:: php
-    
     $rootCollection = new RouteCollection();
-    
+
     $subCollection = new RouteCollection();
     $subCollection->add( /*...*/ );
     $subCollection->add( /*...*/ );
-    
+
     $rootCollection->addCollection($subCollection, '/prefix', array('_scheme' => 'https'));
 
-Set the request parameters
+Set the Request Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :class:`Symfony\\Component\\Routing\\RequestContext` provides information 
-about a request. You can define all parameters of a HTTP request with this class:
+about the current request. You can define all parameters of an HTTP request
+with this class via its constructor::
 
-.. code-block:: php
-    
     public function __construct($baseUrl = '', $method = 'GET', $host = 'localhost', $scheme = 'http', $httpPort = 80, $httpsPort = 443)
 
-Normally you can pass the values from the ``$_SERVER`` variable variable to the 
-:class:`Symfony\\Component\\Routing\\RequestContext`. If you use the
-:doc:`HttpFoundation<http_foundation>` component you can use it's 
+.._components-routing-http-foundation:
+
+Normally you can pass the values from the ``$_SERVER`` variable to populate the 
+:class:`Symfony\\Component\\Routing\\RequestContext`. But If you use the
+:doc:`HttpFoundation<http_foundation>` component, you can use its 
 :class:`Symfony\\Component\\HttpFoundation\\Request` class to feed the 
-:class:`Symfony\\Component\\Routing\\RequestContext` in a shortcut:
-  
-.. code-block:: php
-    
+:class:`Symfony\\Component\\Routing\\RequestContext` in a shortcut::
+
     use Symfony\Component\HttpFoundation\Request;
-    
+
     $context = new RequestContext();
     $context->fromRequest(Request::createFromGlobals());
 
 Generate a URL
 ~~~~~~~~~~~~~~
 
-While the :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher` tries to find 
-a route that fits the given request you can also build an URL from a certain route:
+While the :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher` tries
+to find a route that fits the given request you can also build a URL from
+a certain route::
 
-.. code-block:: php
-    
     use Symfony\Component\Routing\Generator\UrlGenerator;
 
     $routes = new RouteCollection();
     $routes->add('show_post', new Route('/show/{slug}'));
 
-    $context = new RequestContext();
+    $context = new RequestContext($_SERVER['REQUEST_URI']);
 
     $generator = new UrlGenerator($routes, $context);
 
-    $url = $generator->generate('show_post', 'My_Blog_Post');
-    // /show/My_Blog_Post
+    $url = $generator->generate('show_post', array(
+        'slug' => 'my-blog-post'
+    ));
+    // /show/my-blog-post
 
 .. note::
-    
-    If you have defined the ``_scheme`` requirement an absolute URL is generated
+
+    If you have defined the ``_scheme`` requirement, an absolute URL is generated
     if the scheme of the current :class:`Symfony\\Component\\Routing\\RequestContext`
-    isn't the same.
+    does not match the requirement.
 
-Load routes from a file
+Load Routes from a File
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-There is a number of loader classes. They give you the ability to load a collection
-of route definitions from external files. 
-The loaders expect a :class:`Symfony\\Component\\Config\\FileLocator` as the 
-constructor argument. You can use the :class:`Symfony\\Component\\Config\\FileLocator`
+You've already seen how you can easily add routes to a collection right inside
+PHP. But you can also load routes from a number of different files.
+
+The Routing component comes with a number of loader classes, each giving
+you the ability to load a collection of route definitions from an external
+file of some format.
+Each loader expects a :class:`Symfony\\Component\\Config\\FileLocator` instance
+as the constructor argument. You can use the :class:`Symfony\\Component\\Config\\FileLocator`
 to define an array of paths in which the loader will look for the requested files.
-If the file could be found the loader returns a :class:`Symfony\\Component\\Routing\\RouteCollection`.
+If the file is found, the loader returns a :class:`Symfony\\Component\\Routing\\RouteCollection`.
+
+If you're using the ``YamlFileLoader``, then route definitions look like this:
 
 .. code-block:: yaml
 
@@ -181,11 +208,13 @@ If the file could be found the loader returns a :class:`Symfony\\Component\\Rout
         pattern: /foo/bar
         defaults: { controller: 'MyController::foobarAction' }
 
-.. code-block:: php
-    
+To load this file, you can use the following code. This assumes that your
+``routes.yml`` file is in the same directory as the below code::
+
     use Symfony\Component\Config\FileLocator;
     use Symfony\Component\Routing\Loader\YamlFileLoader;
 
+    // look inside *this* directory
     $locator = new FileLocator(array(__DIR__));
     $loader = new YamlFileLoader($locator);
     $collection = $loader->load('routes.yml');
@@ -197,63 +226,69 @@ other loaders that work the same way:
 * :class:`Symfony\\Component\\Routing\\Loader\\PhpFileLoader`
 
 If you use the :class:`Symfony\\Component\\Routing\\Loader\\PhpFileLoader` you
-have to provide the name of a php file which returns a :class:`Symfony\\Component\\Routing\\RouteCollection`:
+have to provide the name of a php file which returns a :class:`Symfony\\Component\\Routing\\RouteCollection`::
 
-.. code-block:: php
-    
     // RouteProvider.php
     use Symfony\Component\Routing\RouteCollection;
     use Symfony\Component\Routing\Route;
 
     $collection = new RouteCollection();
     $collection->add('route_name', new Route('/foo', array('controller' => 'ExampleController')));
     // ...
-    
+
     return $collection;
 
+Routes as Closures
+..................
+
 There is also the :class:`Symfony\\Component\\Routing\\Loader\\ClosureLoader`, which 
-calls a closure and uses the result as a :class:`Symfony\\Component\\Routing\\RouteCollection`:
+calls a closure and uses the result as a :class:`Symfony\\Component\\Routing\\RouteCollection`::
 
-.. code-block:: php
-    
     use Symfony\Component\Routing\Loader\ClosureLoader;
-    
+
     $closure = function() {
         return new RouteCollection();
     };
 
     $loader = new ClosureLoader();
     $collection = $loader->load($closure);
 
+Routes as Annotations
+.....................
+
 Last but not least there are
 :class:`Symfony\\Component\\Routing\\Loader\\AnnotationDirectoryLoader` and
 :class:`Symfony\\Component\\Routing\\Loader\\AnnotationFileLoader` to load
-route definitions from class annotations.
+route definitions from class annotations. The specific details are left
+out here.
 
 The all-in-one Router
 ~~~~~~~~~~~~~~~~~~~~~
 
-The :class:`Symfony\\Component\\Routing\\Router` class is a all-in-one package of 
-the routing algorithm. The constructor expects a loader instance, a path to the 
-main route definition and some other settings:
+The :class:`Symfony\\Component\\Routing\\Router` class is a all-in-one package
+to quickly use the Routing component. The constructor expects a loader instance,
+a path to the main route definition and some other settings::
 
-.. code-block:: php
-    
     public function __construct(LoaderInterface $loader, $resource, array $options = array(), RequestContext $context = null, array $defaults = array());
 
 With the ``cache_dir`` option you can enable route caching (if you provide a 
 path) or disable caching (if it's set to ``null``). The caching is done 
 automatically in the background if you want to use it. A basic example of the 
-:class:`Symfony\\Component\\Routing\\Router` class would look like:
+:class:`Symfony\\Component\\Routing\\Router` class would look like::
 
-.. code-block:: php
-    
     $locator = new FileLocator(array(__DIR__));
-    $router = new Router(new YamlFileLoader($locator), "routes.yml");
+    $requestContext = new RequestContext($_SERVER['REQUEST_URI']);
+
+    $router = new Router(
+        new YamlFileLoader($locator),
+        "routes.yml",
+        array('cache_dir' => __DIR__.'/cache'),
+        $requestContext,
+    );
     $router->match('/foo/bar');
 
 .. note::
-    
-    If you use caching the Routing component will compile new classes which 
+
+    If you use caching, the Routing component will compile new classes which 
     are saved in the ``cache_dir``. This means your script must have write 
     permissions for that location.