8000 Merge branch '3.4' · symfony/symfony-docs@1952d7c · GitHub
[go: up one dir, main page]
Skip to content

Commit 1952d7c

Browse files
wouterjwouterj
committed
Merge branch '3.4'
2 parents 5710d64 + 7bb20ba commit 1952d7c

22 files changed

+140
-46
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
@@ -314,6 +314,51 @@ see `Enable other Features`_.
314314
315315
var_dump($person->getWouter()); // array(...)
316316
317+
Writing to Array Properties
318+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
319+
320+
The ``PropertyAccessor`` class allows to update the content of arrays stored in
321+
properties through *adder* and *remover* methods.
322+
323+
.. code-block:: p 9E88 hp
324+
325+
// ...
326+
class Person
327+
{
328+
/**
329+
* @var string[]
330+
*/
331+
private $children = array();
332+
333+
public function getChildren(): array
334+
{
335+
return $this->children;
336+
}
337+
338+
public function addChild(string $name): void
339+
{
340+
$this->children[$name] = $name;
341+
}
342+
343+
public function removeChild(string $name): void
344+
{
345+
unset($this->children[$name]);
346+
}
347+
}
348+
349+
$person = new Person();
350+
$accessor->setValue($person, 'children', array('kevin', 'wouter'));
351+
352+
var_dump($person->getChildren()); // array('kevin', 'wouter')
353+
354+
The PropertyAccess component checks for methods called ``add<SingularOfThePropertyName>()``
355+
and ``remove<SingularOfThePropertyName>()``. Both methods must be defined.
356+
For instance, in the previous example, the component looks for the ``addChild()``
357+
and ``removeChild()`` methods to access to the ``children`` property.
358+
`The Inflector component`_ is used to find the singular of a property name.
359+
360+
If available, *adder* and *remover* methods have priority over a *setter* method.
361+
317362
Checking Property Paths
318363
-----------------------
319364

@@ -407,3 +452,4 @@ Or you can pass parameters directly to the constructor (not the recommended way)
407452

408453

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

‎components/serializer.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -563,6 +563,13 @@ There are several types of normalizers available:
563563
This normalizer converts :phpclass:`SplFileInfo` objects into a data URI
564564
string (``data:...``) such that files can be embedded into serialized data.
565565

566+
:class:`Symfony\\Component\\Serializer\\Normalizer\\DateIntervalNormalizer`
567+
This normalizer converts :phpclass:`DateInterval` objects into strings.
568+
By default it uses the ``P%yY%mM%dDT%hH%iM%sS`` format.
569+
570+
.. versionadded:: 3.4
571+
The ``DateIntervalNormalizer`` normalizer was added in Symfony 3.4.
572+
566573
Encoders
567574
--------
568575

‎frontend/encore/bootstrap.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,14 @@ file into ``global.scss``. You can even customize the Bootstrap variables first!
3535
in the ``bootstrap`` directory instead - e.g. ``~bootstrap-sass/assets/stylesheets/bootstrap/alerts``.
3636

3737
After including ``bootstrap-sass``, your Webpack builds might become slow. To fix
38-
this, you can use the ``resolve_url_loader`` option:
38+
this, you can use the ``resolveUrlLoader`` option:
3939

4040
.. code-block:: diff
4141
4242
// webpack.config.js
4343
Encore
4444
+ .enableSassLoader(function(sassOptions) {}, {
45-
+ resolve_url_loader: false
45+
+ resolveUrlLoader: false
4646
+ })
4747
;
4848

‎frontend/encore/shared-entry.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ on your page before any other JavaScript file:
3232
.. code-block:: twig
3333
3434
<!-- these two files now must be included in every page -->
35-
<script src="{{ asset('build/manifest.js') }}"></script>
35+
<script src="{{ asset('build/manifest.json') }}"></script>
3636
<script src="{{ asset('build/vendor.js') }}"></script>
3737
3838
<!-- here you link to the specific JS files needed by the current page -->
@@ -42,7 +42,7 @@ on your page before any other JavaScript file:
4242
<link rel="stylesheet" href="{{ asset('build/vendor.css') }}" />
4343
4444
The ``vendor.js`` file contains all the common code that has been extracted from
45-
the other files, so it's obvious that it must be included. The other file (``manifest.js``)
45+
the other files, so it's obvious that it must be included. The other file (``manifest.json``)
4646
is less obvious: it's needed so that Webpack knows how to load those shared modules.
4747

4848
.. tip::

‎frontend/encore/simple-example.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ To build the assets, use the ``encore`` executable:
7272
7373
# shorter version of the above 3 commands
7474
$ yarn run encore dev
75-
$ yarn run encore dev -- --watch
75+
$ yarn run encore dev --watch
7676
$ yarn run encore production
7777
7878
.. note::

‎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

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

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

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

‎logging/monolog_console.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ example, in ``config_dev.yml``:
111111
112112
Now, log messages will be shown on the console based on the log levels and verbosity.
113113
By default (normal verbosity level), warnings and higher will be shown. But in
114-
:doc:`full verbostiy mode </console/verbosity>`, all messages will be shown.
114+
:doc:`full verbosity mode </console/verbosity>`, all messages will be shown.
115115

116116
.. _ConsoleHandler: https://github.com/symfony/MonologBridge/blob/master/Handler/ConsoleHandler.php
117117
.. _MonologBridge: https://github.com/symfony 10000 /MonologBridge

‎reference/configuration/framework.rst

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,7 @@ Configuration
117117
* `default_doctrine_provider`_
118118
* `default_psr6_provider`_
119119
* `default_redis_provider`_
120+
* `default_memcached_provider`_
120121
* `pools`_
121122
* :ref:`name <reference-cache-pools-name>`
122123
* `adapter`_
@@ -250,7 +251,7 @@ need to escape the percent signs (``%``) by doubling them.
250251
.. note::
251252

252253
If both ``framework.ide`` and ``xdebug.file_link_format`` are defined,
253-
Symfony uses the value of the ``framework.ide`` option.
254+
Symfony uses the value of the ``xdebug.file_link_format`` option.
254255

255256
.. tip::
256257

@@ -1733,7 +1734,7 @@ app
17331734

17341735
The cache adapter used by the ``cache.app`` service. The FrameworkBundle
17351736
ships with multiple adapters: ``apcu``, ``doctrine``, ``system``, ``filesystem``,
1736-
``psr6`` and ``redis``.
1737+
``psr6``, ``redis`` and ``memcached``.
17371738

17381739
.. tip::
17391740

@@ -1780,6 +1781,17 @@ default_redis_provider
17801781
The DSN to use by the Redis provider. The provider is available as the ``cache.redis``
17811782
service.
17821783

1784+
default_memcached_provider
1785+
..........................
1786+
1787+
.. versionadded:: 3.3
1788+
The ``default_memcached_provider`` option was introduced in Symfony 3.3.
1789+
1790+
**type**: ``string`` **default**: ``memcached://localhost``
1791+
1792+
The DSN to use by the Memcached provider. The provider is available as the ``cache.memcached``
1793+
service.
1794+
17831795
pools
17841796
.....
17851797

@@ -2017,6 +2029,7 @@ Full Default Configuration
20172029
default_doctrine_provider: ~
20182030
default_psr6_provider: ~
20192031
default_redis_provider: 'redis://localhost'
2032+
default_memcached_provider: 'memcached://localhost'
20202033
pools:
20212034
# Prototype
20222035
name:

‎reference/constraints/Collection.rst

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

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

315315
The message shown if `allowExtraFields`_ is false and an extra field is
316316
detected.
@@ -328,7 +328,7 @@ option are not present in the underlying collection.
328328
missingFieldsMessage
329329
~~~~~~~~~~~~~~~~~~~~
330330

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

333333
The message shown if `allowMissingFields`_ is false and one or more fields
334334
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
@@ -3,16 +3,23 @@ choice_value
33

44
**type**: ``callable`` or ``string`` **default**: ``null``
55

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

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

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

1724
.. caution::
1825

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@ to a field. To avoid duplicated keyword messages, you can configure the label
1414
format to a static value, like::
1515
1616
// ...
17-
$profileFormBuilder->add('address', new AddressType(), array(
17+
$profileFormBuilder->add('address', AddressType::class, array(
1818
'label_format' => 'form.address.%name%',
1919
));
2020
21-
$invoiceFormBuilder->add('invoice', new AddressType(), array(
21+
$invoiceFormBuilder->add('invoice', AddressType::class, array(
2222
'label_format' => 'form.address.%name%',
2323
));
2424

‎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
@@ -53,7 +53,7 @@ so you can also pass your own value (e.g. ``0b00110``).
5353
But what if the IP of my Reverse Proxy Changes Constantly!
5454
----------------------------------------------------------
5555

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

‎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: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -572,6 +572,20 @@ Actually, once you define a parameter, it can be referenced via the ``%parameter
572572
syntax in *any* other service configuration file - like ``config.yml``. Many parameters
573573
are defined in a :ref:`parameters.yml file <config-parameters-yml>`.
574574

575+
You can then fetch the parameter in the service::
576+
577+
class SiteUpdateManager
578+
{
579+
// ...
580+
581+
private $adminEmail;
582+
583+
public function __construct($adminEmail)
584+
{
585+
$this->adminEmail = $adminEmail;
586+
}
587+
}
588+
575589
You can also fetch parameters directly from the container::
576590

577591
public function newAction()
@@ -844,9 +858,9 @@ key. For example, the default Symfony configuration contains this:
844858
845859
# the namespace prefix for classes (must end in \)
846860
AppBundle\:
847-
# accepts a glob pattern
861+
# create services for all the classes found in this directory...
848862
resource: '../../src/AppBundle/*'
849-
# exclude some paths
863+
# ...except for the classes located in these directories
850864
exclude: '../../src/AppBundle/{Entity,Repository}'
851865
852866
# these were imported above, but we want to add some extra config
@@ -901,6 +915,11 @@ key. For example, the default Symfony configuration contains this:
901915
// $this is a reference to the current loader
902916
$this->registerClasses($definition, 'AppBundle\\Controller\\', '../../src/AppBundle/Controller/*');
903917
918+
.. tip::
919+
920+
The value of the ``resource`` and ``exclude`` options can be any valid
921+
`glob pattern`_.
922+
904923
This can be used to quickly make many classes available as services and apply some
905924
default configuration. The ``id`` of each service is its fully-qualified class name.
906925
You can override any service that's imported by using its id (class name) below
@@ -1044,3 +1063,4 @@ Learn more
10441063

10451064
.. _`service-oriented architecture`: https://en.wikipedia.org/wiki/Service-oriented_architecture
10461065
.. _`Symfony Standard Edition (version 3.3) services.yml`: https://github.com/symfony/symfony-standard/blob/3.3/app/config/services.yml
1066+
.. _`glob pattern`: https://en.wikipedia.org/wiki/Glob_(programming)

0 commit comments

Comments
 (0)
0