Merge branch '2.7' into 2.8

* 2.7: (37 commits)
  Minor rewording for the security:checker article
  add missing dot at the end of sentence
  add labels for old headlines
  delivery adresses are separate XML element nodes
  Removed the description of the deprecated `delivery_address` option
  Removed any mention of the deprecated delivery_address option
  Removed the mention to the deprecated delivery_address option
  Fixed a minor syntax issue
  Fixed a minor syntax issue
  Update Swiftmailer configuration docs
  Added a tip about the TMPDIR env variable
  adding the namespace for ArrayInput
  use short config syntax for factories
  Minor fix and rewording
  Update file_permissions.rst
  Update console.rst
  Minor change
  Improved code example of `prepend` method
  Fixed the signature of prepend method in the code example
  Fixed tag namespace in the example of xml configuration
  ...

Author: xabbuh

best_practices/security.rst

@@ -216,7 +216,7 @@ Checking Permissions without @Security
 
 The above example with ``@Security`` only works because we're using the
 :ref:`ParamConverter <best-practices-paramconverter>`, which gives the expression
-access to the a ``post`` variable. If you don't use this, or have some other
+access to the ``post`` variable. If you don't use this, or have some other
 more advanced use-case, you can always do the same security check in PHP:
 
 .. code-block:: php

bundles/prepend_extension.rst

@@ -56,6 +56,7 @@ The following example illustrates how to prepend
 a configuration setting in multiple bundles as well as disable a flag in multiple bundles
 in case a specific other bundle is not registered::
 
+    // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
     public function prepend(ContainerBuilder $container)
     {
         // get all bundles
@@ -69,8 +70,10 @@ in case a specific other bundle is not registered::
                     case 'acme_something':
                     case 'acme_other':
                         // set use_acme_goodbye to false in the config of
-                        // acme_something and acme_other note that if the user manually
-                        // configured use_acme_goodbye to true in the app/config/config.yml
+                        // acme_something and acme_other
+                        //
+                        // note that if the user manually configured
+                        // use_acme_goodbye to true in app/config/config.yml
                         // then the setting would in the end be true and not false
                         $container->prependExtensionConfig($name, $config);
                         break;

components/dependency_injection/compilation.rst

@@ -204,7 +204,7 @@ The XML version of the config would then look like this:
         xsi:schemaLocation="http://www.example.com/symfony/schema/ http://www.example.com/symfony/schema/hello-1.0.xsd">
 
         <acme_demo:config>
-            <acme_demo:foo>fooValue</acme_hello:foo>
+            <acme_demo:foo>fooValue</acme_demo:foo>
             <acme_demo:bar>barValue</acme_demo:bar>
         </acme_demo:config>
     </container>
@@ -292,7 +292,7 @@ method is called by implementing
     {
         // ...
 
-        public function prepend()
+        public function prepend(ContainerBuilder $container)
         {
             // ...
 

components/filesystem/lock_handler.rst

@@ -45,9 +45,19 @@ the file, so you can pass any value for this argument.
     to avoid name collisions, ``LockHandler`` also appends a hash to the name of
     the lock file.
 
-By default, the lock will be created in the temporary directory, but you can
-optionally select the directory where locks are created by passing it as the
-second argument of the constructor.
+By default, the lock will be created in the system's temporary directory, but
+you can optionally select the directory where locks are created by passing it as
+the second argument of the constructor.
+
+.. tip::
+
+    Another way to configure the directory where the locks are created is to
+    define a special environment variable, because PHP will use that value to
+    override the default temporary directory. On Unix-based systems, define the
+    ``TMPDIR`` variable. On Windows systems, define any of these variables:
+    ``TMP``, ``TEMP`` or ``USERPROFILE`` (they are checked in this order). This
+    technique is useful for example when deploying a third-party Symfony
+    application whose code can't be modified.
 
 The :method:`Symfony\\Component\\Filesystem\\LockHandler::lock` method tries to
 acquire the lock. If the lock is acquired, the method returns ``true``,

console.rst

@@ -4,7 +4,7 @@
 Console Commands
 ================
 
-The Symfony framework provide lots of commands through the ``app/console`` script
+The Symfony framework provides lots of commands through the ``app/console`` script
 (e.g. the well-known ``app/console cache:clear`` command). These commands are
 created with the :doc:`Console component </components/console>`. You can also
 use it to create your own commands.
@@ -176,7 +176,7 @@ instead::
         }
     }
 
-Now, once you created the required services and logic, the command will execute
+Now, once you have created the required services and logic, the command will execute
 the ``create()`` method of the ``app.user_manager`` service and the user will
 be created.
 

console/calling_commands.rst

@@ -10,6 +10,9 @@ generating Doctrine2 proxies, dumping Assetic assets, ...).
 
 Calling a command from another one is straightforward::
 
+    use Symfony\Component\Console\Input\ArrayInput;
+    // ...
+
     protected function execute(InputInterface $input, OutputInterface $output)
     {
         $command = $this->getApplication()->find('demo:greet');

email.rst

@@ -83,7 +83,7 @@ The following configuration attributes are available:
 
   * ``type`` (how to queue the messages, ``file`` or ``memory`` is supported, see :doc:`/email/spool`)
   * ``path`` (where to store the messages)
-* ``delivery_address`` (an email address where to send ALL emails)
+* ``delivery_addresses`` (an array of email addresses where to send ALL emails)
 * ``disable_delivery`` (set to true to disable delivery completely)
 
 Sending Emails

email/dev_environment.rst

@@ -53,20 +53,22 @@ will not be sent when you run tests, but will continue to be sent in the
 If you'd also like to disable deliver in the ``dev`` environment, simply
 add this same configuration to the ``config_dev.yml`` file.
 
-Sending to a Specified Address
-------------------------------
+.. _sending-to-a-specified-address:
 
-You can also choose to have all email sent to a specific address, instead
+Sending to a Specified Address(es)
+----------------------------------
+
+You can also choose to have all email sent to a specific address or a list of addresses, instead
 of the address actually specified when sending the message. This can be done
-via the ``delivery_address`` option:
+via the ``delivery_addresses`` option:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # app/config/config_dev.yml
         swiftmailer:
-            delivery_address: '[email protected]'
+            delivery_addresses: ['[email protected]']
 
     .. code-block:: xml
 
@@ -78,14 +80,16 @@ via the ``delivery_address`` option:
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
-            <swiftmailer:config delivery-address="[email protected]" />
+            <swiftmailer:config>
+                <swiftmailer:delivery-address>[email protected]</swiftmailer:delivery-address>
+            </swiftmailer:config>
         </container>
 
     .. code-block:: php
 
         // app/config/config_dev.php
         $container->loadFromExtension('swiftmailer', array(
-            'delivery_address'  => "[email protected]",
+            'delivery_addresses' => array("[email protected]"),
         ));
 
 Now, suppose you're sending an email to ``[email protected]``.
@@ -139,7 +143,7 @@ by adding the ``delivery_whitelist`` option:
 
         # app/config/config_dev.yml
         swiftmailer:
-            delivery_address: [email protected]
+            delivery_addresses: ['[email protected]']
             delivery_whitelist:
                # all email addresses matching these regexes will be delivered
                # like normal, as well as being sent to [email protected]
@@ -158,19 +162,20 @@ by adding the ``delivery_whitelist`` option:
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
-            <swiftmailer:config delivery-address="[email protected]">
+            <swiftmailer:config>
                 <!-- all email addresses matching these regexes will be delivered
                      like normal, as well as being sent to [email protected] -->
                 <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
                 <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
+                <swiftmailer:delivery-address>[email protected]</swiftmailer:delivery-address>
             </swiftmailer:config>
         </container>
 
     .. code-block:: php
 
         // app/config/config_dev.php
         $container->loadFromExtension('swiftmailer', array(
-            'delivery_address'  => "[email protected]",
+            'delivery_addresses'  => array("[email protected]"),
             'delivery_whitelist' => array(
                 // all email addresses matching these regexes will be delivered
                 // like normal, as well as being sent to [email protected]

frontend/custom_version_strategy.rst

@@ -0,0 +1,201 @@
+.. index::
+   single: Asset; Custom Version Strategy
+
+How to Use a Custom Version Strategy for Assets
+===============================================
+
+.. versionadded:: 2.7
+    The Asset component was introduced in Symfony 2.7.
+
+Asset versioning is a technique that improves the performance of web
+applications by adding a version identifier to the URL of the static assets
+(CSS, JavaScript, images, etc.) When the content of the asset changes, its
+identifier is also modified to force the browser to download it again instead of
+reusing the cached asset.
+
+Symfony supports asset versioning thanks to the
+:ref:`version <reference-framework-assets-version>` and
+:ref:`version_format <reference-framework-assets-version-format>` configuration
+options. If your application requires a more advanced versioning, such as
+generating the version dynamically based on some external information, you can
+create your own version strategy.
+
+Creating your Own Asset Version Strategy
+----------------------------------------
+
+The following example shows how to create a version strategy compatible with
+`gulp-buster`_. This tool defines a configuration file called ``busters.json``
+which maps each asset file to its content hash:
+
+.. code-block:: json
+
+    {
+        "js/script.js": "f9c7afd05729f10f55b689f36bb20172",
+        "css/style.css": "91cd067f79a5839536b46c494c4272d8"
+    }
+
+Implement VersionStrategyInterface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Asset version strategies are PHP classes that implement the
+:class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface`.
+In this example, the constructor of the class takes as arguments the path to
+the manifest file generated by `gulp-buster`_ and the format of the generated
+version string::
+
+    // src/AppBundle/Asset/VersionStrategy/GulpBusterVersionStrategy.php
+    namespace AppBundle\Asset\VersionStrategy;
+
+    use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
+
+    class GulpBusterVersionStrategy implements VersionStrategyInterface
+    {
+        /**
+         * @var string
+         */
+        private $manifestPath;
+
+        /**
+         * @var string
+         */
+        private $format;
+
+        /**
+         * @var string[]
+         */
+        private $hashes;
+
+        /**
+         * @param string      $manifestPath
+         * @param string|null $format
+         */
+        public function __construct($manifestPath, $format = null)
+        {
+            $this->manifestPath = $manifestPath;
+            $this->format = $format ?: '%s?%s';
+        }
+
+        public function getVersion($path)
+        {
+            if (!is_array($this->hashes)) {
+                $this->hashes = $this->loadManifest();
+            }
+
+            return isset($this->hashes[$path]) ? $this->hashes[$path] : '';
+        }
+
+        public function applyVersion($path)
+        {
+            $version = $this->getVersion($path);
+
+            if ('' === $version) {
+                return $path;
+            }
+
+            $versionized = sprintf($this->format, ltrim($path, '/'), $version);
+
+            if ($path && '/' === $path[0]) {
+                return '/'.$versionized;
+            }
+
+            return $versionized;
+        }
+
+        private function loadManifest(array $options)
+        {
+            return json_decode(file_get_contents($this->manifestPath), true);
+        }
+    }
+
+Register the Strategy Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After creating the strategy PHP class, register it as a Symfony service.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.assets.versioning.gulp_buster:
+                class: AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy
+                arguments:
+                    - "%kernel.root_dir%/../busters.json"
+                    - "%%s?version=%%s"
+                public: false
+
+    .. 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.assets.versioning.gulp_buster"
+                 class="AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy" public="false">
+                    <argument>%kernel.root_dir%/../busters.json</argument>
+                    <argument>%%s?version=%%s</argument>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use Symfony\Component\DependencyInjection\Definition;
+
+        $definition = new Definition(
+            'AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy',
+            array(
+                '%kernel.root_dir%/../busters.json',
+                '%%s?version=%%s',
+            )
+        );
+        $definition->setPublic(false);
+
+        $container->setDefinition('app.assets.versioning.gulp_buster', $definition);
+
+Finally, enable the new asset versioning for all the application assets or just
+for some :ref:`asset package <reference-framework-assets-packages>` thanks to
+the :ref:`version_strategy <reference-framework-assets-version_strategy>` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            # ...
+            assets:
+                version_strategy: 'app.assets.versioning.gulp_buster'
+
+    .. 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"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            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>
+                <framework:assets version-strategy="app.assets.versioning.gulp_buster" />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            // ...
+            'assets' => array(
+                'version_strategy' => 'app.assets.versioning.gulp_buster',
+            ),
+        ));
+
+.. _`gulp-buster`: https://www.npmjs.com/package/gulp-buster