Skip to content

Commit b56880b

Browse files
wouterjwouterj
committed
Merge branch '2.7' into 2.8
Conflicts: components/security/secure_tools.rst
2 parents 075a81d + d1e109e commit b56880b

37 files changed

+296
-79
lines changed

‎best_practices/tests.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,12 +113,13 @@ pure JavaScript-based testing tools.
113113
Learn More about Functional Tests
114114
---------------------------------
115115

116-
Consider using `Faker`_ and `Alice`_ libraries to generate real-looking data
117-
for your test fixtures.
116+
Consider using the `HautelookAliceBundle`_ to generate real-looking data for
117+
your test fixtures using `Faker`_ and `Alice`_.
118118

119119
.. _`Faker`: https://github.com/fzaninotto/Faker
120120
.. _`Alice`: https://github.com/nelmio/alice
121121
.. _`PhpUnit`: https://phpunit.de/
122122
.. _`PhpSpec`: http://www.phpspec.net/
123123
.. _`Mink`: http://mink.behat.org
124124
.. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software)
125+
.. _`HautelookAliceBundle`: https://github.com/hautelook/AliceBundle

‎book/security.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -513,7 +513,7 @@ else, you'll want to encode their passwords. The best algorithm to use is
513513
.. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
514514

515515
Of course, your users' passwords now need to be encoded with this exact algorithm.
516-
For hardcoded users, since 2.7 you can use the built-in command :
516+
For hardcoded users, since 2.7 you can use the built-in command:
517517

518518
.. code-block:: bash
519519

‎components/form/introduction.rst‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -113,45 +113,45 @@ CSRF Protection
113113
~~~~~~~~~~~~~~~
114114

115115
Protection against CSRF attacks is built into the Form component, but you need
116-
to explicitly enable it or replace it with a custom solution. The following
117-
snippet adds CSRF protection to the form factory::
116+
to explicitly enable it or replace it with a custom solution. If you want to
117+
use the built-in support, require the Security CSRF component by executing
118+
``composer require symfony/security-csrf``.
119+
120+
The following snippet adds CSRF protection to the form factory::
118121

119122
use Symfony\Component\Form\Forms;
120-
use Symfony\Component\Form\Extension\Csrf\CsrfExtension;
121-
use Symfony\Component\Form\Extension\Csrf\CsrfProvider\SessionCsrfProvider;
122123
use Symfony\Component\HttpFoundation\Session\Session;
123-
124-
// generate a CSRF secret from somewhere
125-
$csrfSecret = '<generated token>';
124+
use Symfony\Component\Security\Extension\Csrf\CsrfExtension;
125+
use Symfony\Component\Security\Csrf\TokenStorage\SessionTokenStorage;
126+
use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
127+
use Symfony\Component\Security\Csrf\CsrfTokenManager;
126128

127129
// create a Session object from the HttpFoundation component
128130
$session = new Session();
129131

130-
$csrfProvider = new SessionCsrfProvider($session, $csrfSecret);
132+
$csrfGenerator = new UriSafeTokenGenerator();
133+
$csrfStorage = new SessionTokenStorage($session);
134+
$csrfManager = new CsrfTokenManager($csrfGenerator, $csrfStorage);
131135

132136
$formFactory = Forms::createFormFactoryBuilder()
133137
// ...
134-
->addExtension(new CsrfExtension($csrfProvider))
138+
->addExtension(new CsrfExtension($csrfStorage))
135139
->getFormFactory();
136140

137-
To secure your application against CSRF attacks, you need to define a CSRF
138-
secret. Generate a random string with at least 32 characters, insert it in the
139-
above snippet and make sure that nobody except your web server can access
140-
the secret.
141-
142141
Internally, this extension will automatically add a hidden field to every
143-
form (called ``_token`` by default) whose value is automatically generated
144-
and validated when binding the form.
142+
form (called ``_token`` by default) whose value is automatically generated by
143+
the CSRF generator and validated when binding the form.
145144

146145
.. tip::
147146

148147
If you're not using the HttpFoundation component, you can use
149-
:class:`Symfony\\Component\\Form\\Extension\\Csrf\\CsrfProvider\\DefaultCsrfProvider`
148+
:class:`Symfony\\Component\\Security\\Csrf\\TokenStorage\\NativeSessionTokenStorage`
150149
instead, which relies on PHP's native session handling::
151150

152-
use Symfony\Component\Form\Extension\Csrf\CsrfProvider\DefaultCsrfProvider;
151+
use Symfony\Component\Security\Csrf\TokenStorage\NativeSessionTokenStorage;
153152

154-
$csrfProvider = new DefaultCsrfProvider($csrfSecret);
153+
$csrfStorage = new NativeSessionTokenStorage();
154+
// ...
155155

156156
Twig Templating
157157
~~~~~~~~~~~~~~~

‎components/security/secure_tools.rst‎

Lines changed: 25 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,43 @@
1-
Securely Generating Random Numbers
2-
==================================
1+
Securely Generating Random Values
2+
=================================
33

44
The Symfony Security component comes with a collection of nice utilities
55
related to security. These utilities are used by Symfony, but you should
66
also use them if you want to solve the problem they address.
77

8-
Generating a Secure random Number
8+
Generating a Secure random String
99
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1010

11-
Whenever you need to generate a secure random number, you are highly
12-
encouraged to use the Symfony
13-
:class:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom` class::
11+
Whenever you need to generate a secure random string, you are highly
12+
encouraged to use the :phpfunction:`random_bytes` function::
1413

15-
use Symfony\Component\Security\Core\Util\SecureRandom;
14+
$random = random_bytes(10);
1615

17-
$generator = new SecureRandom();
18-
$random = $generator->nextBytes(10);
16+
The function returns a random string, suitable for cryptographic use, of
17+
the number bytes passed as an argument (10 in the above example).
1918

20-
The
21-
:method:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom::nextBytes`
22-
method returns a random string composed of the number of characters passed as
23-
an argument (10 in the above example).
19+
.. tip::
2420

25-
The SecureRandom class works better when OpenSSL is installed. But when it's
26-
not available, it falls back to an internal algorithm, which needs a seed file
27-
to work correctly. Just pass a file name to enable it::
21+
The ``random_bytes()`` function returns a binary string which may contain
22+
the ``\0`` character. This can cause trouble in several common scenarios,
23+
such as storing this value in a database or including it as part of the
24+
URL. The solution is to encode or hash the value returned by
25+
``random_bytes()`` (to do that, you can use a simple ``base64_encode()``
26+
PHP function).
2827

29-
use Symfony\Component\Security\Core\Util\SecureRandom;
28+
Generating a Secure Random Number
29+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3030

31-
$generator = new SecureRandom('/some/path/to/store/the/seed.txt');
31+
If you need to generate a cryptographically secure random integer, you should
32+
use the :phpfunction:`random_int` function::
3233

33-
$random = $generator->nextBytes(10);
34-
$hashedRandom = md5($random); // see tip below
34+
$random = random_int(1, 10);
3535

3636
.. note::
3737

38-
If you're using the Symfony Framework, you can get a secure random number
39-
generator via the ``security.secure_random`` service.
40-
41-
.. tip::
38+
PHP 7 and up provide the ``random_bytes()`` and ``random_int()`` functions
39+
natively, for older versions of PHP a polyfill is provided by the
40+
`Symfony Polyfill Component`_ and the `paragonie/random_compat package`_.
4241

43-
The ``nextBytes()`` method returns a binary string which may contain the
44-
``\0`` character. This can cause trouble in several common scenarios, such
45-
as storing this value in a database or including it as part of the URL. The
46-
solution is to hash the value returned by ``nextBytes()`` (to do that, you
47-
can use a simple ``md5()`` PHP function).
42+
.. _`Symfony Polyfill Component`: https://github.com/symfony/polyfill
43+
.. _`paragonie/random_compat package`: https://github.com/paragonie/random_compat

‎components/translation/usage.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,8 @@ recommended format. These files are parsed by one of the loader classes.
139139
'symfony.great' => 'J\'aime Symfony',
140140
);
141141
142+
.. _translation-real-vs-keyword-messages:
143+
142144
.. sidebar:: Using Real or Keyword Messages
143145

144146
This example illustrates the two different philosophies when creating

‎cookbook/email/gmail.rst‎

Lines changed: 73 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,6 @@ During development, instead of using a regular SMTP server to send emails, you
88
might find using Gmail easier and more practical. The SwiftmailerBundle makes
99
it really easy.
1010

11-
.. tip::
12-
13-
Instead of using your regular Gmail account, it's of course recommended
14-
that you create a special account.
15-
1611
In the development configuration file, change the ``transport`` setting to
1712
``gmail`` and set the ``username`` and ``password`` to the Google credentials:
1813

@@ -55,33 +50,87 @@ In the development configuration file, change the ``transport`` setting to
5550
'password' => 'your_gmail_password',
5651
));
5752
58-
You're done!
59-
6053
.. tip::
6154

62-
If you are using the Symfony Standard Edition, configure the parameters in ``parameters.yml``:
55+
It's more convenient to configure these options in the ``parameters.yml``
56+
file:
6357

6458
.. code-block:: yaml
6559
6660
# app/config/parameters.yml
6761
parameters:
6862
# ...
69-
mailer_transport: gmail
70-
mailer_host: ~
71-
mailer_user: your_gmail_username
72-
mailer_password: your_gmail_password
73-
74-
.. note::
75-
76-
The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
77-
and sets ``encryption``, ``auth_mode`` and ``host`` to work with Gmail.
78-
79-
.. note::
80-
81-
Depending on your Gmail account settings, you may get authentication errors
82-
within your app. If your Gmail account uses 2-Step-Verification, you should
83-
`generate an App password`_ to use for your ``mailer_password`` parameter.
84-
You should also ensure that you `allow less secure apps to access your Gmail account`_.
63+
mailer_user: your_gmail_username
64+
mailer_password: your_gmail_password
65+
66+
.. configuration-block::
67+
68+
.. code-block:: yaml
69+
70+
# app/config/config_dev.yml
71+
swiftmailer:
72+
transport: gmail
73+
username: '%mailer_user%'
74+
password: '%mailer_password%'
75+
76+
.. code-block:: xml
77+
78+
<!-- app/config/config_dev.xml -->
79+
<?xml version="1.0" encoding="UTF-8" ?>
80+
<container xmlns="http://symfony.com/schema/dic/services"
81+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
82+
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
83+
xsi:schemaLocation="http://symfony.com/schema/dic/services
84+
http://symfony.com/schema/dic/services/services-1.0.xsd
85+
http://symfony.com/schema/dic/swiftmailer
86+
http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
87+
88+
<!-- ... -->
89+
<swiftmailer:config
90+
transport="gmail"
91+
username="%mailer_user%"
92+
password="%mailer_password%"
93+
/>
94+
</container>
95+
96+
.. code-block:: php
97+
98+
// app/config/config_dev.php
99+
$container->loadFromExtension('swiftmailer', array(
100+
'transport' => 'gmail',
101+
'username' => '%mailer_user%',
102+
'password' => '%mailer_password%',
103+
));
104+
105+
Redefining the Default Configuration Parameters
106+
-----------------------------------------------
107+
108+
The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
109+
and sets these options:
110+
111+
============== ==================
112+
Option Value
113+
============== ==================
114+
``encryption`` ``ssl``
115+
``auth_mode`` ``login``
116+
``host`` ``smtp.gmail.com``
117+
============== ==================
118+
119+
If your application uses ``tls`` encryption or ``oauth`` authentication, you
120+
must override the default options by defining the ``encryption`` and ``auth_mode``
121+
parameters.
122+
123+
If you are using 2-Step-Verification, you must `generate an App password`_ and
124+
use this as your ``mailer_password`` value.
125+
126+
If your Gmail account uses 2-Step-Verification, you must `generate an App password`_
127+
and use it as the value of the ``mailer_password`` parameter. You must also ensure
128+
that you `allow less secure apps to access your Gmail account`_.
129+
130+
.. seealso::
131+
132+
see the :doc:`Swiftmailer configuration reference </reference/configuration/swiftmailer>`
133+
for more details.
85134

86135
.. _`generate an App password`: https://support.google.com/accounts/answer/185833
87136
.. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255

‎cookbook/request/load_balancer_reverse_proxy.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
8383
// web/app.php
8484

8585
// ...
86-
Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR')));
86+
Request::setTrustedProxies(array('127.0.0.1', $request->server->get('REMOTE_ADDR')));
8787

8888
$response = $kernel->handle($request);
8989
// ...

‎cookbook/routing/redirect_trailing_slash.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,26 @@ system, as explained below:
3737

3838
.. configuration-block::
3939

40+
.. code-block:: php-annotations
41+
42+
// src/AppBundle/Controller/RedirectingController.php
43+
namespace AppBundle\Controller;
44+
45+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
46+
use Symfony\Component\HttpFoundation\Request;
47+
48+
class RedirectingController extends Controller
49+
{
50+
/**
51+
* @Route("/{url}", name="remove_trailing_slash",
52+
* requirements={"url" = ".*\/$"}, methods={"GET"})
53+
*/
54+
public function removeTrailingSlashAction(Request $request)
55+
{
56+
// ...
57+
}
58+
}
59+
4060
.. code-block:: yaml
4161
4262
remove_trailing_slash:

‎create_framework/unit_testing.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ using `PHPUnit`_. Create a PHPUnit configuration file in
2626
<directory>./tests</directory>
2727
</testsuite>
2828
</testsuites>
29+
30+
<filter>
31+
<whitelist processUncoveredFilesFromWhitelist="true">
32+
<directory suffix=".php">./src</directory>
33+
</whitelist>
34+
</filter>
2935
</phpunit>
3036
3137
This configuration defines sensible defaults for most PHPUnit settings; more
@@ -180,6 +186,12 @@ Open ``example.com/cov/src/Simplex/Framework.php.html`` in a browser and check
180186
that all the lines for the Framework class are green (it means that they have
181187
been visited when the tests were executed).
182188

189+
Alternatively you can output the result directly to the console:
190+
191+
.. code-block:: bash
192+
193+
$ phpunit --coverage-text
194+
183195
Thanks to the simple object-oriented code that we have written so far, we have
184196
been able to write unit-tests to cover all possible use cases of our
185197
framework; test doubles ensured that we were actually testing our code and not

‎glossary.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,11 @@ Glossary
125125
Symfony's configuration files. See the :doc:`/components/yaml/introduction`
126126
chapter.
127127

128+
Annotation
129+
Annotations are metadata written alongside your code. They can either be explanatory and will be
130+
ignored during execution or add functionality to the line of code directly below as a means of
131+
configuration. For example, the annotation ``@var`` describes the type of a variable, whereas in
132+
Symfony2 ``@Assert`` can add validation to a member variable of a class (see :doc:`/book/validation` chapter).
128133

129134
.. _`service-oriented architecture`: https://wikipedia.org/wiki/Service-oriented_architecture
130135
.. _`HTTP Wikipedia`: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

0 commit comments

Comments
 (0)