Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

.platform.app.yaml

@@ -46,10 +46,15 @@ disk: 512
 # Build time dependencies.
 dependencies:
   python:
-    sphinx: "1.3.6"
+    virtualenv: 15.1.0
 
 # The hooks that will be performed when the package is deployed.
 hooks:
     build: |
-      pip install git+https://github.com/fabpot/sphinx-php.git
+      virtualenv .virtualenv
+      . .virtualenv/bin/activate
+      # Platform.sh currently sets PIP_USER=1.
+      export PIP_USER=
+      pip install pip==9.0.1 wheel==0.29.0
+      pip install -r requirements.txt
       make -C _build html

components/console/helpers/progressbar.rst

@@ -170,7 +170,7 @@ current progress of the bar. Here is a list of the built-in placeholders:
 * ``remaining``: The remaining time to complete the task (not available if no max is defined);
 * ``estimated``: The estimated time to complete the task (not available if no max is defined);
 * ``memory``: The current memory usage;
-* ``message``: The current message attached to the progress bar.
+* ``message``: used to display arbitrary messages in the progress bar (as explained later).
 
 For instance, here is how you could set the format to be the same as the
 ``debug`` one::
@@ -181,20 +181,6 @@ Notice the ``:6s`` part added to some placeholders? That's how you can tweak
 the appearance of the bar (formatting and alignment). The part after the colon
 (``:``) is used to set the ``sprintf`` format of the string.
 
-The ``message`` placeholder is a bit special as you must set the value
-yourself::
-
-    $bar->setMessage('Task starts');
-    $bar->start();
-
-    $bar->setMessage('Task in progress...');
-    $bar->advance();
-
-    // ...
-
-    $bar->setMessage('Task is finished');
-    $bar->finish();
-
 Instead of setting the format for a given instance of a progress bar, you can
 also define global formats::
 
@@ -305,25 +291,41 @@ that displays the number of remaining steps::
 Custom Messages
 ~~~~~~~~~~~~~~~
 
-The ``%message%`` placeholder allows you to specify a custom message to be
-displayed with the progress bar. But if you need more than one, just define
-your own::
+Progress bars define a placeholder called ``message`` to display arbitrary
+messages. However, none of the built-in formats include that placeholder, so
+before displaying these messages, you must define your own custom format::
 
-    $bar->setMessage('Task starts');
-    $bar->setMessage('', 'filename');
-    $bar->start();
+    $progressBar = new ProgressBar($output, 100);
+    $progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message%');
+    $progressBar->setFormat('custom');
 
-    $bar->setMessage('Task is in progress...');
-    while ($file = array_pop($files)) {
-        $bar->setMessage($filename, 'filename');
-        $bar->advance();
-    }
+Now, use the ``setMessage()`` method to set the value of the ``%message%``
+placeholder before displaying the progress bar:
 
-    $bar->setMessage('Task is finished');
-    $bar->setMessage('', 'filename');
-    $bar->finish();
+    // ...
+    $progressBar->setMessage('Start');
+    $progressBar->start();
+    // 0/100 -- Start
+
+    $progressBar->advance();
+    $progressBar->setMessage('Task is in progress...');
+    // 1/100 -- Task is in progress...
+
+Messages can be combined with custom placeholders too. In this example, the
+progress bar uses the ``%message%`` and ``%filename%`` placeholders::
 
-For the ``filename`` to be part of the progress bar, just add the
-``%filename%`` placeholder in your format::
+    $progressBar = new ProgressBar($output, 100);
+    $progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message% (%filename%)');
+    $progressBar->setFormat('custom');
 
-    $bar->setFormat(" %message%\n %current%/%max%\n Working on %filename%");
+The ``setMessage()`` method accepts a second optional argument to set the value
+of the custom placeholders::
+
+    // ...
+    // $files = array('client-001/invoices.xml', '...');
+    foreach ($files as $filename) {
+        $progressBar->setMessage('Importing invoices...');
+        $progressBar->setMessage($filename, 'filename');
+        $progressBar->advance();
+        // 2/100 -- Importing invoices... (client-001/invoices.xml)
+    }

components/console/helpers/questionhelper.rst

@@ -295,7 +295,7 @@ You can also use a validator with a hidden question::
         $question = new Question('Please enter your password');
         $question->setValidator(function ($value) {
             if (trim($value) == '') {
-                throw new \Exception('The password can not be empty');
+                throw new \Exception('The password cannot be empty');
             }
 
             return $value;

components/dotenv.rst

@@ -0,0 +1,107 @@
+.. index::
+   single: Dotenv
+   single: Components; Dotenv
+
+The Dotenv Component
+====================
+
+    The Dotenv Component parses ``.env`` files to make environment variables
+    stored in them accessible via ``getenv()``, ``$_ENV`` or ``$_SERVER``.
+
+.. versionadded:: 3.3
+    The Dotenv component was introduced in Symfony 3.3.
+
+Installation
+------------
+
+You can install the component in 2 different ways:
+
+* :doc:`Install it via Composer </components/using_components>` (``symfony/dotenv`` on `Packagist`_);
+* Use the official Git repository (https://github.com/symfony/dotenv).
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+Sensitive information and environment-dependent settings should be defined as
+environment variables (as recommended for `twelve-factor applications`_). Using
+a ``.env`` file to store those environment variables eases development and CI
+management by keeping them in one "standard" place and agnostic of the
+technology stack you are using (Nginx vs PHP built-in server for instance).
+
+.. note::
+
+    PHP has a lot of different implementations of this "pattern". This
+    implementation's goal is to replicate what ``source .env`` would do. It
+    tries to be as similar as possible with the standard shell's behavior (so
+    no value validation for instance).
+
+Load a ``.env`` file in your PHP application via ``Dotenv::load()``::
+
+    use Symfony\Component\Dotenv\Dotenv;
+
+    $dotenv = new Dotenv();
+    $dotenv->load(__DIR__.'/.env');
+
+    // You can also load several files
+    $dotenv->load(__DIR__.'/.env', __DIR__.'/.env.dev');
+
+Given the following ``.env`` file content:
+
+.. code-block:: bash
+
+    # .env
+    DB_USER=root
+    DB_PASS=pass
+
+Access the value with ``getenv()`` in your code::
+
+    $dbUser = getenv('DB_USER');
+    // you can also use ``$_ENV`` or ``$_SERVER``
+
+.. note::
+
+    Symfony Dotenv never overwrites existing environment variables.
+
+You should never store a ``.env`` file in your code repository as it might
+contain sensitive information; create a ``.env.dist`` file with sensible
+defaults instead.
+
+Symfony Dotenv should only be used in development/testing/staging environments.
+For production environments, use "real" environment variables.
+
+As a ``.env`` file is a regular shell script, you can ``source`` it in your own
+shell scripts:
+
+.. code-block:: terminal
+
+    source .env
+
+Add comments by prefixing them with ``#``:
+
+.. code-block:: bash
+
+    # Database credentials
+    DB_USER=root
+    DB_PASS=pass # This is the secret password
+
+Use environment variables in values by prefixing variables with ``$``:
+
+.. code-block:: bash
+
+    DB_USER=root
+    DB_PASS=${DB_USER}pass # Include the user as a password prefix
+
+Embed commands via ``$()`` (not supported on Windows):
+
+.. code-block:: bash
+
+    START_TIME=$(date)
+
+.. note::
+
+    Note that using ``$()`` might not work depending on your shell.
+
+.. _Packagist: https://packagist.org/packages/symfony/dotenv
+.. _twelve-factor applications: http://www.12factor.net/

components/filesystem.rst

@@ -283,6 +283,21 @@ complete new file (but never a partially-written file)::
 
 The ``file.txt`` file contains ``Hello World`` now.
 
+appendToFile
+~~~~~~~~~~~~
+
+.. versionadded:: 3.3
+    The :method:`Symfony\\Component\\Filesystem\\Filesystem::appendToFile`
+    method was introduced in Symfony 3.3.
+
+:method:`Symfony\\Component\\Filesystem\\Filesystem::appendToFile` adds new
+contents at the end of some file::
+
+    $fs->appendToFile('logs.txt', 'Email sent to user@example.com');
+
+If either the file or its containing directory doesn't exist, this method
+creates them before appending the contents.
+
 Error Handling
 --------------
 

components/phpunit_bridge.rst

@@ -345,7 +345,7 @@ namespaces in the ``phpunit.xml`` file, as done for example in the
             <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
                 <arguments>
                     <array>
-                        <element><string>Symfony\Component\HttpFoundation</string></element>
+                        <element key="time-sensitive"><string>Symfony\Component\HttpFoundation</string></element>
                     </array>
                 </arguments>
             </listener>

components/process.rst

@@ -373,7 +373,7 @@ Use :method:`Symfony\\Component\\Process\\Process::disableOutput` and
 
 .. caution::
 
-    You can not enable or disable the output while the process is running.
+    You cannot enable or disable the output while the process is running.
 
     If you disable the output, you cannot access ``getOutput()``,
     ``getIncrementalOutput()``, ``getErrorOutput()``, ``getIncrementalErrorOutput()`` or

components/var_dumper.rst

@@ -88,7 +88,7 @@ of your application may just break it by e.g. sending HTTP headers or
 corrupting your view, the bundle configures the ``dump()`` function so that
 variables are dumped in the web debug toolbar.
 
-But if the toolbar can not be displayed because you e.g. called ``die``/``exit``
+But if the toolbar cannot be displayed because you e.g. called ``die``/``exit``
 or a fatal error occurred, then dumps are written on the regular output.
 
 In a Twig template, two constructs are available for dumping a variable.

console/hide_commands.rst

@@ -30,3 +30,7 @@ In those cases, you can define the command as **hidden** by setting the
 
 Hidden commands behave the same as normal commands but they are no longer displayed
 in command listings, so end-users are not aware of their existence.
+
+.. note::
+
+    Hidden commands are still available using the JSON or XML descriptor.

controller/soap_web_service.rst

@@ -8,7 +8,7 @@ How to Create a SOAP Web Service in a Symfony Controller
 
 Setting up a controller to act as a SOAP server is simple with a couple
 tools. You must, of course, have the `PHP SOAP`_ extension installed.
-As the PHP SOAP extension can not currently generate a WSDL, you must either
+As the PHP SOAP extension cannot currently generate a WSDL, you must either
 create one from scratch or use a 3rd party generator.
 
 .. note::