Merge branch '2.6' into 2.7

* 2.6: (91 commits)
  [#5064] Minor language tweaks
  Fixing bad merge conflict (forgot to save!)
  Remove unnecessary component reference
  Correct RegisterListenersPass namespace
  Fix service id
  Switched the first example to a static constructor method
  added some more components for Tobion as a merger
  Fixed variable name in : Reference -> validation constraints -> count -> basic usage -> PHP
  [#5036] Typo fix (probably mine originally) caught by xabbuh
  reword to serves
  Adding a link to define "lts"
  Better wording
  Minor improvement for symfony-installer with LTS
  Updating for new security service names in 2.6
  [#5033] Tweaking variable name to "match" the service id
  [#5017] Minor language tweaks
  [#5015] Updating the security service name for 2.6 - thanks to Cordoval
  [#5015] Very small tweak
  [#5011] Adding one more fix I missed
  [#5011] Fixing minor build issue
  ...

Conflicts:
	book/security.rst

book/controller.rst

@@ -429,35 +429,47 @@ A great way to see the core functionality in action is to look in the
 Redirecting
 ~~~~~~~~~~~
 
-If you want to redirect the user to another page, use the
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::redirect`
-method::
+If you want to redirect the user to another page, use the ``redirectToRoute()`` method::
 
     public function indexAction()
     {
-        return $this->redirect($this->generateUrl('homepage'));
+        return $this->redirectToRoute('homepage');
+
+        // redirectToRoute is equivalent to using redirect() and generateUrl() together:
+        // return $this->redirect($this->generateUrl('homepage'), 301);
     }
 
-The ``generateUrl()`` method is just a helper function that generates the URL
-for a given route. For more information, see the :doc:`Routing </book/routing>`
-chapter.
+.. versionadded:: 2.6
+    The ``redirectToRoute()`` method was added in Symfony 2.6. Previously (and still now), you
+    could use ``redirect()`` and ``generateUrl()`` together for this (see the example above).
+
+Or, if you want to redirect externally, just use ``redirect()`` and pass it the URL::
+
+    public function indexAction()
+    {
+        return $this->redirect('http://symfony.com/doc');
+    }
 
-By default, the ``redirect()`` method performs a 302 (temporary) redirect. To
+By default, the ``redirectToRoute()`` method performs a 302 (temporary) redirect. To
 perform a 301 (permanent) redirect, modify the second argument::
 
     public function indexAction()
     {
-        return $this->redirect($this->generateUrl('homepage'), 301);
+        return $this->redirectToRoute('homepage', array(), 301);
     }
 
 .. tip::
 
-    The ``redirect()`` method is simply a shortcut that creates a ``Response``
-    object that specializes in redirecting the user. It's equivalent to::
+    The ``redirectToRoute()`` method is simply a shortcut that creates a
+    ``Response`` object that specializes in redirecting the user. It's
+    equivalent to::
 
         use Symfony\Component\HttpFoundation\RedirectResponse;
 
-        return new RedirectResponse($this->generateUrl('homepage'));
+        public function indexAction()
+        {
+            return new RedirectResponse($this->generateUrl('homepage'));
+        }
 
 .. index::
    single: Controller; Rendering templates
@@ -623,12 +635,14 @@ For example, imagine you're processing a form submit::
         if ($form->isValid()) {
             // do some sort of processing
 
-            $request->getSession()->getFlashBag()->add(
+            $this->addFlash(
                 'notice',
                 'Your changes were saved!'
             );
 
-            return $this->redirect($this->generateUrl(...));
+            // $this->addFlash is equivalent to $this->get('session')->getFlashBag()->add
+
+            return $this->redirectToRoute(...);
         }
 
         return $this->render(...);
@@ -638,8 +652,8 @@ After processing the request, the controller sets a ``notice`` flash message
 in the session and then redirects. The name (``notice``) isn't significant -
 it's just something you invent and reference next.
 
-In the template of the next page (or even better, in your base layout template),
-the following code will render the ``notice`` message:
+In the template of the next action, the following code could be used to render
+the ``notice`` message:
 
 .. configuration-block::
 

book/doctrine.rst

@@ -667,7 +667,7 @@ you have a route that maps a product id to an update action in a controller::
         $product->setName('New product name!');
         $em->flush();
 
-        return $this->redirect($this->generateUrl('homepage'));
+        return $this->redirectToRoute('homepage');
     }
 
 Updating an object involves just three steps:
@@ -778,6 +778,8 @@ entities (the topic of :ref:`relations <book-doctrine-relations>` will be
 covered later), group, etc. For more information, see the official
 `Doctrine Query Language`_ documentation.
 
+.. _book-doctrine-custom-repository-classes:
+
 Custom Repository Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

book/forms.rst

@@ -234,7 +234,7 @@ controller::
         if ($form->isValid()) {
             // perform some action, such as saving the task to the database
 
-            return $this->redirect($this->generateUrl('task_success'));
+            return $this->redirectToRoute('task_success');
         }
 
         // ...
@@ -319,7 +319,7 @@ querying if the "Save and add" button was clicked::
             ? 'task_new'
             : 'task_success';
 
-        return $this->redirect($this->generateUrl($nextAction));
+        return $this->redirectToRoute($nextAction);
     }
 
 .. index::
@@ -1237,7 +1237,7 @@ it after a form submission can be done when the form is valid::
         $em->persist($task);
         $em->flush();
 
-        return $this->redirect($this->generateUrl('task_success'));
+        return $this->redirectToRoute('task_success');
     }
 
 If, for some reason, you don't have access to your original ``$task`` object,

book/http_cache.rst

@@ -166,6 +166,12 @@ kernel::
 The caching kernel will immediately act as a reverse proxy - caching responses
 from your application and returning them to the client.
 
+.. caution::
+
+    If you're using the :ref:`framework.http_method_override <configuration-framework-http_method_override>`
+    option to read the HTTP method from a ``_method`` parameter, see the
+    above link for a tweak you need to make.
+
 .. tip::
 
     The cache kernel has a special ``getLog()`` method that returns a string

book/installation.rst

@@ -98,6 +98,17 @@ number as the second argument of the ``new`` command:
     # Windows
     c:\projects\> php symfony.phar new my_project_name 2.3.23
 
+If you want your project to be based on the latest :ref:`Symfony LTS version <releases-lts>`,
+pass ``lts`` as the second argument of the ``new`` command:
+
+.. code-block:: bash
+
+    # Linux, Mac OS X
+    $ symfony new my_project_name lts
+
+    # Windows
+    c:\projects\> php symfony.phar new my_project_name lts
+
 Read the :doc:`Symfony Release process </contributing/community/releases>`
 to better understand why there are several Symfony versions and which one
 to use for your projects.

book/performance.rst

@@ -18,8 +18,9 @@ Use a Byte Code Cache (e.g. APC)
 One of the best (and easiest) things that you should do to improve your performance
 is to use a "byte code cache". The idea of a byte code cache is to remove
 the need to constantly recompile the PHP source code. There are a number of
-`byte code caches`_ available, some of which are open source. The most widely
-used byte code cache is probably `APC`_
+`byte code caches`_ available, some of which are open source. As of PHP 5.5,
+PHP comes with `OPcache`_ built-in. For older versions, the most widely used
+byte code cache is probably `APC`_
 
 Using a byte code cache really has no downside, and Symfony has been architected
 to perform really well in this type of environment.
@@ -139,6 +140,7 @@ feature is disabled in the byte code cache (e.g. ``apc.stat=0`` in APC), there
 is no longer a reason to use a bootstrap file.
 
 .. _`byte code caches`: http://en.wikipedia.org/wiki/List_of_PHP_accelerators
+.. _`OPcache`: http://php.net/manual/en/book.opcache.php
 .. _`APC`: http://php.net/manual/en/book.apc.php
 .. _`autoload.php`: https://github.com/symfony/symfony-standard/blob/master/app/autoload.php
 .. _`bootstrap file`: https://github.com/sensio/SensioDistributionBundle/blob/master/Composer/ScriptHandler.php

book/propel.rst

@@ -244,7 +244,7 @@ have a route that maps a product id to an update action in a controller::
             $product->setName('New product name!');
             $product->save();
 
-            return $this->redirect($this->generateUrl('homepage'));
+            return $this->redirectToRoute('homepage');
         }
     }
 

book/routing.rst

@@ -45,7 +45,7 @@ The route is simple:
         class BlogController extends Controller
         {
             /**
-             * @Route("/blog/{slug}")
+             * @Route("/blog/{slug}", name="blog_show")
              */
             public function showAction($slug)
             {

book/security.rst

@@ -813,20 +813,29 @@ You can easily deny access from inside a controller::
 
     public function helloAction($name)
     {
-        if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
-            throw $this->createAccessDeniedException();
-        }
+        // The second parameter is used to specify on what object the role is tested.
+        $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'Unable to access this page!');
+
+        // Old way :
+        // if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
+        //     throw $this->createAccessDeniedException('Unable to access this page!');
+        // }
 
         // ...
     }
 
 .. versionadded:: 2.6
-     The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
-     to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
+    The ``denyAccessUnlessGranted()`` method was introduced in Symfony 2.6. Previously (and
+    still now), you could check access directly and throw the ``AccessDeniedException`` as shown
+    in the example above).
+
+.. versionadded:: 2.6
+    The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
+    to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
 
-The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createAccessDeniedException`
-method creates a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
-object, which ultimately triggers a 403 HTTP response inside Symfony.
+In both cases, a special
+:class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
+is thrown, which ultimately triggers a 403 HTTP response inside Symfony.
 
 That's it! If the user isn't logged in yet, they will be asked to login (e.g.
 redirected to the login page). If they *are* logged in, they'll be shown

book/testing.rst

@@ -394,7 +394,7 @@ or perform more complex requests. Some useful examples::
         array('photo' => $photo)
     );
 
-    // Perform a DELETE requests and pass HTTP headers
+    // Perform a DELETE request and pass HTTP headers
     $client->request(
         'DELETE',
         '/post/12',

book/validation.rst

@@ -232,7 +232,7 @@ workflow looks like the following from inside a controller::
         if ($form->isValid()) {
             // the validation passed, do something with the $author object
 
-            return $this->redirect($this->generateUrl(...));
+            return $this->redirectToRoute(...);
         }
 
         return $this->render('author/form.html.twig', array(

components/config/definition.rst

@@ -95,13 +95,13 @@ Node Type
 ~~~~~~~~~
 
 It is possible to validate the type of a provided value by using the appropriate
-node definition. Node type are available for:
+node definition. Node types are available for:
 
-* scalar
+* scalar (generic type that includes booleans, strings, integers, floats and ``null``)
 * boolean
 * integer
 * float
-* enum
+* enum (similar to scalar, but it only allows a finite set of values)
 * array
 * variable (no validation)
 
@@ -288,7 +288,8 @@ All options can be documented using the
 :method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::info`
 method.
 
-The info will be printed as a comment when dumping the configuration tree.
+The info will be printed as a comment when dumping the configuration tree with
+the ``config:dump`` command.
 
 .. versionadded:: 2.6
     Since Symfony 2.6, the info will also be added to the exception message

components/config/introduction.rst

@@ -9,13 +9,6 @@ The Config Component
     combine, autofill and validate configuration values of any kind, whatever
     their source may be (YAML, XML, INI files, or for instance a database).
 
-.. caution::
-
-    The ``IniFileLoader`` parses the file contents using the
-    :phpfunction:`parse_ini_file` function, therefore, you can only set
-    parameters to string values. To set parameters to other data types
-    (e.g. boolean, integer, etc), the other loaders are recommended.
-
 Installation
 ------------
 

components/config/resources.rst

@@ -4,6 +4,13 @@
 Loading Resources
 =================
 
+.. caution::
+
+    The ``IniFileLoader`` parses the file contents using the
+    :phpfunction:`parse_ini_file` function. Therefore, you can only set
+    parameters to string values. To set parameters to other data types
+    (e.g. boolean, integer, etc), the other loaders are recommended.
+
 Locating Resources
 ------------------
 

components/console/introduction.rst

@@ -20,15 +20,6 @@ You can install the component in 2 different ways:
 * :doc:`Install it via Composer </components/using_components>` (``symfony/console`` on `Packagist`_);
 * Use the official Git repository (https://github.com/symfony/Console).
 
-.. note::
-
-    Windows does not support ANSI colors by default so the Console component detects and
-    disables colors where Windows does not have support. However, if Windows is not
-    configured with an ANSI driver and your console commands invoke other scripts which
-    emit ANSI color sequences, they will be shown as raw escape characters.
-
-    To enable ANSI color support for Windows, please install `ANSICON`_.
-
 Creating a basic Command
 ------------------------
 
@@ -124,6 +115,14 @@ This prints::
 Coloring the Output
 ~~~~~~~~~~~~~~~~~~~
 
+.. note::
+
+    By default, the Windows command console doesn't support output coloring. The
+    Console component disables output coloring for Windows systems, but if your
+    commands invoke other scripts which emit color sequences, they will be
+    wrongly displayed as raw escape characters. Install the `ConEmu`_ or `ANSICON`_
+    free applications to add coloring support to your Windows command console.
+
 Whenever you output text, you can surround the text with tags to color its
 output. For example::
 
@@ -324,9 +323,11 @@ declare a one-letter shortcut that you can call with a single dash like
 
 .. tip::
 
-    It is also possible to make an option *optionally* accept a value (so that
-    ``--yell``, ``--yell=loud`` or ``--yell loud`` work). Options can also be configured to
-    accept an array of values.
+    There is nothing forbidding you to create a command with an option that
+    optionally accepts a value. However, there is no way you can distinguish
+    when the option was used without a value (``command --yell``) or when it
+    wasn't used at all (``command``). In both cases, the value retrieved for
+    the option will be ``null``.
 
 For example, add a new option to the command that can be used to specify
 how many times in a row the message should be printed::
@@ -533,4 +534,5 @@ Learn More!
 * :doc:`/components/console/console_arguments`
 
 .. _Packagist: https://packagist.org/packages/symfony/console
+.. _ConEmu: https://code.google.com/p/conemu-maximus5/
 .. _ANSICON: https://github.com/adoxa/ansicon/releases

components/dependency_injection/factories.rst

@@ -69,6 +69,14 @@ configure the service container to use the
 
         $container->setDefinition('newsletter_manager', $definition);
 
+.. note::
+
+    When using a factory to create services, the value chosen for the ``class``
+    option has no effect on the resulting service. The actual class name only
+    depends on the object that is returned by the factory. However, the configured
+    class name may be used by compiler passes and therefore should be set to a
+    sensible value.
+
 Now, the method will be called statically. If the factory class itself should
 be instantiated and the resulting object's method called, configure the factory
 itself as a service. In this case, the method (e.g. get) should be changed to

components/event_dispatcher/introduction.rst

@@ -212,14 +212,14 @@ instance of ``Symfony\Component\HttpKernel\Event\FilterResponseEvent``::
     and the
     :doc:`DependencyInjection component </components/dependency_injection/introduction>`,
     you can use the
-    :class:`Symfony\\Component\\HttpKernel\\DependencyInjection\\RegisterListenersPass`
-    from the HttpKernel component to tag services as event listeners::
+    :class:`Symfony\\Component\\EventDispatcher\\DependencyInjection\\RegisterListenersPass`
+    to tag services as event listeners::
 
         use Symfony\Component\DependencyInjection\ContainerBuilder;
         use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
         use Symfony\Component\DependencyInjection\Reference;
-        use Symfony\Component\HttpKernel\DependencyInjection\RegisterListenersPass;
+        use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass;
 
         $containerBuilder = new ContainerBuilder(new ParameterBag());
         $containerBuilder->addCompilerPass(new RegisterListenersPass());