Merge branch '2.4'

book/http_cache.rst

@@ -526,11 +526,9 @@ the application whether or not the cached response is still valid. If the
 cache *is* still valid, your application should return a 304 status code
 and no content. This tells the cache that it's ok to return the cached response.
 
-Under this model, you mainly save bandwidth as the representation is not
-sent twice to the same client (a 304 response is sent instead). But if you
-design your application carefully, you might be able to get the bare minimum
-data needed to send a 304 response and save CPU also (see below for an implementation
-example).
+Under this model, you only save CPU if you're able to determine that the
+cached response is still valid by doing *less* work than generating the whole
+page again (see below for an implementation example).
 
 .. tip::
 
@@ -578,10 +576,10 @@ automatically sets the ``Response`` status code to 304.
 
 .. note::
 
-    The ``If-None-Match`` request header equals the ``ETag`` header of the
-    last response sent to the client for the particular resource. This is
-    how the client and server communicate with each other and decide whether
-    or not the resource has been updated since it was cached.
+    The cache sets the ``If-None-Match`` header on the request to the ``ETag``
+    of the original cached response before sending the request back to the
+    app. This is how the cache and server communicate with each other and
+    decide whether or not the resource has been updated since it was cached.
 
 This algorithm is simple enough and very generic, but you need to create the
 whole ``Response`` before being able to compute the ETag, which is sub-optimal.
@@ -646,10 +644,10 @@ the ``Response`` will be set to a 304 status code.
 
 .. note::
 
-    The ``If-Modified-Since`` request header equals the ``Last-Modified``
-    header of the last response sent to the client for the particular resource.
-    This is how the client and server communicate with each other and decide
-    whether or not the resource has been updated since it was cached.
+    The cache sets the ``If-Modified-Since`` header on the request to the ``Last-Modified``
+    of the original cached response before sending the request back to the
+    app. This is how the cache and server communicate with each other and
+    decide whether or not the resource has been updated since it was cached.
 
 .. index::
    single: Cache; Conditional get

book/internals.rst

@@ -172,7 +172,10 @@ Event):
 #. Listeners of the ``kernel.response`` event can manipulate the ``Response``
    (content and headers);
 
-#. The Response is returned.
+#. The Response is returned;
+
+#. Listeners of the ``kernel.terminate`` event can perform tasks after the
+   Response has been served.
 
 If an Exception is thrown during processing, the ``kernel.exception`` is
 notified and listeners are given a chance to convert the Exception to a
@@ -367,6 +370,8 @@ The FrameworkBundle registers several listeners:
 ``kernel.terminate`` Event
 ..........................
 
+*Event Class*: :class:`Symfony\\Component\\HttpKernel\\Event\\PostResponseEvent`
+
 The purpose of this event is to perform "heavier" tasks after the response
 was already served to the client.
 
@@ -647,7 +652,7 @@ If you enable the web profiler, you also need to mount the profiler routes:
 
 As the profiler adds some overhead, you might want to enable it only under
 certain circumstances in the production environment. The ``only_exceptions``
-settings limits profiling to 500 pages, but what if you want to get
+settings limits profiling to exceptions, but what if you want to get
 information when the client IP comes from a specific address, or for a limited
 portion of the website? You can use a Profiler Matcher, learn more about that
 in ":doc:`/cookbook/profiler/matchers`".

components/dependency_injection/parameters.rst

@@ -155,7 +155,6 @@ making the class of a service a parameter:
             <service id="mailer" class="%mailer.class%">
                 <argument>%mailer.transport%</argument>
             </service>
-
         </services>
 
     .. code-block:: php
@@ -344,6 +343,15 @@ Start the string with  ``@`` or ``@?`` to reference a service in YAML.
 * ``@?mailer`` references the ``mailer`` service. If the service does not
   exist, it will be ignored;
 
+.. code-block:: yaml
+
+    parameters:
+        # if 'my_mailer' service isn't defined, an exception will be raised
+        foo: @my_mailer
+
+        # if 'my_logger' service isn't defined, 'bar' will be null
+        bar: @?my_logger
+
 .. tip::
 
     Use ``@@`` to escape the ``@`` symbol in YAML. ``@@mailer`` will be
@@ -359,6 +367,16 @@ is thrown. Valid values for ``on-invalid`` are ``null`` (uses ``null`` in place
 of the missing service) or ``ignored`` (very similar, except if used on a
 method call, the method call is removed).
 
+.. code-block:: xml
+
+    <parameters>
+        <!-- if 'my_mailer' service isn't defined, an exception will be raised -->
+        <parameter key="foo" type="service" id="my_mailer" />
+
+        <!-- if 'my_logger' service isn't defined, 'bar' will be null -->
+        <parameter key="bar" type="service" id="my_logger" on-invalid="null" />
+    </parameters>
+
 PHP
 ~~~
 
@@ -367,3 +385,15 @@ In PHP, you can use the
 a service. The invalid behavior is configured using the second constructor
 argument and constants from
 :class:`Symfony\\Component\\DependencyInjection\\ContainerInterface`.
+
+.. code-block:: php
+
+    use Symfony\Component\DependencyInjection\Reference;
+
+    // if 'my_mailer' service isn't defined, an exception will be raised
+    $container->setParameter('foo', new Reference('my_mailer'));
+
+    // if 'my_logger' service isn't defined, 'bar' will be null
+    $container->setParameter('bar', new Reference('my_logger',
+        ContainerInterface::NULL_ON_INVALID_REFERENCE
+    ));

components/http_foundation/session_configuration.rst

@@ -13,16 +13,16 @@ Save Handlers
 ~~~~~~~~~~~~~
 
 The PHP session workflow has 6 possible operations that may occur. The normal
-session follows `open`, `read`, `write` and `close`, with the possibility of
-`destroy` and `gc` (garbage collection which will expire any old sessions: `gc`
-is called randomly according to PHP's configuration and if called, it is invoked
-after the `open` operation). You can read more about this at
+session follows ``open``, ``read``, ``write`` and ``close``, with the possibility
+of ``destroy`` and ``gc`` (garbage collection which will expire any old sessions:
+``gc`` is called randomly according to PHP's configuration and if called, it is
+invoked after the ``open`` operation). You can read more about this at
 `php.net/session.customhandler`_
 
 Native PHP Save Handlers
 ------------------------
 
-So-called 'native' handlers, are save handlers which are either compiled into
+So-called native handlers, are save handlers which are either compiled into
 PHP or provided by PHP extensions, such as PHP-Sqlite, PHP-Memcached and so on.
 
 All native save handlers are internal to PHP and as such, have no public facing API.
@@ -50,14 +50,16 @@ Example usage::
 
 .. note::
 
-    With the exception of the ``files`` handler which is built into PHP and always available,
-    the availability of the other handlers depends on those PHP extensions being active at runtime.
+    With the exception of the ``files`` handler which is built into PHP and
+    always available, the availability of the other handlers depends on those
+    PHP extensions being active at runtime.
 
 .. note::
 
-    Native save handlers provide a quick solution to session storage, however, in complex systems
-    where you need more control, custom save handlers may provide more freedom and flexibility.
-    Symfony2 provides several implementations which you may further customize as required.
+    Native save handlers provide a quick solution to session storage, however,
+    in complex systems where you need more control, custom save handlers may
+    provide more freedom and flexibility. Symfony2 provides several implementations
+    which you may further customize as required.
 
 Custom Save Handlers
 --------------------
@@ -183,14 +185,14 @@ session is started. The session can be destroyed as required. This method of
 processing can allow the expiry of sessions to be integrated into the user
 experience, for example, by displaying a message.
 
-Symfony2 records some basic meta-data about each session to give you complete
+Symfony2 records some basic metadata about each session to give you complete
 freedom in this area.
 
-Session meta-data
-~~~~~~~~~~~~~~~~~
+Session metadata
+~~~~~~~~~~~~~~~~
 
-Sessions are decorated with some basic meta-data to enable fine control over the
-security settings. The session object has a getter for the meta-data,
+Sessions are decorated with some basic metadata to enable fine control over the
+security settings. The session object has a getter for the metadata,
 :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag` which
 exposes an instance of :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag`::
 
@@ -199,7 +201,7 @@ exposes an instance of :class:`Symfony\\Component\\HttpFoundation\\Session\\Stor
 
 Both methods return a Unix timestamp (relative to the server).
 
-This meta-data can be used to explicitly expire a session on access, e.g.::
+This metadata can be used to explicitly expire a session on access, e.g.::
 
     $session->start();
     if (time() - $session->getMetadataBag()->getLastUsed() > $maxIdleTime) {
@@ -220,15 +222,15 @@ PHP 5.4 compatibility
 
 Since PHP 5.4.0, :phpclass:`SessionHandler` and :phpclass:`SessionHandlerInterface`
 are available. Symfony provides forward compatibility for the :phpclass:`SessionHandlerInterface`
-so it can be used under PHP 5.3. This greatly improves inter-operability with other
+so it can be used under PHP 5.3. This greatly improves interoperability with other
 libraries.
 
 :phpclass:`SessionHandler` is a special PHP internal class which exposes native save
 handlers to PHP user-space.
 
 In order to provide a solution for those using PHP 5.4, Symfony2 has a special
 class called :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeSessionHandler`
-which under PHP 5.4, extends from `\SessionHandler` and under PHP 5.3 is just a
+which under PHP 5.4, extends from ``\SessionHandler`` and under PHP 5.3 is just a
 empty base class. This provides some interesting opportunities to leverage
 PHP 5.4 functionality if it is available.
 
@@ -251,12 +253,12 @@ wrapped by one.
 
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeProxy`
 is used automatically under PHP 5.3 when internal PHP save handlers are specified
-using the `Native*SessionHandler` classes, while
+using the ``Native*SessionHandler`` classes, while
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\SessionHandlerProxy`
 will be used to wrap any custom save handlers, that implement :phpclass:`SessionHandlerInterface`.
 
 From PHP 5.4 and above, all session handlers implement :phpclass:`SessionHandlerInterface`
-including `Native*SessionHandler` classes which inherit from :phpclass:`SessionHandler`.
+including ``Native*SessionHandler`` classes which inherit from :phpclass:`SessionHandler`.
 
 The proxy mechanism allows you to get more deeply involved in session save handler
 classes. A proxy for example could be used to encrypt any session transaction

components/http_foundation/sessions.rst

@@ -121,7 +121,7 @@ an array. A few methods exist for "Bag" management:
   Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface`.
   This is just a shortcut for convenience.
 
-Session meta-data
+Session metadata
 
 * :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag`:
   Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag`
@@ -132,16 +132,16 @@ Session Data Management
 
 PHP's session management requires the use of the ``$_SESSION`` super-global,
 however, this interferes somewhat with code testability and encapsulation in a
-OOP paradigm. To help overcome this, Symfony2 uses 'session bags' linked to the
-session to encapsulate a specific dataset of 'attributes' or 'flash messages'.
+OOP paradigm. To help overcome this, Symfony2 uses *session bags* linked to the
+session to encapsulate a specific dataset of attributes or flash messages.
 
 This approach also mitigates namespace pollution within the ``$_SESSION``
 super-global because each bag stores all its data under a unique namespace.
 This allows Symfony2 to peacefully co-exist with other applications or libraries
 that might use the ``$_SESSION`` super-global and all data remains completely
 compatible with Symfony2's session management.
 
-Symfony2 provides 2 kinds of storage bags, with two separate implementations.
+Symfony2 provides two kinds of storage bags, with two separate implementations.
 Everything is written against interfaces so you may extend or create your own
 bag types if necessary.
 
@@ -172,11 +172,11 @@ and remember me login settings or other user based state information.
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\NamespacedAttributeBag`
   This implementation allows for attributes to be stored in a structured namespace.
 
-Any plain `key => value` storage system is limited in the extent to which
+Any plain key-value storage system is limited in the extent to which
 complex data can be stored since each key must be unique. You can achieve
 namespacing by introducing a naming convention to the keys so different parts of
-your application could operate without clashing. For example, `module1.foo` and
-`module2.foo`. However, sometimes this is not very practical when the attributes
+your application could operate without clashing. For example, ``module1.foo`` and
+``module2.foo``. However, sometimes this is not very practical when the attributes
 data is an array, for example a set of tokens. In this case, managing the array
 becomes a burden because you have to retrieve the array then process it and
 store it again::

components/options_resolver.rst

@@ -107,7 +107,8 @@ the ``OptionsResolver`` class::
 
         protected function configureOptions(OptionsResolverInterface $resolver)
         {
-            // ... configure the resolver, you will learn this in the sections below
+            // ... configure the resolver, you will learn this
+            // in the sections below
         }
     }
 
@@ -256,7 +257,9 @@ again. When using a closure as the new value it is passed 2 arguments:
         $resolver->setDefaults(array(
             'encryption' => 'tls', // simple overwrite
             'host' => function (Options $options, $previousValue) {
-                return 'localhost' == $previousValue ? '127.0.0.1' : $previousValue;
+                return 'localhost' == $previousValue
+                    ? '127.0.0.1'
+                    : $previousValue;
             },
         ));
     }

components/property_access/introduction.rst

@@ -192,7 +192,9 @@ enable this feature by using :class:`Symfony\\Component\\PropertyAccess\\Propert
         {
             $property = lcfirst(substr($name, 3));
             if ('get' === substr($name, 0, 3)) {
-                return isset($this->children[$property]) ? $this->children[$property] : null;
+                return isset($this->children[$property])
+                    ? $this->children[$property]
+                    : null;
             } elseif ('set' === substr($name, 0, 3)) {
                 $value = 1 == count($args) ? $args[0] : null;
                 $this->children[$property] = $value;
@@ -285,7 +287,9 @@ see `Enable other Features`_.
         {
             $property = lcfirst(substr($name, 3));
             if ('get' === substr($name, 0, 3)) {
-                return isset($this->children[$property]) ? $this->children[$property] : null;
+                return isset($this->children[$property])
+                    ? $this->children[$property]
+                    : null;
             } elseif ('set' === substr($name, 0, 3)) {
                 $value = 1 == count($args) ? $args[0] : null;
                 $this->children[$property] = $value;
@@ -303,7 +307,7 @@ see `Enable other Features`_.
 
     $accessor->setValue($person, 'wouter', array(...));
 
-    echo $person->getWouter() // array(...)
+    echo $person->getWouter(); // array(...)
 
 Mixing Objects and Arrays
 -------------------------

components/security/firewall.rst

@@ -12,14 +12,17 @@ certain action or resource of the application::
 
     use Symfony\Component\Security\Core\SecurityContext;
     use Symfony\Component\Security\Core\Exception\AccessDeniedException;
-    
+
     // instance of Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface
     $authenticationManager = ...;
 
     // instance of Symfony\Component\Security\Core\Authorization\AccessDecisionManagerInterface
     $accessDecisionManager = ...;
 
-    $securityContext = new SecurityContext($authenticationManager, $accessDecisionManager);
+    $securityContext = new SecurityContext(
+        $authenticationManager,
+        $accessDecisionManager
+    );
 
     // ... authenticate the user
 
@@ -71,7 +74,10 @@ with the event dispatcher that is used by the :class:`Symfony\\Component\\HttpKe
 
     $firewall = new Firewall($map, $dispatcher);
 
-    $dispatcher->addListener(KernelEvents::REQUEST, array($firewall, 'onKernelRequest');
+    $dispatcher->addListener(
+        KernelEvents::REQUEST,
+        array($firewall, 'onKernelRequest')
+    );
 
 The firewall is registered to listen to the ``kernel.request`` event that
 will be dispatched by the HttpKernel at the beginning of each request

components/serializer.rst

@@ -186,7 +186,7 @@ JMSSerializer
 
 A popular third-party library, `JMS serializer`_, provides a more
 sophisticated albeit more complex solution. This library includes the
-ability to configure how your objects should be serialize/deserialized via
+ability to configure how your objects should be serialized/deserialized via
 annotations (as well as YAML, XML and PHP), integration with the Doctrine ORM,
 and handling of other complex cases (e.g. circular references).
 

components/stopwatch.rst

@@ -64,13 +64,13 @@ call::
 In addition to periods, you can get other useful information from the event object.
 For example::
 
-    $event->getCategory();      // Returns the category the event was started in
-    $event->getOrigin();        // Returns the event start time in milliseconds
-    $event->ensureStopped();    // Stops all periods not already stopped
-    $event->getStartTime();     // Returns the start time of the very first period
-    $event->getEndTime();       // Returns the end time of the very last period
-    $event->getDuration();      // Returns the event duration, including all periods
-    $event->getMemory();        // Returns the max memory usage of all periods
+    $event->getCategory();   // Returns the category the event was started in
+    $event->getOrigin();     // Returns the event start time in milliseconds
+    $event->ensureStopped(); // Stops all periods not already stopped
+    $event->getStartTime();  // Returns the start time of the very first period
+    $event->getEndTime();    // Returns the end time of the very last period
+    $event->getDuration();   // Returns the event duration, including all periods
+    $event->getMemory();     // Returns the max memory usage of all periods
 
 Sections
 --------