Skip to content

Commit 2253d5e

Browse files
javiereguiluzjaviereguiluz
committed
Merge remote-tracking branch 'upstream/master'
2 parents b4c6abc + 81e8c13 commit 2253d5e

File tree

115 files changed

+1072
-650
lines changed

Some content is hidden

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

115 files changed

+1072
-650
lines changed

‎best_practices/business-logic.rst

+8-5
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ your app that's not specific to the framework (e.g. routing and controllers).
1010
Domain classes, Doctrine entities and regular PHP classes that are used as
1111
services are good examples of business logic.
1212

13-
For most projects, you should store everything inside the ``AppBundle``.
13+
For most projects, you should store everything inside the AppBundle.
1414
Inside here, you can create whatever directories you want to organize things:
1515

1616
.. code-block:: text
@@ -45,7 +45,7 @@ and put things there:
4545
4646
.. tip::
4747

48-
The recommended approach of using the ``AppBundle`` directory is for
48+
The recommended approach of using the ``AppBundle/`` directory is for
4949
simplicity. If you're advanced enough to know what needs to live in
5050
a bundle and what can live outside of one, then feel free to do that.
5151

@@ -140,9 +140,12 @@ the class namespace as a parameter:
140140
# app/config/services.yml
141141
142142
# service definition with class namespace as parameter
143+
parameters:
144+
slugger.class: AppBundle\Utils\Slugger
145+
143146
services:
144147
app.slugger:
145-
class: AppBundle\Utils\Slugger
148+
class: "%slugger.class%"
146149
147150
This practice is cumbersome and completely unnecessary for your own services:
148151

@@ -166,8 +169,8 @@ library or strategy you want for this.
166169

167170
In practice, many Symfony applications rely on the independent
168171
`Doctrine project`_ to define their model using entities and repositories.
169-
Just like with business logic, we recommend storing Doctrine entities in
170-
the ``AppBundle``
172+
Just like with business logic, we recommend storing Doctrine entities in the
173+
AppBundle.
171174

172175
The three entities defined by our sample blog application are a good example:
173176

‎best_practices/configuration.rst

+2
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ and security credentials) and different environments (development, production).
66
That's why Symfony recommends that you split the application configuration into
77
three parts.
88

9+
.. _config-parameters.yml:
10+
911
Infrastructure-Related Configuration
1012
------------------------------------
1113

‎best_practices/controllers.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ into a service.
1313

1414
.. best-practice::
1515

16-
Make your controller extend the ``FrameworkBundle`` base Controller and
17-
use annotations to configure routing, caching and security whenever possible.
16+
Make your controller extend the FrameworkBundle base controller and use
17+
annotations to configure routing, caching and security whenever possible.
1818

1919
Coupling the controllers to the underlying framework allows you to leverage
2020
all of its features and increases your productivity.

‎best_practices/creating-the-project.rst

+11-11
Original file line numberDiff line numberDiff line change
@@ -109,26 +109,26 @@ Application Bundles
109109

110110
When Symfony 2.0 was released, most developers naturally adopted the symfony
111111
1.x way of dividing applications into logical modules. That's why many Symfony
112-
apps use bundles to divide their code into logical features: ``UserBundle``,
113-
``ProductBundle``, ``InvoiceBundle``, etc.
112+
apps use bundles to divide their code into logical features: UserBundle,
113+
ProductBundle, InvoiceBundle, etc.
114114

115115
But a bundle is *meant* to be something that can be reused as a stand-alone
116-
piece of software. If ``UserBundle`` cannot be used *"as is"* in other Symfony
117-
apps, then it shouldn't be its own bundle. Moreover ``InvoiceBundle`` depends
118-
on ``ProductBundle``, then there's no advantage to having two separate bundles.
116+
piece of software. If UserBundle cannot be used *"as is"* in other Symfony
117+
apps, then it shouldn't be its own bundle. Moreover InvoiceBundle depends on
118+
ProductBundle, then there's no advantage to having two separate bundles.
119119

120120
.. best-practice::
121121

122-
Create only one bundle called ``AppBundle`` for your application logic
122+
Create only one bundle called AppBundle for your application logic
123123

124-
Implementing a single ``AppBundle`` bundle in your projects will make your code
124+
Implementing a single AppBundle bundle in your projects will make your code
125125
more concise and easier to understand. Starting in Symfony 2.6, the official
126-
Symfony documentation uses the ``AppBundle`` name.
126+
Symfony documentation uses the AppBundle name.
127127

128128
.. note::
129129

130-
There is no need to prefix the ``AppBundle`` with your own vendor (e.g.
131-
``AcmeAppBundle``), because this application bundle is never going to be
130+
There is no need to prefix the AppBundle with your own vendor (e.g.
131+
AcmeAppBundle), because this application bundle is never going to be
132132
shared.
133133

134134
All in all, this is the typical directory structure of a Symfony application
@@ -152,7 +152,7 @@ that follows these best practices:
152152
153153
.. tip::
154154

155-
If your Symfony installation doesn't come with a pre-generated ``AppBundle``,
155+
If your Symfony installation doesn't come with a pre-generated AppBundle,
156156
you can generate it by hand executing this command:
157157

158158
.. code-block:: bash

‎best_practices/forms.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ form in its own PHP class::
2121

2222
use Symfony\Component\Form\AbstractType;
2323
use Symfony\Component\Form\FormBuilderInterface;
24-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
24+
use Symfony\Component\OptionsResolver\OptionsResolver;
2525

2626
class PostType extends AbstractType
2727
{
@@ -36,7 +36,7 @@ form in its own PHP class::
3636
;
3737
}
3838

39-
public function setDefaultOptions(OptionsResolverInterface $resolver)
39+
public function configureOptions(OptionsResolver $resolver)
4040
{
4141
$resolver->setDefaults(array(
4242
'data_class' => 'AppBundle\Entity\Post'

‎best_practices/security.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ Security Voters
245245

246246
If your security logic is complex and can't be centralized into a method
247247
like ``isAuthor()``, you should leverage custom voters. These are an order
248-
of magnitude easier than :doc:`ACL's </cookbook/security/acl>` and will give
248+
of magnitude easier than :doc:`ACLs </cookbook/security/acl>` and will give
249249
you the flexibility you need in almost all cases.
250250

251251
First, create a voter class. The following example shows a voter that implements

‎book/controller.rst

+5-5
Original file line numberDiff line numberDiff line change
@@ -228,9 +228,9 @@ Simple, right?
228228
Route Parameters as Controller Arguments
229229
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
230230

231-
You already know that the route points to the ``HelloController::indexAction()`` method
232-
that lives inside ``AppBundle``. What's more interesting is the argument
233-
that is passed to that method::
231+
You already know that the route points to the
232+
``HelloController::indexAction()`` method that lives inside AppBundle. What's
233+
more interesting is the argument that is passed to that method::
234234

235235
// src/AppBundle/Controller/HelloController.php
236236
// ...
@@ -771,8 +771,8 @@ object that's returned from *that* controller::
771771
Notice that the ``forward()`` method uses a special string representation
772772
of the controller (see :ref:`controller-string-syntax`). In this case, the
773773
target controller function will be ``SomethingController::fancyAction()``
774-
inside the ``AppBundle``. The array passed to the method becomes the arguments
775-
on the resulting controller. This same idea is used when embedding controllers
774+
inside the AppBundle. The array passed to the method becomes the arguments on
775+
the resulting controller. This same idea is used when embedding controllers
776776
into templates (see :ref:`templating-embedding-controller`). The target
777777
controller method would look something like this::
778778

‎book/doctrine.rst

+19-11
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,10 @@ information. By convention, this information is usually configured in an
7777
<container xmlns="http://symfony.com/schema/dic/services"
7878
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
7979
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
80-
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
81-
http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
80+
xsi:schemaLocation="http://symfony.com/schema/dic/services
81+
http://symfony.com/schema/dic/services/services-1.0.xsd
82+
http://symfony.com/schema/dic/doctrine
83+
http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
8284
8385
<doctrine:config>
8486
<doctrine:dbal
@@ -165,8 +167,10 @@ for you:
165167
<container xmlns="http://symfony.com/schema/dic/services"
166168
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
167169
xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
168-
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
169-
http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
170+
xsi:schemaLocation="http://symfony.com/schema/dic/services
171+
http://symfony.com/schema/dic/services/services-1.0.xsd
172+
http://symfony.com/schema/dic/doctrine
173+
http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
170174
171175
<doctrine:config>
172176
<doctrine:dbal
@@ -193,7 +197,7 @@ Creating an Entity Class
193197
Suppose you're building an application where products need to be displayed.
194198
Without even thinking about Doctrine or databases, you already know that
195199
you need a ``Product`` object to represent those products. Create this class
196-
inside the ``Entity`` directory of your ``AppBundle``::
200+
inside the ``Entity`` directory of your AppBundle::
197201

198202
// src/AppBundle/Entity/Product.php
199203
namespace AppBundle\Entity;
@@ -426,6 +430,7 @@ mapping information) of a bundle or an entire namespace:
426430
427431
# generates all entities in the AppBundle
428432
$ php app/console doctrine:generate:entities AppBundle
433+
429434
# generates all entities of bundles in the Acme namespace
430435
$ php app/console doctrine:generate:entities Acme
431436
@@ -864,7 +869,7 @@ You can use this new method just like the default finder methods of the reposito
864869

865870
$em = $this->getDoctrine()->getManager();
866871
$products = $em->getRepository('AppBundle:Product')
867-
->findAllOrderedByName();
872+
->findAllOrderedByName();
868873

869874
.. note::
870875

@@ -884,7 +889,9 @@ you can let Doctrine create the class for you.
884889

885890
.. code-block:: bash
886891
887-
$ php app/console doctrine:generate:entity --entity="AppBundle:Category" --fields="name:string(255)"
892+
$ php app/console doctrine:generate:entity \
893+
--entity="AppBundle:Category" \
894+
--fields="name:string(255)"
888895
889896
This task generates the ``Category`` entity for you, with an ``id`` field,
890897
a ``name`` field and the associated getter and setter functions.
@@ -929,7 +936,8 @@ To relate the ``Category`` and ``Product`` entities, start by creating a
929936
products:
930937
targetEntity: Product
931938
mappedBy: category
932-
# don't forget to init the collection in the __construct() method of the entity
939+
# don't forget to init the collection in the __construct() method
940+
# of the entity
933941
934942
.. code-block:: xml
935943
@@ -1038,7 +1046,7 @@ methods for you:
10381046

10391047
.. code-block:: bash
10401048
1041-
$ php app/console doctrine:generate:entities Acme
1049+
$ php app/console doctrine:generate:entities AppBundle
10421050
10431051
Ignore the Doctrine metadata for a moment. You now have two classes - ``Category``
10441052
and ``Product`` with a natural one-to-many relationship. The ``Category``
@@ -1151,7 +1159,7 @@ the category (i.e. it's "lazily loaded").
11511159

11521160
You can also query in the other direction::
11531161

1154-
public function showProductAction($id)
1162+
public function showProductsAction($id)
11551163
{
11561164
$category = $this->getDoctrine()
11571165
->getRepository('AppBundle:Category')
@@ -1372,7 +1380,7 @@ list of all available types and more information, see Doctrine's
13721380
Summary
13731381
-------
13741382

1375-
With Doctrine, you can focus on your objects and how they're useful in your
1383+
With Doctrine, you can focus on your objects and how they're used in your
13761384
application and worry about database persistence second. This is because
13771385
Doctrine allows you to use any PHP object to hold your data and relies on
13781386
mapping metadata information to map an object's data to a particular database

‎book/forms.rst

+22-18
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,7 @@ That's it! Just three lines are needed to render the complete form:
175175
Renders all the fields, which includes the field element itself, a label
176176
and any validation error messages for the field.
177177

178-
``form_end()``
178+
``form_end(form)``
179179
Renders the end tag of the form and any fields that have not
180180
yet been rendered, in case you rendered each field yourself. This is useful
181181
for rendering hidden fields and taking advantage of the automatic
@@ -470,13 +470,17 @@ you'll need to specify which validation group(s) your form should use::
470470
'validation_groups' => array('registration'),
471471
))->add(...);
472472

473+
.. versionadded:: 2.7
474+
The ``configureOptions()`` method was introduced in Symfony 2.7. Previously,
475+
the method was called ``setDefaultOptions()``.
476+
473477
If you're creating :ref:`form classes <book-form-creating-form-classes>` (a
474-
good practice), then you'll need to add the following to the ``setDefaultOptions()``
478+
good practice), then you'll need to add the following to the ``configureOptions()``
475479
method::
476480

477-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
481+
use Symfony\Component\OptionsResolver\OptionsResolver;
478482

479-
public function setDefaultOptions(OptionsResolverInterface $resolver)
483+
public function configureOptions(OptionsResolver $resolver)
480484
{
481485
$resolver->setDefaults(array(
482486
'validation_groups' => array('registration'),
@@ -498,9 +502,9 @@ Disabling Validation
498502
Sometimes it is useful to suppress the validation of a form altogether. For
499503
these cases you can set the ``validation_groups`` option to ``false``::
500504

501-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
505+
use Symfony\Component\OptionsResolver\OptionsResolver;
502506

503-
public function setDefaultOptions(OptionsResolverInterface $resolver)
507+
public function configureOptions(OptionsResolver $resolver)
504508
{
505509
$resolver->setDefaults(array(
506510
'validation_groups' => false,
@@ -524,10 +528,10 @@ If you need some advanced logic to determine the validation groups (e.g.
524528
based on submitted data), you can set the ``validation_groups`` option
525529
to an array callback::
526530

527-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
531+
use Symfony\Component\OptionsResolver\OptionsResolver;
528532

529533
// ...
530-
public function setDefaultOptions(OptionsResolverInterface $resolver)
534+
public function configureOptions(OptionsResolver $resolver)
531535
{
532536
$resolver->setDefaults(array(
533537
'validation_groups' => array(
@@ -544,10 +548,10 @@ You can also define whole logic inline by using a ``Closure``::
544548

545549
use Acme\AcmeBundle\Entity\Client;
546550
use Symfony\Component\Form\FormInterface;
547-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
551+
use Symfony\Component\OptionsResolver\OptionsResolver;
548552

549553
// ...
550-
public function setDefaultOptions(OptionsResolverInterface $resolver)
554+
public function configureOptions(OptionsResolver $resolver)
551555
{
552556
$resolver->setDefaults(array(
553557
'validation_groups' => function(FormInterface $form) {
@@ -567,10 +571,10 @@ of the entity as well you have to adjust the option as follows::
567571

568572
use Acme\AcmeBundle\Entity\Client;
569573
use Symfony\Component\Form\FormInterface;
570-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
574+
use Symfony\Component\OptionsResolver\OptionsResolver;
571575

572576
// ...
573-
public function setDefaultOptions(OptionsResolverInterface $resolver)
577+
public function configureOptions(OptionsResolver $resolver)
574578
{
575579
$resolver->setDefaults(array(
576580
'validation_groups' => function(FormInterface $form) {
@@ -1090,9 +1094,9 @@ the choice is ultimately up to you.
10901094
good idea to explicitly specify the ``data_class`` option by adding the
10911095
following to your form type class::
10921096

1093-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
1097+
use Symfony\Component\OptionsResolver\OptionsResolver;
10941098

1095-
public function setDefaultOptions(OptionsResolverInterface $resolver)
1099+
public function configureOptions(OptionsResolver $resolver)
10961100
{
10971101
$resolver->setDefaults(array(
10981102
'data_class' => 'AppBundle\Entity\Task',
@@ -1321,7 +1325,7 @@ create a form class so that a ``Category`` object can be modified by the user::
13211325

13221326
use Symfony\Component\Form\AbstractType;
13231327
use Symfony\Component\Form\FormBuilderInterface;
1324-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
1328+
use Symfony\Component\OptionsResolver\OptionsResolver;
13251329

13261330
class CategoryType extends AbstractType
13271331
{
@@ -1330,7 +1334,7 @@ create a form class so that a ``Category`` object can be modified by the user::
13301334
$builder->add('name');
13311335
}
13321336

1333-
public function setDefaultOptions(OptionsResolverInterface $resolver)
1337+
public function configureOptions(OptionsResolver $resolver)
13341338
{
13351339
$resolver->setDefaults(array(
13361340
'data_class' => 'AppBundle\Entity\Category',
@@ -1756,13 +1760,13 @@ that all un-rendered fields are output.
17561760

17571761
The CSRF token can be customized on a form-by-form basis. For example::
17581762

1759-
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
1763+
use Symfony\Component\OptionsResolver\OptionsResolver;
17601764

17611765
class TaskType extends AbstractType
17621766
{
17631767
// ...
17641768

1765-
public function setDefaultOptions(OptionsResolverInterface $resolver)
1769+
public function configureOptions(OptionsResolver $resolver)
17661770
{
17671771
$resolver->setDefaults(array(
17681772
'data_class' => 'AppBundle\Entity\Task',

‎book/from_flat_php_to_symfony2.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -244,7 +244,7 @@ the layout:
244244

245245
<?php include 'layout.php' ?>
246246

247-
You now have a setup that will allow you to reuse the layout.
247+
You now have a setup that will allow you to reuse the layout.
248248
Unfortunately, to accomplish this, you're forced to use a few ugly
249249
PHP functions (``ob_start()``, ``ob_get_clean()``) in the template. Symfony
250250
uses a Templating component that allows this to be accomplished cleanly

0 commit comments

Comments
 (0)