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

Commit 89f98ee

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.0' into 4.1
* 4.0: (27 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 classname typo fixed Update datetime.rst components/phpunit_bridge.rst Add best practice note about version Fixed formatting Autowiring - Rephrase aliasing when multiple classes implement same interface ...
2 parents 2cb5242 + 7639556 commit 89f98ee

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+148
-86
lines changed

‎best_practices/i18n.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Internationalization
33

44
Internationalization and localization adapt the applications and their contents
55
to the specific region or language of the users. In Symfony this is an opt-in
6-
feature that needs to be installed before using it (``composer require translation``).
6+
feature that needs to be installed before using it (``composer require symfony/translation``).
77

88
Translation Source File Location
99
--------------------------------

‎bundles/best_practices.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,7 @@ of Symfony and the latest beta release:
239239
# it helps with testing legacy code and deprecations (composer require symfony/phpunit-bridge)
240240
- ./vendor/bin/simple-phpunit $PHPUNIT_FLAGS
241241
242-
Consider using `Travis cron`_ too to make sure your project is built even if
242+
Consider using the `Travis cron`_ tool to make sure your project is built even if
243243
there are no new pull requests or commits.
244244

245245
Installation

‎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/console/events.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ can wrap or change the exception or do anything useful before the exception is
9595
thrown by the application.
9696

9797
Listeners receive a
98-
:class:`Symfony\\Component\\Console\\Event\\ConsoleExceptionEvent` event::
98+
:class:`Symfony\\Component\\Console\\Event\\ConsoleErrorEvent` event::
9999

100100
use Symfony\Component\Console\Event\ConsoleErrorEvent;
101101
use Symfony\Component\Console\ConsoleEvents;

‎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 1C6A `_ 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;
@@ -860,7 +860,7 @@ Here, we set it to 2 for the ``$child`` property:
860860
/**
861861
* @MaxDepth(2)
862862
*/
863-
public $foo;
863+
public $child;
864864
865865
// ...
866866
}
@@ -869,7 +869,7 @@ Here, we set it to 2 for the ``$child`` property:
869869
870870
Acme\MyObj:
871871
attributes:
872-
foo:
872+
child:
873873
max_depth: 2
874874
875875
.. code-block:: xml
@@ -881,7 +881,7 @@ Here, we set it to 2 for the ``$child`` property:
881881
http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
882882
>
883883
<class name="Acme\MyObj">
884-
<attribute name="foo" max-depth="2" />
884+
<attribute name="child" max-depth="2" />
885885
</class>
886886
</serializer>
887887

‎components/var_dumper.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Alternatively, you can clone the `<https://github.com/symfony/var-dumper>`_ repo
2323
.. note::
2424

2525
If using it inside a Symfony application, make sure that the DebugBundle has
26-
been installed (or run ``composer require debug`` to install it).
26+
been installed (or run ``composer require symfony/debug-bundle`` to install it).
2727

2828
.. _components-var-dumper-dump:
2929

‎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

‎contributing/code/reproducer.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ to a route definition. Then, after creating your project:
6565
of controllers, actions, etc. as in your original application.
6666
#. Create a simple controller and add your routing definition that shows the bug.
6767
#. Don't create or modify any other file.
68-
#. Execute ``composer require server`` and use the ``server:run`` command to browse
69-
to the new route and see if the bug appears or not.
68+
#. Execute ``composer require symfony/web-server-bundle`` and use the ``server:run``
69+
command to browse to the new route and see if the bug appears or not.
7070
#. If you can see the bug, you're done and you can already share the code with us.
7171
#. If you can't see the bug, you must keep making small changes. For example, if
7272
your original route was defined using XML, forget about the previous route

‎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
{

0 commit comments

Comments
 (0)
0