diff --git a/changelog.rst b/changelog.rst index 39130134835..9d5ae8227e9 100644 --- a/changelog.rst +++ b/changelog.rst @@ -186,6 +186,7 @@ New Documentation * `#6744 `_ [Form] Ambiguous block prefixes render incorrectly (foaly-nr1) * `#6611 `_ Discourage the use of controllers as services (javiereguiluz) * `#5672 `_ Add constants to BC promise (WouterJ) +* `#6737 `_ Document the file() controller helper (javiereguiluz) * `#6707 `_ Describe serialization config location in cookbook (jcrombez, WouterJ) * `#6726 `_ Use getParameter method in controllers (peterkokot) * `#6727 `_ Updated the condition to display console name (mickaelandrieu) @@ -204,6 +205,7 @@ Fixed Documentation * `#6714 `_ UppercaseRot13Transformer wrong class name used (jevgenijusr) * `#6704 `_ Encountered an error when following the steps for contribution (chancegarcia) * `#6708 `_ Routes should be just imported, not mounted (OndraM) +* `#6708 `_ Routes should be just imported, not mounted (OndraM) Minor Documentation Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -224,6 +226,7 @@ Minor Documentation Changes * `#100 `_ Add file extension to SOAP article (WouterJ) * `#92 `_ Make usage of "The" in the edition list consistent (WouterJ) * `#91 `_ Create a section for "Getting Started" so we can generate a book (javiereguiluz) +* `#86 `_ bootstrapping Workflow component docs (weaverryan) * `#77 `_ Proofing the controller chapter (weaverryan) * `#90 `_ Fixed doc build issues (javiereguiluz) * `#82 `_ Bootstrapping property info doc (weaverryan) @@ -290,6 +293,7 @@ New Documentation ~~~~~~~~~~~~~~~~~ * `#6515 `_ Added the documentation for the Cache component (javiereguiluz) +* `#6623 `_ [Console] Adapt doc for easier testing of commands needing user inputs (chalasr) * `#6690 `_ Added an example for a different method of verbosity level usage. (smatyas) * `#6648 `_ Process: callbacks now allowed when output disabled (avindra) * `#6587 `_ Updating recommended email settings for monolog (jorgelbg) diff --git a/components/config/definition.rst b/components/config/definition.rst index e7654c0c14c..c383fa5cd39 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -736,6 +736,7 @@ the following ways: - ``ifTrue()`` - ``ifString()`` - ``ifNull()`` +- ``ifEmpty()`` (since Symfony 3.2) - ``ifArray()`` - ``ifInArray()`` - ``ifNotInArray()`` diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst index 6ea453beeb7..9c9284f2768 100644 --- a/components/console/helpers/questionhelper.rst +++ b/components/console/helpers/questionhelper.rst @@ -277,7 +277,7 @@ Testing a Command that Expects Input ------------------------------------ If you want to write a unit test for a command which expects some kind of input -from the command line, you need to set the helper input stream:: +from the command line, you need to set the inputs that the command expects:: use Symfony\Component\Console\Helper\QuestionHelper; use Symfony\Component\Console\Helper\HelperSet; @@ -289,26 +289,30 @@ from the command line, you need to set the helper input stream:: // ... $commandTester = new CommandTester($command); - $helper = $command->getHelper('question'); - $helper->setInputStream($this->getInputStream("Test\n")); // Equals to a user inputting "Test" and hitting ENTER - // If you need to enter a confirmation, "yes\n" will work + $commandTester->setInputs(array('Test')); + + // Equals to a user inputting "This", "That" and hitting ENTER + // This can be used for answering two separated questions for instance + $commandTester->setInputs(array('This', 'That')); + + // For simulating a positive answer to a confirmation question, adding an + // additional input saying "yes" will work + $commandTester->setInputs(array('yes')); $commandTester->execute(array('command' => $command->getName())); // $this->assertRegExp('/.../', $commandTester->getDisplay()); } - protected function getInputStream($input) - { - $stream = fopen('php://memory', 'r+', false); - fputs($stream, $input); - rewind($stream); +By calling :method:`Symfony\\Component\\Console\\Tester\\CommandTester::setInputs`, +you imitate what the console would do internally with all user input through the CLI. +This method takes an array as only argument with, for each input that the command expects, +a string representing what the user would have typed. +This way you can test any user interaction (even complex ones) by passing the appropriate inputs. - return $stream; - } +.. note:: -By setting the input stream of the ``QuestionHelper``, you imitate what the -console would do internally with all user input through the CLI. This way -you can test any user interaction (even complex ones) by passing an appropriate -input stream. + The :class:`Symfony\\Component\\Console\\Tester\\CommandTester` automatically + simulates a user hitting ``ENTER`` after each input, no need for passing + an additional input. diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index ee6438649ed..10bab433341 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -20,13 +20,16 @@ It comes with the following features: * Provides a ``ClockMock`` helper class for time-sensitive tests. +* Provides a modified version of phpunit that does not embed ``symfony/yaml`` nor + ``prophecy`` to prevent any conflicts with these dependencies. + Installation ------------ You can install the component in 2 different ways: * :doc:`Install it via Composer ` - (``symfony/phpunit-bridge`` on `Packagist`_); as a dev dependency; + (``symfony/phpunit-bridge`` on `Packagist`_); as a ``dev`` dependency; * Use the official Git repository (https://github.com/symfony/phpunit-bridge). @@ -326,6 +329,35 @@ namespaces in the ``phpunit.xml`` file, as done for example in the +Modified PHPUnit script +----------------------- + +.. versionadded:: 3.2 + The modified PHPUnit script script was introduced in Symfony 3.2. + +This bridge provides a modified version of PHPUnit that you can call by using +its ``bin/simple-phpunit`` command. It has the following features: + +* Does not embed ``symfony/yaml`` nor ``prophecy`` to prevent any conflicts with + these dependencies; +* Uses PHPUnit 4.8 when run with PHP <=5.5 and PHPUnit 5.1 when run with PHP >=5.6; +* Collects and replays skipped tests when the ``SYMFONY_PHPUNIT_SKIPPED_TESTS`` + env var is defined: the env var should specify a file name that will be used for + storing skipped tests on a first run, and replay them on the second run; +* Parallelizes test suites execution when given a directory as argument, scanning + this directory for ``phpunit.xml.dist`` files up to ``SYMFONY_PHPUNIT_MAX_DEPTH`` + levels (specified as an env var, defaults to ``3``); + +The script writes the modified PHPUnit it builds in a directory that can be +configured by the ``SYMFONY_PHPUNIT_DIR`` env var, or in the same directory as +the ``simple-phpunit`` if it is not provided. + +If you have installed the bridge through Composer, you can run it by calling e.g.: + +.. code-block:: bash + + $ vendor/bin/simple-phpunit + .. _PHPUnit: https://phpunit.de .. _`PHPUnit event listener`: https://phpunit.de/manual/current/en/extending-phpunit.html#extending-phpunit.PHPUnit_Framework_TestListener .. _`PHP error handler`: http://php.net/manual/en/book.errorfunc.php diff --git a/components/workflow.rst b/components/workflow.rst new file mode 100644 index 00000000000..656d37f2e65 --- /dev/null +++ b/components/workflow.rst @@ -0,0 +1,24 @@ +.. index:: + single: Workflow + single: Components; Workflow + +The Workflow Component +====================== + + The Workflow component provides tools for managing a workflow or finite state + machine. + +.. versionadded:: 3.2 + The Workflow component was introduced in Symfony 3.2. + +Installation +------------ + +You can install the component in 2 different ways: + +* :doc:`Install it via Composer ` (``symfony/workflow`` on `Packagist`_); +* Use the official Git repository (https://github.com/symfony/workflow). + +For more information, see the code in the Git Repository. + +.. _Packagist: https://packagist.org/packages/symfony/workflow diff --git a/controller.rst b/controller.rst index a75f1c714fc..4130b489dde 100644 --- a/controller.rst +++ b/controller.rst @@ -504,6 +504,12 @@ There are special classes that make certain kinds of responses easier: :class:`Symfony\\Component\\HttpFoundation\\StreamedResponse`. See :ref:`streaming-response`. +.. seealso:: + + Now that you know the basics you can continue your research on Symfony + ``Request`` and ``Response`` object in the + :ref:`HttpFoundation component documentation `. + JSON Helper ~~~~~~~~~~~ @@ -527,11 +533,39 @@ If the :doc:`serializer service ` is enabled in your application, contents passed to ``json()`` are encoded with it. Otherwise, the :phpfunction:`json_encode` function is used. -.. seealso:: +File helper +~~~~~~~~~~~ - Now that you know the basics you can continue your research on Symfony - ``Request`` and ``Response`` object in the - :ref:`HttpFoundation component documentation `. +.. versionadded:: 3.2 + The ``file()`` helper was introduced in Symfony 3.2. + +You can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::file` +helper to serve a file from inside a controller:: + + public function fileAction() + { + // send the file contents and force the browser to download it + return $this->file('/path/to/some_file.pdf'); + } + +The ``file()`` helper provides some arguments to configure its behavior:: + + use Symfony\Component\HttpFoundation\File\File; + use Symfony\Component\HttpFoundation\ResponseHeaderBag; + + public function fileAction() + { + // load the file from the filesystem + $file = new File('/path/to/some_file.pdf'); + + return $this->file($file); + + // rename the downloaded file + return $this->file($file, 'custom_name.pdf'); + + // display the file contents in the browser instead of downloading it + return $this->file('invoice_3241.pdf', 'my_invoice.pdf', ResponseHeaderBag::DISPOSITION_INLINE); + } Final Thoughts --------------