Merge branch '2.4' into 2.5

book/internals.rst

@@ -208,6 +208,10 @@ processing must only occur on the master request).
 Events
 ~~~~~~
 
+.. versionadded:: 2.4
+    The ``isMasterRequest()`` method was introduced in Symfony 2.4.
+    Prior, the ``getRequestType()`` method must be used.
+
 Each event thrown by the Kernel is a subclass of
 :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`. This means that
 each event has access to the same basic information:
@@ -216,22 +220,25 @@ each event has access to the same basic information:
   - returns the *type* of the request (``HttpKernelInterface::MASTER_REQUEST``
   or ``HttpKernelInterface::SUB_REQUEST``);
 
+* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::isMasterRequest`
+  - checks if it is a master request;
+
 * :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getKernel`
   - returns the Kernel handling the request;
 
 * :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequest`
   - returns the current ``Request`` being handled.
 
-``getRequestType()``
-....................
+``isMasterRequest()``
+.....................
 
-The ``getRequestType()`` method allows listeners to know the type of the
+The ``isMasterRequest()`` method allows listeners to check the type of the
 request. For instance, if a listener must only be active for master requests,
 add the following code at the beginning of your listener method::
 
     use Symfony\Component\HttpKernel\HttpKernelInterface;
 
-    if (HttpKernelInterface::MASTER_REQUEST !== $event->getRequestType()) {
+    if (!$event->isMasterRequest()) {
         // return immediately
         return;
     }

book/routing.rst

@@ -71,7 +71,9 @@ The route is simple:
 The path defined by the ``blog_show`` route acts like ``/blog/*`` where
 the wildcard is given the name ``slug``. For the URL ``/blog/my-blog-post``,
 the ``slug`` variable gets a value of ``my-blog-post``, which is available
-for you to use in your controller (keep reading).
+for you to use in your controller (keep reading). The ``blog_show`` is the
+internal name of the route, which doesn't have any meaning yet and just needs
+to be unique. Later, you'll use it to generate URLs.
 
 The ``_controller`` parameter is a special key that tells Symfony which controller
 should be executed when a URL matches this route. The ``_controller`` string

components/http_kernel/introduction.rst

@@ -665,12 +665,16 @@ argument as follows::
     $response = $kernel->handle($request, HttpKernelInterface::SUB_REQUEST);
     // do something with this response
 
+.. versionadded:: 2.4
+    The ``isMasterRequest()`` method was introduced in Symfony 2.4.
+    Prior, the ``getRequestType()`` method must be used.
+
 This creates another full request-response cycle where this new ``Request`` is
 transformed into a ``Response``. The only difference internally is that some
 listeners (e.g. security) may only act upon the master request. Each listener
 is passed some sub-class of :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`,
-whose :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequestType`
-can be used to figure out if the current request is a "master" or "sub" request.
+whose :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::isMasterRequest`
+can be used to check if the current request is a "master" or "sub" request.
 
 For example, a listener that only needs to act on the master request may
 look like this::
@@ -680,7 +684,7 @@ look like this::
 
     public function onKernelRequest(GetResponseEvent $event)
     {
-        if (HttpKernelInterface::MASTER_REQUEST !== $event->getRequestType()) {
+        if (!$event->isMasterRequest()) {
             return;
         }
 

components/security/authentication.rst

@@ -237,20 +237,34 @@ method of the password encoder factory is called with the user object as
 its first argument, it will return an encoder of type :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`
 which should be used to encode this user's password::
 
-    // fetch a user of type Acme\Entity\LegacyUser
-    $user = ...
+    // a Acme\Entity\LegacyUser instance
+    $user = ...;
+
+    // the password that was submitted, e.g. when registering
+    $plainPassword = ...;
 
     $encoder = $encoderFactory->getEncoder($user);
 
     // will return $weakEncoder (see above)
+    $encodedPassword = $encoder->encodePassword($plainPassword, $user->getSalt());
+
+    $user->setPassword($encodedPassword);
 
-    $encodedPassword = $encoder->encodePassword($password, $user->getSalt());
+    // ... save the user
 
-    // check if the password is valid:
+Now, when you want to check if the submitted password (e.g. when trying to log
+in) is correct, you can use::
+
+    // fetch the Acme\Entity\LegacyUser
+    $user = ...;
+    
+    // the submitted password, e.g. from the login form
+    $plainPassword = ...;
 
     $validPassword = $encoder->isPasswordValid(
-        $user->getPassword(),
-        $password,
-        $user->getSalt());
+        $user->getPassword(), // the encoded password
+        $plainPassword,       // the submitted password
+        $user->getSalt()
+    );
 
 .. _`CVE-2013-5750`: http://symfony.com/blog/cve-2013-5750-security-issue-in-fosuserbundle-login-form

cookbook/service_container/event_listener.rst

@@ -100,6 +100,10 @@ using a special "tag":
 Request events, checking types
 ------------------------------
 
+.. versionadded:: 2.4
+    The ``isMasterRequest()`` method was introduced in Symfony 2.4.
+    Prior, the ``getRequestType()`` method must be used.
+
 A single page can make several requests (one master request, and then multiple
 sub-requests), which is why when working with the ``KernelEvents::REQUEST``
 event, you might need to check the type of the request. This can be easily
@@ -115,7 +119,7 @@ done as follow::
     {
         public function onKernelRequest(GetResponseEvent $event)
         {
-            if (HttpKernel::MASTER_REQUEST != $event->getRequestType()) {
+            if (!$event->isMasterRequest()) {
                 // don't do anything if it's not the master request
                 return;
             }

cookbook/workflow/new_project_git.rst

@@ -20,51 +20,51 @@ Initial Project Setup
 To get started, you'll need to download Symfony and initialize your local
 git repository:
 
-1. Download the `Symfony2 Standard Edition`_ without vendors.
+#. Download the `Symfony2 Standard Edition`_ using Composer:
 
-2. Unzip/untar the distribution. It will create a folder called Symfony with
-   your new project structure, config files, etc. Rename it to whatever you like.
-
-3. Create a new file called ``.gitignore`` at the root of your new project
-   (e.g. next to the ``composer.json`` file) and paste the following into it. Files
-   matching these patterns will be ignored by Git:
-
-   .. code-block:: text
-
-        /web/bundles/
-        /app/bootstrap*
-        /app/cache/*
-        /app/logs/*
-        /vendor/
-        /app/config/parameters.yml
+   .. code-block:: bash
 
-.. tip::
+        $ php composer.phar create-project symfony/framework-standard-edition path/ ~2.3
 
-   You may also want to create a .gitignore file that can be used system-wide,
-   in which case, you can find more information here: `Github .gitignore`_
-   This way you can exclude files/folders often used by your IDE for all of your projects.
+   Composer will now download the Standard Distribution along with all of the
+   required vendor libraries. For more information about downloading Symfony using
+   Composer, see `Installing Symfony using Composer`_.
 
-4. Initialize your Git repository:
+#. Initialize your Git repository:
 
    .. code-block:: bash
 
         $ git init
 
-5. Add all of the initial files to Git:
+#. Add all of the initial files to Git:
 
    .. code-block:: bash
 
         $ git add .
 
-6. Create an initial commit with your started project:
+   .. tip::
+
+      As you might have noticed, not all files that were downloaded by Composer in step 1,
+      have been staged for commit by Git. Certain files and folders, such as the project's
+      dependencies (which are managed by Composer), ``parameters.yml`` (which contains sensitive
+      information such as database credentials), log and cache files and dumped assets (which are
+      created automatically by your project), should not be committed in Git. To help you prevent
+      committing those files and folders by accident, the Standard Distribution comes with a
+      file called ``.gitignore``, which contains a list of files and folders that Git should
+      ignore.
+
+   .. tip::
+
+      You may also want to create a ``.gitignore`` file that can be used system-wide.
+      This allows you to exclude files/folders for all your projects that are created by
+      your IDE or operating system. For details, see `Github .gitignore`_.
+
+#. Create an initial commit with your started project:
 
    .. code-block:: bash
 
         $ git commit -m "Initial commit"
 
-7. Finally, download all of the third-party vendor libraries by
-   executing Composer. For details, see :ref:`installation-updating-vendors`.
-
 At this point, you have a fully-functional Symfony2 project that's correctly
 committed to Git. You can immediately begin development, committing the new
 changes to your Git repository.
@@ -111,6 +111,7 @@ manage this is `Gitolite`_.
 
 .. _`Git`: http://git-scm.com/
 .. _`Symfony2 Standard Edition`: http://symfony.com/download
+.. _`Installing Symfony using Composer`: http://symfony.com/doc/current/book/installation.html#option-1-composer
 .. _`git submodules`: http://git-scm.com/book/en/Git-Tools-Submodules
 .. _`GitHub`: https://github.com/
 .. _`barebones repository`: http://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository