Merge branch '2.6' into 2.7

Author: wouterj

best_practices/creating-the-project.rst

@@ -8,35 +8,15 @@ In the past, Symfony projects were created with `Composer`_, the dependency mana
 for PHP applications. However, the current recommendation is to use the **Symfony
 Installer**, which has to be installed before creating your first project.
 
-Linux and Mac OS X Systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Open your command console and execute the following:
-
-.. code-block:: bash
-
-    $ curl -LsS http://symfony.com/installer > symfony.phar
-    $ sudo mv symfony.phar /usr/local/bin/symfony
-    $ chmod a+x /usr/local/bin/symfony
-
-Now you can execute the Symfony Installer as a global system command called
-``symfony``.
-
-Windows Systems
-~~~~~~~~~~~~~~~
-
-Open your command console and execute the following:
-
-.. code-block:: bash
-
-    c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar
+.. best-practice::
 
-Then, move the downloaded ``symfony.phar`` file to your projects directory and
-execute it as follows:
+    Use the Symfony Installer to create new Symfony-based projects.
 
-.. code-block:: bash
+Read the :doc:`installation chapter </book/installation>` of the Symfony Book to
+learn how to install and use the Symfony Installer.
 
-    c:\> php symfony.phar
+.. _linux-and-mac-os-x-systems:
+.. _windows-systems:
 
 Creating the Blog Application
 -----------------------------

book/installation.rst

@@ -6,15 +6,14 @@ Installing and Configuring Symfony
 
 The goal of this chapter is to get you up and running with a working application
 built on top of Symfony. In order to simplify the process of creating new
-applications, Symfony provides an installer that must be installed before
-creating the first application.
+applications, Symfony provides an installer application.
 
 Installing the Symfony Installer
 --------------------------------
 
-Using the Symfony Installer is the only recommended way to create new Symfony
-applications. This installer is a PHP application that has to be installed
-only once and then it can create any number of Symfony applications.
+Using the **Symfony Installer** is the only recommended way to create new Symfony
+applications. This installer is a PHP application that has to be installed in your
+system only once and then it can create any number of Symfony applications.
 
 .. note::
 
@@ -29,16 +28,14 @@ ways.
 Linux and Mac OS X Systems
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Open your command console and execute the following three commands:
+Open your command console and execute the following commands:
 
 .. code-block:: bash
 
-    $ curl -LsS http://symfony.com/installer > symfony.phar
-    $ sudo mv symfony.phar /usr/local/bin/symfony
-    $ chmod a+x /usr/local/bin/symfony
+    $ sudo curl -LsS http://symfony.com/installer -o /usr/local/bin/symfony
+    $ sudo chmod a+x /usr/local/bin/symfony
 
-This will create a global ``symfony`` command in your system that will be used
-to create new Symfony applications.
+This will create a global ``symfony`` command in your system.
 
 Windows Systems
 ~~~~~~~~~~~~~~~
@@ -47,21 +44,21 @@ Open your command console and execute the following command:
 
 .. code-block:: bash
 
-    c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar
+    c:\> php -r "readfile('http://symfony.com/installer');" > symfony
 
-Then, move the downloaded ``symfony.phar`` file to your projects directory and
+Then, move the downloaded ``symfony`` file to your project's directory and
 execute it as follows:
 
 .. code-block:: bash
 
-    c:\> move symfony.phar c:\projects
-    c:\projects\> php symfony.phar
+    c:\> move symfony c:\projects
+    c:\projects\> php symfony
 
 Creating the Symfony Application
 --------------------------------
 
-Once the Symfony Installer is ready, create your first Symfony application with
-the ``new`` command:
+Once the Symfony Installer is available, create your first Symfony application
+with the ``new`` command:
 
 .. code-block:: bash
 
@@ -70,7 +67,7 @@ the ``new`` command:
 
     # Windows
     c:\> cd projects/
-    c:\projects\> php symfony.phar new my_project_name
+    c:\projects\> php symfony new my_project_name
 
 This command creates a new directory called ``my_project_name`` that contains a
 fresh new project based on the most recent stable Symfony version available. In
@@ -87,16 +84,22 @@ to meet those requirements.
 Basing your Project on a Specific Symfony Version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If your project needs to be based on a specific Symfony version, pass the version
-number as the second argument of the ``new`` command:
+In case your project needs to be based on a specific Symfony version, use the
+optional second argument of the ``new`` command:
 
 .. code-block:: bash
 
-    # Linux, Mac OS X
-    $ symfony new my_project_name 2.3.23
+    # use the most recent version in any Symfony branch
+    $ symfony new my_project_name 2.3
+    $ symfony new my_project_name 2.5
+    $ symfony new my_project_name 2.6
 
-    # Windows
-    c:\projects\> php symfony.phar new my_project_name 2.3.23
+    # use a specific Symfony version
+    $ symfony new my_project_name 2.3.26
+    $ symfony new my_project_name 2.6.5
+
+    # use the most recent LTS (Long Term Support) version
+    $ symfony new my_project_name lts
 
 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:

components/console/introduction.rst

@@ -85,7 +85,7 @@ an ``Application`` and adds commands to it::
     use Symfony\Component\Console\Application;
 
     $application = new Application();
-    $application->add(new GreetCommand);
+    $application->add(new GreetCommand());
     $application->run();
 
 Test the new console command by running the following

cookbook/deployment/heroku.rst

@@ -220,6 +220,14 @@ application will respond:
 
 You should be seeing your Symfony application in your browser.
 
+.. caution::
+
+    If you take your first steps on Heroku using a fresh installation of
+    the Symfony Standard Edition, you may run into a 404 page not found error.
+    This is because the route for ``/`` is defined by the AcmeDemoBundle, but the
+    AcmeDemoBundle is only loaded in the dev environment (check out your
+    ``AppKernel`` class). Try opening ``/app/example`` from the AppBundle.
+
 .. _`the original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2
 .. _`signup with Heroku`: https://signup.heroku.com/signup/dc
 .. _`Heroku Toolbelt`: https://devcenter.heroku.com/articles/getting-started-with-php#local-workstation-setup

cookbook/deployment/platformsh.rst

@@ -89,7 +89,7 @@ your Git repository which contains the following files:
         disk: 2048
 
 An example of these configurations can be found on `GitHub`_. The list of
-`available services <configure-services>`_ can be found on the Platform.sh documentation.
+`available services`_ can be found on the Platform.sh documentation.
 
 Configure Database Access
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -166,8 +166,8 @@ able to access it in your browser.
 Every code change that you do from now on will be pushed to Git in order to
 redeploy your environment on Platform.sh.
 
-More information about `migrating your database and files <migrate-existing-site>`_ can be found on the
-Platform.sh documentation.
+More information about `migrating your database and files`_ can be found
+on the Platform.sh documentation.
 
 Deploy a new Site
 -----------------
@@ -186,5 +186,5 @@ soon be able to see it in your browser.
 .. _`Platform.sh project`: https://marketplace.commerceguys.com/platform/buy-now
 .. _`Platform.sh configuration files`: https://docs.platform.sh/reference/configuration-files
 .. _`GitHub`: https://github.com/platformsh/platformsh-examples
-.. _`configure-services`: https://docs.platform.sh/reference/configuration-files/#configure-services
-.. _`migrate-existing-site`: https://docs.platform.sh/toolstacks/symfony/migrate-existing-site/
+.. _`available services`: https://docs.platform.sh/reference/configuration-files/#configure-services
+.. _`migrating your database and files`: https://docs.platform.sh/toolstacks/php/symfony/migrate-existing-site/

cookbook/security/remember_me.rst

@@ -8,10 +8,7 @@ Once a user is authenticated, their credentials are typically stored in the
 session. This means that when the session ends they will be logged out and
 have to provide their login details again next time they wish to access the
 application. You can allow users to choose to stay logged in for longer than
-the session lasts using a cookie with the ``remember_me`` firewall option.
-The firewall needs to have a secret key configured, which is used to encrypt
-the cookie's content. It also has several options with default values which
-are shown here:
+the session lasts using a cookie with the ``remember_me`` firewall option:
 
 .. configuration-block::
 
@@ -22,9 +19,8 @@ are shown here:
             main:
                 remember_me:
                     key:      "%secret%"
-                    lifetime: 31536000 # 365 days in seconds
+                    lifetime: 604800 # 1 week in seconds
                     path:     /
-                    domain:   ~ # Defaults to the current domain from $_SERVER
 
     .. code-block:: xml
 
@@ -33,9 +29,8 @@ are shown here:
             <firewall>
                 <remember-me
                     key      = "%secret%"
-                    lifetime = "31536000" <!-- 365 days in seconds -->
+                    lifetime = "604800" <!-- 1 week in seconds -->
                     path     = "/"
-                    domain   = "" <!-- Defaults to the current domain from $_SERVER -->
                 />
             </firewall>
         </config>
@@ -48,14 +43,60 @@ are shown here:
                 'main' => array(
                     'remember_me' => array(
                         'key'      => '%secret%',
-                        'lifetime' => 31536000, // 365 days in seconds
+                        'lifetime' => 604800, // 1 week in seconds
                         'path'     => '/',
-                        'domain'   => '', // Defaults to the current domain from $_SERVER
                     ),
                 ),
             ),
         ));
 
+The ``remember_me`` firewall defines the following configuration options:
+
+``key`` (default value: ``null``)
+    The value used to encrypt the cookie's content. It's common to use the
+    ``secret`` value defined in the ``app/config/parameters.yml`` file.
+
+``name`` (default value: ``REMEMBERME``)
+    The name of the cookie used to keep the user logged in. If you enable the
+    ``remember_me`` feature in several firewalls of the same application, make sure
+    to choose a different name for the cookie of each firewall. Otherwise, you'll
+    face lots of security related problems.
+
+``lifetime`` (default value: ``31536000``)
+    The number of seconds during which the user will remain logged in. By default
+    users are logged in for one year.
+
+``path`` (default value: ``/``)
+    The path where the cookie associated with this feature is used. By default
+    the cookie will be applied to the entire website but you can restrict to a
+    specific section (e.g. ``/forum``, ``/admin``).
+
+``domain`` (default value: ``null``)
+    The domain where the cookie associated with this feature is used. By default
+    cookies use the current domain obtained from ``$_SERVER``.
+
+``secure`` (default value: ``false``)
+    If ``true``, the cookie associated with this feature is sent to the user
+    through an HTTPS secure connection.
+
+``httponly`` (default value: ``true``)
+    If ``true``, the cookie associated with this feature is accessible only
+    through the HTTP protocol. This means that the cookie won't be accessible
+    by scripting languages, such as JavaScript.
+
+``remember_me_parameter`` (default value: ``_remember_me``)
+    The name of the form field checked to decide if the "Remember Me" feature
+    should be enabled or not. Keep reading this article to know how to enable
+    this feature conditionally.
+
+``always_remember_me`` (default value: ``false``)
+    If ``true``, the value of the ``remember_me_parameter`` is ignored and the
+    "Remember Me" feature is always enabled, regardless of the desire of the
+    end user.
+
+Forcing the User to Opt-Out of the Remember Me Feature
+------------------------------------------------------
+
 It's a good idea to provide the user with the option to use or not use the
 remember me functionality, as it will not always be appropriate. The usual
 way of doing this is to add a checkbox to the login form. By giving the checkbox

quick_tour/the_big_picture.rst

@@ -35,17 +35,6 @@ On **Linux** and **Mac OS X** systems, execute the following console commands:
     $ sudo mv symfony.phar /usr/local/bin/symfony
     $ chmod a+x /usr/local/bin/symfony
 
-.. note::
-
-    If your system doesn't have cURL installed, execute the following
-    commands instead:
-
-    .. code-block:: bash
-
-        $ php -r "readfile('http://symfony.com/installer');" > symfony.phar
-        $ sudo mv symfony.phar /usr/local/bin/symfony
-        $ chmod a+x /usr/local/bin/symfony
-
 After installing the Symfony installer, you'll have to open a new console window
 to be able to execute the new ``symfony`` command: