8000 Merge branch '3.4' · symfony/symfony-docs@2c34fcb · GitHub
[go: up one dir, main page]
Skip to content
8000

Commit 2c34fcb

Browse files
xabbuhxabbuh
committed
Merge branch '3.4'
* 3.4: (27 commits) [#8549] update ordered list syntax Minor tweaks Add default_path option reference [Form] Add debug:form command to debug page Added option to disable type enforcement in serializer Explained the possibility of defining custom deprecation messages [config] Add a note about deprecated a node [#8471] minor reword Explained the DomCrawler charset guessing mechanism Added a bundle deprecation notice in other articles [#8497] fix typo Updated Guard article for the GuardAuthenticatorInterface deprecation Deprecate auto picking the first provider Explain the new ColorType a bit more Explain the new TelType a bit more add doc for new tel and color types Update tags.rst Update tags.rst Update tags.rst Update tags.rst ...
2 parents e3ebe0e + 608c8e1 commit 2c34fcb

File tree

15 files changed

+403
-55
lines changed

15 files changed

+403
-55
lines changed

‎bundles/override.rst

Lines changed: 6 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ How to Override any Part of a Bundle
55
====================================
66

77
This document is a quick reference for how to override different parts of
8-
third-party bundles.
8+
third-party bundles without using :doc:`/bundles/inheritance`, which is
9+
deprecated since Symfony 3.4.
910

1011
.. tip::
1112

@@ -18,10 +19,7 @@ third-party bundles.
1819
Templates
1920
---------
2021

21-
For information on overriding templates, see
22-
23-
* :doc:`/templating/overriding`.
24-
* :doc:`/bundles/inheritance`
22+
See :doc:`/templating/overriding`.
2523

2624
Routing
2725
-------
@@ -37,10 +35,10 @@ that routing file into your application, modify it, and import it instead.
3735
Controllers
3836
-----------
3937

40-
Assuming the third-party bundle involved uses non-service controllers (which
41-
is almost always the case), you can easily override controllers via bundle
42-
inheritance. For more information, see :doc:`/bundles/inheritance`.
4338
If the controller is a service, see the next section on how to override it.
39+
Otherwise, define a new route + controller with the same path associated to the
40+
controller you want to override (and make sure that the new route is loaded
41+
before the bundle one).
4442

4543
Services & Configuration
4644
------------------------
@@ -152,13 +150,4 @@ Translations are not related to bundles, but to domains. That means that you
152150
can override the translations from any translation file, as long as it is in
153151
:ref:`the correct domain <using-message-domains>`.
154152

155-
.. caution::
156-
157-
Translation files are not aware of :doc:`bundle inheritance </bundles/inheritance>`.
158-
If you want to override translations from the parent bundle or another bundle,
159-
make sure that the bundle containing *your* translations is loaded after any
160-
bundle whose translations you're overriding. This is done in ``AppKernel``.
161-
162-
Finally, translations located in ``app/Resources/translations`` will override
163-
all the other translations since those files are always loaded last.
164153
.. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

‎components/config/definition.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -424,6 +424,29 @@ has a certain value:
424424
->end()
425425
;
426426
427+
Deprecating the Option
428+
----------------------
429+
430+
You can deprecate options using the
431+
:method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::setDeprecated`
432+
method::
433+
434+
$rootNode
435+
->children()
436+
->integerNode('old_option')
437+
// this outputs the following generic deprecation message:
438+
// The child node "old_option" at path "..." is deprecated.
439+
->setDeprecated()
440+
441+
// you can also pass a custom deprecation message (%node% and %path% placeholders are available):
442+
->setDeprecated('The "%node%" option is deprecated. Use "new_config_option" instead.')
443+
->end()
444+
->end()
445+
;
446+
447+
If you use the Web Debug Toolbar, these deprecation notices are shown when the
448+
configuration is rebuilt.
449+
427450
Documenting the Option
428451
----------------------
429452

‎components/dom_crawler.rst

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -237,10 +237,19 @@ The crawler supports multiple ways of adding the content::
237237

238238
.. note::
239239

240-
When dealing with character sets other than ISO-8859-1, always add HTML
241-
content using the :method:`Symfony\\Component\\DomCrawler\\Crawler::addHtmlContent`
242-
method where you can specify the second parameter to be your target character
243-
set.
240+
The :method:`Symfony\\Component\\DomCrawler\\Crawler::addHtmlContent` and
241+
:method:`Symfony\\Component\\DomCrawler\\Crawler::addXmlContent` methods
242+
default to UTF-8 encoding but you can change this behavior with their second
243+
optional argument.
244+
245+
The :method:`Symfony\\Component\\DomCrawler\\Crawler::addContent` method
246+
guesses the best charset according to the given contents and defaults to
247+
``ISO-8859-1`` in case no charset can be guessed.
248+
249+
.. versionadded:: 3.4
250+
The charset guessing mechanism of the ``addContent()`` method was
251+
introduced in Symfony 3.4. In previous Symfony versions, the ``ISO-8859-1``
252+
charset was always used.
244253

245254
As the Crawler's implementation is based on the DOM extension, it is also able
246255
to interact with native :phpclass:`DOMDocument`, :phpclass:`DOMNodeList`
@@ -397,13 +406,13 @@ a :class:`Symfony\\Component\\DomCrawler\\Form` object that represents the
397406
form that the button lives in::
398407

399408
// button example: <button id="my-super-button" type="submit">My super button</button>
400-
409+
401410
// you can get button by its label
402411
$form = $crawler->selectButton('My super button')->form();
403-
412+
404413
// or by button id (#my-super-button) if the button doesn't have a label
405414
$form = $crawler->selectButton('my-super-button')->form();
406-
415+
407416
// or you can filter the whole form, for example a form has a class attribute: <form class="form-vertical" method="POST">
408417
$crawler->filter('.form-vertical')->form();
409418

‎components/finder.rst

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,12 @@ the Finder instance.
6969
Criteria
7070
--------
7171

72-
There are lots of ways to filter and sort your results.
72+
There are lots of ways to filter and sort your results. You can also use the
73+
:method:`Symfony\\Component\\Finder\\Finder::hasResults` method to check if
74+
there's any file or directory matching the search criteria.
75+
76+
.. versionadded:: 3.4
77+
The ``hasResults()`` method was introduced in Symfony 3.4.
7378

7479
Location
7580
~~~~~~~~

‎components/serializer.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -877,7 +877,7 @@ parameter of the ``ObjectNormalizer``::
877877
public $bar;
878878
}
879879

880-
$normalizer = new ObjectNormalizer(null, null, null, new ReflectionExtractor()); //
880+
$normalizer = new ObjectNormalizer(null, null, null, new ReflectionExtractor());
881881
$serializer = new Serializer(array(new DateTimeNormalizer(), $normalizer));
882882

883883
$obj = $serializer->denormalize(
@@ -892,7 +892,9 @@ parameter of the ``ObjectNormalizer``::
892892
When a ``PropertyTypeExtractor`` is available, the normalizer will also check that the data to denormalize
893893
matches the type of the property (even for primitive types). For instance, if a ``string`` is provided, but
894894
the type of the property is ``int``, an :class:`Symfony\\Component\\Serializer\\Exception\\UnexpectedValueException`
895-
will be thrown.
895+
will be thrown. The type enforcement of the properties can be disabled by setting
896+
the serializer context option ``ObjectNormalizer::DISABLE_TYPE_ENFORCEMENT``
897+
to ``true``.
896898

897899
Learn more
898900
----------

‎debug/debugging.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ that can help you visualize and find the information.
2727

2828
``debug:config``
2929
Shows all configured bundles, their class and their alias.
30+
31+
``debug:form``
32+
Displays information about form types and their options.
3033

3134
``debug:event-dispatcher``
3235
Displays information about all the registered listeners in the event dispatcher.

‎form/form_customization.rst

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,10 +113,17 @@ fragment needed to render every part of a form:
113113
* `bootstrap_3_horizontal_layout.html.twig`_, it's similar to the previous theme,
114114
but the CSS classes applied are the ones used to display the forms horizontally
115115
(i.e. the label and the widget in the same row).
116+
* `bootstrap_4_layout.html.twig`_, same as ``bootstrap_3_layout.html.twig``, but
117+
updated for `Bootstrap 4 CSS framework`_ styles.
118+
* `bootstrap_4_horizontal_layout.html.twig`_, same as ``bootstrap_3_horizontal_layout.html.twig``
119+
but updated for Bootstrap 4 styles.
116120
* `foundation_5_layout.html.twig`_, wraps each form field inside a ``<div>`` element
117121
with the appropriate CSS classes to apply the default `Foundation CSS framework`_
118122
styles.
119123

124+
.. versionadded:: 3.4
125+
The Bootstrap 4 form themes were introduced in Symfony 3.4.
126+
120127
.. caution::
121128

122129
When you use the Bootstrap form themes and render the fields manually,
@@ -211,7 +218,7 @@ this folder.
211218
In this example, the customized fragment name is ``integer_widget`` because
212219
you want to override the HTML ``widget`` for all ``integer`` field types. If
213220
you need to customize ``textarea`` fields, you would customize ``textarea_widget``.
214-
221+
215222
The ``integer`` part comes from the class name: ``IntegerType`` becomes ``integer``,
216223
based on a standard.
217224

@@ -1174,6 +1181,9 @@ more details about this concept in Twig, see :ref:`twig-reference-form-variables
11741181
.. _`form_table_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig
11751182
.. _`bootstrap_3_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig
11761183
.. _`bootstrap_3_horizontal_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_horizontal_layout.html.twig
1177-
.. _`Bootstrap 3 CSS framework`: http://getbootstrap.com/
1184+
.. _`bootstrap_4_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_layout.html.twig
1185+
.. _`bootstrap_4_horizontal_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_horizontal_layout.html.twig
1186+
.. _`Bootstrap 3 CSS framework`: https://getbootstrap.com/docs/3.3/
1187+
.. _`Bootstrap 4 CSS framework`: https://getbootstrap.com/docs/4.0/
11781188
.. _`foundation_5_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/foundation_5_layout.html.twig
11791189
.. _`Foundation CSS framework`: http://foundation.zurb.com/

‎reference/configuration/twig.rst

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ TwigBundle Configuration ("twig")
2020
# Bootstrap:
2121
- bootstrap_3_layout.html.twig
2222
- bootstrap_3_horizontal_layout.html.twig
23+
- bootstrap_4_layout.html.twig
24+
- bootstrap_4_horizontal_layout.html.twig
2325
2426
# Foundation
2527
- foundation_5_layout.html.twig
@@ -52,6 +54,7 @@ TwigBundle Configuration ("twig")
5254
strict_variables: ~
5355
auto_reload: ~
5456
optimizations: ~
57+
default_path: '%kernel.project_dir%/templates'
5558
paths:
5659
'%kernel.project_dir%/vendor/acme/foo-bar/templates': foo_bar
5760
@@ -85,13 +88,14 @@ TwigBundle Configuration ("twig")
8588
debug="%kernel.debug%"
8689
strict-variables="false"
8790
optimizations="true"
91+
default-path="%kernel.project_dir%/templates"
8892
>
8993
<twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
9094
<twig:form-theme>form.html.twig</twig:form-theme>
9195
9296
<twig:global key="foo" id="bar" type="service" />
9397
<twig:global key="pi">3.14</twig:global>
94-
98+
9599
<twig:date format="d.m.Y, H:i:s" interval-format="%d days" timezone="Asia/Tokyo" />
96100
<twig:number-format decimals="2" decimal-point="," thousands-separator="." />
97101
@@ -134,6 +138,7 @@ TwigBundle Configuration ("twig")
134138
'decimal_point' => ',',
135139
'thousands_separator' => '.',
136140
),
141+
'default_path' => '%kernel.project_dir%/templates',
137142
));
138143
139144
.. caution::
@@ -336,6 +341,16 @@ on. Set it to ``0`` to disable all the optimizations. You can even enable or
336341
disable these optimizations selectively, as explained in the Twig documentation
337342
about `the optimizer extension`_.
338343

344+
default_path
345+
~~~~~~~~~~~~
346+
347+
**type**: ``string`` **default**: ``'%kernel.project_dir%/templates'``
348+
349+
.. versionadded:: 3.4
350+
The ``default_path`` option was introduced in Symfony 3.4.
351+
352+
The default directory where Symfony will look for Twig templates.
353+
339354
.. _config-twig-paths:
340355

341356
paths
@@ -344,9 +359,13 @@ paths
344359
**type**: ``array`` **default**: ``null``
345360

346361
This option defines the directories where Symfony will look for Twig templates
347-
in addition to the default locations (``app/Resources/views/`` and the bundles'
348-
``Resources/views/`` directories). This is useful to integrate the templates
349-
included in some library or package used by your application.
362+
in addition to the default locations. Symfony looks for the templates in the
363+
following order:
364+
365+
#. The directories defined in this option;
366+
#. The ``Resources/views/`` directories of the bundles used in the application;
367+
#. The ``src/Resources/views/`` directory of the application;
368+
#. The directory defined in the ``default_path`` option.
350369

351370
The values of the ``paths`` option are defined as ``key: value`` pairs where the
352371
``value`` part can be ``null``. For example:

‎reference/forms/types.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ Form Types Reference
1919
types/search
2020
types/url
2121
types/range
22+
types/tel
23+
types/color
2224

2325
types/choice
2426
types/entity

‎reference/forms/types/color.rst

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.. index::
2+
single: Forms; Fields; ColorType
3+
4+
ColorType Field
5+
===============
6+
7+
The ``ColorType`` field is a text field that is rendered using the HTML5
8+
``<input type="color">`` tag. Depending on each browser, the behavior of this
9+
form field can vary substantially. Some browsers display it as a simple text
10+
field, while others display a native color picker.
11+
12+
The value of the underlying ``<input type="color">`` field is always a
13+
7-character string specifying an RGB color in lower case hexadecimal notation.
14+
That's why it's not possible to select semi-transparent colors with this
15+
element.
16+
17+
+-------------+---------------------------------------------------------------------+
18+
| Rendered as | ``input`` ``color`` field (a text box) |
19+
+-------------+---------------------------------------------------------------------+
20+
| Inherited | - `data`_ |
21+
| options | - `disabled`_ |
22+
| | - `empty_data`_ |
23+
| | - `error_bubbling`_ |
24+
| | - `error_mapping`_ |
25+
| | - `label`_ |
26+
| | - `label_attr`_ |
27+
| | - `label_format`_ |
28+
| | - `mapped`_ |
29+
| | - `required`_ |
30+
| | - `trim`_ |
31+
+-------------+---------------------------------------------------------------------+
32+
| Parent type | :doc:`TextType </reference/forms/types/text>` |
33+
+-------------+---------------------------------------------------------------------+
34+
| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ColorType` |
35+
+-------------+---------------------------------------------------------------------+
36+
37+
Inherited Options
38+
-----------------
39+
40+
These options inherit from the :doc:`FormType </reference/forms/types/form>`:
41+
42+
.. include:: /reference/forms/types/options/data.rst.inc
43+
44+
.. include:: /reference/forms/types/options/disabled.rst.inc
45+
46+
.. include:: /reference/forms/types/options/empty_data.rst.inc
47+
:end-before: DEFAULT_PLACEHOLDER
48+
49+
The default value is ``''`` (the empty string).
50+
51+
.. include:: /reference/forms/types/options/empty_data.rst.inc
52+
:start-after: DEFAULT_PLACEHOLDER
53+
54+
.. include:: /reference/forms/types/options/error_bubbling.rst.inc
55+
56+
.. include:: /reference/forms/types/options/error_mapping.rst.inc
57+
58+
.. include:: /reference/forms/types/options/label.rst.inc
59+
60+
.. include:: /reference/forms/types/options/label_attr.rst.inc
61+
62+
.. include:: /reference/forms/types/options/label_format.rst.inc
63+
64+
.. include:: /reference/forms/types/options/mapped.rst.inc
65+
66+
.. include:: /reference/forms/types/options/required.rst.inc
67+
68+
.. include:: /reference/forms/types/options/trim.rst.inc

‎reference/forms/types/map.rst.inc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Text Fields
1212
* :doc:`SearchType </reference/forms/types/search>`
1313
* :doc:`UrlType </reference/forms/types/url>`
1414
* :doc:`RangeType </reference/forms/types/range>`
15+
* :doc:`TelType </reference/forms/types/tel>`
16+
* :doc:`ColorType </reference/forms/types/color>`
1517

1618
Choice Fields
1719
~~~~~~~~~~~~~

0 commit comments

Comments
 (0)
0