8000 Merge branch '2.7' into 2.8 · symfony/symfony-docs@923c187 · GitHub
[go: up one dir, main page]
Skip to content

Commit 923c187

Browse files
wouterjwouterj
committed
Merge branch '2.7' into 2.8
2 parents ed8d805 + b39756f commit 923c187

File tree

12 files changed

+97
-22
lines changed

12 files changed

+97
-22
lines changed

‎components/finder.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ Search in several locations by chaining calls to
8383
:method:`Symfony\\Component\\Finder\\Finder::in`::
8484

8585
// search inside *both* directories
86-
$finder->files()->in(array(__DIR__, '/elsewhere'));
86+
$finder->in(array(__DIR__, '/elsewhere'));
8787

8888
// same as above
8989
$finder->in(__DIR__)->in('/elsewhere');

‎components/property_access.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,51 @@ see `Enable other Features`_.
321321
322322
var_dump($person->getWouter()); // array(...)
323323
324+
Writing to Array Properties
325+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
326+
327+
The ``PropertyAccessor`` class allows to update the content of arrays stored in
328+
properties through *adder* and *remover* methods.
329+
330+
.. code-block:: php
331+
332+
// ...
333+
class Person
334+
{
335+
/**
336+
* @var string[]
337+
*/
338+
private $children = array();
339+
340+
public function getChildren(): array
341+
{
342+
return $this->children;
343+
}
344+
345+
public function addChild(string $name): void
346+
{
347+
$this->children[$name] = $name;
348+
}
349+
350+
public function removeChild(string $name): void
351+
{
352+
unset($this->children[$name]);
353+
}
354+
}
355+
356+
$person = new Person();
357+
$accessor->setValue($person, 'children', array('kevin', 'wouter'));
358+
359+
var_dump($person->getChildren()); // array('kevin', 'wouter')
360+
361+
The PropertyAccess component checks for methods called ``add<SingularOfThePropertyName>()``
362+
and ``remove<SingularOfThePropertyName>()``. Both methods must be defined.
363+
For instance, in the previous example, the component looks for the ``addChild()``
364+
and ``removeChild()`` methods to access to the ``children`` property.
365+
`The Inflector component`_ is used to find the singular of a property name.
366+
367+
If available, *adder* and *remover* methods have priority over a *setter* method.
368+
324369
Checking Property Paths
325370
-----------------------
326371

@@ -414,3 +459,4 @@ Or you can pass parameters directly to the constructor (not the recommended way)
414459

415460

416461
.. _Packagist: https://packagist.org/packages/symfony/property-access
462+
.. _The Inflector component: https://github.com/symfony/inflector

‎http_cache.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ Nottingham's `Cache Tutorial`_.
3333
.. index::
3434
single: Cache; Proxy
3535
single: Cache; Reverse proxy
36-
single: Cache; Gateway
3736

3837
.. _gateway-caches:
3938

@@ -286,11 +285,15 @@ Safe Methods: Only caching GET or HEAD requests
286285
HTTP caching only works for "safe" HTTP methods (like GET and HEAD). This means
287286
two things:
288287

289-
* Don't try to cache PUT, POST or DELETE requests. It won't work and with good
290-
reason. These methods are meant to be used when mutating the state of your application
288+
* Don't try to cache PUT or DELETE requests. It won't work and with good reason.
289+
These methods are meant to be used when mutating the state of your application
291290
(e.g. deleting a blog post). Caching them would prevent certain requests from hitting
292291
and mutating your application.
293292

293+
* POST requests are generally considered uncachable, but `they can be cached`_
294+
when they include explicit freshness information. However POST caching is not
295+
widely implemented, so you should avoid it if possible.
296+
294297
* You should *never* change the state of your application (e.g. update a blog post)
295298
when responding to a GET or HEAD request. If those requests are cached, future
296299
requests may not actually hit your server.
@@ -366,3 +369,4 @@ Learn more
366369
.. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234
367370
.. _`RFC 7232 - Conditional Requests`: https://tools.ietf.org/html/rfc7232
368371
.. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/
372+
.. _`they can be cached`: https://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-20#section-2.3.4

‎reference/constraints/Collection.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -314,7 +314,7 @@ error will be returned. If set to ``true``, extra fields are ok.
314314
extraFieldsMessage
315315
~~~~~~~~~~~~~~~~~~
316316

317-
**type**: ``boolean`` **default**: ``The fields {{ fields }} were not expected.``
317+
**type**: ``boolean`` **default**: ``This field was not expected.``
318318

319319
The message shown if `allowExtraFields`_ is false and an extra field is
320320
detected.
@@ -332,7 +332,7 @@ option are not present in the underlying collection.
332332
missingFieldsMessage
333333
~~~~~~~~~~~~~~~~~~~~
334334

335-
**type**: ``boolean`` **default**: ``The fields {{ fields }} are missing.``
335+
**type**: ``boolean`` **default**: ``This field is missing.``
336336

337337
The message shown if `allowMissingFields`_ is false and one or more fields
338338
are missing from the underlying collection.

‎reference/constraints/Length.rst

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
Length
22
======
33

4-
Validates that a given string length is *between* some minimum and maximum
5-
value.
4+
Validates that a given string length is *between* some minimum and maximum value.
5+
6+
.. caution::
7+
8+
``null`` and empty strings are not handled by this constraint. You need to
9+
also add the :doc:`/reference/constraints/NotBlank` or :doc:`/reference/constraints/NotNull`
10+
constraints to validate against these.
611

712
+----------------+----------------------------------------------------------------------+
813
| Applies to | :ref:`property or method <validation-property-target>` |

‎reference/forms/types/options/choice_value.rst.inc

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,23 @@ choice_value
66

77
**type**: ``callable`` or ``string`` **default**: ``null``
88

9-
Returns the string "value" for each choice. This is used in the ``value`` attribute
10-
in HTML and submitted in the POST/PUT requests. You don't normally need to worry
11-
about this, but it might be handy when processing an API request (since you can
12-
configure the value that will be sent in the API request).
9+
Returns the string "value" for each choice, which must be unique across all choices.
10+
This is used in the ``value`` attribute in HTML and submitted in the POST/PUT requests.
11+
You don't normally need to worry about this, but it might be handy when processing
12+
an API request (since you can configure the value that will be sent in the API request).
1313

14-
This can be a callable or a property path. See `choice_label`_ for similar usage.
15-
If ``null`` is used, an incrementing integer is used as the name.
14+
This can be a callable or a property path. If ``null`` is given, an incrementing
15+
integer is used as the value.
1616

17-
If you are using a callable to populate ``choice_value``, you need to check
18-
for the case that the value of the field may be ``null``.
17+
If you pass a callable, it will receive one argument: the choice itself. When using
18+
the :doc:`/reference/forms/types/entity`, the argument will be the entity object
19+
for each choice or ``null`` in some cases, which you need to handle:
20+
21+
.. code-block:: php
22+
23+
'choice_value' => function (MyOptionEntity $entity = null) {
24+
return $entity ? $entity->getId() : '';
25+
},
1926

2027
.. caution::
2128

‎request/load_balancer_reverse_proxy.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy
22
==========================================================================
33

44
When you deploy your application, you may be behind a load balancer (e.g.
5-
an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for
5+
an AWS Elastic Load Balancing) or a reverse proxy (e.g. Varnish for
66
:doc:`caching</http_cache>`).
77

88
For the most part, this doesn't cause any problems with Symfony. But, when
@@ -74,7 +74,7 @@ using HTTPS.
7474
But what if the IP of my Reverse Proxy Changes Constantly!
7575
----------------------------------------------------------
7676

77-
Some reverse proxies (like Amazon's Elastic Load Balancers) don't have a
77+
Some reverse proxies (like AWS Elastic Load Balancing) don't have a
7878
static IP address or even a range that you can target with the CIDR notation.
7979
In this case, you'll need to - *very carefully* - trust *all* proxies.
8080

‎security/csrf_in_login_form.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ for CSRF. In this article you'll learn how you can use it in your login form.
1616
Configuring CSRF Protection
1717
---------------------------
1818

19-
First, make sure that the CSRF protection is enabled in the main cofiguration
19+
First, make sure that the CSRF protection is enabled in the main configuration
2020
file:
2121

2222
.. configuration-block::

‎service_container.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -402,6 +402,20 @@ Actually, once you define a parameter, it can be referenced via the ``%parameter
402402
syntax in *any* other service configuration file - like ``config.yml``. Many parameters
403403
are defined in a :ref:`parameters.yml file <config-parameters-yml>`.
404404

405+
You can then fetch the parameter in the service::
406+
407+
class SiteUpdateManager
408+
{
409+
// ...
410+
411+
private $adminEmail;
412+
413+
public function __construct($adminEmail)
414+
{
415+
$this->adminEmail = $adminEmail;
416+
}
417+
}
418+
405419
You can also fetch parameters directly from the container::
406420

407421
public function newAction()

‎service_container/parameters.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,6 @@ and hidden with the service definition:
8080
.. code-block:: php
8181
8282
use AppBundle\Mailer;
83-
use Symfony\Component\DependencyInjection\Reference;
8483
8584
$container->setParameter('mailer.transport', 'sendmail');
8685

‎templating.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Creating and Using Templates
66

77
As explained in :doc:`the previous article </controller>`, controllers are
88
responsible for handling each request that comes into a Symfony application and
9-
the usually end up rendering a template to generate the response contents.
9+
they usually end up rendering a template to generate the response contents.
1010

1111
In reality, the controller delegates most of the heavy work to other places so
1212
that code can be tested and reused. When a controller needs to generate HTML,

‎validation/custom_constraint.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ includes some simple default logic::
4545
// in the base Symfony\Component\Validator\Constraint class
4646
public function validatedBy()
4747
{
48-
return ContainsAlphanumericValidator::class;
48+
return get_class($this).'Validator';
4949
}
5050

5151
In other words, if you create a custom ``Constraint`` (e.g. ``MyConstraint``),

0 commit comments

Comments
 (0)
0