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

Commit c7a0fce

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.0'
* 4.0: (36 commits) add note about same-state transitions Corrected recipes minor #8205 Move JavaScript to separate file (technetium, javiereguiluz) [Workflow] Document the new transition completed event [error_pages] Removing misleading checker in code example Added the env vars in the nginx config too Commented the env vars and mentioned that they are optional fix syntax errors and add some more crosslinks Updated LDAP documentation for Symfony 3.1 Updating example README to match note below it Update docs for setting custom response code in exception handler ...
2 parents 77910b3 + 90bf0fe commit c7a0fce

File tree

19 files changed

+236
-100
lines changed

19 files changed

+236
-100
lines changed

‎best_practices/security.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,13 @@ of ``bcrypt`` are the inclusion of a *salt* value to protect against rainbow
3737
table attacks, and its adaptive nature, which allows to make it slower to
3838
remain resistant to brute-force search attacks.
3939

40+
.. note::
41+
42+
:ref:`Argon2i <reference-security-argon2i>` is the hashing algorithm as
43+
recommended by industry standards, but this won't be available to you unless
44+
you are using PHP 7.2+ or have the `libsodium`_ extension installed.
45+
``bcrypt`` is sufficient for most applications.
46+
4047
With this in mind, here is the authentication setup from our application,
4148
which uses a login form to load users from the database:
4249

@@ -408,3 +415,4 @@ Next: :doc:`/best_practices/web-assets`
408415
.. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
409416
.. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
410417
.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
418+
.. _`libsodium`: https://pecl.php.net/package/libsodium

‎bundles/best_practices.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ following standardized instructions in your ``README.md`` file.
220220
following command to download the latest stable version of this bundle:
221221
222222
```console
223-
$ composer require <package-name> "~1"
223+
$ composer require <package-name>
224224
```
225225
226226
This command requires you to have Composer installed globally, as explained
@@ -278,7 +278,7 @@ following standardized instructions in your ``README.md`` file.
278278
279279
.. code-block:: terminal
280280
281-
$ composer require <package-name> "~1"
281+
$ composer require <package-name>
282282
283283
This command requires you to have Composer installed globally, as explained
284284
in the `installation chapter`_ of the Composer documentation.

‎components/filesystem/lock_handler.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ LockHandler
66
.. caution::
77

88
The ``LockHandler`` utility was removed in Symfony 4.0. Use the new Symfony
9-
Lock component instead.
9+
:doc:`Lock component </components/lock>` instead.

‎components/ldap.rst

Lines changed: 27 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ and query against an LDAP server.
2525

2626
The ``Ldap`` class uses an :class:`Symfony\\Component\\Ldap\\Adapter\\AdapterInterface`
2727
to communicate with an LDAP server. The :class:`adapter <Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\Adapter>`
28-
for PHP's built-in LDAP extension, for example, can be configured
29-
using the following options:
28+
for PHP's built-in LDAP extension, for example, can be configured using the
29+
following options:
3030

3131
``host``
3232
IP or hostname of the LDAP server
@@ -38,31 +38,39 @@ using the following options:
3838
The version of the LDAP protocol to use
3939

4040
``encryption``
41-
The encryption protocol : ``ssl``, ``tls`` or ``none`` (default)
41+
The encryption protocol: ``ssl``, ``tls`` or ``none`` (default)
42+
43+
``connection_string``
44+
  You may use this option instead of ``host`` and ``port`` to connect to the
45+
LDAP server
46+
47+
``optReferrals``
48+
Specifies whether to automatically follow referrals returned by the LDAP server
4249

4350
``options``
44-
LDAP server's options as defined in :class:`ConnectionOptions <Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\ConnectionOptions>`
51+
LDAP server's options as defined in
52+
:class:`ConnectionOptions <Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\ConnectionOptions>`
4553

4654
For example, to connect to a start-TLS secured LDAP server::
4755

48-
use Symfony\Component\Ldap\Adapter\ExtLdap\Adapter;
4956
use Symfony\Component\Ldap\Ldap;
5057

51-
$adapter = new Adapter(array(
58+
$ldap = Ldap::create('ext_ldap', array(
5259
'host' => 'my-server',
53-
'port' => 389,
54-
'encryption' => 'tls',
55-
'options' => array(
56-
'protocol_version' => 3,
57-
'referrals' => false,
58-
),
60+
'encryption' => 'ssl',
5961
));
60-
$ldap = new Ldap($adapter);
62+
63+
Or you could directly specify a connection string::
64+
65+
use Symfony\Component\Ldap\Ldap;
66+
67+
$ldap = Ldap::create('ext_ldap', array('connection_string' => 'ldaps://my-server:636'));
6168

6269
The :method:`Symfony\\Component\\Ldap\\Ldap::bind` method
6370
authenticates a previously configured connection using both the
6471
distinguished name (DN) and the password of a user::
6572

73+
use Symfony\Component\Ldap\Ldap;
6674
// ...
6775

6876
$ldap->bind($dn, $password);
@@ -71,6 +79,7 @@ Once bound (or if you enabled anonymous authentication on your
7179
LDAP server), you may query the LDAP server using the
7280
:method:`Symfony\\Component\\Ldap\\Ldap::query` method::
7381

82+
use Symfony\Component\Ldap\Ldap;
7483
// ...
7584

7685
$query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
@@ -85,19 +94,21 @@ all entries in a single call and do something with the results'
8594
array, you may use the
8695
:method:`Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\Collection::toArray` method::
8796

97+
use Symfony\Component\Ldap\Ldap;
8898
// ...
8999

90100
$query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
91101
$results = $query->execute()->toArray();
92102

93103
// Do something with the results array
94104

95-
Creating or updating entries
105+
Creating or Updating Entries
96106
----------------------------
97107

98-
Since version 3.1, The Ldap component provides means to create
99-
new LDAP entries, update or even delete existing ones::
108+
The Ldap component provides means to create new LDAP entries, update or even
109+
delete existing ones::
100110

111+
use Symfony\Component\Ldap\Ldap;
101112
use Symfony\Component\Ldap\Entry;
102113
// ...
103114

‎console/lockable_trait.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,10 @@ Prevent Multiple Executions of a Console Command
22
================================================
33

44
A simple but effective way to prevent multiple executions of the same command in
5-
a single server is to use **file locks**. The Lock component eases the creation
6-
and release of these locks.
5+
a single server is to use `locks`_. The :doc:`Lock component </components/lock>`
6+
provides multiple classes to create locks based on the filesystem (:ref:`FlockStore <lock-store-flock>`),
7+
shared memory (:ref:`SemaphoreStore <lock-store-semaphore>`) and even databases
8+
and Redis servers.
79

810
In addition, the Console component provides a PHP trait called ``LockableTrait``
911
that adds two convenient methods to lock and release commands::
@@ -35,3 +37,5 @@ that adds two convenient methods to lock and release commands::
3537
$this->release();
3638
}
3739
}
40+
41+
.. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science)

‎controller/error_pages.rst

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,10 +98,6 @@ To override the 404 error template for HTML pages, create a new
9898
{% block body %}
9999
<h1>Page not found</h1>
100100

101-
{% if is_granted('IS_AUTHENTICATED_FULLY') %}
102-
{# ... #}
103-
{% endif %}
104-
105101
<p>
106102
The requested page couldn't be located. Checkout for any URL
107103
misspelling or <a href="{{ path('homepage') }}">return to the homepage</a>.

‎doctrine/registration_form.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ With some validation added, your class may look something like this::
138138

139139
public function getSalt()
140140
{
141-
// The bcrypt algorithm doesn't require a separate salt.
141+
// The bcrypt and argon2i algorithms don't require a separate salt.
142142
// You *may* need a real salt if you choose a different encoder.
143143
return null;
144144
}

‎form/unit_testing.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ To solve this, you have to mock the injected dependencies, instantiate your own
115115
form type and use the :class:`Symfony\\Component\\Form\\PreloadedExtension` to
116116
make sure the ``FormRegistry`` uses the created instance::
117117

118-
// tests/Form/Type/TestedTypeTests.php
118+
// tests/Form/Type/TestedTypeTest.php
119119
namespace App\Tests\Form\Type;
120120

121121
use App\Form\Type\TestedType;
@@ -169,7 +169,7 @@ will be raised if you try to test a class that depends on other extensions.
169169
The :method:`Symfony\\Component\\Form\\Test\\TypeTestCase::getExtensions` method
170170
allows you to return a list of extensions to register::
171171

172-
// tests/Form/Type/TestedTypeTests.php
172+
// tests/Form/Type/TestedTypeTest.php
173173
namespace App\Tests\Form\Type;
174174

175175
// ...
@@ -216,7 +216,7 @@ Testing against Different Sets of Data
216216
If you are not familiar yet with PHPUnit's `data providers`_, this might be
217217
a good opportunity to use them::
218218

219-
// tests/Form/Type/TestedTypeTests.php
219+
// tests/Form/Type/TestedTypeTest.php
220220
namespace App\Tests\Form\Type;
221221

222222
use App\Form\Type\TestedType;

‎page_creation.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ simple two-step process:
2020

2121
.. seealso::
2222

23-
Do you prefer video tutorials? Check out the `Joyful Development with Symfony`_
23+
Do you prefer video tutorials? Check out the `Stellar Development with Symfony`_
2424
screencast series from KnpUniversity.
2525

2626
.. seealso::
@@ -341,5 +341,5 @@ Go Deeper with HTTP & Framework Fundamentals
341341

342342
.. _`Twig`: http://twig.sensiolabs.org
343343
.. _`Composer`: https://getcomposer.org
344-
.. _`Joyful Development with Symfony`: http://knpuniversity.com/screencast/symfony/first-page
344+
.. _`Stellar Development with Symfony`: https://knpuniversity.com/screencast/symfony/setup
345345
.. _`symfony.sh`: https://symfony.sh/

‎reference/configuration/security.rst

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,10 @@ Each part will be explained in the next section.
6464
algorithm: plaintext
6565
ignore_case: false
6666
67+
# Argon2i encoder
68+
Acme\DemoBundle\Entity\User6:
69+
algorithm: argon2i
70+
6771
providers: # Required
6872
# Examples:
6973
my_in_memory_provider:
@@ -592,7 +596,7 @@ persisting the encoded password alone is enough.
592596

593597
.. note::
594598

595-
All the encoded passwords are ``60`` characters long, so make sure to
599+
BCrypt encoded passwords are ``60`` characters long, so make sure to
596600
allocate enough space for them to be persisted.
597601

598602
.. tip::
@@ -601,7 +605,63 @@ persisting the encoded password alone is enough.
601605
the cost to ``4``, which is the minimum value allowed, in the ``test``
602606
environment configuration.
603607

604-
.. _reference-security-firewall-context:
608+
.. _reference-security-argon2i:
609+
610+
Using the Argon2i Password Encoder
611+
----------------------------------
612+
613+
.. caution::
614+
615+
To use this encoder, you either need to use PHP version 7.2 or install
616+
the `libsodium`_ extension.
617+
618+
.. configuration-block::
619+
620+
.. code-block:: yaml
621+
622+
# app/config/security.yml
623+
security:
624+
# ...
625+
626+
encoders:
627+
Symfony\Component\Security\Core\User\User:
628+
algorithm: argon2i
629+
630+
.. code-block:: xml
631+
632+
<!-- app/config/security.xml -->
633+
<config>
634+
<!-- ... -->
635+
<encoder
636+
class="Symfony\Component\Security\Core\User\User"
637+
algorithm="argon2i"
638+
/>
639+
</config>
640+
641+
.. code-block:: php
642+
643+
// app/config/security.php
644+
use Symfony\Component\Security\Core\User\User;
645+
646+
$container->loadFromExtension('security', array(
647+
// ...
648+
'encoders' => array(
649+
User::class => array(
650+
'algorithm' => 'argon2i',
651+
),
652+
),
653+
));
654+
655+
A salt for each new password is generated automatically and need not be
656+
persisted. Since an encoded password contains the salt used to encode it,
657+
persisting the encoded password alone is enough.
658+
659+
.. note::
660+
661+
Argon2i encoded passwords are ``96`` characters long, but due to the hashing
662+
requirements saved in the resulting hash this may change in the future.
663+
664+
.. _reference-security-firewall-context:
605665

606666
Firewall Context
607667
----------------
@@ -678,3 +738,4 @@ multiple firewalls, the "context" could actually be shared:
678738

679739
.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
680740
.. _`ircmaxell/password-compat`: https://packagist.org/packages/ircmaxell/password-compat
741+
.. _`libsodium`: https://pecl.php.net/package/libsodium

‎reference/events.rst

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -217,22 +217,35 @@ sent as response::
217217
that forwards the ``Request`` to a given controller defined by the
218218
``exception_listener.controller`` parameter.
219219

220-
.. note::
220+
Symfony uses the following logic to determine the HTTP status code of the
221+
response:
222+
223+
* If :method:`Symfony\\Component\\HttpFoundation\\Response::isClientError`,
224+
:method:`Symfony\\Component\\HttpFoundation\\Response::isServerError` or
225+
:method:`Symfony\\Component\\HttpFoundation\\Response::isRedirect` is true,
226+
then the status code on your ``Response`` object is used;
227+
228+
* If the original exception implements
229+
:class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface`,
230+
then ``getStatusCode()`` is called on the exception and used (the headers
231+
from ``getHeaders()`` are also added);
221232

222-
Symfony uses the following logic to determine the HTTP status code of the
223-
response:
233+
* If both of the above aren't true, then a 500 status code is used.
224234

225-
* If :method:`Symfony\\Component\\HttpFoundation\\Response::isClientError`,
226-
:method:`Symfony\\Component\\HttpFoundation\\Response::isServerError` or
227-
:method:`Symfony\\Component\\HttpFoundation\\Response::isRedirect` is true,
228-
then the status code on your ``Response`` object is used;
235+
.. note::
236+
237+
If you want to overwrite the status code of the exception response, which
238+
you should not without a good reason, call
239+
``GetResponseForExceptionEvent::allowSuccessfulResponse()`` first and then
240+
set the status code on the response::
229241

230-
* If the original exception implements
231-
:class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface`,
232-
then ``getStatusCode()`` is called on the exception and used (the headers
233-
from ``getHeaders()`` are also added);
242+
$event->allowSuccessfulResponse();
243+
$response = new Response('No Content', 204);
244+
$event->setResponse($response);
234245

235-
* If both of the above aren't true, then a 500 status code is used.
246+
The status code sent to the client in the above example will be ``204``. If
247+
``$event->allowSuccessfulResponse()`` is omitted, then the kernel will set
248+
an appropriate status code based on the type of exception thrown.
236249

237250
.. seealso::
238251

0 commit comments

Comments
 (0)
0