8000 Merge branch '4.0' into 4.1 · symfony/symfony-docs@a0c278a · GitHub
[go: up one dir, main page]
Skip to content

Commit a0c278a

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.0' into 4.1
* 4.0: Update deployment.rst Update typescript.rst Corrected titles of test tools and use safe url for phpspec Add 2 solutions for the 'option with optional argument' problem Simplify the explanation leaving just one solution Add 2 solutions for the 'option with optional argument' problem ocramius/proxy-manager isn't needed anymore Fix a typo in the HTML5 date form property Add URL-encoding notice Minor reword Export workflow chart to SVG Fixed a RST syntax issue Remove extra brace in the release schedule Update 3.3-di-changes.rst
2 parents 05fa5fe + b649271 commit a0c278a

File tree

11 files changed

+78
-42
lines changed

11 files changed

+78
-42
lines changed

‎best_practices/tests.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Unit Tests
1313
Unit tests are used to test your "business logic", which should live in classes
1414
that are independent of Symfony. For that reason, Symfony doesn't really
1515
have an opinion on what tools you use for unit testing. However, the most
16-
popular tools are `PhpUnit`_ and `PhpSpec`_.
16+
popular tools are `PHPUnit`_ and `PHPSpec`_.
1717

1818
Functional Tests
1919
----------------
@@ -114,8 +114,8 @@ Learn More about Functional Tests
114114
Consider using the `HautelookAliceBundle`_ to generate real-looking data for
115115
your test fixtures using `Faker`_ and `Alice`_.
116116

117-
.. _`PhpUnit`: https://phpunit.de/
118-
.. _`PhpSpec`: http://www.phpspec.net/
117+
.. _`PHPUnit`: https://phpunit.de/
118+
.. _`PHPSpec`: https://www.phpspec.net/
119119
.. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software)
120 8000 120
.. _`Mink`: http://mink.behat.org
121121
.. _`HautelookAliceBundle`: https://github.com/hautelook/AliceBundle

‎console/input.rst

Lines changed: 53 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,15 @@ values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or
179179
``--iterations=5``), but short options can only use white spaces or no
180180
separation at all (e.g. ``-i 5`` or ``-i5``).
181181

182+
.. caution::
183+
184+
While it is possible to separate an option from its value with a white space,
185+
using this form leads to an ambiguity should the option appear before the
186+
command name. For example, ``php app/console --iterations 5 app:greet Fabien``
187+
is ambiguous; Symfony would interpret ``5`` as the command name. To avoid
188+
this situation, always place options after the command name, or avoid using
189+
a space to separate the option name from its value.
190+
182191
There are four option variants you can use:
183192

184193
``InputOption::VALUE_IS_ARRAY``
@@ -209,21 +218,53 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or
209218
array('blue', 'red')
210219
);
211220

212-
.. tip::
221+
Options with optional arguments
222+
-------------------------------
223+
224+
There is nothing forbidding you to create a command with an option that
225+
optionally accepts a value, but it's a bit tricky. Consider this example::
226+
227+
// ...
228+
use Symfony\Component\Console\Input\InputOption;
229+
230+
$this
231+
// ...
232+
->addOption(
233+
'yell',
234+
null,
235+
InputOption::VALUE_OPTIONAL,
236+
'Should I yell while greeting?'
237+
);
238+
239+
This option can be used in 3 ways: ``--yell``, ``yell=louder``, and not passing
240+
the option at all. However, it's hard to distinguish between passing the option
241+
without a value (``greet --yell``) and not passing the option (``greet``).
242+
243+
To solve this issue, you have to set the option's default value to ``false``::
244+
245+
// ...
246+
use Symfony\Component\Console\Input\InputOption;
247+
248+
$this
249+
// ...
250+
->addOption(
251+
'yell',
252+
null,
253+
InputOption::VALUE_OPTIONAL,
254+
'Should I yell while greeting?',
255+
false // this is the new default value, instead of null
256+
);
213257

214-
There is nothing forbidding you to create a command with an option that
215-
optionally accepts a value. However, there is no way you can distinguish
216-
when the option was used without a value (``command --language``) or when
217-
it wasn't used at all (``command``). In both cases, the value retrieved for
218-
the option will be ``null``.
258+
Now check the value of the option and keep in mind that ``false !== null``::
259+
260+
$optionValue = $input->getOptions('yell');
261+
$yell = ($optionValue !== false);
262+
$yellLouder = ($optionValue === 'louder');
219263

220264
.. caution::
221265

222-
While it is possible to separate an option from its value with a white space,
223-
using this form leads to an ambiguity should the option appear before the
224-
command name. For example, ``php bin/console --iterations 5 app:greet Fabien``
225-
is ambiguous; Symfony would interpret ``5`` as the command name. To avoid
226-
this situation, always place options after the command name, or avoid using
227-
a space to separate the option name from its value.
266+
Due to a PHP limitation, passing an empty string is indistinguishable from
267+
not passing any value at all. In ``command --prefix`` and ``command --prefix=''``
268+
cases, the value of the ``prefix`` option will be ``null``.
228269

229270
.. _`docopt standard`: http://docopt.org/

‎contributing/community/releases.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ Version Feature Freeze Release End of Maintenance End of Life
122122
`2.6`_ 09/2014 11/2014 07/2015 (8 months) 01/2016
123123
`2.7`_ (LTS) 03/2015 05/2015 05/2018 (36 months) 05/2019
124124
`2.8`_ (LTS) 09/2015 11/2015 11/2018 (36 months [2]_) 11/2019
125-
`3.0`_ 09/2015 11/2015 07/2016 (8 months) [3]_) 01/2017
125+
`3.0`_ 09/2015 11/2015 07/2016 (8 months [3]_) 01/2017
126126
`3.1`_ 03/2016 05/2016 01/2017 (8 months) 07/2017
127127
`3.2`_ 09/2016 11/2016 07/2017 (8 months) 01/2018
128128
`3.3`_ 03/2017 05/2017 01/2018 (8 months) 07/2018
@@ -194,7 +194,7 @@ version is published every two years and there is a year to upgrade.
194194

195195
.. _Semantic Versioning: https://semver.org/
196196
.. _Git repository: https://github.com/symfony/symfony
197-
.. _SensioLabs: http://sensiolabs.com/
197+
.. _SensioLabs: https://sensiolabs.com/
198198
.. _roadmap notification: https://symfony.com/roadmap
199199
.. _extended to September 2014: https://symfony.com/blog/extended-maintenance-for-symfony-2-4
200200
.. _timeline calculator: https://symfony.com/roadmap#checker

‎deployment.rst

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -116,11 +116,8 @@ you'll need to do:
116116
A) Check Requirements
117117
~~~~~~~~~~~~~~~~~~~~~
118118

119-
Check if your server meets the requirements by running:
120-
121-
.. code-block:: terminal
122-
123-
$ php bin/symfony_requirements
119+
Use the :doc:`Symfony Requirements Checker </reference/requirements>` to check
120+
if your server meets the technical requirements to run Symfony applications.
124121

125122
.. _b-configure-your-app-config-parameters-yml-file:
126123

‎email.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@ environment variable in the ``.env`` file:
3737
# use this to disable email delivery
3838
MAILER_URL=null://localhost
3939
40-
# use this to configure a traditional SMTP server
40+
# use this to configure a traditional SMTP server (make sure to URL-encode the
41+
# values of the username and password if they contain non-alphanumeric characters
42+
# such as '+', '@', ':' and '*', which are reserved in URLs)
4143
MAILER_URL=smtp://localhost:25?encryption=ssl&auth_mode=login&username=&password=
4244
4345
Refer to the :doc:`SwiftMailer configuration reference </reference/configuration/swiftmailer>`

‎frontend/encore/typescript.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ also configure the `ts-loader options`_ via a callback:
2828
2929
.enableTypeScriptLoader(function (typeScriptConfigOptions) {
3030
typeScriptConfigOptions.transpileOnly = true;
31-
typeScriptConfigOptions.configFileName = '/path/to/tsconfig.json';
31+
typeScriptConfigOptions.configFile = '/path/to/tsconfig.json';
3232
});
3333
3434
If React assets are enabled (``.enableReactPreset()``), any ``.tsx`` file will be

‎reference/forms/types/options/html5.rst.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@ html5
66
If this is set to ``true`` (the default), it'll use the HTML5 type (date, time
77
or datetime) to render the field. When set to ``false``, it'll use the text type.
88

9-
This is useful when you want to use a custom JavaScript datapicker, which
9+
This is useful when you want to use a custom JavaScript datepicker, which
1010
often requires a text type instead of an HTML5 type.

‎service_container/3.3-di-changes.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
The Symfony 3.3 DI Container Changes Explained (autowiring, _defaults, etc)
22
===========================================================================
33

4-
If you look at the ``services.yaml`` file in a new Symfony 3.3 project, you'll
4+
If you look at the ``services.yaml`` file in a new Symfony 3.3 or newer project, you'll
55
notice some big changes: ``_defaults``, ``autowiring``, ``autoconfigure`` and more.
66
These features are designed to *automate* configuration and make development faster,
77
without sacrificing predictability, which is very important! Another goal is to make
@@ -589,6 +589,8 @@ to the new id. Create a new ``legacy_aliases.yml`` file:
589589
590590
# app/config/legacy_aliases.yml
591591
services:
592+
_defaults:
593+
public: true
592594
# aliases so that the old service ids can still be accessed
593595
# remove these if/when you are not fetching these directly
594596
# from the container via $container->get()

‎service_container/lazy_services.rst

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -26,21 +26,12 @@ until you interact with the proxy in some way.
2626
Installation
2727
------------
2828

29-
In order to use the lazy service instantiation, you will first need to install
30-
the ``ocramius/proxy-manager`` package:
29+
In order to use the lazy service instantiation, you will need to install the
30+
``symfony/proxy-manager-bridge`` package:
3131

3232
.. code-block:: terminal
3333
34-
$ composer require ocramius/proxy-manager
35-
36-
.. note::
37-
38-
If you're not using the full-stack framework, you also have to install the
39- `ProxyManager bridge`_
40-
41-
.. code-block:: terminal
42-
43-
$ composer require symfony/proxy-manager-bridge
34+
$ composer require symfony/proxy-manager-bridge
4435
4536
Configuration
4637
-------------

‎testing.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -271,9 +271,9 @@ document::
271271
Instead of installing each testing dependency individually, you can use the
272272
Symfony Test pack to install all those dependencies at once:
273273

274-
.. code-block:: terminal
274+
.. code-block:: terminal
275275
276-
$ composer require --dev symfony/test-pack
276+
$ composer require --dev symfony/test-pack
277277
278278
.. index::
279279
single: Tests; Assertions

‎workflow/dumping-workflows.rst

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ different dumpers both based on Dot.
1010

1111
Use the ``GraphvizDumper`` or ``StateMachineGraphvizDumper`` to create DOT
1212
files, or use ``PlantUmlDumper`` for PlantUML files. Both types can be converted
13-
to PNG images.
13+
to PNG or SVG images.
1414

1515
Images of the workflow defined above:
1616

@@ -31,6 +31,9 @@ Images of the workflow defined above:
3131
$ php dump-graph-dot.php | dot -Tpng -o dot_graph.png
3232
$ php dump-graph-puml.php | java -jar plantuml.jar -p > puml_graph.png
3333
34+
# run this command if you prefer SVG images:
35+
# $ php dump-graph-dot.php | dot -Tsvg -o dot_graph.svg
36+
3437
The DOT result will look like this:
3538

3639
.. image:: /_images/components/workflow/blogpost.png
@@ -44,7 +47,7 @@ Inside a Symfony application, you can dump the files with those commands using
4447

4548
.. code-block:: terminal
4649
47-
$ php bin/console workflow:dump name | dot -Tpng -o graph.png
50+
$ php bin/console workflow:dump name | dot -Tsvg -o graph.svg
4851
$ php bin/console workflow:dump name --dump-format=puml | java -jar plantuml.jar -p > workflow.png
4952
5053
.. note::

0 commit comments

Comments
 (0)
0