Merge remote-tracking branch 'upstream/2.7' into 2.7

Author: javiereguiluz

components/filesystem.rst

@@ -79,12 +79,13 @@ exists
 ~~~~~~
 
 :method:`Symfony\\Component\\Filesystem\\Filesystem::exists` checks for the
-presence of all files or directories and returns ``false`` if a file is missing::
+presence of one or more files or directories and returns ``false`` if any of
+them is missing::
 
     // this directory exists, return true
     $fs->exists('/tmp/photos');
 
-    // rabbit.jpg exists, bottle.png does not exists, return false
+    // rabbit.jpg exists, bottle.png does not exist, return false
     $fs->exists(array('rabbit.jpg', 'bottle.png'));
 
 .. note::
@@ -95,10 +96,11 @@ presence of all files or directories and returns ``false`` if a file is missing:
 copy
 ~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` is used to copy
-files. If the target already exists, the file is copied only if the source
-modification date is later than the target. This behavior can be overridden by
-the third boolean argument::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` makes a copy of a
+single file (use :method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` to
+copy directories). If the target already exists, the file is copied only if the
+source modification date is later than the target. This behavior can be overridden
+by the third boolean argument::
 
     // works only if image-ICC has been modified after image.jpg
     $fs->copy('image-ICC.jpg', 'image.jpg');
@@ -128,8 +130,8 @@ your own with the second argument. The third argument is the access time::
 chown
 ~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` is used to change
-the owner of a file. The third argument is a boolean recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` changes the owner of
+a file. The third argument is a boolean recursive option::
 
     // set the owner of the lolcat video to www-data
     $fs->chown('lolcat.mp4', 'www-data');
@@ -144,8 +146,8 @@ the owner of a file. The third argument is a boolean recursive option::
 chgrp
 ~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` is used to change
-the group of a file. The third argument is a boolean recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` changes the group of
+a file. The third argument is a boolean recursive option::
 
     // set the group of the lolcat video to nginx
     $fs->chgrp('lolcat.mp4', 'nginx');
@@ -160,8 +162,8 @@ the group of a file. The third argument is a boolean recursive option::
 chmod
 ~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` is used to change
-the mode of a file. The fourth argument is a boolean recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` changes the mode or
+permissions of a file. The fourth argument is a boolean recursive option::
 
     // set the mode of the video to 0600
     $fs->chmod('video.ogg', 0600);
@@ -176,8 +178,8 @@ the mode of a file. The fourth argument is a boolean recursive option::
 remove
 ~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` is used to remove
-files, symlinks, directories easily::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` deletes files,
+directories and symlinks::
 
     $fs->remove(array('symlink', '/path/to/directory', 'activity.log'));
 
@@ -189,8 +191,8 @@ files, symlinks, directories easily::
 rename
 ~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::rename` is used to rename
-files and directories::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::rename` changes the name
+of a single file or directory::
 
     // rename a file
     $fs->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg');
@@ -213,8 +215,8 @@ support symbolic links, a third boolean argument is available::
 makePathRelative
 ~~~~~~~~~~~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` returns
-the relative path of a directory given another one::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` takes two
+absolute paths and returns the relative path from the second path to the first one::
 
     // returns '../'
     $fs->makePathRelative(
@@ -227,8 +229,10 @@ the relative path of a directory given another one::
 mirror
 ~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` mirrors a
-directory::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` copies all the
+contents of the source directory into the target one (use the
+:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` method to copy single
+files)::
 
     $fs->mirror('/path/to/source', '/path/to/target');
 
@@ -253,8 +257,8 @@ dumpFile
 .. versionadded:: 2.3
     The ``dumpFile()`` was introduced in Symfony 2.3.
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` allows you to
-dump contents to a file. It does this in an atomic manner: it writes a temporary
+:method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` saves the given
+contents into a file. It does this in an atomic manner: it writes a temporary
 file first and then moves it to the new file location when it's finished.
 This means that the user will always see either the complete old file or
 complete new file (but never a partially-written file)::

components/finder.rst

@@ -55,6 +55,12 @@ the Finder instance.
     :phpfunction:`iterator_to_array` method, or get the number of items with
     :phpfunction:`iterator_count`.
 
+.. caution::
+
+    The ``Finder`` object doesn't reset its internal state automatically.
+    This means that you need to create a new instance if you do not want
+    get mixed results.
+
 .. caution::
 
     When searching through multiple locations passed to the

console/command_in_controller.rst

@@ -43,8 +43,12 @@ Run this command from inside your controller via::
 
             $input = new ArrayInput(array(
                'command' => 'swiftmailer:spool:send',
+               // (optional) define the value of command arguments
+               'fooArgument' => 'barValue',
+               // (optional) pass options to the command
                '--message-limit' => $messages,
             ));
+
             // You can use NullOutput() if you don't need the output
             $output = new BufferedOutput();
             $application->run($input, $output);

deployment/platformsh.rst

@@ -16,9 +16,8 @@ In this guide, it is assumed your codebase is already versioned with Git.
 Get a Project on Platform.sh
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You need to subscribe to a `Platform.sh project`_. Choose the development plan
-and go through the checkout process. Once your project is ready, give it a name
-and choose: **Import an existing site**.
+You need to `subscribe to a Platform.sh plan`_ and go through the checkout process.
+Once your project is ready, give it a name and choose: **Import an existing site**.
 
 Prepare Your Application
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -189,6 +188,7 @@ soon be able to see it in your browser.
 .. _`Platform.sh`: https://platform.sh
 .. _`Platform.sh documentation`: https://docs.platform.sh/frameworks/symfony.html
 .. _`Platform.sh project`: https://accounts.platform.sh/platform/buy-now
+.. _`subscribe to a Platform.sh plan`: https://accounts.platform.sh/platform/buy-now
 .. _`Platform.sh configuration files`: https://docs.platform.sh/configuration/services.html
 .. _`GitHub`: https://github.com/platformsh/platformsh-examples
 .. _`available services`: https://docs.platform.sh/reference/configuration-files/#configure-services

http_cache.rst

@@ -33,7 +33,6 @@ Nottingham's `Cache Tutorial`_.
 .. index::
    single: Cache; Proxy
    single: Cache; Reverse proxy
-   single: Cache; Gateway
 
 .. _gateway-caches:
 
@@ -286,11 +285,15 @@ Safe Methods: Only caching GET or HEAD requests
 HTTP caching only works for "safe" HTTP methods (like GET and HEAD). This means
 two things:
 
-* Don't try to cache PUT, POST or DELETE requests. It won't work and with good
-  reason. These methods are meant to be used when mutating the state of your application
+* Don't try to cache PUT or DELETE requests. It won't work and with good reason.
+  These methods are meant to be used when mutating the state of your application
   (e.g. deleting a blog post). Caching them would prevent certain requests from hitting
   and mutating your application.
 
+* POST requests are generally considered uncachable, but `they can be cached`_
+  when they include explicit freshness information. However POST caching is not
+  widely implemented, so you should avoid it if possible.
+
 * You should *never* change the state of your application (e.g. update a blog post)
   when responding to a GET or HEAD request. If those requests are cached, future
   requests may not actually hit your server.
@@ -366,3 +369,4 @@ Learn more
 .. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234
 .. _`RFC 7232 - Conditional Requests`: https://tools.ietf.org/html/rfc7232
 .. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/
+.. _`they can be cached`: https://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-20#section-2.3.4

page_creation.rst

@@ -94,8 +94,9 @@ If you're returning HTML from your controller, you'll probably want to render
 a template. Fortunately, Symfony comes with `Twig`_: a templating language that's
 easy, powerful and actually quite fun.
 
-First, make sure that ``LuckyController`` extends Symfony's base
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class::
+First, import the base :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller`
+class as shown on line 5 below. Then, let your ``LuckyController`` class
+extend the base class::
 
     // src/AppBundle/Controller/LuckyController.php
     // ...

reference/configuration/doctrine.rst

@@ -108,9 +108,6 @@ Full Default Configuration
                                 # True to use a pooled server with the oci8 driver
                                 pooled:               ~
 
-                                # the version of your database engine
-                                server_version:       ~
-
                                 # Configuring MultipleActiveResultSets for the pdo_sqlsrv driver
                                 MultipleActiveResultSets:  ~
 

security/named_encoders.rst

@@ -124,3 +124,51 @@ the name of the encoder to use::
             return null; // use the default encoder
         }
     }
+
+If you created your own password encoder implementing the
+:class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`,
+you must register a service for it in order to use it as a named encoder:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+            encoders:
+                app_encoder:
+                    id: 'app.password_encoder_service'
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd"
+        >
+
+            <config>
+                <!-- ... -->
+                <encoder class="app_encoder"
+                    id="app.password_encoder_service" />
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            // ...
+            'encoders' => array(
+                'app_encoder' => array(
+                    'id' => 'app.password_encoder_service'
+                ),
+            ),
+        ));
+
+This creates an encoder named ``app_encoder`` from a service named
+``app.password_encoder_service``.

service_container/parameters.rst

@@ -80,7 +80,6 @@ and hidden with the service definition:
     .. code-block:: php
 
         use AppBundle\Mailer;
-        use Symfony\Component\DependencyInjection\Reference;
 
         $container->setParameter('mailer.transport', 'sendmail');
 

session/proxy_examples.rst

@@ -88,19 +88,22 @@ 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::
+If you want to encrypt the session data, you can use the proxy to encrypt and
+decrypt the session as required. The following example uses the `php-encryption`_
+library, but you can adapt it to any other library that you may be using::
 
     // src/AppBundle/Session/EncryptedSessionProxy.php
     namespace AppBundle\Session;
 
+    use Defuse\Crypto\Crypto;
+    use Defuse\Crypto\Key;
     use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy;
 
     class EncryptedSessionProxy extends SessionHandlerProxy
     {
         private $key;
 
-        public function __construct(\SessionHandlerInterface $handler, $key)
+        public function __construct(\SessionHandlerInterface $handler, Key $key)
         {
             $this->key = $key;
 
@@ -111,12 +114,12 @@ and decrypt the session as required::
         {
             $data = parent::read($id);
 
-            return mcrypt_decrypt(\MCRYPT_3DES, $this->key, $data);
+            return Crypto::decrypt($data, $this->key);
         }
 
         public function write($id, $data)
         {
-            $data = mcrypt_encrypt(\MCRYPT_3DES, $this->key, $data);
+            $data = Crypto::encrypt($data, $this->key);
 
             return parent::write($id, $data);
         }
@@ -155,3 +158,5 @@ can intercept the session before it is written::
             return parent::write($id, $data);
         }
     }
+
+.. _`php-encryption`: https://github.com/defuse/php-encryption