Merge branch '2.4' into 2.5

* 2.4:
  Fixed description for session storage
  Added a note about the automatic handling of the memory spool in the CLI
  Added July changelog
  Added July changelog
  [Contributing] extended Symfony 2.4 maintenance
  field dependent empty_data option description
  add note on Symfony SE forks for bug reports

Conflicts:
	changelog.rst

Author: weaverryan

changelog.rst

@@ -57,12 +57,12 @@ Minor Documentation Changes
 - `c2eda93 <https://github.com/symfony/symfony-docs/commit/c2eda939ad8681721cd1b12bcedadd1faf294725>`_ #4034 Update internals.rst (redstar504)
 - `a5ad0df <https://github.com/symfony/symfony-docs/commit/a5ad0dfbf9ad2dcc84e7f9c6de73c8bad2a89e2f>`_ #4035 Update version in Rework your Patch section (yguedidi)
 - `eed8d64 <https://github.com/symfony/symfony-docs/commit/eed8d646ad134bba1002f98800cab46d06241a05>`_ #4026 Updating Symfony version from 2.4 to 2.5 (danielsan)
+- `12752c1 <https://github.com/symfony/symfony-docs/commit/12752c1decd5ec5a3bce960c094f45738122152f>`_ #4013 Removed wrong reference to cookbook (gquemener)
+- `ec832dc <https://github.com/symfony/symfony-docs/commit/ec832dc4eadbe5afdfb5f39994b69748b733a85b>`_ #3994 [Console] Fix Console component $app to $this and use of getHelper() method (eko)
 - `d8b037a <https://github.com/symfony/symfony-docs/commit/d8b037a989c1581ae671e81284d0d758254d8e1e>`_ #4019 Update twig_reference.rst (redstar504)
 - `7ea87e6 <https://github.com/symfony/symfony-docs/commit/7ea87e63e3417c59e47972b9cf12ca76cce4b195>`_ #4016 Fixed the format of one letter-based list (javiereguiluz)
 - `579a873 <https://github.com/symfony/symfony-docs/commit/579a8732299dd944998ab3fee4fa738a3c45cea2>`_ #4015 Fixed bad indenting (the list was treated as a blockquote) (javiereguiluz)
-- `12752c1 <https://github.com/symfony/symfony-docs/commit/12752c1decd5ec5a3bce960c094f45738122152f>`_ #4013 Removed wrong reference to cookbook (gquemener)
 - `4669620 <https://github.com/symfony/symfony-docs/commit/466962051e0753557fc75d9d449083d68ae48992>`_ #4004 use GitHub instead of Github (xabbuh)
-- `ec832dc <https://github.com/symfony/symfony-docs/commit/ec832dc4eadbe5afdfb5f39994b69748b733a85b>`_ #3994 [Console] Fix Console component $app to $this and use of getHelper() method (eko)
 - `a3fe74f <https://github.com/symfony/symfony-docs/commit/a3fe74f4fad9f691dc570fb9234acd15bd6ccfdc>`_ #3993 [Console] Fix Console component getHelperSet()->get() to getHelper() (eko)
 - `a41af7e <https://github.com/symfony/symfony-docs/commit/a41af7e0f4a10cf7a6230598fd955dab2559935e>`_ #3880 document the mysterious abc part of the header (greg0ire)
 - `90773b0 <https://github.com/symfony/symfony-docs/commit/90773b03425388542d1b0face5368eb4c47ce3b8>`_ #3990 Move the section about collect: false to the cookbook entry (weaverryan)

contributing/code/bugs.rst

@@ -25,6 +25,10 @@ If your problem definitely looks like a bug, report it using the official bug
 * Describe the steps needed to reproduce the bug with short code examples
   (providing a unit test that illustrates the bug is best);
 
+* If the bug you experienced affects more than one layer, providing a simple
+  failing unit test may not be sufficient. In this case, please fork the
+  `Symfony Standard Edition`_ and reproduce your issue on a new branch;
+
 * Give as much detail as possible about your environment (OS, PHP version,
   Symfony version, enabled extensions, ...);
 
@@ -35,3 +39,4 @@ If your problem definitely looks like a bug, report it using the official bug
 .. _forum: http://forum.symfony-project.org/
 .. _IRC channel: irc://irc.freenode.net/symfony
 .. _tracker: https://github.com/symfony/symfony/issues
+.. _Symfony Standard Edition: https://github.com/symfony/symfony-standard/

contributing/community/releases.rst

@@ -86,29 +86,31 @@ Below is the schedule for the first few versions that use this release model:
 
 This results in very predictable dates and maintenance periods:
 
-+---------+---------+---------------------+-------------+
-| Version | Release | End of Maintenance  | End of Life |
-+=========+=========+=====================+=============+
-| 2.0     | 07/2011 | 03/2013 (20 months) | 09/2013     |
-+---------+---------+---------------------+-------------+
-| 2.1     | 09/2012 | 05/2013 (9 months)  | 11/2013     |
-+---------+---------+---------------------+-------------+
-| 2.2     | 03/2013 | 11/2013 (8 months)  | 05/2014     |
-+---------+---------+---------------------+-------------+
-| **2.3** | 05/2013 | 05/2016 (36 months) | 05/2017     |
-+---------+---------+---------------------+-------------+
-| 2.4     | 11/2013 | 07/2014 (8 months)  | 01/2015     |
-+---------+---------+---------------------+-------------+
-| 2.5     | 05/2014 | 01/2015 (8 months)  | 07/2015     |
-+---------+---------+---------------------+-------------+
-| 2.6     | 11/2014 | 07/2015 (8 months)  | 01/2016     |
-+---------+---------+---------------------+-------------+
-| **2.7** | 05/2015 | 05/2018 (36 months) | 05/2019     |
-+---------+---------+---------------------+-------------+
-| 2.8     | 11/2015 | 07/2016 (8 months)  | 01/2017     |
-+---------+---------+---------------------+-------------+
-| ...     | ...     | ...                 | ...         |
-+---------+---------+---------------------+-------------+
++---------+---------+--------------------------+-------------+
+| Version | Release | End of Maintenance       | End of Life |
++=========+=========+==========================+=============+
+| 2.0     | 07/2011 | 03/2013 (20 months)      | 09/2013     |
++---------+---------+--------------------------+-------------+
+| 2.1     | 09/2012 | 05/2013 (9 months)       | 11/2013     |
++---------+---------+--------------------------+-------------+
+| 2.2     | 03/2013 | 11/2013 (8 months)       | 05/2014     |
++---------+---------+--------------------------+-------------+
+| **2.3** | 05/2013 | 05/2016 (36 months)      | 05/2017     |
++---------+---------+--------------------------+-------------+
+| 2.4     | 11/2013 | 09/2014 (10 months [1]_) | 01/2015     |
++---------+---------+--------------------------+-------------+
+| 2.5     | 05/2014 | 01/2015 (8 months)       | 07/2015     |
++---------+---------+--------------------------+-------------+
+| 2.6     | 11/2014 | 07/2015 (8 months)       | 01/2016     |
++---------+---------+--------------------------+-------------+
+| **2.7** | 05/2015 | 05/2018 (36 months)      | 05/2019     |
++---------+---------+--------------------------+-------------+
+| 2.8     | 11/2015 | 07/2016 (8 months)       | 01/2017     |
++---------+---------+--------------------------+-------------+
+| ...     | ...     | ...                      | ...         |
++---------+---------+--------------------------+-------------+
+
+.. [1] Symfony 2.4 maintenance has been `extended to September 2014`_.
 
 .. tip::
 
@@ -179,4 +181,5 @@ version is published every two years and there is a year to upgrade.
 .. _Git repository: https://github.com/symfony/symfony
 .. _SensioLabs:     http://sensiolabs.com/
 .. _roadmap notification: http://symfony.com/roadmap
+.. _extended to September 2014: http://symfony.com/blog/extended-maintenance-for-symfony-2-4
 .. _timeline calculator: http://symfony.com/roadmap

cookbook/console/sending_emails.rst

@@ -85,6 +85,10 @@ from the ``router`` service and override its settings::
 Using Memory Spooling
 ---------------------
 
+.. versionadded: 2.3
+    When using Symfony 2.3+ and SwiftmailerBundle 2.3.5+, the memory spool is now
+    handled automatically in the CLI and the code below is not necessary anymore.
+
 Sending emails in a console command works the same way as described in the
 :doc:`/cookbook/email/email` cookbook except if memory spooling is used.
 

cookbook/security/api_key_authentication.rst

@@ -232,7 +232,7 @@ you can use to create an error ``Response``.
 
     class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface, AuthenticationFailureHandlerInterface
     {
-        //...
+        // ...
 
         public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
         {
@@ -427,6 +427,51 @@ configuration or set it to ``false``:
             ),
         ));
 
+Even though the token is being stored in the session, the credentials - in this
+case the API key (i.e. ``$token->getCredentials()``) - are not stored in the session
+for security reasons. To take advantage of the session, update ``ApiKeyAuthenticator``
+to see if the stored token has a valid User object that can be used::
+
+    // src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php
+    // ...
+
+    class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface
+    {
+        // ...
+        public function authenticateToken(TokenInterface $token, UserProviderInterface $userProvider, $providerKey)
+        {
+            $apiKey = $token->getCredentials();
+            $username = $this->userProvider->getUsernameForApiKey($apiKey);
+
+            // User is the Entity which represents your user
+            $user = $token->getUser();
+            if ($user instanceof User) {
+                return new PreAuthenticatedToken(
+                    $user,
+                    $apiKey,
+                    $providerKey,
+                    $user->getRoles()
+                );
+            }
+
+            if (!$username) {
+                throw new AuthenticationException(
+                    sprintf('API Key "%s" does not exist.', $apiKey)
+                );
+            }
+
+            $user = $this->userProvider->loadUserByUsername($username);
+
+            return new PreAuthenticatedToken(
+                $user,
+                $apiKey,
+                $providerKey,
+                $user->getRoles()
+            );
+        }
+        // ...
+    }
+
 Storing authentication information in the session works like this:
 
 #. At the end of each request, Symfony serializes the token object (returned

images/release-process.jpg

@@ -115,6 +115,16 @@ Overridden Options
 ------------------
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 compound
 ~~~~~~~~

reference/forms/types/choice.rst

@@ -374,6 +374,12 @@ error_bubbling
 .. include:: /reference/forms/types/options/by_reference.rst.inc
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/collection.rst

@@ -76,6 +76,16 @@ These options inherit from the :doc:`choice </reference/forms/types/choice>` typ
 These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc
 

reference/forms/types/country.rst

@@ -66,6 +66,16 @@ These options inherit from the :doc:`choice</reference/forms/types/choice>` type
 These options inherit from the :doc:`form</reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The actual default value of this option depends on other field options:
+
+* If ``multiple`` is ``false`` and ``expanded`` is ``false``, then ``''``
+  (empty string);
+* Otherwise ``array()`` (empty array).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
 
 .. include:: /reference/forms/types/options/required.rst.inc