Merge branch '3.2'

xabbuh · xabbuh · commit c7af8cf55403 · 2017-03-04T11:09:30.000+01:00
* 3.2: (24 commits) Minor rewords Update session_configuration.rst [#7522] minor wording improvement [#7513] fix line length Update 'ide' example in framework.rst [#7219] move versionadded in front of description Improved the image for Doctrine + Web Debug Toolbar [Serializer] Docs for the PropertyInfo integration Finished this PR section chronology in comment Removed the example about Redis Update cache.rst Update bundles/configuration.rst Fix typos Removed tip that was meant for the 2.x versions fix usage of the session flag bag API Add caution related to deprecate mail transport Use https URLs when possible [Requirements] Clarify what are JSON and ctype Proposed a minor reword ...
diff --git a/_images/doctrine/doctrine_web_debug_toolbar.png b/_images/doctrine/doctrine_web_debug_toolbar.png
diff --git a/_images/doctrine/web_debug_toolbar.png b/_images/doctrine/web_debug_toolbar.png
diff --git a/bundles/configuration.rst b/bundles/configuration.rst
@@ -83,7 +83,7 @@ bundle configuration would look like:
         <?xml version="1.0" ?>
 
         <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:acme-social="http://example.org/dic/schema/acme_social"
+            xmlns:acme-social="http://example.org/schema/dic/acme_social"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
 
diff --git a/components/cache.rst b/components/cache.rst
@@ -143,7 +143,7 @@ concepts:
 **Adapter**
     It implements the actual caching mechanism to store the information in the
     filesystem, in a database, etc. The component provides several ready to use
-    adapters for common caching backends (Redis, APCu, etc.)
+    adapters for common caching backends (Redis, APCu, Doctrine, PDO, etc.)
 
 Basic Usage (PSR-6)
 -------------------
diff --git a/components/cache/cache_invalidation.rst b/components/cache/cache_invalidation.rst
@@ -7,7 +7,7 @@ Cache Invalidation
 
 Cache invalidation is the process of removing all cached items related to a
 change in the state of your model. The most basic kind of invalidation is direct
-items deletion. But when the state of a primary resource has spread accross
+items deletion. But when the state of a primary resource has spread across
 several cached items, keeping them in sync can be difficult.
 
 The Symfony Cache component provides two mechanisms to help solving this problem:
diff --git a/components/config/caching.rst b/components/config/caching.rst
@@ -38,8 +38,8 @@ should be regenerated::
         $resources = array();
 
         foreach ($yamlUserFiles as $yamlUserFile) {
-            // see the previous article "Loading resources" to
-            // see where $delegatingLoader comes from
+            // see the article "Loading resources" to
+            // know where $delegatingLoader comes from
             $delegatingLoader->load($yamlUserFile);
             $resources[] = new FileResource($yamlUserFile);
         }
diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst
@@ -139,6 +139,20 @@ the ``php.ini`` directive ``session.gc_maxlifetime``. The meaning in this contex
 that any stored session that was saved more than ``gc_maxlifetime`` ago should be
 deleted. This allows one to expire records based on idle time.
 
+However, some operating systems do their own session handling and set the
+``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
+collection. That's why Symfony now overwrites this value to ``1``.
+
+If you wish to use the original value set in your ``php.ini``, add the following
+configuration:
+
+.. code-block:: yaml
+
+    # config.yml
+    framework:
+        session:
+            gc_probability: null
+
 You can configure these settings by passing ``gc_probability``, ``gc_divisor``
 and ``gc_maxlifetime`` in an array to the constructor of
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\NativeSessionStorage`
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -821,6 +821,74 @@ you indicate that you're expecting an array instead of a single object.
     $data = ...; // The serialized data from the previous example
     $persons = $serializer->deserialize($data, 'Acme\Person[]', 'json');
 
+Recursive Denormalization and Type Safety
+-----------------------------------------
+
+The Serializer Component can use the :doc:`PropertyInfo Component </components/property_info>` to denormalize
+complex types (objects). The type of the class' property will be guessed using the provided
+extractor and used to recursively denormalize the inner data.
+
+When using the Symfony Standard Edition, all normalizers are automatically configured to use the registered extractors.
+When using the component standalone, an implementation of :class:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface`,
+(usually an instance of :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`) must be passed as the 4th
+parameter of the ``ObjectNormalizer``::
+
+    use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
+    use Symfony\Component\Serializer\Serializer;
+    use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+    use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+
+    namespace Acme;
+
+    class ObjectOuter
+    {
+        private $inner;
+        private $date;
+
+        public function getInner()
+        {
+            return $this->inner;
+        }
+
+        public function setInner(ObjectInner $inner)
+        {
+            $this->inner = $inner;
+        }
+
+        public function setDate(\DateTimeInterface $date)
+        {
+            $this->date = $date;
+        }
+
+        public function getDate()
+        {
+            return $this->date;
+        }
+    }
+
+    class ObjectInner
+    {
+        public $foo;
+        public $bar;
+    }
+
+    $normalizer = new ObjectNormalizer(null, null, null, new ReflectionExtractor()); //
+    $serializer = new Serializer(array(new DateTimeNormalizer(), $normalizer));
+
+    $obj = $serializer->denormalize(
+        array('inner' => array('foo' => 'foo', 'bar' => 'bar'), 'date' => '1988/01/21'),
+         'Acme\ObjectOuter'
+    );
+
+    dump($obj->getInner()->foo); // 'foo'
+    dump($obj->getInner()->bar); // 'bar'
+    dump($obj->getDate()->format('Y-m-d')); // '1988-01-21'
+
+When a ``PropertyTypeExtractor`` is available, the normalizer will also check that the data to denormalize
+matches the type of the property (even for primitive types). For instance, if a ``string`` is provided, but
+the type of the property is ``int``, an :class:`Symfony\\Component\\Serializer\\Exception\\UnexpectedValueException`
+will be thrown.
+
 Learn more
 ----------
 
diff --git a/controller.rst b/controller.rst
@@ -436,14 +436,14 @@ read any flash messages from the session:
         <!-- app/Resources/views/base.html.php -->
 
         // you can read and display just one flash message type...
-        <?php foreach ($view['session']->getFlash('notice') as $message): ?>
+        <?php foreach ($view['session']->getFlashBag()->get('notice') as $message): ?>
             <div class="flash-notice">
                 <?php echo $message ?>
             </div>
         <?php endforeach ?>
 
         // ...or you can read and display every flash message available
-        <?php foreach ($view['session']->getFlashes() as $type => $flash_messages): ?>
+        <?php foreach ($view['session']->getFlashBag()->all() as $type => $flash_messages): ?>
             <?php foreach ($flash_messages as $flash_message): ?>
                 <div class="flash-<?php echo $type ?>">
                     <?php echo $message ?>
diff --git a/controller/service.rst b/controller/service.rst
@@ -336,12 +336,6 @@ controller:
 
         return new StreamedResponse($callback);
 
-.. tip::
-
-    ``getRequest()`` has been deprecated. Instead, have an argument to your
-    controller action method called ``Request $request``. The order of the
-    parameters is not important, but the typehint must be provided.
-
 .. _`Controller class source code`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php
 .. _`base Controller class`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php
 .. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/routing.html#controller-as-service
diff --git a/doctrine.rst b/doctrine.rst
@@ -707,19 +707,17 @@ to easily fetch objects based on multiple conditions::
 
 .. tip::
 
-    When you render any page, you can see how many queries were made in the
-    bottom right corner of the web debug toolbar.
+    When rendering a page requires to make some database calls, the web debug
+    toolbar at the bottom of the page displays the number of queries and the
+    time it took to execute them:
 
-    .. image:: /_images/doctrine/web_debug_toolbar.png
+    .. image:: /_images/doctrine/doctrine_web_debug_toolbar.png
        :align: center
-       :scale: 50
-       :width: 350
+       :class: with-browser
 
-    If you click the icon, the profiler will open, showing you the exact
-    queries that were made.
-
-    The icon will turn yellow if there were more than 50 queries on the
-    page. This could indicate that something is not correct.
+    If the number of database queries is too high, the icon will turn yellow to
+    indicate that something may not be correct. Click on the icon to open the
+    Symfony Profiler and see the exact queries that were executed.
 
 Updating an Object
 ~~~~~~~~~~~~~~~~~~
diff --git a/email.rst b/email.rst
@@ -86,6 +86,12 @@ The following configuration attributes are available:
 * ``delivery_addresses`` (an array of email addresses where to send ALL emails)
 * ``disable_delivery`` (set to true to disable delivery completely)
 
+.. caution::
+
+    Starting from SwiftMailer 5.4.5, the ``mail`` transport is deprecated
+    and will be removed in version 6. Consider using another transport like
+    ``smtp``, ``sendmail`` or ``gmail``.
+
 Sending Emails
 --------------
 
diff --git a/logging.rst b/logging.rst
@@ -308,6 +308,15 @@ option of your handler to ``rotating_file``:
             ),
         ));
 
+Using a Logger inside a Service
+-------------------------------
+
+To use a logger in your own services, add the ``@logger`` service as an argument
+of those services. If you want to use a pre-configured logger which uses a
+specific channel (``app`` by default), use the ``monolog.logger`` tag  with the
+``channel`` property as explained in the
+:ref:`Dependency Injection reference <dic_tags-monolog>`.
+
 Adding extra Data to each Log (e.g. a unique request token)
 -----------------------------------------------------------
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -216,8 +216,12 @@ ide
 Symfony turns file paths seen in variable dumps and exception messages into
 links that open those files right inside your browser. If you prefer to open
 those files in your favorite IDE or text editor, set this option to any of the
-following values: ``phpstorm`` (requires `PhpStormProtocol`_), ``sublime``,
-``textmate``, ``macvim`` and ``emacs``.
+following values: ``phpstorm``, ``sublime``, ``textmate``, ``macvim`` and ``emacs``.
+
+.. note::
+
+    The ``phpstorm`` option is supported natively by PhpStorm on MacOS,
+    Windows requires `PhpStormProtocol`_ and Linux requires `phpstorm-url-handler`_.
 
 If you use another editor, the expected configuration value is a URL template
 that contains an ``%f`` placeholder where the file path is expected and ``%l``
@@ -230,7 +234,7 @@ doubling them to prevent Symfony from interpreting them as container parameters)
 
         # app/config/config.yml
         framework:
-            ide: 'phpstorm://open?file=%%f&line=%%l'
+            ide: 'myide://open?url=file://%%f&line=%%l'
 
     .. code-block:: xml
 
@@ -242,14 +246,14 @@ doubling them to prevent Symfony from interpreting them as container parameters)
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
-            <framework:config ide="phpstorm://open?file=%%f&line=%%l" />
+            <framework:config ide="myide://open?url=file://%%f&line=%%l" />
         </container>
 
     .. code-block:: php
 
         // app/config/config.php
         $container->loadFromExtension('framework', array(
-            'ide' => 'phpstorm://open?file=%%f&line=%%l',
+            'ide' => 'myide://open?url=file://%%f&line=%%l',
         ));
 
 Since every developer uses a different IDE, the recommended way to enable this
@@ -1670,4 +1674,5 @@ Full Default Configuration
 .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html
 .. _`egulias/email-validator`: https://github.com/egulias/EmailValidator
 .. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol
+.. _`phpstorm-url-handler`: https://github.com/sanduhrs/phpstorm-url-handler
 .. _`blue/green deployment`: http://martinfowler.com/bliki/BlueGreenDeployment.html
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -184,6 +184,27 @@ The ``choice_loader`` can be used to only partially load the choices in cases wh
 a fully-loaded list is not necessary. This is only needed in advanced cases and
 would replace the ``choices`` option.
 
+.. versionadded:: 3.2
+    The :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\CallbackChoiceLoader`
+    was introduced in Symfony 3.2.
+
+You can use an instance of :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\CallbackChoiceLoader` 
+if you want to take advantage of lazy loading::
+
+    use Symfony\Component\Form\ChoiceList\Loader\CallbackChoiceLoader;
+    use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
+    // ...
+
+    $builder->add('constants', ChoiceType::class, array(
+        'choice_loader' => new CallbackChoiceLoader(function() {
+            return StaticClass::getConstants();
+        },
+    ));
+
+This will cause the call of ``StaticClass::getConstants()`` to not happen if the
+request is redirected and if there is no pre set or submitted data. Otherwise
+the choice options would need to be resolved thus triggering the callback.
+
 .. include:: /reference/forms/types/options/choice_name.rst.inc
 
 .. include:: /reference/forms/types/options/choice_translation_domain.rst.inc
diff --git a/reference/requirements.rst b/reference/requirements.rst
@@ -22,8 +22,8 @@ Required
 --------
 
 * PHP needs to be a minimum version of PHP 5.5.9
-* JSON needs to be enabled
-* ctype needs to be enabled
+* `JSON extension`_ needs to be enabled
+* `ctype extension`_ needs to be enabled
 * Your ``php.ini`` needs to have the ``date.timezone`` setting
 
 Optional
@@ -50,3 +50,6 @@ Doctrine
 If you want to use Doctrine, you will need to have PDO installed. Additionally,
 you need to have the PDO driver installed for the database server you want
 to use.
+
+.. _`JSON extension`: https://php.net/manual/book.json.php
+.. _`ctype extension`: https://php.net/manual/book.ctype.php
diff --git a/workflow.rst b/workflow.rst
@@ -7,7 +7,7 @@ a user submits a series of different forms to complete a task. Such processes ar
 best kept away from your models and should be defined in configuration.
 
 A **definition** of a workflow consist of places and actions to get from one
-place to another. The actions are called **transistions**. A workflow does also
+place to another. The actions are called **transitions**. A workflow does also
 need to know each object's position in the workflow. That **marking store** writes
 to a property of the object to remember the current place.
 
