symfony · andrerom · Oct 20, 2014 · Jun 19, 2015 · Jun 19, 2015 · Jun 19, 2015
diff --git a/changelog.rst b/changelog.rst
@@ -20,13 +20,15 @@ New Documentation
 ~~~~~~~~~~~~~~~~~
 
 * `#5423 <https://github.com/symfony/symfony-docs/pull/5423>`_ [Security] add & update doc entries on AbstractVoter implementation (Inoryy, javiereguiluz)
+* `#5409 <https://github.com/symfony/symfony-docs/pull/5409>`_ [Reference] document new Doctrine APC cache service (xabbuh)
 * `#5401 <https://github.com/symfony/symfony-docs/pull/5401>`_ Added some more docs about the remember me feature (WouterJ)
 * `#5384 <https://github.com/symfony/symfony-docs/pull/5384>`_ Added information about the new date handling in the comparison constraints and Range (webmozart, javiereguiluz)
 * `#5382 <https://github.com/symfony/symfony-docs/pull/5382>`_ Added support for standard Forwarded header (tony-co, javiereguiluz)
 * `#5361 <https://github.com/symfony/symfony-docs/pull/5361>`_ Document security.switch_user event (Rvanlaak)
 * `#5332 <https://github.com/symfony/symfony-docs/pull/5332>`_ [Serializer] ObjectNormalizer, object_to_populate doc. Minor enhancements. (dunglas)
 * `#5335 <https://github.com/symfony/symfony-docs/pull/5335>`_ [Serializer] Updated the cookbook. (dunglas)
 * `#5313 <https://github.com/symfony/symfony-docs/pull/5313>`_ Documented the overridden form options (javiereguiluz)
+* `#5360 <https://github.com/symfony/symfony-docs/pull/5360>`_ [Serializer] Array Denormalization (derrabus)
 * `#5307 <https://github.com/symfony/symfony-docs/pull/5307>`_ Update data_transformers.rst (zebba)
 * `#5186 <https://github.com/symfony/symfony-docs/pull/5186>`_ Added a new article about using/installing unstable Symfony versions (javiereguiluz)
 * `#5166 <https://github.com/symfony/symfony-docs/pull/5166>`_ Proposed a new article about using pure PHP libraries with Assetic (javiereguiluz)
@@ -42,6 +44,7 @@ New Documentation
 * `#5355 <https://github.com/symfony/symfony-docs/pull/5355>`_ Added a mention to the Symfony Demo application (javiereguiluz)
 * `#5331 <https://github.com/symfony/symfony-docs/pull/5331>`_ [PSR-7] Bridge documentation (dunglas)
 * `#5373 <https://github.com/symfony/symfony-docs/pull/5373>`_ Added mentions to some popular (and useful) Symfony bundles (javiereguiluz)
+* `#4354 <https://github.com/symfony/symfony-docs/pull/4354>`_ [WCM] Added depreciation note for the cascade_validation constraint (peterrehm)
 
 Fixed Documentation
 ~~~~~~~~~~~~~~~~~~~
@@ -88,6 +91,7 @@ Minor Documentation Changes
 * `#5381 <https://github.com/symfony/symfony-docs/pull/5381>`_ remove Yoda condition (greg0ire)
 * `#5452 <https://github.com/symfony/symfony-docs/pull/5452>`_ [#5388] change echo and print in examples (snoek09)
 * `#5451 <https://github.com/symfony/symfony-docs/pull/5451>`_ [#5388] change echo and print in examples (snoek09)
+* `#3782 <https://github.com/symfony/symfony-docs/pull/3782>`_ [Form] Deprecate read_only option (snoob)
 * `#5432 <https://github.com/symfony/symfony-docs/pull/5432>`_ removed squashing stuff. fixes #5368 (OskarStark)
 * `#5383 <https://github.com/symfony/symfony-docs/pull/5383>`_ Reword a paragraph about service configurations (richardudovich)
 * `#5389 <https://github.com/symfony/symfony-docs/pull/5389>`_ Updates to security.rst (HexTitan)

diff --git a/components/serializer.rst b/components/serializer.rst
@@ -632,6 +632,55 @@ having unique identifiers::
     var_dump($serializer->serialize($org, 'json'));
     // {"name":"Les-Tilleuls.coop","members":[{"name":"K\u00e9vin", organization: "Les-Tilleuls.coop"}]}
 
+Handling Arrays
+---------------
+
+The Serializer component is capable of handling arrays of objects as well.
+Serializing arrays works just like serializing a single object::
+
+    use Acme\Person;
+
+    $person1 = new Person();
+    $person1->setName('foo');
+    $person1->setAge(99);
+    $person1->setSportsman(false);
+
+    $person2 = new Person();
+    $person2->setName('bar');
+    $person2->setAge(33);
+    $person2->setSportsman(true);
+
+    $persons = array($person1, $person2);
+    $data = $serializer->serialize($persons, 'json');
+
+    // $data contains [{"name":"foo","age":99,"sportsman":false},{"name":"bar","age":33,"sportsman":true}]
+
+.. versionadded:: 2.8
+    The :class:`Symfony\\Component\\Serializer\\Normalizer\\ArrayDenormalizer`
+    class was introduced in 2.8. Prior to Symfony 2.8, only the serialization of
+    arrays is supported.
+
+If you want to deserialize such a structure, you need to add the
+:class:`Symfony\\Component\\Serializer\\Normalizer\\ArrayDenormalizer`
+to the set of normalizers. By appending ``[]`` to the type parameter of the
+:method:`Symfony\\Component\\Serializer\\Serializer::deserialize` method,
+you indicate that you're expecting an array instead of a single object.
+
+.. code-block:: php
+
+    use Symfony\Component\Serializer\Encoder\JsonEncoder;
+    use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
+    use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
+    use Symfony\Component\Serializer\Serializer;
+
+    $serializer = new Serializer(
+        array(new GetSetMethodNormalizer(), new ArrayDenormalizer()),
+        array(new JsonEncoder())
+    );
+
+    $data = ...; // The serialized data from the previous example
+    $persons = $serializer->deserialize($data, 'Acme\Person[]', 'json');
+
 .. seealso::
 
     A popular alternative to the Symfony Serializer Component is the third-party

diff --git a/cookbook/bundles/dependencies.rst b/cookbook/bundles/dependencies.rst
@@ -0,0 +1,97 @@
+.. index::
+   single: Bundle; Dependencies
+
+How to Use Bundle Dependencies to Load other Bundles
+====================================================
+
+.. versionadded:: 2.8
+    Support for bundle dependencies was introduced in Symfony 2.8.
+
+When working on your own bundle(s), you'll sometimes have the need to reuse
+other bundles, either by just requiring, overriding or inheriting from them.
+
+While Composer takes care about making sure these dependencies are loaded,
+you'll also need to enable these bundles in the kernel.
+
+If your bundle is meant to be reused, bundle dependencies will complicate
+your installation documentation. This makes installation and upgrading your
+bundle more tedious for your users.
+
+You can avoid this by specifying your dependencies. This will make sure that
+they are loaded in the kernel. It'll also make sure they are loaded *before*
+your own bundle, to make sure you can extend them.
+
+Additional use case for this is for distribution bundle use cases where one
+bundle is in fact bundling several others.
+
+Specifying dependencies
+-----------------------
+
+Dependencies are specified using a Fully Qualified Name for the bundle class in same
+format as PHP uses for ``get_class`` and for ``class`` constant introduced in PHP 5.5.
+
+This implies you can only specify bundles that does not take arguments in it's constructor.
+This is in-line with Symfony best practice and furthermore avoids same bundle being loaded
+several times.
+
+Specifying dependencies is accomplished by implementing the
+:class:`Symfony\\Component\\HttpKernel\\Bundle\\BundleDependenciesInterface`::
+
+    // src/CacheBundle/CacheBundle.php
+    namespace CacheBundle;
+
+    use Symfony\Component\HttpKernel\Bundle\Bundle;
+    use Symfony\Component\HttpKernel\Bundle\BundleDependenciesInterface;
+
+    class CacheBundle extends Bundle implements BundleDependenciesInterface
+    {
+        public function getBundleDependencies($environment, $debug)
+        {
+            return array('FOS\HttpCacheBundle\FOSHttpCacheBundle' => self::DEP_REQUIRED);
+        }
+    }
+
+.. tip::
+
+    If your bundle requires PHP 5.5 or higher, you can also take advantage of
+    the ``class`` constant::
+
+        use FOS\HttpCacheBundle\FOSHttpCacheBundle;
+
+        // ...
+        public function getBundleDependencies($environment, $debug)
+        {
+            return array(FOSHttpCacheBundle::class => self::DEP_REQUIRED);
+        }
+
+.. tip::
+
+    If your dependency is only to be loaded in ``dev`` or when debugging use the provided arguments::
+
+        use Egulias\SecurityDebugCommandBundle\EguliasSecurityDebugCommandBundle;
+
+        // ...
+        public function getBundleDependencies($environment, $debug)
+        {
+            if ($environment !== 'dev')
+                return array();
+
+            return array('Egulias\SecurityDebugCommandBundle\EguliasSecurityDebugCommandBundle' => self::DEP_REQUIRED);
+        }
+
+
+Specifying optional dependencies
+--------------------------------
+
+Specifying a optional dependency follows the same format but with a different constant::
+
+        // ...
+        public function getBundleDependencies($environment, $debug)
+        {
+            return array('Oneup\FlysystemBundle\OneupFlysystemBundle' => self::DEP_OPTIONAL);
+        }
+
+ .. tip::
+
+     Make sure to not use PHP's ``class`` constant in combination with optional dependencies as that effectively will
+     make PHP error when they are missing.
diff --git a/cookbook/bundles/index.rst b/cookbook/bundles/index.rst
@@ -7,6 +7,7 @@ Bundles
     installation
     best_practices
     inheritance
+    dependencies
     override
     remove
     extension

diff --git a/cookbook/console/console_command.rst b/cookbook/console/console_command.rst
@@ -82,6 +82,11 @@ for details.
 Getting Services from the Service Container
 -------------------------------------------
 
+.. caution::
+
+    The "container scopes" concept explained in this section has been deprecated
+    in Symfony 2.8 and it will be removed in Symfony 3.0.
+
 By using :class:`Symfony\\Bundle\\FrameworkBundle\\Command\\ContainerAwareCommand`
 as the base class for the command (instead of the more basic
 :class:`Symfony\\Component\\Console\\Command\\Command`), you have access to the

diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -12,6 +12,7 @@
   * :doc:`/cookbook/bundles/installation`
   * :doc:`/cookbook/bundles/best_practices`
   * :doc:`/cookbook/bundles/inheritance`
+  * :doc:`/cookbook/bundles/dependencies`
   * :doc:`/cookbook/bundles/override`
   * :doc:`/cookbook/bundles/remove`
   * :doc:`/cookbook/bundles/extension`

diff --git a/cookbook/service_container/scopes.rst b/cookbook/service_container/scopes.rst
@@ -4,6 +4,11 @@
 How to Work with Scopes
 =======================
 
+.. caution::
+
+    The "container scopes" concept explained in this article has been deprecated
+    in Symfony 2.8 and it will be removed in Symfony 3.0.
+
 This article is all about scopes, a somewhat advanced topic related to the
 :doc:`/book/service_container`. If you've ever gotten an error mentioning
 "scopes" when creating services, then this article is for you.

diff --git a/cookbook/web_server/built_in.rst b/cookbook/web_server/built_in.rst
@@ -39,6 +39,18 @@ can change the socket passing an IP address and a port as a command-line argumen
 
     $ php app/console server:run 192.168.0.1:8080
 
+.. note::
+
+    You can use the ``--force`` option to force the web server start
+    if the process wasn't correctly stopped (without using the ``server:stop`` command).
+
+    .. code-block:: bash
+
+        $ php app/console server:start --force
+
+    .. versionadded:: 2.8
+        The ``--force`` option was introduced in Symfony 2.8.
+
 .. note::
 
     You can use the ``server:status`` command to check if a web server is

diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -1374,6 +1374,13 @@ cache
 The service that is used to persist class metadata in a cache. The service
 has to implement the :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface`.
 
+.. versionadded:: 2.8
+    The ``validator.mapping.cache.doctrine.apc`` service was introduced in
+    Symfony 2.8.
+
+Set this option to ``validator.mapping.cache.doctrine.apc`` to use the APC
+cache provide from the Doctrine project.
+
 .. _reference-validation-enable_annotations:
 
 enable_annotations

diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst
@@ -358,8 +358,6 @@ done by using a public ``vars`` property on the
 +------------------------+-------------------------------------------------------------------------------------+
 | ``value``              | The value that will be used when rendering (commonly the ``value`` HTML attribute). |
 +------------------------+-------------------------------------------------------------------------------------+
-| ``read_only``          | If ``true``, ``readonly="readonly"`` is added to the field.                         |
-+------------------------+-------------------------------------------------------------------------------------+
 | ``disabled``           | If ``true``, ``disabled="disabled"`` is added to the field.                         |
 +------------------------+-------------------------------------------------------------------------------------+
 | ``required``           | If ``true``, a ``required`` attribute is added to the field to activate HTML5       |

diff --git a/reference/forms/types.rst b/reference/forms/types.rst
@@ -18,6 +18,7 @@ Form Types Reference
    types/percent
    types/search
    types/url
+   types/range
 
    types/choice
    types/entity

diff --git a/reference/forms/types/birthday.rst b/reference/forms/types/birthday.rst
@@ -41,7 +41,7 @@ option defaults to 120 years ago to the current year.
 |                      | - `invalid_message`_                                                          |
 |                      | - `invalid_message_parameters`_                                               |
 |                      | - `mapped`_                                                                   |
-|                      | - `read_only`_                                                                |
+|                      | - `read_only`_ (deprecated as of 2.8)                                         |
 +----------------------+-------------------------------------------------------------------------------+
 | Parent type          | :doc:`date </reference/forms/types/date>`                                     |
 +----------------------+-------------------------------------------------------------------------------+

diff --git a/reference/forms/types/checkbox.rst b/reference/forms/types/checkbox.rst
@@ -23,7 +23,7 @@ true, if the box is unchecked, the value will be set to false.
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                              |

diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -32,7 +32,7 @@ option.
 |             | - `label`_                                                                   |
 |             | - `label_attr`_                                                              |
 |             | - `mapped`_                                                                  |
-|             | - `read_only`_                                                               |
+|             | - `read_only`_ (deprecated as of 2.8)                                        |
 |             | - `required`_                                                                |
 +-------------+------------------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                                    |

diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst
@@ -42,7 +42,7 @@ you should just use the ``choice`` type directly.
 |             | - `label`_                                                            |
 |             | - `label_attr`_                                                       |
 |             | - `mapped`_                                                           |
-|             | - `read_only`_                                                        |
+|             | - `read_only`_ (deprecated as of 2.8)                                 |
 |             | - `required`_                                                         |
 +-------------+-----------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                         |

diff --git a/reference/forms/types/currency.rst b/reference/forms/types/currency.rst
@@ -35,7 +35,7 @@ you should just use the ``choice`` type directly.
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `mapped`_                                                            |
-|             | - `read_only`_                                                         |
+|             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                          |

diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst
@@ -42,7 +42,7 @@ day and year) or three select boxes (see the `widget`_ option).
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
 |                      | - `mapped`_                                                                 |
-|                      | - `read_only`_                                                              |
+|                      | - `read_only`_ (deprecated as of 2.8)                                       |
 +----------------------+-----------------------------------------------------------------------------+
 | Parent type          | :doc:`form </reference/forms/types/form>`                                   |
 +----------------------+-----------------------------------------------------------------------------+

diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst
@@ -45,7 +45,7 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array.
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
 |                      | - `mapped`_                                                                 |
-|                      | - `read_only`_                                                              |
+|                      | - `read_only`_ (deprecated as of 2.8)                                       |
 +----------------------+-----------------------------------------------------------------------------+
 | Parent type          | :doc:`form </reference/forms/types/form>`                                   |
 +----------------------+-----------------------------------------------------------------------------+

diff --git a/reference/forms/types/email.rst b/reference/forms/types/email.rst
@@ -19,7 +19,7 @@ The ``email`` field is a text field that is rendered using the HTML5
 |             | - `label_attr`_                                                     |
 |             | - `mapped`_                                                         |
 |             | - `max_length`_ (deprecated as of 2.5)                              |
-|             | - `read_only`_                                                      |
+|             | - `read_only`_ (deprecated as of 2.8)                               |
 |             | - `required`_                                                       |
 |             | - `trim`_                                                           |
 +-------------+---------------------------------------------------------------------+

diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst
@@ -39,7 +39,7 @@ objects from the database.
 |             | - `label`_                                                       |
 |             | - `label_attr`_                                                  |
 |             | - `mapped`_                                                      |
-|             | - `read_only`_                                                   |
+|             | - `read_only`_ (deprecated as of 2.8)                            |
 |             | - `required`_                                                    |
 +-------------+------------------------------------------------------------------+
 | Parent type | :doc:`choice </reference/forms/types/choice>`                    |