10000 be keen to newcomers · symfony/symfony-docs@06206bc · GitHub
[go: up one dir, main page]
Skip to content

Commit 06206bc

Browse files
OskarStarkOskarStark
committed
be keen to newcomers
1 parent facbe1a commit 06206bc

Some content is hidden

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

55 files changed

+112
-129
lines changed

‎best_practices/business-logic.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ This practice is cumbersome and completely unnecessary for your own services.
176176
Don't define parameters for the classes of your services.
177177

178178
This practice was wrongly adopted from third-party bundles. When Symfony
179-
introduced its service container, some developers used this technique to easily
179+
introduced its service container, some developers used this technique to
180180
allow overriding services. However, overriding a service by just changing its
181181
class name is a very rare use case because, frequently, the new service has
182182
different constructor arguments.

‎best_practices/controllers.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ Fetching Services
119119

120120
If you extend the base ``Controller`` class, you can access services directly from
121121
the container via ``$this->container->get()`` or ``$this->get()``. But instead, you
122-
should use dependency injection to fetch services: most easily done by
122+
should use dependency injection to fetch services by
123123
:ref:`type-hinting action method arguments <controller-accessing-services>`:
124124

125125
.. best-practice::
@@ -209,8 +209,7 @@ flexible::
209209
}
210210

211211
The point is this: the ParamConverter shortcut is great for simple situations.
212-
But you shouldn't forget that querying for entities directly is still very
213-
easy.
212+
But you shouldn't forget that querying for entities directly is not to hard.
214213

215214
Pre and Post Hooks
216215
------------------

‎best_practices/security.rst

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -108,8 +108,7 @@ The @Security Annotation
108108
------------------------
109109

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

114113
In our application, you need the ``ROLE_ADMIN`` in order to create a new post.
115114
Using ``@Security``, this looks like:
@@ -156,7 +155,7 @@ Notice that this requires the use of the `ParamConverter`_, which automatically
156155
queries for the ``Post`` object and puts it on the ``$post`` argument. This
157156
is what makes it possible to use the ``post`` variable in the expression.
158157

159-
This has one major drawback: an expression in an annotation cannot easily
158+
This has one major drawback: an expression in an annotation cannot
160159
be reused in other parts of the application. Imagine that you want to add
161160
a link in a template 10000 that will only be seen by authors. Right now you'll
162161
need to repeat the expression code using Twig syntax:
@@ -167,7 +166,7 @@ need to repeat the expression code using Twig syntax:
167166
<a href=""> ... </a>
168167
{% endif %}
169168

170-
The easiest solution - if your logic is simple enough - is to add a new method
169+
The best solution - if your logic is simple enough - is to add a new method
171170
to the ``Post`` entity that checks if a given user is its author::
172171

173172
// src/AppBundle/Entity/Post.php

‎best_practices/templates.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ scattered through lots of bundles.
5858
Use a prefixed underscore for partial templates in template names.
5959

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

‎bundles/best_practices.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ There are two types of bundles:
99
* Application-specific bundles: only used to build your application;
1010
* Reusable bundles: meant to be shared across many projects.
1111

12-
This article is all about how to structure your **reusable bundles** so that
13-
they're easy to configure and extend. Many of these recommendations do not
12+
This article is all about how to structure your **reusable bundles** to be
13+
configurable and extendable. Many of these recommendations do not
1414
apply to application bundles because you'll want to keep those as simple
1515
as possible. For application bundles, just follow the practices shown throughout
1616
the guides.

‎bundles/inheritance.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@ Then, register the third-party FOSUserBundle as the "parent" of your bundle::
3535
}
3636
}
3737

38-
By making this simple change, you can now override several parts of the FOSUserBundle
39-
simply by creating a file with the same name.
38+
By making this small change, you can now override several parts of the FOSUserBundle
39+
by creating a file with the same name.
4040

4141
.. note::
4242

@@ -82,8 +82,8 @@ original method, and change its functionality::
8282
Overriding Resources: Templates, Routing, etc
8383
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8484

85-
Most resources can also be overridden, simply by creating a file in the same
86-
location as your parent bundle.
85+
Most resources can also be overridden by creating a file in the same location
86+
as your parent bundle.
8787

8888
For example, it's very common to need to override the FOSUserBundle's
8989
``layout.html.twig`` template so that it uses your application's base layout.

‎configuration/configuration_organization.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ How to Organize Configuration Files
66

77
The default Symfony Standard Edition defines three
88
:doc:`execution environments </configuration/environments>` called
9-
``dev``, ``prod`` and ``test``. An environment simply represents a way to
9+
``dev``, ``prod`` and ``test``. An environment represents a way to
1010
execute the same codebase with different configurations.
1111

1212
In order to select the configuration file to load for each environment, Symfony

‎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 the article :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
Environment Variables
1413
---------------------

‎configuration/front_controllers_and_kernel.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ The front controller can be chosen by requesting URLs like:
5555
http://localhost/app_dev.php/some/path/...
5656
5757
As you can see, this URL contains the PHP script to be used as the front
58-
controller. You can use that to easily switch the front controller or use
58+
controller. You can use that to switch the front controller or use
5959
a custom one by placing it in the ``web/`` directory (e.g. ``app_cache.php``).
6060

6161
When using Apache and the `RewriteRule shipped with the Symfony Standard Edition`_,
@@ -153,7 +153,7 @@ front controller to the ``AppKernel``'s constructor. This name can then be
153153
used in the :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`
154154
method to decide which configuration files to load.
155155

156-
The Symfony Standard Edition's `AppKernel`_ class implements this method by simply
156+
The Symfony Standard Edition's `AppKernel`_ class implements this method by
157157
loading the ``app/config/config_*environment*.yml`` file. You are, of course,
158158
free to implement this method differently if you need a more sophisticated
159159
way of loading your configuration.

‎configuration/micro_kernel_trait.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -350,4 +350,4 @@ Then see webpage in browser:
350350

351351
Hey, that looks a lot like a *traditional* Symfony application! You're right: the
352352
``MicroKernelTrait`` *is* still Symfony: but you can control your structure and
353-
features quite easily.
353+
features in a lightweight way.

‎configuration/override_dir_structure.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ How to Override Symfony's default Directory Structure
55
=====================================================
66

77
Symfony automatically ships with a default directory structure. You can
8-
easily override this directory structure to create your own. The default
8+
override this directory structure to create your own. The default
99
directory structure is:
1010

1111
.. code-block:: text
@@ -140,9 +140,9 @@ Override the ``web`` Directory
140140

141141
If you need to rename or move your ``web`` directory, the only thing you
142142
need to guarantee is that the path to the ``var`` directory is still correct
143-
in your ``app.php`` and ``app_dev.php`` front controllers. If you simply
144-
renamed the directory, you're fine. But if you moved it in some way, you
145-
may need to modify these paths inside those files::
143+
in your ``app.php`` and ``app_dev.php`` front controllers. If you renamed
144+
the directory, you're fine. But if you moved it in some way, you may need
145+
to modify these paths inside those files::
146146

147147
require_once __DIR__.'/../path/to/app/autoload.php';
148148

‎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: 6 additions & 6 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 is quite hard 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::
@@ -201,7 +201,7 @@ You can also simulate a request::
201201

202202
$request = Request::create('/index.php?name=Fabien');
203203

204-
With the ``Response`` class, you can easily tweak the response::
204+
With the ``Response`` class, you can tweak the response::
205205

206206
$response = new Response();
207207

‎email/cloud.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ option. If setting up and maintaining your own reliable mail server causes
1212
you a headache there's a simple solution: Leverage the cloud to send your
1313
emails.
1414

15-
This article shows how easy it is to integrate
16-
`Amazon's Simple Email Service (SES)`_ into Symfony.
15+
This article shows how to integrate `Amazon's Simple Email Service (SES)`_
16+
into Symfony.
1717

1818
.. note::
1919

@@ -75,7 +75,7 @@ and complete the configuration with the provided ``username`` and ``password``:
7575
]);
7676
7777
The ``port`` and ``encryption`` keys are not present in the Symfony Standard
78-
Edition configuration by default, but you can simply add them as needed.
78+
Edition configuration by default, but you can add them if needed.
7979

8080
And that's it, you're ready to start sending emails through the cloud!
8181

‎email/gmail.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ How to Use Gmail to Send Emails
55
===============================
66

77
During development, instead of using a regular SMTP server to send emails, you
8-
might find using Gmail easier and more practical. The SwiftmailerBundle makes
9-
it really easy.
8+
might find using Gmail easier and more practical. You can achieve this with the
9+
SwiftmailerBundle without much effort.
1010

1111
In the development configuration file, change the ``transport`` setting to
1212
``gmail`` and set the ``username`` and ``password`` to the Google credentials:
@@ -105,7 +105,7 @@ In the development configuration file, change the ``transport`` setting to
105105
Redefining the Default Configuration Parameters
106106
-----------------------------------------------
107107

108-
The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
108+
The ``gmail`` transport is a shortcut that uses the ``smtp`` transport
109109
and sets these options:
110110

111111
============== ==================

‎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 an easy controller action that sends an email::
13+
Start with an controller action that sends an email::
1414

1515
public function sendEmailAction($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
@@ -249,8 +249,8 @@ link for details), create a ``shipping_widget`` block to handle this:
249249
Using the Field Type
250250
--------------------
251251

252-
You can now use your custom field type immediately, simply by creating a
253-
new instance of the type in one of your forms::
252+
You can now use your custom field type by creating a new instance
253+
of the type in one of your forms::
254254

255255
// src/AppBundle/Form/Type/OrderType.php
256256
namespace AppBundle\Form\Type;

‎form/data_transformers.rst

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,7 @@ Harder Example: Transforming an Issue Number into an Issue Entity
121121
Say you have a many-to-one relation from the Task entity to an Issue entity (i.e. each
122122
Task has an optional foreign key to its related Issue). Adding a listbox with all
123123
possible issues could eventually get *really* long and take a long time to load.
124-
Instead, you decide you want to add a textbox, where the user can simply enter the
125-
issue number.
124+
Instead, you decide you want to add a textbox, where the user can enter the issue number.
126125

127126
Start by setting up the text field like normal::
128127

@@ -300,9 +299,9 @@ know to pass your ``TaskType`` an instance of the ``IssueToNumberTransformer``.
300299
For more information about defining form types as services, read
301300
:doc:`register your form type as a service </form/form_dependencies>`.
302301

303-
Now, you can easily use your ``TaskType``::
302+
Now, you can use your ``TaskType``::
304303

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

308307
// ...

‎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, it is really easy to handle form
8-
submissions::
7+
Handle the form submission via the ``handleRequest()``::
98

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

‎form/dynamic_form_modification.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -232,8 +232,7 @@ Using an event listener, your form might look like this::
232232
The problem is now to get the current user and create a choice field that
233233
contains only this user's friends.
234234

235-
Luckily it is pretty easy to inject a service inside of the form. This can be
236-
done in the constructor::
235+
The service can be injected into the form via its constructor::
237236

238237
use Symfony\Component\Security\Core\Security;
239238
// ...

‎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/events.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Using form events, you may modify information or fields at different steps
1111
of the workflow: from the population of the form to the submission of the
1212
data from the request.
1313

14-
Registering an event listener is very easy using the Form component.
14+
Registering an event listener is straightforward using the Form component.
1515

1616
For example, if you wish to register a function to the
1717
``FormEvents::PRE_SUBMIT`` event, the following code lets you add a field,
@@ -262,7 +262,7 @@ Event Listeners
262262

263263
An event listener may be any type of valid callable.
264264

265-
Creating and binding an event listener to the form is very easy::
265+
Creating and binding an event listener to the form::
266266

267267
// ...
268268

‎form/form_collections.rst

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

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

518517
// src/AppBundle/Entity/Task.php
519518

‎form/form_customization.rst

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,8 @@ templating engine.
1212
Form Rendering Basics
1313
---------------------
1414

15-
Recall that the label, error and HTML widget of a form field can easily
16-
be rendered by using the ``form_row()`` Twig function or the ``row`` PHP helper
17-
method:
15+
Recall that the label, error and HTML widget of a form field can be rendered
16+
by using the ``form_row()`` Twig function or the ``row`` PHP helper method:
1817

1918
.. code-block:: twig
2019
@@ -206,13 +205,13 @@ Form Theming in Twig
206205
When customizing the form field block in Twig, you have two options on *where*
207206
the customized form block can live:
208207

209-
+--------------------------------------+-----------------------------------+-------------------------------------------+
210-
| Method | Pros | Cons |
211-
+======================================+===================================+===========================================+
212-
| Inside the same template as the form | Quick and easy | Can't be reused in other templates |
213-
+--------------------------------------+-----------------------------------+-------------------------------------------+
214-
| Inside a separate template | Can be reused by many templates | Requires an extra template to be created |
215-
+--------------------------------------+-----------------------------------+-------------------------------------------+
208+
+--------------------------------------+------------------------------------+------------------------------------------+
209+
| Method | Pros | Cons |
210+
+======================================+====================================+==========================================+
211+
| Inside the same template as the form | No need for an extra template file | Can't be reused in other templates |
212+
+--------------------------------------+------------------------------------+------------------------------------------+
213+
| Inside a separate template | Can be reused by many templates | Requires an extra template to be created |
214+
+--------------------------------------+------------------------------------+------------------------------------------+
216215

217216
Both methods have the same effect but are better in different situations.
218217

0 commit comments

Comments
 (0)
0