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

Commit 7639556

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '3.4' into 4.0
* 3.4: (24 commits) Added a caution note about env vars and the profiler Use gender-neutral language in the main Serializer article Fix error on @MaxDepth property for annotation, yaml and xml. Change property according to documentation Link to the asset component documentation New section about JSON file manifest strategy Removed the term "simple" from creating a new page Update datetime.rst components/phpunit_bridge.rst Add best practice note about version Fixed formatting Autowiring - Rephrase aliasing when multiple classes implement same interface Use is_numeric() ...
2 parents 5c5218a + 3fd845a commit 7639556

File tree

14 files changed

+98
-36
lines changed

14 files changed

+98
-36
lines changed

‎components/asset.rst

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,33 @@ string as the second argument of the ``StaticVersionStrategy`` constructor::
139139
echo $package->getUrl('image.png');
140140
// result: v1/image.png
141141

142+
JSON File Manifest
143+
..................
144+
145+
A popular strategy to manage asset versioning, which is used by tools such as
146+
`Webpack`_, is to generate a JSON file mapping all source file names to their
147+
corresponding output file:
148+
149+
.. code-block:: json
150+
151+
// rev-manifest.json
152+
{
153+
"css/app.css": "build/css/app.b916426ea1d10021f3f17ce8031f93c2.css",
154+
"js/app.js": "build/js/app.13630905267b809161e71d0f8a0c017b.js",
155+
"...": "..."
156+
}
157+
158+
In those cases, use the
159+
:class:`Symfony\\Component\\Asset\\VersionStrategy\\JsonManifestVersionStrategy`::
160+
161+
use Symfony\Component\Asset\Package;
162+
use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
163+
164+
$package = new Package(new JsonManifestVersionStrategy(__DIR__'./rev-manifest.json'));
165+
166+
echo $package->getUrl('css/app.css');
167+
// result: build/css/app.b916426ea1d10021f3f17ce8031f93c2.css
168+
142169
Custom Version Strategies
143170
.........................
144171

@@ -349,3 +376,4 @@ Learn more
349376
----------
350377

351378
.. _Packagist: https://packagist.org/packages/symfony/asset
379+
.. _`Webpack`: https://webpack.js.org/

‎components/phpunit_bridge.rst

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,19 @@ Installation
2828

2929
.. code-block:: terminal
3030
31-
$ composer require --dev symfony/phpunit-bridge
31+
$ composer require --dev "symfony/phpunit-bridge:*"
3232
3333
Alternatively, you can clone the `<https://github.com/symfony/phpunit-bridge>`_ repository.
3434

3535
.. include:: /components/require_autoload.rst.inc
3636

37+
.. note::
38+
39+
The PHPUnit bridge is designed to work with all maintained versions of
40+
Symfony components, even across different major versions of them. You should
41+
always use its very latest stable major version to get the most accurate
42+
deprecation report.
43+
3744
If you plan to :ref:`write-assertions-about-deprecations` and use the regular
3845
PHPUnit script (not the modified PHPUnit script provided by Symfony), you have
3946
to register a new `test listener`_ called ``SymfonyTestsListener``:

‎components/serializer.rst

Lines changed: 23 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ simple schema.
1313

1414
.. image:: /_images/components/serializer/serializer_workflow.png
1515

16-
As you can see in the picture above, an array is used as a man in
17-
the middle. This way, Encoders will only deal with turning specific
18-
**formats** into **arrays** and vice versa. The same way, Normalizers
16+
As you can see in the picture above, an array is used as an intermediary between
17+
objects and serialized contents. This way, encoders will only deal with turning
18+
specific **formats** into **arrays** and vice versa. The same way, Normalizers
1919
will deal with turning specific **objects** into **arrays** and vice versa.
2020

2121
Serialization is a complex topic. This component may not cover all your use cases out of the box,
@@ -63,13 +63,13 @@ Serializing an Object
6363
For the sake of this example, assume the following class already
6464
exists in your project::
6565

66-
namespace Acme;
66+
namespace App\Model;
6767

6868
class Person
6969
{
7070
private $age;
7171
private $name;
72-
private $sportsman;
72+
private $sportsperson;
7373
private $createdAt;
7474

7575
// Getters
@@ -89,9 +89,9 @@ exists in your project::
8989
}
9090

9191
// Issers
92-
public function isSportsman()
92+
public function isSportsperson()
9393
{
94-
return $this->sportsman;
94+
return $this->sportsperson;
9595
}
9696

9797
// Setters
@@ -105,9 +105,9 @@ exists in your project::
105105
$this->age = $age;
106106
}
107107

108-
public function setSportsman($sportsman)
108+
public function setSportsperson($sportsperson)
109109
{
110-
$this->sportsman = $sportsman;
110+
$this->sportsperson = $sportsperson;
111111
}
112112

113113
public function setCreatedAt($createdAt)
@@ -119,14 +119,14 @@ exists in your project::
119119
Now, if you want to serialize this object into JSON, you only need to
120120
use the Serializer service created before::
121121

122-
$person = new Acme\Person();
122+
$person = new App\Model\Person();
123123
$person->setName('foo');
124124
$person->setAge(99);
125-
$person->setSportsman(false);
125+
$person->setSportsperson(false);
126126

127127
$jsonContent = $serializer->serialize($person, 'json');
128128

129-
// $jsonContent contains {"name":"foo","age":99,"sportsman":false}
129+
// $jsonContent contains {"name":"foo","age":99,"sportsperson":false}
130130

131131
echo $jsonContent; // or return it in a Response
132132

@@ -140,13 +140,13 @@ Deserializing an Object
140140
You'll now learn how to do the exact opposite. This time, the information
141141
of the ``Person`` class would be encoded in XML format::
142142

143-
use Acme\Person;
143+
use App\Model\Person;
144144

145145
$data = <<<EOF
146146
<person>
147147
<name>foo</name>
148148
<age>99</age>
149-
<sportsman>false</sportsman>
149+
<sportsperson>false</sportsperson>
150150
</person>
151151
EOF;
152152

@@ -187,7 +187,7 @@ The serializer can also be used to update an existing object::
187187
$person = new Person();
188188
$person->setName('bar');
189189
$person->setAge(99);
190-
$person->setSportsman(true);
190+
$person->setSportsperson(true);
191191

192192
$data = <<<EOF
193193
<person>
@@ -197,7 +197,7 @@ The serializer can also be used to update an existing object::
197197
EOF;
198198

199199
$serializer->deserialize($data, Person::class, 'xml', array('object_to_populate' => $person));
200-
// $person = Acme\Person(name: 'foo', age: '69', sportsman: true)
200+
// $person = App\Model\Person(name: 'foo', age: '69', sportsperson: true)
201201

202202
This is a common need when working with an ORM.
203203

@@ -400,7 +400,7 @@ method on the normalizer definition::
400400
$encoder = new JsonEncoder();
401401

402402
$serializer = new Serializer(array($normalizer), array($encoder));
403-
$serializer->serialize($person, 'json'); // Output: {"name":"foo","sportsman":false}
403+
$serializer->serialize($person, 'json'); // Output: {"name":"foo","sportsperson":false}
404404

405405
.. _component-serializer-converting-property-names-when-serializing-and-deserializing:
406406

@@ -512,8 +512,8 @@ Serializing Boolean Attributes
512512
------------------------------
513513

514514
If you are using isser methods (methods prefixed by ``is``, like
515-
``Acme\Person::isSportsman()``), the Serializer component will automatically
516-
detect and use it to serialize related attributes.
515+
``App\Model\Person::isSportsperson()``), the Serializer component will
516+
automatically detect and use it to serialize related attributes.
517517

518518
The ``ObjectNormalizer`` also takes care of methods starting with ``has``, ``add``
519519
and ``remove``.
@@ -523,7 +523,7 @@ Using Callbacks to Serialize Properties with Object Instances
523523

524524
When serializing, you can set a callback to format a specific object property::
525525

526-
use Acme\Person;
526+
use App\Model\Person;
527527
use Symfony\Component\Serializer\Encoder\JsonEncoder;
528528
use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
529529
use Symfony\Component\Serializer\Serializer;
@@ -775,7 +775,7 @@ Here, we set it to 2 for the ``$child`` property:
775775
/**
776776
* @MaxDepth(2)
777777
*/
778-
public $foo;
778+
public $child;
779779
780780
// ...
781781
}
@@ -784,7 +784,7 @@ Here, we set it to 2 for the ``$child`` property:
784784
785785
Acme\MyObj:
786786
attributes:
787-
foo:
787+
child:
788788
max_depth: 2
789789
790790
.. code-block:: xml
@@ -796,7 +796,7 @@ Here, we set it to 2 for the ``$child`` property:
796796
http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
797797
>
798798
<class name="Acme\MyObj">
799-
<attribute name="foo" max-depth="2" />
799+
<attribute name="child" max-depth="2" />
800800
</class>
801801
</serializer>
802802

‎configuration/external_parameters.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,10 @@ the following:
130130
environment variables, exposing sensitive information such as the database
131131
credentials.
132132

133+
The values of the env vars are also exposed in the web interface of the
134+
:doc:`Symfony profiler </profiler>`. In practice this shouldn't be a
135+
problem because the web profiler must **never** be enabled in production.
136+
133137
Constants
134138
---------
135139

‎console/lazy_commands.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ which will be responsible for returning ``Command`` instances::
1818
use Symfony\Component\Console\CommandLoader\FactoryCommandLoader;
1919

2020
$commandLoader = new FactoryCommandLoader(array(
21-
'app:heavy' => function () { return new HeavyCommand() },
21+
'app:heavy' => function () { return new HeavyCommand(); },
2222
));
2323

2424
$application = new Application();
@@ -48,7 +48,7 @@ array of ``Command`` factories as its only constructor argument::
4848
use Symfony\Component\Console\CommandLoader\FactoryCommandLoader;
4949

5050
$commandLoader = new FactoryCommandLoader(array(
51-
'app:foo' => function () { return new FooCommand() },
51+
'app:foo' => function () { return new FooCommand(); },
5252
'app:bar' => array(BarCommand::class, 'create'),
5353
));
5454

‎console/style.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -235,11 +235,11 @@ User Input Methods
235235
the third argument::
236236

237237
$io->ask('Number of workers to start', 1, function ($number) {
238-
if (!is_integer($number)) {
239-
throw new \RuntimeException('You must type an integer.');
238+
if (!is_numeric($number)) {
239+
throw new \RuntimeException('You must type a number.');
240240
}
241241

242-
return $number;
242+
return (int) $number;
243243
});
244244

245245
:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::askHidden`

‎contributing/code/bc.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ backward compatibility promise:
8282
+-----------------------------------------------+-----------------------------+
8383
| Add a default value to an argument | Yes |
8484
+-----------------------------------------------+-----------------------------+
85+
| Add a return type to an implemented method | Yes |
86+
+-----------------------------------------------+-----------------------------+
8587

8688
Using our Classes
8789
~~~~~~~~~~~~~~~~~
@@ -173,6 +175,8 @@ Remove default value of an argument No
173175
Add type hint to an argument No
174176
Remove type hint of an argument No
175177
Change argument type No
178+
Add return type No
179+
Remove return type No [9]_
176180
Change return type No
177181
**Constants**
178182
Add constant Yes
@@ -229,6 +233,8 @@ Remove default value of an argument No
229233
Add type hint to an argument No [7]_ [8]_
230234
Remove type hint of an argument No [7]_ [8]_
231235
Change argument type No [7]_ [8]_
236+
Add return type No [7]_ [8]_
237+
Remove return type No [7]_ [8]_ [9]_
232238
Change return type No [7]_ [8]_
233239
**Protected Methods**
234240
Add protected method Yes
@@ -244,6 +250,8 @@ Remove default value of an argument No [7]_
244250
Add type hint to an argument No [7]_ [8]_
245251
Remove type hint of an argument No [7]_ [8]_
246252
Change argument type No [7]_ [8]_
253+
Add return type No [7]_ [8]_
254+
Remove return type No [7]_ [8]_ [9]_
247255
Change return type No [7]_ [8]_
248256
**Private Methods**
249257
Add private method Yes
@@ -257,6 +265,8 @@ Remove default value of an argument Yes
257265
Add type hint to an argument Yes
258266
Remove type hint of an argument Yes
259267
Change argument type Yes
268+
Add return type Yes
269+
Remove return type Yes
260270
Change return type Yes
261271
**Static Methods**
262272
Turn non static into static No [7]_ [8]_
@@ -300,6 +310,8 @@ Change value of a constant Yes [1]_ [5]_
300310
Changing an argument type is only possible with a parent type.
301311
Changing a return type is only possible with a child type.
302312
313+
.. [9] Allowed for the ``void`` return type.
314+
303315
.. _Semantic Versioning: https://semver.org/
304316
.. _scalar type: https://php.net/manual/en/function.is-scalar.php
305317
.. _boolean values: https://php.net/manual/en/function.boolval.php

‎contributing/code/core_team.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ Active Core Members
9797
* **Tobias Nyholm** (`Nyholm`_) manages the official and contrib recipes
9898
repositories;
9999

100-
* **Samuel Rozé** (`sroze`_) can merge into Messenger_ component.
100+
* **Samuel Rozé** (`sroze`_) can merge into the Messenger_ component.
101101

102102
* **Deciders Team** (``@symfony/deciders`` on GitHub):
103103

‎controller/argument_value_resolver.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,8 +88,11 @@ retrieved from the token storage::
8888
namespace App\ArgumentResolver;
8989

9090
use App\Entity\User;
91+
use Symfony\Component\HttpFoundation\Request;
9192
use Symfony\Component\HttpKernel\Controller\ArgumentValueResolverInterface;
93+
use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
9294
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
95+
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
9396

9497
class UserValueResolver implements ArgumentValueResolverInterface
9598
{

‎frontend/encore/versioning.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,8 @@ like normal:
5959
<script src="{{ asset('build/app.js') }}"></script>
6060
6161
<link href="{{ asset('build/dashboard.css') }}" rel="stylesheet" />
62+
63+
Learn more
64+
----------
65+
66+
* :doc:`/components/asset`

‎page_creation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Create your First Page in Symfony
88
=================================
99

1010
Creating a new page - whether it's an HTML page or a JSON endpoint - is a
11-
simple two-step process:
11+
two-step process:
1212

1313
#. **Create a route**: A route is the URL (e.g. ``/about``) to your page and
1414
points to a controller;

‎reference/forms/types/collection.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,7 +343,7 @@ type::
343343
entry_type
344344
~~~~~~~~~~
345345

346-
**type**: ``string`` or :class:`Symfony\\Component\\Form\\FormTypeInterface` **default**: ``Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType``
346+
**type**: ``string`` **default**: ``Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType``
347347

348348
This is the field type for each item in this collection (e.g. ``TextType``,
349349
``ChoiceType``, etc). For example, if you have an array of email addresses,

‎reference/forms/types/datetime.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,8 @@ If the ``widget`` option is set to ``single_text``, this option specifies
109109
the format of the input, i.e. how Symfony will interpret the given input
110110
as a datetime string. It defaults to the `RFC 3339`_ format which is used
111111
by the HTML5 ``datetime`` field. Keeping the default value will cause the
112-
field to be rendered as an ``input`` field with ``type="datetime"``.
112+
field to be rendered as an ``input`` field with ``type="datetime"``. For
113+
more information on valid formats, see `Date/Time Format Syntax`_.
113114

114115
.. include:: /reference/forms/types/options/hours.rst.inc
115116

@@ -214,3 +215,4 @@ Field Variables
214215
+----------+------------+----------------------------------------------------------------------+
215216

216217
.. _`RFC 3339`: https://tools.ietf.org/html/rfc3339
218+
.. _`Date/Time Format Syntax`: http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax

‎service_container/autowiring.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -358,9 +358,10 @@ Suppose you create a second class - ``UppercaseTransformer`` that implements
358358
}
359359

360360
If you register this as a service, you now have *two* services that implement the
361-
``App\Util\TransformerInterface`` type. Symfony doesn't know which one should
362-
be used for autowiring, so you need to choose one by creating an alias from the type
363-
to the correct service id (see :ref:`autowiring-interface-alias`).
361+
``App\Util\TransformerInterface`` type. Autowiring subsystem can not decide
362+
which one to use. Remember, autowiring isn't magic; it simply looks for a service
363+
whose id matches the type-hint. So you need to choose one by creating an alias
364+
from the type to the correct service id (see :ref:`autowiring-interface-alias`).
364365

365366
If you want ``Rot13Transformer`` to be the service that's used for autowiring, create
366367
that alias:

0 commit comments

Comments
 (0)
0