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

Commit 3570711

Browse files
weaverryanweaverryan
committed
Merge branch '2.3' into 2.4
2 parents de03953 + 3e7028d commit 3570711

File tree

21 files changed

+133
-81
lines changed

21 files changed

+133
-81
lines changed

‎book/http_cache.rst

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -526,11 +526,9 @@ the application whether or not the cached response is still valid. If the
526526
cache *is* still valid, your application should return a 304 status code
527527
and no content. This tells the cache that it's ok to return the cached response.
528528

529-
Under this model, you mainly save bandwidth as the representation is not
530-
sent twice to the same client (a 304 response is sent instead). But if you
531-
design your application carefully, you might be able to get the bare minimum
532-
data needed to send a 304 response and save CPU also (see below for an implementation
533-
example).
529+
Under this model, you only save CPU if you're able to determine that the
530+
cached response is still valid by doing *less* work than generating the whole
531+
page again (see below for an implementation example).
534532

535533
.. tip::
536534

@@ -578,10 +576,10 @@ automatically sets the ``Response`` status code to 304.
578576

579577
.. note::
580578

581-
The ``If-None-Match`` request header equals the ``ETag`` header of the
582-
last response sent to the client for the particular resource. This is
583-
how the client and server communicate with each other and decide whether
584-
or not the resource has been updated since it was cached.
579+
The cache sets the ``If-None-Match`` header on the request to the ``ETag``
580+
of the original cached response before sending the request back to the
581+
app. This is how the cache and server communicate with each other and
582+
decide whether or not the resource has been updated since it was cached.
585583

586584
This algorithm is simple enough and very generic, but you need to create the
587585
whole ``Response`` before being able to compute the ETag, which is sub-optimal.
@@ -646,10 +644,10 @@ the ``Response`` will be set to a 304 status code.
646644

647645
.. note::
648646

649-
The ``If-Modified-Since`` request header equals the ``Last-Modified``
650-
header of the last response sent to the client for the particular resource.
651-
This is how the client and server communicate with each other and decide
652-
whether or not the resource has been updated since it was cached.
647+
The cache sets the ``If-Modified-Since`` header on the request to the ``Last-Modified``
648+
of the original cached response before sending the request back to the
649+
app. This is how the cache and server communicate with each other and
650+
decide whether or not the resource has been updated since it was cached.
653651

654652
.. index::
655653
single: Cache; Conditional get

‎book/internals.rst

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,10 @@ Event):
172172
#. Listeners of the ``kernel.response`` event can manipulate the ``Response``
173173
(content and headers);
174174

175-
#. The Response is returned.
175+
#. The Response is returned;
176+
177+
#. Listeners of the ``kernel.terminate`` event can perform tasks after the
178+
Response has been served.
176179

177180
If an Exception is thrown during processing, the ``kernel.exception`` is
178181
notified and listeners are given a chance to convert the Exception to a
@@ -367,6 +370,8 @@ The FrameworkBundle registers several listeners:
367370
``kernel.terminate`` Event
368371
..........................
369372

373+
*Event Class*: :class:`Symfony\\Component\\HttpKernel\\Event\\PostResponseEvent`
374+
370375
The purpose of this event is to perform "heavier" tasks after the response
371376
was already served to the client.
372377

@@ -647,7 +652,7 @@ If you enable the web profiler, you also need to mount the profiler routes:
647652
648653
As the profiler adds some overhead, you might want to enable it only under
649654
certain circumstances in the production environment. The ``only_exceptions``
650-
settings limits profiling to 500 pages, but what if you want to get
655+
settings limits profiling to exceptions, but what if you want to get
651656
information when the client IP comes from a specific address, or for a limited
652657
portion of the website? You can use a Profiler Matcher, learn more about that
653658
in ":doc:`/cookbook/profiler/matchers`".

‎components/dependency_injection/parameters.rst

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,6 @@ making the class of a service a parameter:
155155
<service id="mailer" class="%mailer.class%">
156156
<argument>%mailer.transport%</argument>
157157
</service>
158-
159158
</services>
160159
161160
.. code-block:: php
@@ -344,6 +343,15 @@ Start the string with ``@`` or ``@?`` to reference a service in YAML.
344343
* ``@?mailer`` references the ``mailer`` service. If the service does not
345344
exist, it will be ignored;
346345

346+
.. code-block:: yaml
347+
348+
parameters:
349+
# if 'my_mailer' service isn't defined, an exception will be raised
350+
foo: @my_mailer
351+
352+
# if 'my_logger' service isn't defined, 'bar' will be null
353+
bar: @?my_logger
354+
347355
.. tip::
348356

349357
Use ``@@`` to escape the ``@`` symbol in YAML. ``@@mailer`` will be
@@ -359,6 +367,16 @@ is thrown. Valid values for ``on-invalid`` are ``null`` (uses ``null`` in place
359367
of the missing service) or ``ignored`` (very similar, except if used on a
360368
method call, the method call is removed).
361369

370+
.. code-block:: xml
371+
372+
<parameters>
373+
<!-- if 'my_mailer' service isn't defined, an exception will be raised -->
374+
<parameter key="foo" type="service" id="my_mailer" />
375+
376+
<!-- if 'my_logger' service isn't defined, 'bar' will be null -->
377+
<parameter key="bar" type="service" id="my_logger" on-invalid="null" />
378+
</parameters>
379+
362380
PHP
363381
~~~
364382

@@ -367,3 +385,15 @@ In PHP, you can use the
367385
a service. The invalid behavior is configured using the second constructor
368386
argument and constants from
369387
:class:`Symfony\\Component\\DependencyInjection\\ContainerInterface`.
388+
389+
.. code-block:: php
390+
391+
use Symfony\Component\DependencyInjection\Reference;
392+
393+
// if 'my_mailer' service isn't defined, an exception will be raised
394+
$container->setParameter('foo', new Reference('my_mailer'));
395+
396+
// if 'my_logger' service isn't defined, 'bar' will be null
397+
$container->setParameter('bar', new Reference('my_logger',
398+
ContainerInterface::NULL_ON_INVALID_REFERENCE
399+
));

‎components/http_foundation/session_configuration.rst

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,16 @@ Save Handlers
1313
~~~~~~~~~~~~~
1414

1515
The PHP session workflow has 6 possible operations that may occur. The normal
16-
session follows `open`, `read`, `write` and `close`, with the possibility of
17-
`destroy` and `gc` (garbage collection which will expire any old sessions: `gc`
18-
is called randomly according to PHP's configuration and if called, it is invoked
19-
after the `open` operation). You can read more about this at
16+
session follows ``open``, ``read``, ``write`` and ``close``, with the possibility
17+
of ``destroy`` and ``gc`` (garbage collection which will expire any old sessions:
18+
``gc`` is called randomly according to PHP's configuration and if called, it is
19+
invoked after the ``open`` operation). You can read more about this at
2020
`php.net/session.customhandler`_
2121

2222
Native PHP Save Handlers
2323
------------------------
2424

25-
So-called 'native' handlers, are save handlers which are either compiled into
25+
So-called native handlers, are save handlers which are either compiled into
2626
PHP or provided by PHP extensions, such as PHP-Sqlite, PHP-Memcached and so on.
2727

2828
All native save handlers are internal to PHP and as such, have no public facing API.
@@ -50,14 +50,16 @@ Example usage::
5050

5151
.. note::
5252

53-
With the exception of the ``files`` handler which is built into PHP and always available,
54-
the availability of the other handlers depends on those PHP extensions being active at runtime.
53+
With the exception of the ``files`` handler which is built into PHP and
54+
always available, the availability of the other handlers depends on those
55+
PHP extensions being active at runtime.
5556

5657
.. note::
5758

58-
Native save handlers provide a quick solution to session storage, however, in complex systems
59-
where you need more control, custom save handlers may provide more freedom and flexibility.
60-
Symfony2 provides several implementations which you may further customize as required.
59+
Native save handlers provide a quick solution to session storage, however,
60+
in complex systems where you need more control, custom save handlers may
61+
provide more freedom and flexibility. Symfony2 provides several implementations
62+
which you may further customize as required.
6163

6264
Custom Save Handlers
6365
--------------------
@@ -183,14 +185,14 @@ session is started. The session can be destroyed as required. This method of
183185
processing can allow the expiry of sessions to be integrated into the user
184186
experience, for example, by displaying a message.
185187

186-
Symfony2 records some basic meta-data about each session to give you complete
188+
Symfony2 records some basic metadata about each session to give you complete
187189
freedom in this area.
188190

189-
Session meta-data
190-
~~~~~~~~~~~~~~~~~
191+
Session metadata
192+
~~~~~~~~~~~~~~~~
191193

192-
Sessions are decorated with some basic meta-data to enable fine control over the
193-
security settings. The session object has a getter for the meta-data,
194+
Sessions are decorated with some basic metadata to enable fine control over the
195+
security settings. The session object has a getter for the metadata,
194196
:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag` which
195197
exposes an instance of :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag`::
196198

@@ -199,7 +201,7 @@ exposes an instance of :class:`Symfony\\Component\\HttpFoundation\\Session\\Stor
199201

200202
Both methods return a Unix timestamp (relative to the server).
201203

202-
This meta-data can be used to explicitly expire a session on access, e.g.::
204+
This metadata can be used to explicitly expire a session on access, e.g.::
203205

204206
$session->start();
205207
if (time() - $session->getMetadataBag()->getLastUsed() > $maxIdleTime) {
@@ -220,15 +222,15 @@ PHP 5.4 compatibility
220222

221223
Since PHP 5.4.0, :phpclass:`SessionHandler` and :phpclass:`SessionHandlerInterface`
222224
are available. Symfony provides forward compatibility for the :phpclass:`SessionHandlerInterface`
223-
so it can be used under PHP 5.3. This greatly improves inter-operability with other
225+
so it can be used under PHP 5.3. This greatly improves interoperability with other
224226
libraries.
225227

226228
:phpclass:`SessionHandler` is a special PHP internal class which exposes native save
227229
handlers to PHP user-space.
228230

229231
In order to provide a solution for those using PHP 5.4, Symfony2 has a special
230232
class called :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeSessionHandler`
231-
which under PHP 5.4, extends from `\SessionHandler` and under PHP 5.3 is just a
233+
which under PHP 5.4, extends from ``\SessionHandler`` and under PHP 5.3 is just a
232234
empty base class. This provides some interesting opportunities to leverage
233235
PHP 5.4 functionality if it is available.
234236

@@ -251,12 +253,12 @@ wrapped by one.
251253

252254
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeProxy`
253255
is used automatically under PHP 5.3 when internal PHP save handlers are specified
254-
using the `Native*SessionHandler` classes, while
256+
using the ``Native*SessionHandler`` classes, while
255257
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\SessionHandlerProxy`
256258
will be used to wrap any custom save handlers, that implement :phpclass:`SessionHandlerInterface`.
257259

258260
From PHP 5.4 and above, all session handlers implement :phpclass:`SessionHandlerInterface`
259-
including `Native*SessionHandler` classes which inherit from :phpclass:`SessionHandler`.
261+
including ``Native*SessionHandler`` classes which inherit from :phpclass:`SessionHandler`.
260262

261263
The proxy mechanism allows you to get more deeply involved in session save handler
262264
classes. A proxy for example could be used to encrypt any session transaction

‎components/http_foundation/sessions.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ an array. A few methods exist for "Bag" management:
121121
Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface`.
122122
This is just a shortcut for convenience.
123123

124-
Session meta-data
124+
Session metadata
125125

126126
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag`:
127127
Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag`
@@ -132,16 +132,16 @@ Session Data Management
132132

133133
PHP's session management requires the use of the ``$_SESSION`` super-global,
134134
however, this interferes somewhat with code testability and encapsulation in a
135-
OOP paradigm. To help overcome this, Symfony2 uses 'session bags' linked to the
136-
session to encapsulate a specific dataset of 'attributes' or 'flash messages'.
135+
OOP paradigm. To help overcome this, Symfony2 uses *session bags* linked to the
136+
session to encapsulate a specific dataset of attributes or flash messages.
137137

138138
This approach also mitigates namespace pollution within the ``$_SESSION``
139139
super-global because each bag stores all its data under a unique namespace.
140140
This allows Symfony2 to peacefully co-exist with other applications or libraries
141141
that might use the ``$_SESSION`` super-global and all data remains completely
142142
compatible with Symfony2's session management.
143143

144-
Symfony2 provides 2 kinds of storage bags, with two separate implementations.
144+
Symfony2 provides two kinds of storage bags, with two separate implementations.
145145
Everything is written against interfaces so you may extend or create your own
146146
bag types if necessary.
147147

@@ -172,11 +172,11 @@ and remember me login settings or other user based state information.
172172
* :class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\NamespacedAttributeBag`
173173
This implementation allows for attributes to be stored in a structured namespace.
174174

175-
Any plain `key => value` storage system is limited in the extent to which
175+
Any plain key-value storage system is limited in the extent to which
176176
complex data can be stored since each key must be unique. You can achieve
177177
namespacing by introducing a naming convention to the keys so different parts of
178-
your application could operate without clashing. For example, `module1.foo` and
179-
`module2.foo`. However, sometimes this is not very practical when the attributes
178+
your application could operate without clashing. For example, ``module1.foo`` and
179+
``module2.foo``. However, sometimes this is not very practical when the attributes
180180
data is an array, for example a set of tokens. In this case, managing the array
181181
becomes a burden because you have to retrieve the array then process it and
182182
store it again::

‎components/options_resolver.rst

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,8 @@ the ``OptionsResolver`` class::
107107

108108
protected function configureOptions(OptionsResolverInterface $resolver)
109109
{
110-
// ... configure the resolver, you will learn this in the sections below
110+
// ... configure the resolver, you will learn this
111+
// in the sections below
111112
}
112113
}
113114

@@ -256,7 +257,9 @@ again. When using a closure as the new value it is passed 2 arguments:
256257
$resolver->setDefaults(array(
257258
'encryption' => 'tls', // simple overwrite
258259
'host' => function (Options $options, $previousValue) {
259-
return 'localhost' == $previousValue ? '127.0.0.1' : $previousValue;
260+
return 'localhost' == $previousValue
261+
? '127.0.0.1'
262+
: $previousValue;
260263
},
261264
));
262265
}

‎components/property_access/introduction.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,9 @@ enable this feature by using :class:`Symfony\\Component\\PropertyAccess\\Propert
196196
{
197197
$property = lcfirst(substr($name, 3));
198198
if ('get' === substr($name, 0, 3)) {
199-
return isset($this->children[$property]) ? $this->children[$property] : null;
199+
return isset($this->children[$property])
200+
? $this->children[$property]
201+
: null;
200202
} elseif ('set' === substr($name, 0, 3)) {
201203
$value = 1 == count($args) ? $args[0] : null;
202204
$this->children[$property] = $value;
@@ -289,7 +291,9 @@ see `Enable other Features`_.
289291
{
290292
$property = lcfirst(substr($name, 3));
291293
if ('get' === substr($name, 0, 3)) {
292-
return isset($this->children[$property]) ? $this->children[$property] : null;
294+
return isset($this->children[$property])
295+
? $this->children[$property]
296+
: null;
293297
} elseif ('set' === substr($name, 0, 3)) {
294298
$value = 1 == count($args) ? $args[0] : null;
295299
$this->children[$property] = $value;
@@ -307,7 +311,7 @@ see `Enable other Features`_.
307311
308312
$accessor->setValue($person, 'wouter', array(...));
309313
310-
echo $person->getWouter() // array(...)
314+
echo $person->getWouter(); // array(...)
311315
312316
Mixing Objects and Arrays
313317
-------------------------

‎components/security/firewall.rst

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,17 @@ certain action or resource of the application::
1212

1313
use Symfony\Component\Security\Core\SecurityContext;
1414
use Symfony\Component\Security\Core\Exception\AccessDeniedException;
15-
15+
1616
// instance of Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface
1717
$authenticationManager = ...;
1818

1919
// instance of Symfony\Component\Security\Core\Authorization\AccessDecisionManagerInterface
2020
$accessDecisionManager = ...;
2121

22-
$securityContext = new SecurityContext($authenticationManager, $accessDecisionManager);
22+
$securityContext = new SecurityContext(
23+
$authenticationManager,
24+
$accessDecisionManager
25+
);
2326

2427
// ... authenticate the user
2528

@@ -71,7 +74,10 @@ with the event dispatcher that is used by the :class:`Symfony\\Component\\HttpKe
7174

7275
$firewall = new Firewall($map, $dispatcher);
7376

74-
$dispatcher->addListener(KernelEvents::REQUEST, array($firewall, 'onKernelRequest');
77+
$dispatcher->addListener(
78+
KernelEvents::REQUEST,
79+
array($firewall, 'onKernelRequest')
80+
);
7581

7682
The firewall is registered to listen to the ``kernel.request`` event that
7783
will be dispatched by the HttpKernel at the beginning of each request

‎components/serializer.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ JMSSerializer
186186

187187
A popular third-party library, `JMS serializer`_, provides a more
188188
sophisticated albeit more complex solution. This library includes the
189-
ability to configure how your objects should be serialize/deserialized via
189+
ability to configure how your objects should be serialized/deserialized via
190190
annotations (as well as YAML, XML and PHP), integration with the Doctrine ORM,
191191
and handling of other complex cases (e.g. circular references).
192192

‎components/stopwatch.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -69,13 +69,13 @@ call::
6969
In addition to periods, you can get other useful information from the event object.
7070
For example::
7171

72-
$event->getCategory(); // Returns the category the event was started in
73-
$event->getOrigin(); // Returns the event start time in milliseconds
74-
$event->ensureStopped(); // Stops all periods not already stopped
75-
$event->getStartTime(); // Returns the start time of the very first period
76-
$event->getEndTime(); // Returns the end time of the very last period
77-
$event->getDuration(); // Returns the event duration, including all periods
78-
$event->getMemory(); // Returns the max memory usage of all periods
72+
$event->getCategory(); // Returns the category the event was started in
73+
$event->getOrigin(); // Returns the event start time in milliseconds
74+
$event->ensureStopped(); // Stops all periods not already stopped
75+
$event->getStartTime(); // Returns the start time of the very first period
76+
$event->getEndTime(); // Returns the end time of the very last period
77+
$event->getDuration(); // Returns the event duration, including all periods
78+
$event->getMemory(); // Returns the max memory usage of all periods
7979

8080
Sections
8181
--------

0 commit comments

Comments
 (0)
0