Merge branch '2.3' into 2.4

Author: weaverryan

book/routing.rst

@@ -75,7 +75,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/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/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