Skip to content

Commit 7681e39

Browse files
weaverryanweaverryan
committed
Merge branch '2.7'
* 2.7: (47 commits) Removed duplicate "long"s terminate file with newline move title back and move description to separate file as suggested in PR #4892 move title out of included file as suggested in PR #4892 Add possible values for widget_type [#4842] Making 2 sentences changes as suggested by WouterJ in pull request #4842 Add meaning of yellow icon for number of queries Fixing bad link name fix typo in event flow diagrams Many fixes thanks to stof, WouterJ, xabbuh and dupuchba added Jakub as a merger for the DomCrawler component Changes thanks to WouterJ and xabbuh [#5094] Removing mkdir - it's not needed (thanks xabbuh) some tweaks to #4601 Moving index down to correct section [#4989] Language tweaks and making the example simpler Remove useless setLocale() call and add code block with locale setter Finaly touches on translation locale setting note Review note about setting the translator locale in a controller. ...
2 parents 3fb0d42 + 8566263 commit 7681e39

36 files changed

+542
-521
lines changed

‎best_practices/forms.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,3 +207,21 @@ Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement
207207
for clarity. This isn't technically needed, since ``isValid()`` first calls
208208
``isSubmitted()``. But without this, the flow doesn't read well as it *looks*
209209
like the form is *always* processed (even on the GET request).
210+
211+
Custom Form Field Types
212+
-----------------------
213+
214+
.. best-practice::
215+
216+
Add the ``app_`` prefix to your custom form field types to avoid collisions.
217+
218+
Custom form field types inherit from the ``AbstractType`` class, which defines the
219+
``getName()`` method to configure the name of that form type. These names must
220+
be unique in the application.
221+
222+
If a custom form type uses the same name as any of the Symfony's built-in form
223+
types, it will override it. The same happens when the custom form type matches
224+
any of the types defined by the third-party bundles installed in your application.
225+
226+
Add the ``app_`` prefix to your custom form field types to avoid name collisions
227+
that can lead to hard to debug errors.

‎book/controller.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -451,7 +451,7 @@ Or, if you want to redirect externally, just use ``redirect()`` and pass it the
451451
}
452452

453453
By default, the ``redirectToRoute()`` method performs a 302 (temporary) redirect. To
454-
perform a 301 (permanent) redirect, modify the second argument::
454+
perform a 301 (permanent) redirect, modify the third argument::
455455

456456
public function indexAction()
457457
{

‎book/doctrine.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -646,6 +646,9 @@ to easily fetch objects based on multiple conditions::
646646

647647
If you click the icon, the profiler will open, showing you the exact
648648
queries that were made.
649+
650+
The icon will turn yellow if there were more than 50 queries on the
651+
page. This could indicate that something is not correct.
649652

650653
Updating an Object
651654
~~~~~~~~~~~~~~~~~~

‎book/forms.rst‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1061,9 +1061,16 @@ that will house the logic for building the task form::
10611061
}
10621062
}
10631063

1064-
This new class contains all the directions needed to create the task form
1065-
(note that the ``getName()`` method should return a unique identifier for this
1066-
form "type"). It can be used to quickly build a form object in the controller::
1064+
.. caution::
1065+
1066+
The ``getName()`` method returns the identifier of this form "type". These
1067+
identifiers must be unique in the application. Unless you want to override
1068+
a built-in type, they should be different from the default Symfony types
1069+
and from any type defined by a third-party bundle installed in your application.
1070+
Consider prefixing your types with ``app_`` to avoid identifier collisions.
1071+
1072+
This new class contains all the directions needed to create the task form. It can
1073+
be used to quickly build a form object in the controller::
10671074

10681075
// src/AppBundle/Controller/DefaultController.php
10691076

‎book/http_fundamentals.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -460,7 +460,7 @@ by adding an entry for ``/contact`` to your routing configuration file:
460460
461461
When someone visits the ``/contact`` page, this route is matched, and the
462462
specified controller is executed. As you'll learn in the :doc:`routing chapter </book/routing>`,
463-
the ``AcmeDemoBundle:Main:contact`` string is a short syntax that points to a
463+
the ``AppBundle:Main:contact`` string is a short syntax that points to a
464464
specific PHP method ``contactAction`` inside a class called ``MainController``::
465465

466466
// src/AppBundle/Controller/MainController.php

‎book/translation.rst‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -427,17 +427,28 @@ via the ``request`` object::
427427
public function indexAction(Request $request)
428428
{
429429
$locale = $request->getLocale();
430-
431-
$request->setLocale('en_US');
432430
}
433431

434-
.. tip::
432+
To set the user's locale, you may want to create a custom event listener
433+
so that it's set before any other parts of the system (i.e. the translator)
434+
need it::
435435

436-
Read :doc:`/cookbook/session/locale_sticky_session` to learn how to store
437-
the user's locale in the session.
436+
public function onKernelRequest(GetResponseEvent $event)
437+
{
438+
$request = $event->getRequest();
438439

439-
.. index::
440-
single: Translations; Fallback and default locale
440+
// some logic to determine the $locale
441+
$request->getSession()->set('_locale', $locale);
442+
}
443+
444+
Read :doc:`/cookbook/session/locale_sticky_session` for more on the topic.
445+
446+
.. note::
447+
448+
Setting the locale using ``$request->setLocale()`` in the controller
449+
is too late to affect the translator. Either set the locale via a listener
450+
(like above), the URL (see next) or call ``setLocale()`` directly on
451+
the ``translator`` service.
441452

442453
See the :ref:`book-translation-locale-url` section below about setting the
443454
locale via routing.
@@ -518,6 +529,9 @@ in your application.
518529
Read :doc:`/cookbook/routing/service_container_parameters` to learn how to
519530
avoid hardcoding the ``_locale`` requirement in all your routes.
520531

532+
.. index::
533+
single: Translations; Fallback and default locale
534+
521535
Setting a default Locale
522536
~~~~~~~~~~~~~~~~~~~~~~~~
523537

‎components/asset/introduction.rst‎

Lines changed: 65 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -26,15 +26,16 @@ simple. Hardcoding URLs can be a disadvantage because:
2626
asset. When using the Asset component, you can group assets in packages to
2727
avoid repeating the common part of their path;
2828
* **Versioning is difficult**: it has to be custom managed for each
29-
application. Adding a version to the asset URLs is essential for some applications
30-
because it allows to control how the assets are cached. The Asset component
31-
allows to define different versioning strategies for each package;
29+
application. Adding a version (e.g. ``main.css?v=5``) to the asset URLs
30+
is essential for some applications because it allows you to control how
31+
the assets are cached. The Asset component allows you to define different
32+
versioning strategies for each package;
3233
* **Moving assets location** is cumbersome and error-prone: it requires you to
3334
carefully update the URLs of all assets included in all templates. The Asset
3435
component allows to move assets effortlessly just by changing the base path
3536
value associated with the package of assets;
36-
* **It's nearly impossible to use multiple CDNs**: this technique requires to
37-
change the URL of the asset randomly for each request. The Asset component
37+
* **It's nearly impossible to use multiple CDNs**: this technique requires
38+
you to change the URL of the asset randomly for each request. The Asset component
3839
provides out-of-the-box support for any number of multiple CDNs, both regular
3940
(``http://``) and secure (``https://``).
4041

@@ -65,7 +66,7 @@ any versioning::
6566
echo $package->getUrl('/image.png');
6667
// result: /image.png
6768

68-
Packages implement the :class:`Symfony\\Component\\Asset\\PackageInterface`,
69+
Packages implement :class:`Symfony\\Component\\Asset\\PackageInterface`,
6970
which defines the following two methods:
7071

7172
:method:`Symfony\\Component\\Asset\\PackageInterface::getVersion`
@@ -74,18 +75,27 @@ which defines the following two methods:
7475
:method:`Symfony\\Component\\Asset\\PackageInterface::getUrl`
7576
Returns an absolute or root-relative public path.
7677

78+
With a package, you can:
79+
80+
A) :ref:`version the assets <component-assets-versioning>`;
81+
B) set a :ref:`common base path <component-assets-path-package>` (e.g. ``/css``)
82+
for the assets;
83+
C) :ref:`configure a CDN <component-assets-cdn>` for the assets
84+
85+
.. _component-assets-versioning:
86+
7787
Versioned Assets
7888
~~~~~~~~~~~~~~~~
7989

80-
One of the main features of the Asset component is to manage the versioning of
81-
the application's assets. Asset versions are commonly used to control how these
82-
assets are cached.
90+
One of the main features of the Asset component is the ability to manage
91+
the versioning of the application's assets. Asset versions are commonly used
92+
to control how these assets are cached.
8393

84-
Instead of relying on a simple version mechanism, the Asset component allows to
85-
define advanced versioning strategies via PHP classes. The two built-in strategies
86-
provided by the component are :class:`Symfony\\Component\\Asset\\VersionStrategy\\EmptyVersionStrategy`,
94+
Instead of relying on a simple version mechanism, the Asset component allows
95+
you to define advanced versioning strategies via PHP classes. The two built-in
96+
strategies are the :class:`Symfony\\Component\\Asset\\VersionStrategy\\EmptyVersionStrategy`,
8797
which doesn't add any version to the asset and :class:`Symfony\\Component\\Asset\\VersionStrategy\\StaticVersionStrategy`,
88-
which allows to set the version with a format string.
98+
which allows you to set the version with a format string.
8999

90100
In this example, the ``StaticVersionStrategy`` is used to append the ``v1``
91101
suffix to any asset path::
@@ -143,13 +153,15 @@ every day::
143153
}
144154
}
145155

156+
.. _component-assets-path-package:
157+
146158
Grouped Assets
147159
~~~~~~~~~~~~~~
148160

149-
It's common for applications to store their assets in a common path. If that's
150-
your case, replace the default :class:`Symfony\\Component\\Asset\\Package` class
151-
by :class:`Symfony\\Component\\Asset\\PathPackage` to avoid repeating the same
152-
path time and again::
161+
Often, many assets live under a common path (e.g. ``/static/images``). If
162+
that's your case, replace the default :class:`Symfony\\Component\\Asset\\Package`
163+
class with :class:`Symfony\\Component\\Asset\\PathPackage` to avoid repeating
164+
that path over and over again::
153165

154166
use Symfony\Component\Asset\PathPackage;
155167
// ...
@@ -162,9 +174,9 @@ path time and again::
162174
Request Context Aware Assets
163175
............................
164176

165-
If you are also using the HttpFoundation component in your project, for example
166-
in a Symfony application, the ``PathPackage`` class can take into account the
167-
context of the current request::
177+
If you are also using the :doc:`HttpFoundation </components/http_foundation/introduction>`
178+
component in your project (for instance, in a Symfony application), the ``PathPackage``
179+
class can take into account the context of the current request::
168180

169181
use Symfony\Component\Asset\PathPackage;
170182
use Symfony\Component\Asset\Context\RequestStackContext;
@@ -179,10 +191,13 @@ context of the current request::
179191
echo $package->getUrl('/logo.png');
180192
// result: /somewhere/static/images/logo.png?v1
181193

182-
When the request context is set (via an optional third argument), in addition to
183-
the configured base path, ``PathPackage`` also prepends the current request base
184-
URL (``/somewhere/`` in this example) to assets. This allows your website to be
185-
hosted anywhere under the web server root directory.
194+
Now that the request context is set, the ``PathPackage`` will prepend the
195+
current request base URL. So, for example, if your entire site is hosted under
196+
the ``/somewhere`` directory of your web server root directory and the configured
197+
base path is ``/static/images``, all paths will be prefixed with
198+
``/somewhere/static/images``.
199+
200+
.. _component-assets-cdn:
186201

187202
Absolute Assets and CDNs
188203
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -202,25 +217,44 @@ class to generate absolute URLs for their assets::
202217
echo $package->getUrl('/logo.png');
203218
// result: http://static.example.com/images/logo.png?v1
204219

220+
You can also pass a schema-agnostic URL::
221+
222+
use Symfony\Component\Asset\UrlPackage;
223+
// ...
224+
225+
$package = new UrlPackage(
226+
'//static.example.com/images/',
227+
new StaticVersionStrategy('v1')
228+
);
229+
230+
echo $package->getUrl('/logo.png');
231+
// result: //static.example.com/images/logo.png?v1
232+
233+
This is useful because assets will automatically be requested via HTTPS if
234+
a visitor is viewing your site in https. Just make sure that your CDN host
235+
supports https.
236+
205237
In case you serve assets from more than one domain to improve application
206-
performance, pass an array of URLs as the first argument of ``UrlPackage``
238+
performance, pass an array of URLs as the first argument to the ``UrlPackage``
207239
constructor::
208240

209241
use Symfony\Component\Asset\UrlPackage;
210242
// ...
211243

212244
$urls = array(
213-
'http://static1.example.com/images/',
214-
'http://static2.example.com/images/',
245+
'//static1.example.com/images/',
246+
'//static2.example.com/images/',
215247
);
216248
$package = new UrlPackage($urls, new StaticVersionStrategy('v1'));
217249

218250
echo $package->getUrl('/logo.png');
219251
// result: http://static1.example.com/images/logo.png?v1
252+
echo $package->getUrl('/icon.png');
253+
// result: http://static2.example.com/images/icon.png?v1
220254

221-
The selection of the domain which will serve the asset is deterministic, meaning
222-
that each asset will be always served by the same domain. This behavior simplifies
223-
the management of HTTP cache.
255+
For each asset, one of the URLs will be randomly used. But, the selection
256+
is deterministic, meaning that each asset will be always served by the same
257+
domain. This behavior simplifies the management of HTTP cache.
224258

225259
Request Context Aware Assets
226260
............................
@@ -241,6 +275,7 @@ protocol-relative URLs for HTTPs requests, any base URL for HTTP requests)::
241275
);
242276

243277
echo $package->getUrl('/logo.png');
278+
// assuming the RequestStackContext says that we are on a secure host
244279
// result: https://example.com/logo.png?v1
245280

246281
Named Packages

‎components/using_components.rst‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,6 @@ whatever component you want.
3636
file in your directory. In that case, no worries! Just run
3737
``php composer.phar require symfony/finder``.
3838

39-
If you know you need a specific version of the library, add that to the command:
40-
41-
.. code-block:: bash
42-
43-
$ composer require symfony/finder
44-
4539
**3.** Write your code!
4640

4741
Once Composer has downloaded the component(s), all you need to do is include
@@ -51,7 +45,8 @@ immediately::
5145

5246
// File example: src/script.php
5347

54-
// update this to the path to the "vendor/" directory, relative to this file
48+
// update this to the path to the "vendor/"
49+
// directory, relative to this file
5550
require_once __DIR__.'/../vendor/autoload.php';
5651

5752
use Symfony\Component\Finder\Finder;

‎contributing/code/core_team.rst‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,14 +60,19 @@ Active Core Members
6060
MonologBridge_, and TwigBridge_ components;
6161

6262
* **Kévin Dunglas** (`dunglas`_) can merge into the Serializer_
63-
component.
63+
component;
64+
65+
* **Abdellatif AitBoudad** (`aitboudad`_) can merge into the Translation_
66+
component;
67+
68+
* **Jakub Zalas** (`jakzal`_) can merge into the DomCrawler_ component.
6469

6570
* **Deciders** (``@symfony/deciders`` on GitHub):
6671

67-
* **Jakub Zalas** (`jakzal`_);
6872
* **Jordi Boggiano** (`seldaek`_);
6973
* **Lukas Kahwe Smith** (`lsmith77`_);
70-
* **Ryan Weaver** (`weaverryan`_).
74+
* **Ryan Weaver** (`weaverryan`_);
75+
* **Christian Flothmann** (`xabbuh`_).
7176

7277
Core Membership Application
7378
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -165,6 +170,7 @@ discretion of the **Project Leader**.
165170
.. _PropertyAccess: https://github.com/symfony/PropertyAccess
166171
.. _Routing: https://github.com/symfony/Routing
167172
.. _Serializer: https://github.com/symfony/Serializer
173+
.. _Translation: https://github.com/symfony/Translation
168174
.. _Stopwatch: https://github.com/symfony/Stopwatch
169175
.. _TwigBridge: https://github.com/symfony/TwigBridge
170176
.. _Validator: https://github.com/symfony/Validator
@@ -181,3 +187,5 @@ discretion of the **Project Leader**.
181187
.. _`Seldaek`: https://github.com/Seldaek/
182188
.. _`lsmith77`: https://github.com/lsmith77/
183189
.. _`weaverryan`: https://github.com/weaverryan/
190+
.. _`aitboudad`: https://github.com/aitboudad/
191+
.. _`xabbuh`: https://github.com/xabbuh/

0 commit comments

Comments
 (0)