Merge branch '3.1'

Author: wouterj

changelog.rst

@@ -13,6 +13,66 @@ documentation.
     Do you also want to participate in the Symfony Documentation? Take a look
     at the ":doc:`/contributing/documentation/overview`" article.
 
+June, 2016
+----------
+
+New Documentation
+~~~~~~~~~~~~~~~~~
+
+* `#6515 <https://github.com/symfony/symfony-docs/pull/6515>`_ Added the documentation for the Cache component (javiereguiluz)
+* `#6690 <https://github.com/symfony/symfony-docs/pull/6690>`_ Added an example for a different method of verbosity level usage. (smatyas)
+* `#6648 <https://github.com/symfony/symfony-docs/pull/6648>`_ Process: callbacks now allowed when output disabled (avindra)
+* `#6587 <https://github.com/symfony/symfony-docs/pull/6587>`_ Updating recommended email settings for monolog (jorgelbg)
+* `#6617 <https://github.com/symfony/symfony-docs/pull/6617>`_ [WSSE] - Using a PSR6 cache instead of file cache (Nyholm)
+* `#6438 <https://github.com/symfony/symfony-docs/pull/6438>`_ Added docs about ArgumentValueResolvers (iltar)
+
+Fixed Documentation
+~~~~~~~~~~~~~~~~~~~
+
+* `#6679 <https://github.com/symfony/symfony-docs/pull/6679>`_ Invalid PHP return statement (JohnnyEvo)
+* `#6675 <https://github.com/symfony/symfony-docs/pull/6675>`_ Update broken links to default VCL files (sgrodzicki)
+
+Minor Documentation Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* `#6597 <https://github.com/symfony/symfony-docs/pull/6597>`_ [Validator] Add shorter examples using the default option (alexmart)
+* `#6696 <https://github.com/symfony/symfony-docs/pull/6696>`_ Typo fix (jevgenijusr)
+* `#6693 <https://github.com/symfony/symfony-docs/pull/6693>`_ Add missing parameter (rodnaph)
+* `#6614 <https://github.com/symfony/symfony-docs/pull/6614>`_ Updated the CS rule about return null; and return; (javiereguiluz)
+* `#6680 <https://github.com/symfony/symfony-docs/pull/6680>`_ Fix ldap security examples (jvasseur)
+* `#6692 <https://github.com/symfony/symfony-docs/pull/6692>`_ Update date.rst - Fixes typo (fdarre)
+* `#6689 <https://github.com/symfony/symfony-docs/pull/6689>`_ Hard values for the driver option (iltar)
+* `#6685 <https://github.com/symfony/symfony-docs/pull/6685>`_ NullOutput should be passed to $command->run() (Ma27)
+* `#6676 <https://github.com/symfony/symfony-docs/pull/6676>`_ Removed 'html' from the component description (naroga)
+* `#6674 <https://github.com/symfony/symfony-docs/pull/6674>`_ CheckStyle in Voters cookbook (JakeFr)
+* `#6672 <https://github.com/symfony/symfony-docs/pull/6672>`_ [Book][Testing] remove Symfony core testing note (xabbuh)
+* `#6670 <https://github.com/symfony/symfony-docs/pull/6670>`_ Fix typo 'even' >> 'event' in event_listener.rst (kuusas)
+* `#6667 <https://github.com/symfony/symfony-docs/pull/6667>`_ [Contributing][Code] fix list item terminators (xabbuh)
+* `#6616 <https://github.com/symfony/symfony-docs/pull/6616>`_ Better explain the mandatory/convention location of some elements (rcousens, javiereguiluz)
+* `#6628 <https://github.com/symfony/symfony-docs/pull/6628>`_ Fix for #6625 (kix)
+* `#6668 <https://github.com/symfony/symfony-docs/pull/6668>`_ [Contributing][Code] remove PHPUnit requirement (xabbuh)
+* `#6654 <https://github.com/symfony/symfony-docs/pull/6654>`_ Update upload_file.rst (liubinas)
+* `#6650 <https://github.com/symfony/symfony-docs/pull/6650>`_ fix dumper default representation (Jamal Youssefi)
+* `#6652 <https://github.com/symfony/symfony-docs/pull/6652>`_ ``Finder::path()`` method matching directories and files (soyuka)
+* `#6662 <https://github.com/symfony/symfony-docs/pull/6662>`_ preg_match throw an warning (nicolae-stelian)
+* `#6651 <https://github.com/symfony/symfony-docs/pull/6651>`_ [#6438] some tweaks to the argument value resolver (xabbuh)
+* `#6658 <https://github.com/symfony/symfony-docs/pull/6658>`_ [Process] tweak a sentence (xabbuh)
+* `#6599 <https://github.com/symfony/symfony-docs/pull/6599>`_ Fixed null description of query_builder option (HeahDude)
+* `#6638 <https://github.com/symfony/symfony-docs/pull/6638>`_ swap terminate and exception event descriptions (xabbuh)
+* `#6615 <https://github.com/symfony/symfony-docs/pull/6615>`_ Minor grammar fix (aalaap)
+* `#6637 <https://github.com/symfony/symfony-docs/pull/6637>`_ Update security.rst (norbert-n)
+* `#6644 <https://github.com/symfony/symfony-docs/pull/6644>`_ [Console] Fix wrong quotes in QuestionHelper::setInputStream() (chalasr)
+* `#6645 <https://github.com/symfony/symfony-docs/pull/6645>`_ Fix bootstrap class name help-block (foaly-nr1)
+* `#6642 <https://github.com/symfony/symfony-docs/pull/6642>`_ do not reference unused interface (xabbuh)
+* `#6641 <https://github.com/symfony/symfony-docs/pull/6641>`_ [Book][Form] fix reference to renamed document (xabbuh)
+* `#6579 <https://github.com/symfony/symfony-docs/pull/6579>`_ Added callable validation_groups example (gnat42)
+* `#6626 <https://github.com/symfony/symfony-docs/pull/6626>`_ reflect the EOM of Symfony 2.3 (xabbuh)
+* `#6631 <https://github.com/symfony/symfony-docs/pull/6631>`_ Fix console.exception and console.terminate order (Julien Falque)
+* `#6629 <https://github.com/symfony/symfony-docs/pull/6629>`_ Update options_resolver.rst (atailouloute)
+* `#6627 <https://github.com/symfony/symfony-docs/pull/6627>`_ Fixed a typo in cookbook/security/entity_provider (michaeldegroot)
+* `#6618 <https://github.com/symfony/symfony-docs/pull/6618>`_ Added a note about coding standards and method arguments (javiereguiluz)
+
+
 May, 2016
 ---------
 

components/process.rst

@@ -50,6 +50,25 @@ the contents of the output and
 :method:`Symfony\\Component\\Process\\Process::clearErrorOutput` clears
 the contents of the error output.
 
+.. versionadded:: 3.1
+    Support for streaming the output of a process was introduced in
+    Symfony 3.1.
+
+You can also use the :class:`Symfony\\Component\\Process\\Process` class with the
+foreach construct to get the output while it is generated. By default, the loop waits
+for new output before going to the next iteration::
+
+    $process = new Process('ls -lsa');
+    $process->start();
+
+    foreach ($process as $type => $data) {
+        if ($process::OUT === $type) {
+            echo "\nRead from stdout: ".$data;
+        } else { // $process::ERR === $type
+            echo "\nRead from stderr: ".$data;
+        }
+    }
+
 The ``mustRun()`` method is identical to ``run()``, except that it will throw
 a :class:`Symfony\\Component\\Process\\Exception\\ProcessFailedException`
 if the process couldn't be executed successfully (i.e. the process exited
@@ -128,6 +147,50 @@ are done doing other stuff::
     which means that your code will halt at this line until the external
     process is completed.
 
+Streaming to the Standard Input of a Process
+--------------------------------------------
+
+.. versionadded:: 3.1
+    Support for streaming the input of a process was introduced in
+    Symfony 3.1.
+
+Before a process is started, you can specify its standard input using either the
+:method:`Symfony\\Component\\Process\\Process::setInput` method or the 4th argument
+of the constructor. The provided input can be a string, a stream resource or a
+Traversable object::
+
+    $process = new Process('cat');
+    $process->setInput('foobar');
+    $process->run();
+
+When this input is fully written to the subprocess standard input, the corresponding
+pipe is closed.
+
+In order to write to a subprocess standard input while it is running, the component
+provides the :class:`Symfony\\Component\\Process\\InputStream` class::
+
+    $input = new InputStream();
+    $input->write('foo');
+
+    $process = new Process('cat');
+    $process->setInput($input);
+    $process->start();
+
+    // ... read process output or do other things
+
+    $input->write('bar');
+    $input->close();
+
+    $process->wait();
+
+    // will echo: foobar
+    echo $process->getOutput();
+
+The :method:`Symfony\\Component\\Process\\InputStream::write` method accepts scalars,
+stream resources or Traversable objects as argument. As shown in the above example,
+you need to explicitly call the :method:`Symfony\\Component\\Process\\InputStream::close`
+method when you are done writing to the standard input of the subprocess.
+
 Stopping a Process
 ------------------
 

cookbook/security/impersonating_user.rst

@@ -6,8 +6,18 @@ How to Impersonate a User
 
 Sometimes, it's useful to be able to switch from one user to another without
 having to log out and log in again (for instance when you are debugging or trying
-to understand a bug a user sees that you can't reproduce). This can be easily
-done by activating the ``switch_user`` firewall listener:
+to understand a bug a user sees that you can't reproduce).
+
+.. caution::
+
+    User impersonation is not compatible with
+    :doc:`pre authenticated firewalls </cookbook/security/pre_authenticated>`. The
+    reason is that impersonation requires the authentication state to be maintained
+    server-side, but pre-authenticated information (``SSL_CLIENT_S_DN_Email``,
+    ``REMOTE_USER`` or other) is sent in each request.
+
+Impersonating the user can be easily done by activating the ``switch_user``
+firewall listener:
 
 .. configuration-block::
 

cookbook/security/pre_authenticated.rst

@@ -11,6 +11,14 @@ box, Symfony supports most authentication mechanisms.
 These requests are called *pre authenticated* requests because the user is already
 authenticated when reaching your application.
 
+.. caution::
+
+    :doc:`User impersonation </cookbook/security/impersonating_user>` is not
+    compatible with pre-authenticated firewalls. The reason is that
+    impersonation requires the authentication state to be maintained server-side,
+    but pre-authenticated information (``SSL_CLIENT_S_DN_Email``, ``REMOTE_USER``
+    or other) is sent in each request.
+
 X.509 Client Certificate Authentication
 ---------------------------------------
 
@@ -149,9 +157,3 @@ key in the ``remote_user`` firewall configuration.
     See :ref:`the previous note <cookbook-security-pre-authenticated-user-provider-note>`
     for more information.
 
-.. caution::
-
-    :doc:`User impersonation </cookbook/security/impersonating_user>` is not
-    compatible with ``REMOTE_USER`` based authentication. The reason is that
-    impersonation requires the authentication state to be maintained server-side
-    but ``REMOTE_USER`` information is sent by the browser in each request.

cookbook/session/proxy_examples.rst

@@ -4,26 +4,92 @@
 Session Proxy Examples
 ======================
 
-The session proxy mechanism has a variety of uses and this example demonstrates
-two common uses. Rather than injecting the session handler as normal, a handler
-is injected into the proxy and registered with the session storage driver::
+The session proxy mechanism has a variety of uses and this article demonstrates
+two common uses. Rather than using the regular session handler, you can create
+a custom save handler just by defining a class that extends the
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Proxy\\SessionHandlerProxy`
+class.
 
-    use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
-    use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
+Then, define a new service related to the custom session handler:
 
-    $proxy = new YourProxy(new PdoSessionHandler());
-    $session = new Session(new NativeSessionStorage(array(), $proxy));
+.. configuration-block::
 
-Below, you'll learn two real examples that can be used for ``YourProxy``:
-encryption of session data and readonly guest sessions.
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.session_handler:
+                class: AppBundle\Session\CustomSessionHandler
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.session_handler" class="AppBundle\Session\CustomSessionHandler" />
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->register('app.session_handler', 'AppBundle\Session\CustomSessionHandler');
+
+Finally, use the ``framework.session.handler_id`` configuration option to tell
+Symfony to use your own session handler instead of the default one:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            session:
+                # ...
+                handler_id: app.session_handler
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+            <framework:config>
+                <framework:session handler-id="app.session_handler" ... />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            // ...
+            'session' => array(
+                // ...
+                'handler_id' => 'app.session_handler',
+            ),
+        ));
+
+Keep reading the next sections to learn how to use the session handlers in practice
+to solve two common use cases: encrypt session information and define readonly
+guest sessions.
 
 Encryption of Session Data
 --------------------------
 
 If you wanted to encrypt the session data, you could use the proxy to encrypt
 and decrypt the session as required::
 
+    // src/AppBundle/Session/EncryptedSessionProxy.php
+    namespace AppBundle\Session;
+
     use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy;
 
     class EncryptedSessionProxy extends SessionHandlerProxy
@@ -59,10 +125,13 @@ There are some applications where a session is required for guest users, but
 where there is no particular need to persist the session. In this case you
 can intercept the session before it is written::
 
-    use Foo\User;
+    // src/AppBundle/Session/ReadOnlySessionProxy.php
+    namespace AppBundle\Session;
+
+    use AppBundle\Entity\User;
     use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy;
 
-    class ReadOnlyGuestSessionProxy extends SessionHandlerProxy
+    class ReadOnlySessionProxy extends SessionHandlerProxy
     {
         private $user;