8000 Merge branch '5.1' into 5.x · symfony/symfony-docs@e78aba4 · GitHub
[go: up one dir, main page]
Skip to content

Commit e78aba4

Browse files
wouterjwouterj
committed
Merge branch '5.1' into 5.x
* 5.1: addressed issue #11786 Add array example on ChoiceType choice_attr option [#13619] Moved text into a note and added versionadded Add wither behavior with PHP8 static return type [#14340] Some minor textual changes [Collection forms] Make javascript generic Updating the Installer Related Instructions Non-standard adder/remover methods
2 parents 2a48c44 + ffcd049 commit e78aba4

File tree

5 files changed

+146
-95
lines changed

5 files changed

+146
-95
lines changed

‎components/property_access.rst

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -408,6 +408,45 @@ and ``removeChild()`` methods to access to the ``children`` property.
408408

409409
If available, *adder* and *remover* methods have priority over a *setter* method.
410410

411+
Using non-standard adder/remover methods
412+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
413+
414+
Sometimes, adder and remover methods don't use the standard ``add`` or ``remove`` prefix, like in this example::
415+
416+
// ...
417+
class PeopleList
418+
{
419+
// ...
420+
421+
public function joinPeople(string $people): void
422+
{
423+
$this->peoples[] = $people;
424+
}
425+
426+
public function leavePeople(string $people): void
427+
{
428+
foreach ($this->peoples as $id => $item) {
429+
if ($people === $item) {
430+
unset($this->peoples[$id]);
431+
break;
432+
}
433+
}
434+
}
435+
}
436+
437+
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
438+
use Symfony\Component\PropertyAccess\PropertyAccessor;
439+
440+
$list = new PeopleList();
441+
$reflectionExtractor = new ReflectionExtractor(null, null, ['join', 'leave']);
442+
$propertyAccessor = new PropertyAccessor(false, false, null, true, $reflectionExtractor, $reflectionExtractor);
443+
$propertyAccessor->setValue($person, 'peoples', ['kevin', 'wouter']);
444+
445+
var_dump($person->getPeoples()); // ['kevin', 'wouter']
446+
447+
Instead of calling ``add<SingularOfThePropertyName>()`` and ``remove<SingularOfThePropertyName>()``, the PropertyAccess
448+
component will call ``join<SingularOfThePropertyName>()`` and ``leave<SingularOfThePropertyName>()`` methods.
449+
411450
Checking Property Paths
412451
-----------------------
413452

‎components/serializer.rst

Lines changed: 42 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -896,8 +896,20 @@ The ``XmlEncoder`` will encode this object like that::
896896
<bar>1</bar>< 57AE /span>
897897
</response>
898898

899-
Be aware that this encoder will consider keys beginning with ``@`` as attributes, and will use
900-
the key ``#comment`` for encoding XML comments::
899+
The special ``#`` key can be used to define the data of a node::
900+
901+
['foo' => ['@bar' => 'value', '#' => 'baz']];
902+
903+
// is encoded as follows:
904+
// <?xml version="1.0"?>
905+
// <response>
906+
// <foo bar="value">
907+
// baz
908+
// </foo>
909+
// </response>
910+
911+
Furthermore, keys beginning with ``@`` will be considered attributes, and
912+
the key ``#comment`` can be used for encoding XML comments::
901913

902914
$encoder = new XmlEncoder();
903915
$encoder->encode([
@@ -923,6 +935,34 @@ always as a collection.
923935
changed with the optional ``$encoderIgnoredNodeTypes`` argument of the
924936
``XmlEncoder`` class constructor.
925937

938+
The ``XmlEncoder`` Context Options
939+
..................................
940+
941+
The ``encode()`` method defines a third optional parameter called ``context``
942+
which defines the configuration options for the XmlEncoder an associative array::
943+
944+
$xmlEncoder->encode($array, 'xml', $context);
945+
946+
These are the options available:
947+
948+
``xml_format_output``
949+
If set to true, formats the generated XML with line breaks and indentation.
950+
951+
``xml_version``
952+
Sets the XML version attribute (default: ``1.1``).
953+
954+
``xml_encoding``
955+
Sets the XML encoding attribute (default: ``utf-8``).
956+
957+
``xml_standalone``
958+
Adds standalone attribute in the generated XML (default: ``true``).
959+
960+
``xml_root_node_name``
961+
Sets the root node name (default: ``response``).
962+
963+
``remove_empty_tags``
964+
If set to true, removes all empty tags in the generated XML (default: ``false``).
965+
926966
The ``YamlEncoder``
927967
~~~~~~~~~~~~~~~~~~~
928968

@@ -1234,72 +1274,6 @@ you indicate that you're expecting an array instead of a single object::
12341274
$data = ...; // The serialized data from the previous example
12351275
$persons = $serializer->deserialize($data, 'Acme\Person[]', 'json');
12361276

1237-
The ``XmlEncoder``
1238-
------------------
1239-
1240-
This encoder transforms arrays into XML and vice versa. For example, take an
1241-
object normalized as following::
1242-
1243-
['foo' => [1, 2], 'bar' => true];
1244-
1245-
The ``XmlEncoder`` encodes this object as follows:
1246-
1247-
.. code-block:: xml
1248-
1249-
<?xml version="1.0"?>
1250-
<response>
1251-
<foo>1</foo>
1252-
<foo>2</foo>
1253-
<bar>1</bar>
1254-
</response>
1255-
1256-
The array keys beginning with ``@`` are considered XML attributes::
1257-
1258-
['foo' => ['@bar' => 'value']];
1259-
1260-
// is encoded as follows:
1261-
// <?xml version="1.0"?>
1262-
// <response>
1263-
// <foo bar="value"/>
1264-
// </response>
1265-
1266-
Use the special ``#`` key to define the data of a node::
1267-
1268-
['foo' => ['@bar' => 'value', '#' => 'baz']];
1269-
1270-
// is encoded as follows:
1271-
// <?xml version="1.0"?>
1272-
// <response>
1273-
// <foo bar="value">baz</foo>
1274-
// </response>
1275-
1276-
Context
1277-
~~~~~~~
1278-
1279-
The ``encode()`` method defines a third optional parameter called ``context``
1280-
which defines the configuration options for the XmlEncoder an associative array::
1281-
1282-
$xmlEncoder->encode($array, 'xml', $context);
1283-
1284-
These are the options available:
1285-
1286-
``xml_format_output``
1287-
If set to true, formats the generated XML with line breaks and indentation.
1288-
1289-
``xml_version``
1290-
Sets the XML version attribute (default: ``1.1``).
1291-
1292-
``xml_encoding``
1293-
Sets the XML encoding attribute (default: ``utf-8``).
1294-
1295-
``xml_standalone``
1296-
Adds standalone attribute in the generated XML (default: ``true``).
1297-
1298-
``xml_root_node_name``
1299-
Sets the root node name (default: ``response``).
1300-
1301-
``remove_empty_tags``
1302-
If set to true, removes all empty tags in the generated XML (default: ``false``).
13031277

13041278
The ``CsvEncoder``
13051279
------------------

‎form/form_collections.rst

Lines changed: 23 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,13 @@ the following ``data-prototype`` attribute to the existing ``<ul>`` in your temp
242242

243243
.. code-block:: html+twig
244244

245-
<ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}">
245+
<ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}"></ul>
246+
247+
Now add a button just next to the ``<ul>`` to dynamically add a new tag
248+
249+
.. code-block:: html+twig
250+
251+
<button type="button" class="add_item_link" data-collection-holder-class="tags">Add a tag</button>
246252

247253
On the rendered page, the result will look something like this:
248254

@@ -274,38 +280,27 @@ On the rendered page, the result will look something like this:
274280
and you need to adjust the following JavaScript accordingly.
275281

276282
The goal of this section will be to use JavaScript to read this attribute
277-
and dynamically add new tag forms when the user clicks a "Add a tag" link.
283+
and dynamically add new tag forms when the user clicks the "Add a tag" button.
278284
This example uses jQuery and assumes you have it included somewhere on your page.
279285

280-
Add a ``script`` tag somewhere on your page so you can start writing some JavaScript.
281-
282-
First, add a link to the bottom of the "tags" list via JavaScript. Second,
283-
bind to the "click" event of that link so you can add a new tag form (``addTagForm()``
284-
will be show next):
286+
Add a ``script`` tag somewhere on your page so you can start writing some
287+
JavaScript. In this script, bind to the "click" event of the "Add a tag"
288+
button so you can add a new tag form (``addFormToCollection()`` will be show next):
285289

286290
.. code-block:: javascript
287291
288-
var $collectionHolder;
289-
290-
// setup an "add a tag" link
291-
var $addTagButton = $('<button type="button" class="add_tag_link">Add a tag</button>');
292-
var $newLinkLi = $('<li></li>').append($addTagButton);
293-
294292
jQuery(document).ready(function() {
295293
// Get the ul that holds the collection of tags
296-
$collectionHolder = $('ul.tags');
297-
298-
// add the "add a tag" anchor and li to the tags ul
299-
$collectionHolder.append($newLinkLi);
300-
294+
var $tagsCollectionHolder = $('ul.tags');
301295
// count the current form inputs we have (e.g. 2), use that as the new
302296
// index when inserting a new item (e.g. 2)
303-
$collectionHolder.data('index', $collectionHolder.find('input').length);
297+
$tagsCollectionHolder.data('index', $tagsCollectionHolder.find('input').length);
304298
305-
$addTagButton.on('click', function(e) {
299+
$('body').on('click', '.add_item_link', function(e) {
300+
var $collectionHolderClass = $(e.currentTarget).data('collectionHolderClass');
306301
// add a new tag form (see next code block)
307-
addTagForm($collectionHolder, $newLinkLi);
308-
});
302+
addFormToCollection($collectionHolderClass);
303+
})
309304
});
310305
311306
The ``addTagForm()`` function's job will be to use the ``data-prototype`` attribute
@@ -319,7 +314,10 @@ one example:
319314

320315
.. code-block:: javascript
321316
322-
function addTagForm($collectionHolder, $newLinkLi) {
317+
function addFormToCollection($collectionHolderClass) {
318+
// Get the ul that holds the collection of tags
319+
var $collectionHolder = $('.' + $collectionHolderClass);
320+
323321
// Get the data-prototype explained earlier
324322
var prototype = $collectionHolder.data('prototype');
325323
@@ -341,7 +339,8 @@ one example:
341339
342340
// Display the form in the page in an li, before the "Add a tag" link li
343341
var $newFormLi = $('<li></li>').append(newForm);
344-
$newLinkLi.before($newFormLi);
342+
// Add the new form at the end of the list
343+
$collectionHolder.append($newFormLi)
345344
}
346345
347346
.. note::

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,20 @@ If an array, the keys of the ``choices`` array must be used as keys::
1313
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
1414
// ...
1515

16+
$builder->add('fruits', ChoiceType::class, [
17+
'choices' => [
18+
'Apple' => 1,
19+
'Banana' => 2,
20+
'Durian' => 3,
21+
],
22+
'choice_attr' => [
23+
'Apple' => ['data-color' => 'Red'],
24+
'Banana' => ['data-color' => 'Yellow'],
25+
'Durian' => ['data-color' => 'Green'],
26+
],
27+
]);
28+
29+
// or use a callable
1630
$builder->add('attending', ChoiceType::class, [
1731
'choices' => [
1832
'Yes' => true,

‎service_container/calls.rst

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -90,9 +90,6 @@ instead of mutating the object they were called on::
9090
{
9191
private $logger;
9292

93-
/**
94-
* @return static
95-
*/
9693
public function withLogger(LoggerInterface $logger)
9794
{
9895
$new = clone $this;
@@ -146,3 +143,31 @@ The configuration to tell the container it should do so would be like:
146143
147144
$container->register(MessageGenerator::class)
148145
->addMethodCall('withLogger', [new Reference('logger')], true);
146+
147+
.. tip::
148+
149+
If autowire is enabled, you can also use annotations; with the previous
150+
example it would be::
151+
152+
/**
153+
* @required
154+
* @return static
155+
*/
156+
public function withLogger(LoggerInterface $logger)
157+
{
158+
$new = clone $this;
159+
$new->logger = $logger;
160+
161+
return $new;
162+
}
163+
164+
You can also leverage the PHP 8 ``static`` return type instead of the
165+
``@return static`` annotation. If you don't want a method with a
166+
PHP 8 ``static`` return type and a ``@required`` annotation to behave as
167+
a wither, you can add a ``@return $this`` annotation to disable the
168+
*returns clone* feature.
169+
170+
.. versionadded:: 5.1
171+
172+
Support for the PHP 8 ``static`` return type was introduced in
173+
Symfony 5.1.

0 commit comments

Comments
 (0)
0