8000 --- · symfony/symfony-docs@35f49ce · GitHub
[go: up one dir, main page]

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit 35f49ce

Browse files
committed
---
yaml --- r: 73453 b: refs/heads/5.x c: 217d157 h: refs/heads/5.x i: 73451: 5dacff4
1 parent 61f34da commit 35f49ce

28 files changed

+505
-129
lines changed

[refs]

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,4 +92,4 @@ refs/heads/3.3: 93587037fef6a2f40e0cbdea41754e1e76255fe6
9292
refs/heads/weaverryan-patch-1: a52aee3dceba3357dd59558677811a2ff86d1357
9393
refs/heads/4.0: e887a8b5e5d102235545837506f1d4e883f051a5
9494
refs/heads/4.1: 67f3845bc17a81379c609af1944099706e5b429e
95-
refs/heads/5.x: 53daecd99ad4e9cc041dbb5aace84c47a56a4307
95+
refs/heads/5.x: 217d157f9bd9d7ff14d9e5a7c2fb006cfb1ba3a9

trunk/_build/redirection_map

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -427,3 +427,4 @@
427427
/contributing/community/other /contributing/community
428428
/profiler/storage /profiler
429429
/setup/composer /setup
430+
/security/security_checker /setup
Loading

trunk/components/http_client.rst

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -130,14 +130,18 @@ each request (which overrides any global authentication)::
130130

131131
// Use the same authentication for all requests
132132
$httpClient = HttpClient::create([
133-
// HTTP Basic authentication with only the username and not a password
133+
// HTTP Basic authentication (there are multiple ways of configuring it)
134134
'auth_basic' => ['the-username'],
135-
136-
// HTTP Basic authentication with a username and a password
137135
'auth_basic' => ['the-username', 'the-password'],
136+
'auth_basic' => 'the-username:the-password',
138137

139138
// HTTP Bearer authentication (also called token authentication)
140139
'auth_bearer' => 'the-bearer-token',
140+
141+
// Microsoft NTLM authentication (there are multiple ways of configuring it)
142+
'auth_ntlm' => ['the-username'],
143+
'auth_ntlm' => ['the-username', 'the-password'],
144+
'auth_ntlm' => 'the-username:the-password',
141145
]);
142146

143147
$response = $httpClient->request('GET', 'https://...', [
@@ -147,6 +151,14 @@ each request (which overrides any global authentication)::
147151
// ...
148152
]);
149153

154+
.. note::
155+
156+
The NTLM authentication mechanism requires using the cURL transport.
157+
158+
.. versionadded:: 4.4
159+
160+
The ``auth_ntlm`` option was introduced in Symfony 4.4.
161+
150162
Query String Parameters
151163
~~~~~~~~~~~~~~~~~~~~~~~
152164

trunk/components/lock.rst

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,16 +24,21 @@ Locks are used to guarantee exclusive access to some shared resource. In
2424
Symfony applications, you can use locks for example to ensure that a command is
2525
not executed more than once at the same time (on the same or different servers).
2626

27-
Locks are created using a :class:`Symfony\\Component\\Lock\\Factory` class,
27+
Locks are created using a :class:`Symfony\\Component\\Lock\\LockFactory` class,
2828
which in turn requires another class to manage the storage of locks::
2929

30-
use Symfony\Component\Lock\Factory;
30+
use Symfony\Component\Lock\LockFactory;
3131
use Symfony\Component\Lock\Store\SemaphoreStore;
3232

3333
$store = new SemaphoreStore();
34-
$factory = new Factory($store);
34+
$factory = new LockFactory($store);
3535

36-
The lock is created by calling the :method:`Symfony\\Component\\Lock\\Factory::createLock`
36+
.. versionadded:: 4.4
37+
38+
The ``Symfony\Component\Lock\LockFactory`` class was introduced in Symfony
39+
4.4. In previous versions it was called ``Symfony\Component\Lock\Factory``.
40+
41+
The lock is created by calling the :method:`Symfony\\Component\\Lock\\LockFactory::createLock`
3742
method. Its first argument is an arbitrary string that represents the locked
3843
resource. Then, a call to the :method:`Symfony\\Component\\Lock\\LockInterface::acquire`
3944
method will try to acquire the lock::
@@ -56,7 +61,7 @@ method can be safely called repeatedly, even if the lock is already acquired.
5661
Unlike other implementations, the Lock Component distinguishes locks
5762
instances even when they are created for the same resource. If a lock has
5863
to be used by several services, they should share the same ``Lock`` instance
59-
returned by the ``Factory::createLock`` method.
64+
returned by the ``LockFactory::createLock`` method.
6065

6166
.. tip::
6267

@@ -77,13 +82,13 @@ until the lock is acquired.
7782
Some of the built-in ``Store`` classes support this feature. When they don't,
7883
they can be decorated with the ``RetryTillSaveStore`` class::
7984

80-
use Symfony\Component\Lock\Factory;
85+
use Symfony\Component\Lock\LockFactory;
8186
use Symfony\Component\Lock\Store\RedisStore;
8287
use Symfony\Component\Lock\Store\RetryTillSaveStore;
8388

8489
$store = new RedisStore(new \Predis\Client('tcp://localhost:6379'));
8590
$store = new RetryTillSaveStore($store);
86-
$factory = new Factory($store);
91+
$factory = new LockFactory($store);
8792

8893
$lock = $factory->createLock('notification-flush');
8994
$lock->acquire(true);
@@ -208,8 +213,10 @@ Available Stores
208213
----------------
209214

210215
Locks are created and managed in ``Stores``, which are classes that implement
211-
:class:`Symfony\\Component\\Lock\\StoreInterface`. The component includes the
212-
following built-in store types:
216+
:class:`Symfony\\Component\\Lock\\PersistStoreInterface` and, optionally,
217+
:class:`Symfony\\Component\\Lock\\BlockingStoreInterface`.
218+
219+
The component includes the following built-in store types:
213220

214221
============================================ ====== ======== ========
215222
Store Scope Blocking Expiring
@@ -222,6 +229,12 @@ Store Scope Blocking Expiring
222229
:ref:`ZookeeperStore <lock-store-zookeeper>` remote no no
223230
============================================ ====== ======== ========
224231

232+
.. versionadded:: 4.4
233+
234+
The ``PersistStoreInterface`` and ``BlockingStoreInterface`` interfaces were
235+
introduced in Symfony 4.4. In previous versions there was only one interface
236+
called ``Symfony\Component\Lock\StoreInterface``.
237+
225238
.. _lock-store-flock:
226239

227240
FlockStore

trunk/components/mime.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,8 @@ MIME types and file name extensions::
254254
These methods return arrays with one or more elements. The element position
255255
indicates its priority, so the first returned extension is the preferred one.
256256

257+
.. _components-mime-type-guess:
258+
257259
Guessing the MIME Type
258260
~~~~~~~~~~~~~~~~~~~~~~
259261

trunk/components/phpunit_bridge.rst

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ The PHPUnit Bridge
66
==================
77

88
The PHPUnit Bridge provides utilities to report legacy tests and usage of
9-
deprecated code and a helper for time-sensitive tests.
9+
deprecated code and helpers for mocking native functions related to time,
10+
DNS and class existence.
1011

1112
It comes with the following features:
1213

@@ -19,10 +20,13 @@ It comes with the following features:
1920

2021
* Displays the stack trace of a deprecation on-demand;
2122

22-
* Provides a ``ClockMock`` and ``DnsMock`` helper classes for time or network-sensitive tests.
23+
* Provides a ``ClockMock``, ``DnsMock`` and ``ClassExistsMock`` classes for tests
24+
sensitive to time, network or class existence.
2325

24-
* Provides a modified version of PHPUnit that does not embed ``symfony/yaml`` nor
25-
``prophecy`` to prevent any conflicts with these dependencies.
26+
* Provides a modified version of PHPUnit that allows 1. separating the
27+
dependencies of your app from those of phpunit to prevent any unwanted
28+
constraints to apply; 2. running tests in parallel when a test suite is split
29+
in several phpunit.xml files; 3. recording and replaying skipped tests.
2630

2731
Installation
2832
------------
@@ -517,6 +521,7 @@ constraint to test the validity of the email domain::
517521
$result = $validator->validate('foo@example.com', $constraint);
518522

519523
// ...
524+
}
520525
}
521526

522527
In order to avoid making a real network connection, add the ``@dns-sensitive``
@@ -541,6 +546,7 @@ the data you expect to get for the given hosts::
541546
$result = $validator->validate('foo@example.com', $constraint);
542547

543548
// ...
549+
}
544550
}
545551

546552
The ``withMockedHosts()`` method configuration is defined as an array. The keys
@@ -622,8 +628,8 @@ Modified PHPUnit script
622628
This bridge provides a modified version of PHPUnit that you can call by using
623629
its ``bin/simple-phpunit`` command. It has the following features:
624630

625-
* Does not embed ``symfony/yaml`` nor ``prophecy`` to prevent any conflicts with
626-
these dependencies;
631+
* Works with a standalone vendor directory that doesn't conflict with yours;
632+
* Does not embed ``prophecy`` to prevent any conflicts with its dependencies;
627633
* Uses PHPUnit 4.8 when run with PHP <=5.5, PHPUnit 5.7 when run with PHP >=5.6
628634
and PHPUnit 6.5 when run with PHP >=7.2;
629635
* Collects and replays skipped tests when the ``SYMFONY_PHPUNIT_SKIPPED_TESTS``
@@ -635,9 +641,20 @@ its ``bin/simple-phpunit`` command. It has the following features:
635641

636642
The script writes the modified PHPUnit it builds in a directory that can be
637643
configured by the ``SYMFONY_PHPUNIT_DIR`` env var, or in the same directory as
638-
the ``simple-phpunit`` if it is not provided.
639-
640-
It's also possible to set this env var in the ``phpunit.xml.dist`` file.
644+
the ``simple-phpunit`` if it is not provided. It's also possible to set this
645+
env var in the ``phpunit.xml.dist`` file.
646+
647+
By default, these are the PHPUnit versions used depending on the installed PHP versions:
648+
649+
===================== ===============================
650+
Installed PHP version PHPUnit version used by default
651+
===================== ===============================
652+
PHP <= 5.5 PHPUnit 4.8
653+
PHP 5.6 PHPUnit 5.7
654+
PHP 7.0 PHPUnit 6.5
655+
PHP 7.1 PHPUnit 7.5
656+
PHP >= 7.2 PHPUnit 8.2
657+
===================== ===============================
641658

642659
If you have installed the bridge through Composer, you can run it by calling e.g.:
643660

trunk/components/property_info.rst

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -351,8 +351,9 @@ ReflectionExtractor
351351

352352
Using PHP reflection, the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\ReflectionExtractor`
353353
provides list, type and access information from setter and accessor methods.
354-
It can also give the type of a property, and if it is initializable through the
355-
constructor. It supports return and scalar types for PHP 7::
354+
It can also give the type of a property (even extracting it from the constructor
355+
arguments), and if it is initializable through the constructor. It supports
356+
return and scalar types for PHP 7::
356357

357358
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
358359

@@ -371,6 +372,11 @@ constructor. It supports return and scalar types for PHP 7::
371372
// Initializable information
372373
$reflectionExtractor->isInitializable($class, $property);
373374

375+
.. versionadded:: 4.1
376+
377+
The feature to extract the property types from constructor arguments was
378+
introduced in Symfony 4.1.
379+
374380
.. note::
375381

376382
When using the Symfony framework, this service is automatically registered

trunk/components/var_dumper.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,13 @@ option. Read more about this and other options in
224224
are supported (``Ctrl. + G`` or ``Cmd. + G``, ``F3``, etc.) When
225225
finished, press ``Esc.`` to hide the box again.
226226

227+
If you want to use your browser search input, press ``Ctrl. + F`` or
228+
``Cmd. + F`` again while having focus on VarDumper's search input.
229+
230+
.. versionadded:: 4.4
231+
232+
The feature to use the browser search input was introduced in Symfony 4.4.
233+
227234
Using the VarDumper Component in your PHPUnit Test Suite
228235
--------------------------------------------------------
229236

trunk/contributing/code/security.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,8 @@ Security Advisories
169169
.. tip::
170170

171171
You can check your Symfony application for known security vulnerabilities
172-
using the ``security:check`` command (see :doc:`/security/security_checker`).
172+
using the ``security:check`` command provided by the
173+
:ref:`Symfony security checker <security-checker>`.
173174

174175
Check the `Security Advisories`_ blog category for a list of all security
175176
vulnerabilities that were fixed in Symfony releases, starting from Symfony

trunk/contributing/documentation/format.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -210,9 +210,9 @@ Symfony 5.0 were released today, 4.0 to 4.4 ``versionadded`` and ``deprecated``
210210
tags would be removed from the new ``5.0`` branch.
211211

212212
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
213-
.. _Sphinx: http://sphinx-doc.org/
213+
.. _Sphinx: https://www.sphinx-doc.org/
214214
.. _`Symfony documentation`: https://github.com/symfony/symfony-docs
215-
.. _`reStructuredText Primer`: http://sphinx-doc.org/rest.html
215+
.. _`reStructuredText Primer`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
216216
.. _`reStructuredText Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
217-
.. _`Sphinx Markup Constructs`: http://sphinx-doc.org/markup/
217+
.. _`Sphinx Markup Constructs`: https://www.sphinx-doc.org/en/1.7/markup/index.html
218218
.. _`supported languages`: http://pygments.org/languages/

trunk/doctrine/event_listeners_subscribers.rst

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,17 @@ whenever an object in your database is saved.
1616

1717
Doctrine defines two types of objects that can listen to Doctrine events:
1818
listeners and subscribers. Both are very similar, but listeners are a bit
19-
more straightforward. For more, see `The Event System`_ on Doctrine's website.
19+
more straightforward. For more, see `The Event System`_ on Doctrine's documentation.
2020

21-
The Doctrine website also explains all existing events that can be listened to.
21+
Before using them, keep in mind that Doctrine events are intended for
22+
persistence hooks (i.e. *"save also this when saving that"*). They should not be
23+
used for domain logic, such as logging changes, setting ``updatedAt`` and
24+
``createdAt`` properties, etc.
25+
26+
.. seealso::
27+
28+
This article covers listeners and subscribers for Doctrine ORM. If you are
29+
using ODM for MongoDB, read the `DoctrineMongoDBBundle documentation`_.
2230

2331
Configuring the Listener/Subscriber
2432
-----------------------------------
@@ -256,3 +264,4 @@ numbers mean that listeners are invoked earlier.
256264
257265
.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
258266
.. _`the DoctrineBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineBundle/entity-listeners.html
267+
.. _`DoctrineMongoDBBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineMongoDBBundle/index.html

trunk/event_dispatcher.rst

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,12 @@ The most common way to listen to an event is to register an **event listener**::
2727
namespace App\EventListener;
2828

2929
use Symfony\Component\HttpFoundation\Response;
30-
use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
30+
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
3131
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
3232

3333
class ExceptionListener
3434
{
35-
public function onKernelException(GetResponseForExceptionEvent $event)
35+
public function onKernelException(ExceptionEvent $event)
3636
{
3737
// You get the exception object from the received event
3838
$exception = $event->getException();
@@ -63,10 +63,16 @@ The most common way to listen to an event is to register an **event listener**::
6363
.. tip::
6464

6565
Each event receives a slightly different type of ``$event`` object. For
66-
the ``kernel.exception`` event, it is :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`.
66+
the ``kernel.exception`` event, it is :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`.
6767
Check out the :doc:`Symfony events reference </reference/events>` to see
6868
what type of object each event provides.
6969

70+
.. versionadded::
71+
72+
The :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent` class was
73+
introduced in Symfony 4.3. In previous versions it was called
74+
``Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent``.
75+
7076
Now that the class is created, you need to register it as a service and
7177
notify Symfony that it is a "listener" on the ``kernel.exception`` event by
7278
using a special "tag":
@@ -151,7 +157,7 @@ listen to the same ``kernel.exception`` event::
151157
namespace App\EventSubscriber;
152158

153159
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
154-
use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
160+
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
155161
use Symfony\Component\HttpKernel\KernelEvents;
156162

157163
class ExceptionSubscriber implements EventSubscriberInterface
@@ -168,17 +174,17 @@ listen to the same ``kernel.exception`` event::
168174
];
169175
}
170176

171-
public function processException(GetResponseForExceptionEvent $event)
177+
public function processException(ExceptionEvent $event)
172178
{
173179
// ...
174180
}
175181

176-
public function logException(GetResponseForExceptionEvent $event)
182+
public function logException(ExceptionEvent $event)
177183
{
178184
// ...
179185
}
180186

181-
public function notifyException(GetResponseForExceptionEvent $event)
187+
public function notifyException(ExceptionEvent $event)
182188
{
183189
// ...
184190
}
@@ -207,11 +213,11 @@ or a "sub request"::
207213
// src/EventListener/RequestListener.php
208214
namespace App\EventListener;
209215

210-
use Symfony\Component\HttpKernel\Event\GetResponseEvent;
216+
use Symfony\Component\HttpKernel\Event\RequestEvent;
211217

212218
class RequestListener
213219
{
214-
public function onKernelRequest(GetResponseEvent $event)
220+
public function onKernelRequest(RequestEvent $event)
215221
{
216222
if (!$event->isMasterRequest()) {
217223
// don't do anything if it's not the master request

trunk/frontend.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,6 @@ Other Front-End Articles
109109
.. _`Webpack`: https://webpack.js.org/
110110
.. _`Webpacker`: https://github.com/rails/webpacker
111111
.. _`Mix`: https://laravel.com/docs/mix
112-
.. _`Symfony`: http://symfony.com/
112+
.. _`Symfony`: https://symfony.com/
113113
.. _`Full API`: https://github.com/symfony/webpack-encore/blob/master/index.js
114114
.. _`Webpack Encore screencast series`: https://symfonycasts.com/screencast/webpack-encore

0 commit comments

Comments
 (0)
0