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

Commit 603556f

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.2'
* 4.2: be keen to newcomers Uncomment some code in "Configuring Babel" Fix typo: if -> of
2 parents 5aa9ee5 + 33fdfd6 commit 603556f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+98
-108
lines changed

‎best_practices/controllers.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ Fetching Services
128128

129129
If you extend the base ``AbstractController`` class, you can't access services
130130
directly from the container via ``$this->container->get()`` or ``$this->get()``.
131-
Instead, you must use dependency injection to fetch services: most easily done by
131+
Instead, you must use dependency injection to fetch services by
132132
:ref:`type-hinting action method arguments <controller-accessing-services>`:
133133

134134
.. best-practice::
@@ -218,9 +218,9 @@ flexible::
218218
// ...
219219
}
220220

221-
The point is this: the ParamConverter shortcut is great for simple situations.
222-
But you shouldn't forget that querying for entities directly is still very
223-
easy.
221+
The point is this: the ParamConverter shortcut is great for most situations.
222+
However, there is nothing wrong with querying for entities directly if the
223+
ParamConverter would get complicated.
224224

225225
Pre and Post Hooks
226226
------------------

‎best_practices/security.rst

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -105,8 +105,7 @@ The @Security Annotation
105105
------------------------
106106

107107
For controlling access on a controller-by-controller basis, use the ``@Security``
108-
annotation whenever possible. It's easy to read and is placed consistently
109-
above each action.
108+
annotation whenever possible. Placing it above each action makes it consistent and readable.
110109

111110
In our application, you need the ``ROLE_ADMIN`` in order to create a new post.
112111
Using ``@Security``, this looks like:
@@ -153,7 +152,7 @@ Notice that this requires the use of the `ParamConverter`_, which automatically
153152
queries for the ``Post`` object and puts it on the ``$post`` argument. This
154153
is what makes it possible to use the ``post`` variable in the expression.
155154

156-
This has one major drawback: an expressio 10000 n in an annotation cannot easily
155+
This has one major drawback: an expression in an annotation cannot
157156
be reused in other parts of the application. Imagine that you want to add
158157
a link in a template that will only be seen by authors. Right now you'll
159158
need to repeat the expression code using Twig syntax:
@@ -164,7 +163,7 @@ need to repeat the expression code using Twig syntax:
164163
<a href=""> ... </a>
165164
{% endif %}
166165

167-
The easiest solution - if your logic is simple enough - is to add a new method
166+
A good solution - if your logic is simple enough - can be to add a new method
168167
to the ``Post`` entity that checks if a given user is its author::
169168

170169
// src/Entity/Post.php

‎best_practices/templates.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ and ``edit_form.html.twig`` instead of ``EditForm.html.twig``).
4444
Use a prefixed underscore for partial templates in template names.
4545

4646
You often want to reuse template code using the ``include`` function to avoid
47-
redundant code. To determine those partials easily in the filesystem you should
47+
redundant code. To determine those partials in the filesystem you should
4848
prefix partials and any other template without HTML body or ``extends`` tag
4949
with a single underscore.
5050

‎bundles/best_practices.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@
44
Best Practices for Reusable Bundles
55
===================================
66

7-
This article is all about how to structure your **reusable bundles** so that
8-
they're easy to configure and extend. Reusable bundles are those meant to be
9-
shared privately across many company projects or publicly so any Symfony project
10-
can install them.
7+
This article is all about how to structure your **reusable bundles** to be
8+
configurable and extendable. Reusable bundles are those meant to be shared
9+
privately across many company projects or publicly so any Symfony project can
10+
install them.
1111

1212
.. index::
1313
pair: Bundle; Naming conventions

‎configuration/external_parameters.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@ How to Set external Parameters in the Service Container
77
In :doc:`/configuration`, you learned how to manage your application
88
configuration. At times, it may benefit your application to store certain
99
credentials outside of your project code. Database configuration is one such
10-
example. The flexibility of the Symfony service container allows you to easily
11-
do this.
10+
example. The flexibility of the Symfony service container allows you to do this.
1211

1312
.. _config-env-vars:
1413

‎configuration/front_controllers_and_kernel.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -138,9 +138,8 @@ the ``configureContainer()`` method to decide which configuration files to load.
138138

139139
Symfony's default ``Kernel`` class implements this method by loading first the
140140
config files found on ``config/packages/*`` and then, the files found on
141-
``config/packages/ENVIRONMENT_NAME/``. You are, of course, free to implement
142-
this method differently if you need a more sophisticated way of loading your
143-
configuration.
141+
``config/packages/ENVIRONMENT_NAME/``. You are free to implement this method
142+
differently if you need a more sophisticated way of loading your configuration.
144143

145144
.. _front controller: https://en.wikipedia.org/wiki/Front_Controller_pattern
146145
.. _decorate: https://en.wikipedia.org/wiki/Decorator_pattern

‎configuration/override_dir_structure.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ Override the ``public`` Directory
185185

186186
If you need to rename or move your ``public`` directory, the only thing you need
187187
to guarantee is that the path to the ``var`` directory is still correct in your
188-
``index.php`` front controller. If you simply renamed the directory, you're
188+
``index.php`` front controller. If you renamed the directory, you're
189189
fine. But if you moved it in some way, you may need to modify these paths inside
190190
those files::
191191

‎console/style.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,7 @@ User Input Methods
226226

227227
$io->ask('What is your name?');
228228

229-
You can pass the default value as the second argument so the user can simply
229+
You can pass the default value as the second argument so the user can
230230
hit the <Enter> key to select that value::
231231

232232
$io->ask('Where are you from?', 'United States');
@@ -262,7 +262,7 @@ User Input Methods
262262

263263
$io->confirm('Restart the web server?');
264264

265-
You can pass the default value as the second argument so the user can simply
265+
You can pass the default value as the second argument so the user can
266266
hit the <Enter> key to select that value::
267267

268268
$io->confirm('Restart the web server?', true);
@@ -273,7 +273,7 @@ User Input Methods
273273

274274
$io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3']);
275275

276-
You can pass the default value as the third argument so the user can simply
276+
You can pass the default value as the third argument so the user can
277277
hit the <Enter> key to select that value::
278278

279279
$io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3'], 'queue1');

‎create_framework/http_foundation.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ As you can see for yourself, the simple code we had written first is not that
5252
simple anymore if we want to avoid PHP warnings/notices and make the code
5353
more secure.
5454

55-
Beyond security, this code is not even easily testable. Even if there is not
55+
Beyond security, this code can be complex to test. Even if there is not
5656
much to test, it strikes me that writing unit tests for the simplest possible
5757
snippet of PHP code is not natural and feels ugly. Here is a tentative PHPUnit
5858
unit test for the above code::
@@ -126,10 +126,10 @@ containing the new requirement.
126126
.. sidebar:: Class Autoloading
127127

128128
When installing a new dependency, Composer also generates a
129-
``vendor/autoload.php`` file that allows any class to be easily
130-
`autoloaded`_. Without autoloading, you would need to require the file
131-
where a class is defined before being able to use it. But thanks to
132-
`PSR-4`_, we can just let Composer and PHP do the hard work for us.
129+
``vendor/autoload.php`` file that allows any class to be `autoloaded`_.
130+
Without autoloading, you would need to require the file where a class
131+
is defined before being able to use it. But thanks to `PSR-4`_,
132+
we can just let Composer and PHP do the hard work for us.
133133

134134
Now, let's rewrite our application by using the ``Request`` and the
135135
``Response`` classes::

‎email/dev_environment.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@ How to Work with Emails during Development
66

77
When developing an application which sends email, you will often
88
not want to actually send the email to the specified recipient during
9-
development. If you are using the default Symfony mailer, you
10-
can achieve this through configuration settings without having to
11-
make any changes to your application's code at all. There are two main
12-
choices when it comes to handling email during development: (a) disabling the
9+
development. If you are using the SwiftmailerBundle with Symfony, you
10+
can achieve this through configuration settings without having to make
11+
any changes to your application's code at all. There are two main choices
12+
when it comes to handling email during development: (a) disabling the
1313
sending of email altogether or (b) sending all email to a specific
1414
address (with optional exceptions).
1515

‎email/testing.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ SwiftmailerBundle, which leverages the power of the `Swift Mailer`_ library.
1010
To functionally test that an email was sent, and even assert the email subject,
1111
content or any other headers, you can use :doc:`the Symfony Profiler </profiler>`.
1212

13-
Start with a simple controller action that sends an email::
13+
Start with a controller action that sends an email::
1414

1515
public function sendEmail($name, \Swift_Mailer $mailer)
1616
{

‎form/create_custom_field_type.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -270,8 +270,8 @@ link for details), create a ``shipping_widget`` block to handle this:
270270
Using the Field Type
271271
--------------------
272272

273-
You can now use your custom field type immediately, by creating a
274-
new instance of the type in one of your forms::
273+
You can now use your custom field type by creating a new instance of the type in
274+
one of your forms::
275275

276276
// src/Form/Type/OrderType.php
277277
namespace App\Form\Type;

‎form/data_transformers.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ that message with the ``invalid_message`` option (see below).
252252
Using the Transformer
253253
~~~~~~~~~~~~~~~~~~~~~
254254

255-
Next, you need to use the ``IssueToNumberTransformer`` object inside if ``TaskType``
255+
Next, you need to use the ``IssueToNumberTransformer`` object inside of ``TaskType``
256256
and add it to the ``issue`` field. No problem! Add a ``__construct()`` method
257257
and type-hint the new class::
258258

@@ -302,7 +302,7 @@ know to pass your ``TaskType`` an instance of the ``IssueToNumberTransformer``.
302302

303303
Now, you can use your ``TaskType``::
304304

305-
// e.g. in a controller somewhere
305+
// e.g. somewhere in a controller
306306
$form = $this->createForm(TaskType::class, $task);
307307

308308
// ...

‎form/direct_submit.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@
44
How to Use the submit() Function to Handle Form Submissions
55
===========================================================
66

7-
With the ``handleRequest()`` method, you can handle form
8-
submissions::
7+
Handle the form submission with the ``handleRequest()`` method::
98

109
use Symfony\Component\HttpFoundation\Request;
1110
// ...

‎form/embedded.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ How to Embed Forms
66

77
Often, you'll want to build a form that will include fields from many different
88
objects. For example, a registration form may contain data belonging to
9-
a ``User`` object as well as many ``Address`` objects. Fortunately, this
10-
is easy and natural with the Form component.
9+
a ``User`` object as well as many ``Address`` objects. Fortunately this can
10+
be achieved by the Form component.
1111

1212
.. _forms-embedding-single-object:
1313

‎form/form_collections.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -510,9 +510,8 @@ you will learn about next!).
510510
of the relationship is modified.
511511

512512
The trick is to make sure that the single "Task" is set on each "Tag".
513-
One way to do this is to add some extra logic to ``addTag()``,
514-
which is called by the form type since ``by_reference`` is set to
515-
``false``::
513+
One way to do this is to add some extra logic to ``addTag()``, which
514+
is called by the form type since ``by_reference`` is set to ``false``::
516515

517516
// src/Entity/Task.php
518517

‎forms.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ Forms
1010
Do you prefer video tutorials? Check out the `Symfony Forms screencast series`_.
1111

1212
Dealing with HTML forms is one of the most common - and challenging - tasks for
13-
a web developer. Symfony integrates a Form component that makes dealing with
14-
forms easy. In this article, you'll build a complex form from the ground up,
13+
a web developer. Symfony integrates a Form component that helps you dealing
14+
with forms. In this article, you'll build a complex form from the ground up,
1515
learning the most important features of the form library along the way.
1616

1717
Installation
@@ -70,12 +70,12 @@ going to need to build a form. But before you begin, first focus on the generic
7070
}
7171
}
7272

73-
This class is a "plain-old-PHP-object" because, so far, it has nothing
74-
to do with Symfony or any other library. It's a normal PHP object
75-
that directly solves a problem inside *your* application (i.e. the need to
76-
represent a task in your application). By the end of this article,
77-
you'll be able to submit data to a ``Task`` instance (via an HTML form), validate
78-
its data and persist it to the database.
73+
This class is a "plain-old-PHP-object" because, so far, it has nothing to do
74+
with Symfony or any other library. It's a normal PHP object that directly solves
75+
a problem inside *your* application (i.e. the need to represent a task in your
76+
application). By the end of this article, you'll be able to submit data to a
77+
``Task`` instance (via an HTML form), validate its data and persist it to the
78+
database.
7979

8080
.. index::
8181
single: Forms; Create a form in a controller

‎frontend.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ to solve the most common Webpack use cases.
2828
.. tip::
2929

3030
Encore is made by `Symfony`_ and works *beautifully* in Symfony applications.
31-
But it can easily be used in any application... in any language!
31+
But it can be used in any PHP application and even with other server side
32+
programming languages!
3233

3334
.. _encore-toc:
3435

‎frontend/encore/advanced-config.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
Advanced Webpack Config
22
=======================
33

4-
Encore generates the Webpack configuration that's used in your
4+
Summarized, Encore generates the Webpack configuration that's used in your
55
``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
6-
`configuration options`_, because many can be easily added on your own.
6+
`configuration options`_, because many can be added on your own.
77

88
For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
99
modify the config after fetching it from Encore:

‎frontend/encore/babel.rst

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,19 @@ Need to extend the Babel configuration further? The easiest way is via
1818
1919
.configureBabel(function(babelConfig) {
2020
// add additional presets
21-
// babelConfig.presets.push('@babel/preset-flow');
21+
babelConfig.presets.push('@babel/preset-flow');
2222
2323
// no plugins are added by default, but you can add some
24-
// babelConfig.plugins.push('styled-jsx/babel');
24+
babelConfig.plugins.push('styled-jsx/babel');
2525
}, {
2626
// node_modules is not processed through Babel by default
2727
// but you can whitelist specific modules to process
28-
// include_node_modules: ['foundation-sites']
28+
include_node_modules: ['foundation-sites'],
2929
30-
// or completely control the exclude
31-
// exclude: /bower_components/
30+
// or completely control the exclude rule (note that you
31+
// can't use both "include_node_modules" and "exclude" at
32+
// the same time)
33+
exclude: /bower_components/
3234
})
3335
;
3436

‎frontend/encore/cdn.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
Using a CDN
22
===========
33

4-
Are you deploying to a CDN? That's awesome :) - and configuring Encore for that is
5-
easy. Once you've made sure that your built files are uploaded to the CDN, configure
6-
it in Encore:
4+
Are you deploying to a CDN? That's awesome :) Once you've made sure that your
5+
built files are uploaded to the CDN, configure it in Encore:
76

87
.. code-block:: diff
98

‎logging/formatter.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@ How to Define a Custom Logging Formatter
33

44
Each logging handler uses a ``Formatter`` to format the record before logging
55
it. All Monolog handlers use an instance of
6-
``Monolog\Formatter\LineFormatter`` by default but you can configure a
7-
different one. Your formatter must implement
8-
``Monolog\Formatter\FormatterInterface``.
6+
``Monolog\Formatter\LineFormatter`` by default but you can replace it.
7+
Your formatter must implement ``Monolog\Formatter\FormatterInterface``.
98

109
For example, to use the built-in ``JsonFormatter``, register it as a service then
1110
configure your handler to use it:

‎logging/monolog_email.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,8 +138,8 @@ is then passed onto the ``deduplicated`` handler.
138138
set the ``action_level`` to ``error`` instead of ``critical``. See the
139139
code above for an example.
140140

141-
The ``deduplicated`` handler keeps all the messages for a request and
142-
then passes them onto the nested handler in one go, but only if the records are
141+
The ``deduplicated`` handler keeps all the messages for a request and then
142+
passes them onto the nested handler in one go, but only if the records are
143143
unique over a given period of time (60 seconds by default). If the records are
144144
duplicates they are discarded. Adding this handler reduces the amount of
145145
notifications to a manageable level, specially in critical failure scenarios.

‎reference/constraints/Bic.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ check that the BIC is associated with a given IBAN.
2323
Basic Usage
2424
-----------
2525

26-
To use the Bic validator, simply apply it to a property on an object that
26+
To use the Bic validator, apply it to a property on an object that
2727
will contain a Business Identifier Code (BIC).
2828

2929
.. configuration-block::

‎reference/constraints/Callback.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@ Callback
33

44
The purpose of the Callback constraint is to create completely custom
55
validation rules and to assign any validation errors to specific fields
6-
on your object. If you're using validation with forms, this means that you
7-
can make these custom errors display next to a specific field, instead of
8-
simply at the top of your form.
6+
on your object. If you're using validation with forms, this means that
7+
instead of displaying custom errors at the top of the form, you can
8+
display them next to the field they apply to.
99

1010
This process works by specifying one or more *callback* methods, each of
1111
which will be called during the validation process. Each of those methods

‎reference/constraints/CardScheme.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ a payment through a payment gateway.
2020
Basic Usage
2121
-----------
2222

23-
To use the ``CardScheme`` validator, simply apply it to a property or method
23+
To use the ``CardScheme`` validator, apply it to a property or method
2424
on an object that will contain a credit card number.
2525

2626
.. configuration-block::

‎reference/constraints/Choice.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,8 +127,7 @@ Supplying the Choices with a Callback Function
127127

128128
You can also use a callback function to specify your options. This is useful
129129
if you want to keep your choices in some central location so that, for example,
130-
you can easily access those choices for validation or for building a select
131-
form element::
130+
you can access those choices for validation or for building a select form element::
132131

133132
// src/Entity/Author.php
134133
namespace App\Entity;

0 commit comments

Comments
 (0)
0