Skip to content

Commit c5ebfd0

Browse files
weaverryanweaverryan
committed
Merge branch '2.0' into 2.1
Conflicts: book/installation.rst
2 parents 8e45839 + d4f59d4 commit c5ebfd0

27 files changed

+425
-54
lines changed

‎book/forms.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1593,7 +1593,7 @@ Learn more from the Cookbook
15931593
* :doc:`File Field Reference </reference/forms/types/file>`
15941594
* :doc:`Creating Custom Field Types </cookbook/form/create_custom_field_type>`
15951595
* :doc:`/cookbook/form/form_customization`
1596-
* :doc:`/cookbook/form/dynamic_form_generation`
1596+
* :doc:`/cookbook/form/dynamic_form_modification`
15971597
* :doc:`/cookbook/form/data_transformers`
15981598

15991599
.. _`Symfony2 Form Component`: https://github.com/symfony/Form

‎book/http_fundamentals.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -449,7 +449,7 @@ by adding an entry for ``/contact`` to your routing configuration file:
449449
450450
.. note::
451451

452-
This example uses :doc:`YAML</components/yaml>` to define the routing
452+
This example uses :doc:`YAML</components/yaml/introduction>` to define the routing
453453
configuration. Routing configuration can also be written in other formats
454454
such as XML or PHP.
455455

‎book/installation.rst

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,9 @@ Installing a Symfony2 Distribution
1919

2020
.. tip::
2121

22-
First, check that you have installed and configured a Web server (such as
23-
Apache) with the most recent PHP version possible (PHP 5.3.8 or newer is
24-
recommended). For more information on Symfony2 requirements, see the
25-
:doc:`requirements reference</reference/requirements>`. For information on
26-
configuring your specific web server document root, see the following
27-
documentation: `Apache`_ | `Nginx`_ .
22+
First, check that you have installed and configured a Web server (such
23+
as Apache) with PHP 5.3.8 or higher. For more information on Symfony2
24+
requirements, see the :doc:`requirements reference</reference/requirements>`.
2825

2926
Symfony2 packages "distributions", which are fully-functional applications
3027
that include the Symfony2 core libraries, a selection of useful bundles, a
@@ -218,7 +215,7 @@ If there are any issues, correct them now before moving on.
218215

219216
**Note that not all web servers run as the user** ``www-data`` as in the examples
220217
below. Instead, check which user *your* web server is being run as and
221-
use it place of ``www-data``.
218+
use it in place of ``www-data``.
222219

223220
On a UNIX system, this can be done with one of the following commands:
224221

@@ -287,14 +284,23 @@ Symfony2 should welcome and congratulate you for your hard work so far!
287284

288285
.. image:: /images/quick_tour/welcome.png
289286

287+
.. tip::
288+
289+
To get nice and short urls you should point the document root of your
290+
webserver or virtual host to the ``Symfony/web/`` directory. Though
291+
this is not required for development it is recommended at the time your
292+
application goes into production as all system and configuration files
293+
become inaccessible to clients then. For information on configuring
294+
your specific web server document root, see the following
295+
documentation: `Apache`_ | `Nginx`_ .
296+
290297
Beginning Development
291298
---------------------
292299

293300
Now that you have a fully-functional Symfony2 application, you can begin
294301
development! Your distribution may contain some sample code - check the
295302
``README.md`` file included with the distribution (open it as a text file)
296-
to learn about what sample code was included with your distribution and how
297-
you can remove it later.
303+
to learn about what sample code was included with your distribution.
298304

299305
If you're new to Symfony, check out ":doc:`page_creation`", where you'll
300306
learn how to create pages, change configuration, and do everything else you'll
@@ -303,6 +309,11 @@ need in your new application.
303309
Be sure to also check out the :doc:`Cookbook</cookbook/index>`, which contains
304310
a wide variety of articles about solving specific problems with Symfony.
305311

312+
.. note::
313+
314+
If you want to remove the sample code from your distribution, take a look
315+
at this cookbook article: ":doc:`/cookbook/bundles/remove`"
316+
306317
Using Source Control
307318
--------------------
308319

‎book/security.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -699,7 +699,7 @@ the ``ROLE_ADMIN`` role.
699699
.. caution::
700700

701701
Understanding exactly how ``access_control`` works is **very** important
702-
to make sure you application is properly secured. See :ref:`security-book-access-control-explanation`
702+
to make sure your application is properly secured. See :ref:`security-book-access-control-explanation`
703703
below for detailed information.
704704

705705
You can define as many URL patterns as you need - each is a regular expression.

‎components/config/definition.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,6 @@ Or you may define a prototype for each node inside an array node::
136136
->scalarNode('host')->end()
137137
->scalarNode('username')->end()
138138
->scalarNode('password')->end()
139-
->end()
140139
->end()
141140
->end()
142141
->end()

‎components/console/helpers/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ The Console Helpers
1010
dialoghelper
1111
formatterhelper
1212

13-
The Console Components comes with some usefull helpers. These helpers contain
13+
The Console Components comes with some useful helpers. These helpers contain
1414
function to ease some common tasks.
1515

1616
.. include:: map.rst.inc

‎components/dependency_injection/configurators.rst

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
.. index::
2+
single: Dependency Injection; Service configurators
3+
4+
Configuring Services with a Service Configurator
5+
================================================
6+
7+
The Service Configurator is a feature of the Dependency Injection Container that
8+
allows you to use a callable to configure a service after its instantiation.
9+
10+
You can specify a method in another service, a PHP function or a static method
11+
in a class. The service instance is passed to the callable, allowing the
12+
configurator to do whatever it needs to configure the service after its
13+
creation.
14+
15+
A Service Configurator can be used, for example, when you a have a service that
16+
requires complex setup based on configuration settings coming from different
17+
sources/services. Using an external configurator, you can maintain the service
18+
implementation cleanly and keep it decoupled from the other objects that provide
19+
the configuration needed.
20+
21+
Another interesting use case is when you have multiple objects that share a
22+
common configuration or that should be configured in a similar way at runtime.
23+
24+
For example, suppose you have an application where you send different types of
25+
emails to users. Emails are passed through different formatters that could be
26+
enabled or not depending on some dynamic application settings. You start
27+
defining a ``NewsletterManager`` class like this::
28+
29+
class NewsletterManager implements EmailFormatterAwareInterface
30+
{
31+
protected $mailer;
32+
protected $enabledFormatters;
33+
34+
public function setMailer(Mailer $mailer)
35+
{
36+
$this->mailer = $mailer;
37+
}
38+
39+
public function setEnabledFormatters(array $enabledFormatters)
40+
{
41+
$this->enabledFormatters = $enabledFormatters;
42+
}
43+
44+
// ...
45+
}
46+
47+
48+
and also a ``GreetingCardManager`` class::
49+
50+
class GreetingCardManager implements EmailFormatterAwareInterface
51+
{
52+
protected $mailer;
53+
protected $enabledFormatters;
54+
55+
public function setMailer(Mailer $mailer)
56+
{
57+
$this->mailer = $mailer;
58+
}
59+
60+
public function setEnabledFormatters(array $enabledFormatters)
61+
{
62+
$this->enabledFormatters = $enabledFormatters;
63+
}
64+
65+
// ...
66+
}
67+
68+
69+
As mentioned before, the goal is to set the formatters at runtime depending on
70+
application settings. To do this, you also have an ``EmailFormatterManager``
71+
class which is responsible for loading and validating formatters enabled
72+
in the application::
73+
74+
class EmailFormatterManager
75+
{
76+
protected $enabledFormatters;
77+
78+
public function loadFormatters()
79+
{
80+
// code to configure which formatters to use
81+
$enabledFormatters = array();
82+
// ...
83+
84+
$this->enabledFormatters = $enabledFormatters;
85+
}
86+
87+
public function getEnabledFormatters()
88+
{
89+
return $this->enabledFormatters;
90+
}
91+
92+
// ...
93+
}
94+
95+
If your goal is to avoid having to couple ``NewsletterManager`` and
96+
``GreetingCardManager`` with ``EmailFormatterManager``, then you might want to
97+
create a configurator class to configure these instances::
98+
99+
class EmailConfigurator
100+
{
101+
private $formatterManager;
102+
103+
public function __construct(EmailFormatterManager $formatterManager)
104+
{
105+
$this->formatterManager = $formatterManager;
106+
}
107+
108+
public function configure(EmailFormatterAwareInterface $emailManager)
109+
{
110+
$emailManager->setEnabledFormatters(
111+
$this->formatterManager->getEnabledFormatters()
112+
);
113+
}
114+
115+
// ...
116+
}
117+
118+
The ``EmailConfigurator``'s job is to inject the enabled filters into ``NewsletterManager``
119+
and ``GreetingCardManager`` because they are not aware of where the enabled
120+
filters come from. In the other hand, the ``EmailFormatterManager`` holds the
121+
knowledge about the enabled formatters and how to load them, keeping the single
122+
responsibility principle.
123+
124+
Configurator Service Config
125+
---------------------------
126+
127+
The service config for the above classes would look something like this:
128+
129+
.. configuration-block::
130+
131+
.. code-block:: yaml
132+
133+
services:
134+
my_mailer:
135+
# ...
136+
137+
email_formatter_manager:
138+
class: EmailFormatterManager
139+
# ...
140+
141+
email_configurator:
142+
class: EmailConfigurator
143+
arguments: ["@email_formatter_manager"]
144+
# ...
145+
146+
newsletter_manager:
147+
class: NewsletterManager
148+
calls:
149+
- [setMailer, ["@my_mailer"]]
150+
configurator: ["@email_configurator", configure]
151+
152+
greeting_card_manager:
153+
class: GreetingCardManager
154+
calls:
155+
- [setMailer, ["@my_mailer"]]
156+
configurator: ["@email_configurator", configure]
157+
158+
159+
.. code-block:: xml
160+
161+
<services>
162+
<service id="my_mailer" ...>
163+
<!-- ... -->
164+
</service>
165+
<service id="email_formatter_manager" class="EmailFormatterManager">
166+
<!-- ... -->
167+
</service>
168+
<service id="email_configurator" class="EmailConfigurator">
169+
<argument type="service" id="email_formatter_manager" />
170+
<!-- ... -->
171+
</service>
172+
<service id="newsletter_manager" class="NewsletterManager">
173+
<call method="setMailer">
174+
<argument type="service" id="my_mailer" />
175+
</call>
176+
<configurator service="email_configurator" method="configure" />
177+
</service>
178+
<service id="greeting_card_manager" class="GreetingCardManager">
179+
<call method="setMailer">
180+
<argument type="service" id="my_mailer" />
181+
</call>
182+
<configurator service="email_configurator" method="configure" />
183+
</service>
184+
</services>
185+
186+
.. code-block:: php
187+
188+
use Symfony\Component\DependencyInjection\Definition;
189+
use Symfony\Component\DependencyInjection\Reference;
190+
191+
// ...
192+
$container->setDefinition('my_mailer', ...);
193+
$container->setDefinition('email_formatter_manager', new Definition(
194+
'EmailFormatterManager'
195+
));
196+
$container->setDefinition('email_configurator', new Definition(
197+
'EmailConfigurator'
198+
));
199+
$container->setDefinition('newsletter_manager', new Definition(
200+
'NewsletterManager'
201+
))->addMethodCall('setMailer', array(
202+
new Reference('my_mailer'),
203+
))->setConfigurator(array(
204+
new Reference('email_configurator'),
205+
'configure',
206+
)));
207+
$container->setDefinition('greeting_card_manager', new Definition(
208+
'GreetingCardManager'
209+
))->addMethodCall('setMailer', array(
210+
new Reference('my_mailer'),
211+
))->setConfigurator(array(
212+
new Reference('email_configurator'),
213+
'configure',
214+
)));

‎components/dependency_injection/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
compilation
1111
tags
1212
factories
13+
configurators
1314
parentservices
1415
advanced
1516
workflow

‎components/dependency_injection/introduction.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ Loading a YAML config file::
205205
.. note::
206206

207207
If you want to load YAML config files then you will also need to install
208-
:doc:`The YAML component</components/yaml>`.
208+
:doc:`The YAML component</components/yaml/introduction>`.
209209

210210
The ``newsletter_manager`` and ``mailer`` services can be set up using config files:
211211

‎components/finder.rst

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,14 +48,27 @@ the Finder instance.
4848

4949
.. tip::
5050

51-
A Finder instance is a PHP `Iterator`_. So, instead of iterating over the
51+
A Finder instance is a PHP :phpclass:`Iterator`. So, instead of iterating over the
5252
Finder with ``foreach``, you can also convert it to an array with the
5353
:phpfunction:`iterator_to_array` method, or get the number of items with
5454
:phpfunction:`iterator_count`.
5555

56+
.. caution::
57+
58+
When searching through multiple locations passed to the
59+
:method:`Symfony\\Component\\Finder\\Finder::in` method, a separate iterator
60+
is created internally for every location. This means we have multiple result
61+
sets aggregated into one.
62+
Since :phpfunction:`iterator_to_array` uses keys of result sets by default,
63+
when converting to an array, some keys might be duplicated and their values
64+
overwritten. This can be avoided by passing ``false`` as a second parameter
65+
to :phpfunction:`iterator_to_array`.
66+
5667
Criteria
5768
--------
5869

70+
There are lots of ways to filter and sort your results.
71+
5972
Location
6073
~~~~~~~~
6174

@@ -99,7 +112,7 @@ And it also works with user-defined streams::
99112
Read the `Streams`_ documentation to learn how to create your own streams.
100113

101114
Files or Directories
102-
~~~~~~~~~~~~~~~~~~~~~
115+
~~~~~~~~~~~~~~~~~~~~
103116

104117
By default, the Finder returns files and directories; but the
105118
:method:`Symfony\\Component\\Finder\\Finder::files` and
@@ -261,7 +274,6 @@ The contents of returned files can be read with
261274
}
262275

263276
.. _strtotime: http://www.php.net/manual/en/datetime.formats.php
264-
.. _Iterator: http://www.php.net/manual/en/spl.iterators.php
265277
.. _protocol: http://www.php.net/manual/en/wrappers.php
266278
.. _Streams: http://www.php.net/streams
267279
.. _IEC standard: http://physics.nist.gov/cuu/Units/binary.html

‎components/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,6 @@ The Components
2222
security/index
2323
serializer
2424
templating
25-
yaml
25+
yaml/index
2626

2727
.. include:: /components/map.rst.inc

0 commit comments

Comments
 (0)