Skip to content

Commit f52e138

Browse files
committed
Merge branch '3.4' into 4.0
* 3.4: [symfony#9803] fix minor typos [symfony#9836] fix a minor typo Fix the page title for the mbstring polyfill update Twig documentation links Update licence hint for JMS serializer Update external_resources.rst Add traits to BC policy Mention the DoctrineTestBundle for tests that interact with the database Added the missing versionadded directive Remove duplicate `use` keyword Add missing RuntimeExtensionInterface Document Twig test "rootform"
2 parents 62af33d + bb177d3 commit f52e138

21 files changed

+221
-77
lines changed

best_practices/configuration.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,4 +183,4 @@ just one or two words to describe the purpose of the parameter:
183183
Next: :doc:`/best_practices/business-logic`
184184

185185
.. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle
186-
.. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html
186+
.. _`constant() function`: https://twig.symfony.com/doc/2.x/functions/constant.html

best_practices/templates.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,5 +118,5 @@ be used as a Twig extension.
118118

119119
Next: :doc:`/best_practices/forms`
120120

121-
.. _`Twig`: http://twig.sensiolabs.org/
121+
.. _`Twig`: https://twig.symfony.com/
122122
.. _`Parsedown`: http://parsedown.org/

components/form.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -757,5 +757,5 @@ Learn more
757757
/form/*
758758

759759
.. _Packagist: https://packagist.org/packages/symfony/form
760-
.. _Twig: http://twig.sensiolabs.org
761-
.. _`Twig Configuration`: http://twig.sensiolabs.org/doc/intro.html
760+
.. _Twig: https://twig.symfony.com
761+
.. _`Twig Configuration`: https://twig.symfony.com/doc/2.x/intro.html

components/polyfill_mbstring.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
single: Mbstring
44
single: Components; Polyfill
55

6-
The Symfony Polyfill / Intl Mbstring Component
7-
==============================================
6+
The Symfony Polyfill / Mbstring Component
7+
=========================================
88

99
This component provides a partial, native PHP implementation for the
1010
``mbstring`` PHP extension.

components/serializer.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1024,7 +1024,7 @@ Learn more
10241024
.. seealso::
10251025

10261026
A popular alternative to the Symfony Serializer Component is the third-party
1027-
library, `JMS serializer`_ (released under the Apache license, so incompatible with GPLv2 projects).
1027+
library, `JMS serializer`_ (versions before `v1.12.0` were released under the Apache license, so incompatible with GPLv2 projects).
10281028

10291029
.. _`PSR-1 standard`: https://www.php-fig.org/psr/psr-1/
10301030
.. _`JMS serializer`: https://github.com/schmittjoh/serializer

contributing/code/bc.rst

Lines changed: 134 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,41 @@ covered by our backward compatibility promise:
143143
| Access a private property (via Reflection) | No |
144144
+-----------------------------------------------+-----------------------------+
145145

146+
Using our Traits
147+
~~~~~~~~~~~~~~~~
148+
149+
All traits provided by Symfony may be used in your classes.
150+
151+
.. caution::
152+
153+
The exception to this rule are traits tagged with ``@internal``. Such
154+
traits should not be used.
155+
156+
To be on the safe side, check the following table to know which use cases are
157+
covered by our backward compatibility promise:
158+
159+
+-----------------------------------------------+-----------------------------+
160+
| Use Case | Backward Compatibility |
161+
+===============================================+=============================+
162+
| **If you...** | **Then we guarantee BC...** |
163+
+-----------------------------------------------+-----------------------------+
164+
| Use a trait | Yes |
165+
+-----------------------------------------------+-----------------------------+
166+
| **If you use the trait and...** | **Then we guarantee BC...** |
167+
+-----------------------------------------------+-----------------------------+
168+
| Use it to implement an interface | Yes |
169+
+-----------------------------------------------+-----------------------------+
170+
| Use it to implement an abstract method | Yes |
171+
+-----------------------------------------------+-----------------------------+
172+
| Use it to extend a parent class | Yes |
173+
+-----------------------------------------------+-----------------------------+
174+
| Use it to define an abstract class | Yes |
175+
+-----------------------------------------------+-----------------------------+
176+
| Use a public, protected or private property | Yes |
177+
+-----------------------------------------------+-----------------------------+
178+
| Use a public, protected or private method | Yes |
179+
+-----------------------------------------------+-----------------------------+
180+
146181
Working on Symfony Code
147182
-----------------------
148183

@@ -178,6 +213,9 @@ Change argument type No
178213
Add return type No
179214
Remove return type No [9]_
180215
Change return type No
216+
**Static Methods**
217+
Turn non static into static No
218+
Turn static into non static No
181219
**Constants**
182220
Add constant Yes
183221
Remove constant No
@@ -209,21 +247,28 @@ Move to parent class Yes
209247
Add protected property Yes
210248
Remove protected property No [7]_
211249
Reduce visibility No [7]_
250+
Make public No [7]_
212251
Move to parent class Yes
213252
**Private Properties**
214253
Add private property Yes
254+
Make public or protected Yes
215255
Remove private property Yes
216256
**Constructors**
217257
Add constructor without mandatory arguments Yes [1]_
218258
Remove constructor No
219259
Reduce visibility of a public constructor No
220260
Reduce visibility of a protected constructor No [7]_
221261
Move to parent class Yes
262+
**Destructors**
263+
Add destructor Yes
264+
Remove destructor No
265+
Move to parent class Yes
222266
**Public Methods**
223267
Add public method Yes
224268
Remove public method No
225269
Change name No
226270
Reduce visibility No
271+
Make final No [6]_
227272
Move to parent class Yes
228273
Add argument without a default value No
229274
Add argument with a default value No [7]_ [8]_
@@ -241,6 +286,8 @@ Add protected method Yes
241286
Remove protected method No [7]_
242287
Change name No [7]_
243288
Reduce visibility No [7]_
289+
Make final No [6]_
290+
Make public No [7]_ [8]_
244291
Move to parent class Yes
245292
Add argument without a default value No [7]_
246293
Add argument with a default value No [7]_ [8]_
@@ -257,6 +304,7 @@ Change return type No [7]_ [8]_
257304
Add private method Yes
258305
Remove private method Yes
259306
Change name Yes
307+
Make public or protected Yes
260308
Add argument without a default value Yes
261309
Add argument with a default value Yes
262310
Remove argument Yes
@@ -268,7 +316,7 @@ Change argument type Yes
268316
Add return type Yes
269317
Remove return type Yes
270318
Change return type Yes
271-
**Static Methods**
319+
**Static Methods and Properties**
272320
Turn non static into static No [7]_ [8]_
273321
Turn static into non static No
274322
**Constants**
@@ -277,6 +325,91 @@ Remove constant No
277325
Change value of a constant Yes [1]_ [5]_
278326
================================================== ==============
279327

328+
Changing Traits
329+
~~~~~~~~~~~~~~~
330+
331+
This table tells you which changes you are allowed to do when working on
332+
Symfony's traits:
333+
334+
================================================== ==============
335+
Type of Change Change Allowed
336+
================================================== ==============
337+
Remove entirely No
338+
Change name or namespace No
339+
Use another trait Yes
340+
**Public Properties**
341+
Add public property Yes
342+
Remove public property No
343+
Reduce visibility No
344+
Move to a used trait Yes
345+
**Protected Properties**
346+
Add protected property Yes
347+
Remove protected property No
348+
Reduce visibility No
349+
Make public No
350+
Move to a used trait Yes
351+
**Private Properties**
352+
Add private property Yes
353+
Remove private property No
354+
Make public or protected Yes
355+
Move to a used trait Yes
356+
**Constructors and destructors**
357+
Have constructor or destructor No
358+
**Public Methods**
359+
Add public method Yes
360+
Remove public method No
361+
Change name No
362+
Reduce visibility No
363+
Make final No [6]_
364+
Move to used trait Yes
365+
Add argument without a default value No
366+
Add argument with a default value No
367+
Remove argument No
368+
Add default value to an argument No
369+
Remove default value of an argument No
370+
Add type hint to an argument No
371+
Remove type hint of an argument No
372+
Change argument type No
373+
Change return type No
374+
**Protected Methods**
375+
Add protected method Yes
376+
Remove protected method No
377+
Change name No
378+
Reduce visibility No
379+
Make final No [6]_
380+
Make public No [8]_
381+
Move to used trait Yes
382+
Add argument without a default value No
383+
Add argument with a default value No
384+
Remove argument No
385+
Add default value to an argument No
386+
Remove default value of an argument No
387+
Add type hint to an argument No
388+
Remove type hint of an argument No
389+
Change argument type No
390+
Change return type No
391+
**Private Methods**
392+
Add private method Yes
393+
Remove private method No
394+
Change name No
395+
Make public or protected Yes
396+
Move to used trait Yes
397+
Add argument without a default value No
398+
Add argument with a default value No
399+
Remove argument No
400+
Add default value to an argument No
401+
Remove default value of an argument No
402+
Add type hint to an argument No
403+
Remove type hint of an argument No
404+
Change argument type No
405+
Add return type No
406+
Remove return type No
407+
Change return type No
408+
**Static Methods and Properties**
409+
Turn non static into static No
410+
Turn static into non static No
411+
================================================== ==============
412+
280413
.. [1] Should be avoided. When done, this change must be documented in the
281414
UPGRADE file.
282415

contributing/documentation/standards.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ In addition, documentation follows these rules:
174174
* himself or herself, use themselves
175175

176176
.. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
177-
.. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html
177+
.. _`Twig Coding Standards`: https://twig.symfony.com/doc/2.x/coding_standards.html
178178
.. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3
179179
.. _`American English`: https://en.wikipedia.org/wiki/American_English
180180
.. _`American English Oxford Dictionary`: http://en.oxforddictionaries.com/definition/american_english/

create_framework/http_foundation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,7 @@ component is the start of better interoperability between all frameworks and
288288
applications using it (like `Symfony`_, `Drupal 8`_, `phpBB 3`_, `ezPublish
289289
5`_, `Laravel`_, `Silex`_ and `more`_).
290290

291-
.. _`Twig`: http://twig.sensiolabs.org/
291+
.. _`Twig`: https://twig.symfony.com/
292292
.. _`HTTP specification`: https://tools.ietf.org/wg/httpbis/
293293
.. _`audited`: https://symfony.com/blog/symfony2-security-audit
294294
.. _`Symfony`: https://symfony.com/

introduction/from_flat_php_to_symfony2.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -709,5 +709,5 @@ A good selection of `Symfony community tools`_ can be found on GitHub.
709709
.. _`download Composer`: https://getcomposer.org/download/
710710
.. _`Validator`: https://github.com/symfony/validator
711711
.. _`Varnish`: https://www.varnish-cache.org/
712-
.. _`Twig`: http://twig.sensiolabs.org
712+
.. _`Twig`: https://twig.symfony.com
713713
.. _`Symfony community tools`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

page_creation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,7 @@ Go Deeper with HTTP & Framework Fundamentals
352352

353353
introduction/*
354354

355-
.. _`Twig`: http://twig.sensiolabs.org
355+
.. _`Twig`: https://twig.symfony.com
356356
.. _`Composer`: https://getcomposer.org
357357
.. _`Stellar Development with Symfony`: https://knpuniversity.com/screencast/symfony/setup
358358
.. _`symfony.sh`: https://symfony.sh/

reference/configuration/twig.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -366,4 +366,4 @@ If set to ``true``, Symfony shows an exception whenever a Twig variable,
366366
attribute or method doesn't exist. If set to ``false`` these errors are ignored
367367
and the non-existing values are replaced by ``null``.
368368

369-
.. _`the optimizer extension`: http://twig.sensiolabs.org/doc/api.html#optimizer-extension
369+
.. _`the optimizer extension`: https://twig.symfony.com/doc/2.x/api.html#optimizer-extension

reference/dic_tags.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1183,8 +1183,8 @@ Then, tag it with the ``validator.initializer`` tag (it has no options).
11831183
For an example, see the ``DoctrineInitializer`` class inside the Doctrine
11841184
Bridge.
11851185

1186-
.. _`Twig's documentation`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
1186+
.. _`Twig's documentation`: https://twig.symfony.com/doc/2.x/advanced.html#creating-an-extension
11871187
.. _`Twig official extension repository`: https://github.com/fabpot/Twig-extensions
11881188
.. _`KernelEvents`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/KernelEvents.php
11891189
.. _`SwiftMailer's Plugin Documentation`: http://swiftmailer.org/docs/plugins.html
1190-
.. _`Twig Loader`: http://twig.sensiolabs.org/doc/api.html#loaders
1190+
.. _`Twig Loader`: https://twig.symfony.com/doc/2.x/api.html#loaders

reference/forms/twig_reference.rst

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,28 @@ array).
199199
200200
<option {% if choice is selectedchoice(value) %} selected="selected"{% endif %} ...>
201201
202+
.. _form-twig-rootform:
203+
204+
rootform
205+
~~~~~~~~
206+
207+
This test will check if the current ``form`` does not have a parent form view.
208+
209+
.. code-block:: twig
210+
211+
{# DON'T DO THIS: this simple check can't differentiate between a form having
212+
a parent form view and a form defining a normal form field called 'parent' #}
213+
214+
{% if form.parent is null %}
215+
{{ form_errors(form) }}
216+
{% endif %}
217+
218+
{# DO THIS: this check is always reliable, even if the form defines a field called 'parent' #}
219+
220+
{% if form is rootform %}
221+
{{ form_errors(form) }}
222+
{% endif %}
223+
202224
.. _`twig-reference-form-variables`:
203225

204226
More about Form Variables
@@ -359,4 +381,4 @@ done by using a public ``vars`` property on the
359381
+------------------------+-------------------------------------------------------------------------------------+
360382

361383
.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
362-
.. _`the Twig documentation`: http://twig.sensiolabs.org/doc/templates.html#test-operator
384+
.. _`the Twig documentation`: https://twig.symfony.com/doc/2.x/templates.html#test-operator

reference/twig_reference.rst

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -723,6 +723,20 @@ selectedchoice
723723
Checks if ``selectedValue`` was checked for the provided choice field. Using
724724
this test is the most effective way.
725725

726+
rootform
727+
~~~~~~~~
728+
729+
.. code-block:: twig
730+
731+
{% if form is rootform %}
732+
733+
``form``
734+
**type**: ``FormView``
735+
736+
Checks if the given ``form`` does not have a parent form view. This is the only
737+
safe way of testing it because checking if the form contains a field called
738+
``parent`` is not reliable.
739+
726740
Global Variables
727741
----------------
728742

@@ -746,7 +760,7 @@ The available attributes are:
746760
object representing the security token
747761
* ``app.flashes``, returns flash messages from the session
748762

749-
.. _`Twig Reference`: http://twig.sensiolabs.org/documentation#reference
763+
.. _`Twig Reference`: https://twig.symfony.com/doc/2.x/#reference
750764
.. _`Twig Extensions repository`: https://github.com/twigphp/Twig-extensions
751765
.. _`Twig Extensions documentation`: http://twig-extensions.readthedocs.io/en/latest/
752766
.. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig/Extension

routing/external_resources.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ suppose you want to prefix all application routes with ``/site`` (e.g.
9898

9999
.. code-block:: php-annotations
100100
101-
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
101+
use Symfony\Component\Routing\Annotation\Route;
102102
103103
/**
104104
* @Route("/site")

setup/_update_dep_errors.rst.inc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ Or, you may have deeper issues where different libraries depend on conflicting
2121
versions of other libraries. Check your error message to debug.
2222
2323
Another issue that may happen is that the project dependencies can be installed
24-
in your local computer but not on the remote server. This usually happens when
24+
on your local computer but not on the remote server. This usually happens when
2525
the PHP versions are different on each machine. The solution is to add the
26-
`platform`_ config option in your `composer.json` file to define the highest
27-
PHP version allowed for the dependencies (set it to server's PHP version).
26+
`platform`_ config option to your `composer.json` file to define the highest
27+
PHP version allowed for the dependencies (set it to the server's PHP version).
2828

2929
.. _`platform`: https://getcomposer.org/doc/06-config.md#platform

templating.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -808,11 +808,11 @@ Learn more
808808

809809
/templating/*
810810

811-
.. _`Twig`: http://twig.sensiolabs.org
812-
.. _`tags`: http://twig.sensiolabs.org/doc/tags/index.html
813-
.. _`filters`: http://twig.sensiolabs.org/doc/filters/index.html
814-
.. _`functions`: http://twig.sensiolabs.org/doc/functions/index.html
815-
.. _`add your own extensions`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
816-
.. _`with_context`: http://twig.sensiolabs.org/doc/functions/include.html
817-
.. _`include() function`: http://twig.sensiolabs.org/doc/functions/include.html
818-
.. _`{% include %} tag`: http://twig.sensiolabs.org/doc/tags/include.html
811+
.. _`Twig`: https://twig.symfony.com
812+
.. _`tags`: https://twig.symfony.com/doc/2.x/tags/index.html
813+
.. _`filters`: https://twig.symfony.com/doc/2.x/filters/index.html
814+
.. _`functions`: https://twig.symfony.com/doc/2.x/functions/index.html
815+
.. _`add your own extensions`: https://twig.symfony.com/doc/2.x/advanced.html#creating-an-extension
816+
.. _`with_context`: https://twig.symfony.com/doc/2.x/functions/include.html
817+
.. _`include() function`: https://twig.symfony.com/doc/2.x/functions/include.html
818+
.. _`{% include %} tag`: https://twig.symfony.com/doc/2.x/tags/include.html

0 commit comments

Comments
 (0)