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

Commit 2b0ab71

Browse files
weaverryanweaverryan
committed
Merge branch '2.0'
2 parents d04b06d + 2b900cc commit 2b0ab71

23 files changed

+504
-56
lines changed

‎book/forms.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1502,7 +1502,7 @@ but here's a short example::
15021502
// ...
15031503
;
15041504

1505-
Now, when you call `$form->isValid()`, the constraints setup here are run
1505+
Now, when you call `$form->bindRequest($request)`, the constraints setup here are run
15061506
against your form's data. If you're using a form class, override the ``getDefaultOptions``
15071507
method to specify the option::
15081508

‎book/http_fundamentals.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
6D40
@@ -492,7 +492,7 @@ regardless of how your project is developed. To name a few:
492492
should be handled (e.g. execute the ``contactAction()`` method);
493493

494494
* `Form`_ - A full-featured and flexible framework for creating forms and
495-
handing form submissions;
495+
handling form submissions;
496496

497497
* `Validator`_ A system for creating rules about data and then validating
498498
whether or not user-submitted data follows those rules;

‎components/class_loader.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,5 +122,5 @@ or one of its children, the autoloader will first look for the class under the
122122
``Doctrine`` directory (the last one configured) if not found, before giving up.
123123
The order of the registrations is significant in this case.
124124

125-
.. _standards: http://groups.google.com/group/php-standards/web/psr-0-final-proposal
125+
.. _standards: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
126126
.. _PEAR: http://pear.php.net/manual/en/standards.php

‎components/console.rst

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ The Console Component
77
The Console component eases the creation of beautiful and testable command
88
line interfaces.
99

10-
Symfony2 ships with a Console component, which allows you to create
11-
command-line commands. Your console commands can be used for any recurring
12-
task, such as cronjobs, imports, or other batch jobs.
10+
The Console component allows you to create command-line commands. Your console
11+
commands can be used for any recurring task, such as cronjobs, imports, or
12+
other batch jobs.
1313

1414
Installation
1515
------------
@@ -23,23 +23,16 @@ You can install the component in many different ways:
2323
Creating a basic Command
2424
------------------------
2525

26-
To make the console commands available automatically with Symfony2, create a
27-
``Command`` directory inside your bundle and create a php file suffixed with
28-
``Command.php`` for each command that you want to provide. For example, if you
29-
want to extend the ``AcmeDemoBundle`` (available in the Symfony Standard
30-
Edition) to greet us from the command line, create ``GreetCommand.php`` and
31-
add the following to it::
26+
To make a console command to greet us from the command line, create ``GreetCommand.php``
27+
and add the following to it::
3228

33-
// src/Acme/DemoBundle/Command/GreetCommand.php
34-
namespace Acme\DemoBundle\Command;
35-
36-
use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
29+
use Symfony\Component\Console\Command\Command;
3730
use Symfony\Component\Console\Input\InputArgument;
3831
use Symfony\Component\Console\Input\InputInterface;
3932
use Symfony\Component\Console\Input\InputOption;
4033
use Symfony\Component\Console\Output\OutputInterface;
4134

42-
class GreetCommand extends ContainerAwareCommand
35+
class GreetCommand extends Command
4336
{
4437
protected function configure()
4538
{
@@ -255,9 +248,8 @@ useful one is the :class:`Symfony\\Component\\Console\\Tester\\CommandTester`
255248
class. It uses special input and output classes to ease testing without a real
256249
console::
257250

251+
use Symfony\Component\Console\Application;
258252
use Symfony\Component\Console\Tester\CommandTester;
259-
use Symfony\Bundle\FrameworkBundle\Console\Application;
260-
use Acme\DemoBundle\Command\GreetCommand;
261253

262254
class ListCommandTest extends \PHPUnit_Framework_TestCase
263255
{
@@ -285,7 +277,7 @@ as an array to the :method:`Symfony\\Component\\Console\\Tester\\CommandTester::
285277
method::
286278

287279
use Symfony\Component\Console\Tester\CommandTester;
288-
use Symfony\Bundle\FrameworkBundle\Console\Application;
280+
use Symfony\Component\Console\Application;
289281
use Acme\DemoBundle\Command\GreetCommand;
290282

291283
class ListCommandTest extends \PHPUnit_Framework_TestCase

‎components/dependency_injection.rst

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
.. index::
2+
single: Dependency Injection
3+
4+
The Dependency Injection Component
5+
==================================
6+
7+
The Dependency Injection component allows you to standardize and centralize
8+
the way objects are constructed in your application.
9+
10+
For an introduction to Dependency Injection and service containers see
11+
:doc:`/book/service_container`
12+
13+
Installation
14+
------------
15+
16+
You can install the component in many different ways:
17+
18+
* Use the official Git repository (https://github.com/symfony/DependencyInjection);
19+
* Install it via PEAR ( `pear.symfony.com/DependencyInjection`);
20+
* Install it via Composer (`symfony/dependency-injection` on Packagist).
21+
22+
Basic Usage
23+
-----------
24+
25+
You might have a simple class like the following ``Mailer`` that
26+
you want to make available as a service:
27+
28+
.. code-block:: php
29+
30+
class Mailer
31+
{
32+
private $transport;
33+
34+
public function __construct()
35+
{
36+
$this->transport = 'sendmail';
37+
}
38+
39+
// ...
40+
}
41+
42+
You can register this in the container as a service:
43+
44+
.. code-block:: php
45+
46+
use Symfony\Component\DependencyInjection\ContainerBuilder;
47+
48+
$sc = new ContainerBuilder();
49+
$sc->register('mailer', 'Mailer');
50+
51+
An improvement to the class to make it more flexible would be to allow
52+
the container to set the ``transport`` used. If you change the class
53+
so this is passed into the constructor:
54+
55+
.. code-block:: php
56+
57+
class Mailer
58+
{
59+
private $transport;
60+
61+
public function __construct($transport)
62+
{
63+
$this->transport = $transport;
64+
}
65+
66+
// ...
67+
}
68+
69+
Then you can set the choice of transport in the container:
70+
71+
.. code-block:: php
72+
73+
use Symfony\Component\DependencyInjection\ContainerBuilder;
74+
75+
$sc = new ContainerBuilder();
76+
$sc->register('mailer', 'Mailer')
77+
->addArgument('sendmail'));
78+
79+
This class is now much more flexible as we have separated the choice of
80+
transport out of the implementation and into the container.
81+
82+
Which mail transport you have chosen may be something other services need to
83+
know about. You can avoid having to change it in multiple places by making
84+
it a parameter in the container and then referring to this parameter for the
85+
``Mailer`` service's constructor argument:
86+
87+
88+
.. code-block:: php
89+
90+
use Symfony\Component\DependencyInjection\ContainerBuilder;
91+
92+
$sc = new ContainerBuilder();
93+
$sc->setParameter('mailer.transport', 'sendmail');
94+
$sc->register('mailer', 'Mailer')
95+
->addArgument('%mailer.transport%'));
96+
97+
Now that the ``mailer`` service is in the container you can inject it as
98+
a dependency of other classes. If you have a ``NewsletterManager`` class
99+
like this:
100+
101+
.. code-block:: php
102+
103+
use Mailer;
104+
105+
class NewsletterManager
106+
{
107+
private $mailer;
108+
109+
public function __construct(Mailer $mailer)
110+
{
111+
$this->mailer = $mailer;
112+
}
113+
114+
// ...
115+
}
116+
117+
Then you can register this as a service as well and pass the ``mailer`` service into it:
118+
119+
.. code-block:: php
120+
121+
use Symfony\Component\DependencyInjection\ContainerBuilder;
122+
use Symfony\Component\DependencyInjection\Reference;
123+
124+
$sc = new ContainerBuilder();
125+
126+
$sc->setParameter('mailer.transport', 'sendmail');
127+
$sc->register('mailer', 'Mailer')
128+
->addArgument('%mailer.transport%'));
129+
130+
$sc->register('newsletter_manager', 'NewsletterManager')
131+
->addArgument(new Reference('mailer'));
132+
133+
If the ``NewsletterManager`` did not require the ``Mailer`` and injecting
134+
it was only optional then you could use setter injection instead:
135+
136+
.. code-block:: php
137+
138+
use Mailer;
139+
140+
class NewsletterManager
141+
{
142+
private $mailer;
143+
144+
public function setMailer(Mailer $mailer)
145+
{
146+
$this->mailer = $mailer;
147+
}
148+
149+
// ...
150+
}
151+
152+
You can now choose not to inject a ``Mailer`` into the ``NewsletterManager``.
153+
If you do want to though then the container can call the setter method:
154+
155+
.. code-block:: php
156+
157+
use Symfony\Component\DependencyInjection\ContainerBuilder;
158+
use Symfony\Component\DependencyInjection\Reference;
159+
160+
$sc = new ContainerBuilder();
161+
162+
$sc->setParameter('mailer.transport', 'sendmail');
163+
$sc->register('mailer', 'Mailer')
164+
->addArgument('%mailer.transport%'));
165+
166+
$sc->register('newsletter_manager', 'NewsletterManager')
167+
->addMethodCall('setMailer', new Reference('mailer'));
168+
169+
You could then get your ``newsletter_manager`` service from the container
170+
like this:
171+
172+
.. code-block:: php
173+
174+
use Symfony\Component\DependencyInjection\ContainerBuilder;
175+
use Symfony\Component\DependencyInjection\Reference;
176+
177+
$sc = new ContainerBuilder();
178+
179+
//--
180+
181+
$newsletterManager = $sc->get('newsletter_manager');
182+
183+
Avoiding Your Code Becoming Dependent on the Container
184+
------------------------------------------------------
185+
186+
Whilst you can retrieve services from the container directly it is best
187+
to minimize this. For example, in the ``NewsletterManager`` we injected
188+
the ``mailer`` service in rather than asking for it from the container.
189+
We could have injected the container in and retrieved the ``mailer`` service
190+
from it but it would then be tied to this particular container making it
191+
difficult to reuse the class elsewhere.
192+
193+
You will need to get a service from the container at some point but this
194+
should be as few times as possible at the entry point to your application.
195+
196+
Setting Up the Container with Configuration Files
197+
-------------------------------------------------
198+
199+
As well as setting up the services using PHP as above you can also use configuration
200+
files. To do this you also need to install the Config component:
201+
202+
* Use the official Git repository (https://github.com/symfony/Config);
203+
* Install it via PEAR ( `pear.symfony.com/Config`);
204+
* Install it via Composer (`symfony/config` on Packagist).
205+
206+
Loading an xml config file:
207+
208+
.. code-block:: php
209+
210+
use Symfony\Component\DependencyInjection\ContainerBuilder;
211+
use Symfony\Component\Config\FileLocator;
212+
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
213+
214+
$sc = new ContainerBuilder();
215+
$loader = new XmlFileLoader($container, new FileLocator(__DIR__));
216+
$loader->load('services.xml');
217+
218+
Loading a yaml config file:
219+
220+
.. code-block:: php
221+
222+
use Symfony\Component\DependencyInjection\ContainerBuilder;
223+
use Symfony\Component\Config\FileLocator;
224+
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
225+
226+
$sc = new ContainerBuilder();
227+
$loader = new YamlFileLoader($container, new FileLocator(__DIR__));
228+
$loader->load('services.yml');
229+
230+
The ``newsletter_manager`` and `` mailer`` services can be set up using config files:
231+
232+
.. configuration-block::
233+
234+
.. code-block:: yaml
235+
236+
# src/Acme/HelloBundle/Resources/config/services.yml
237+
parameters:
238+
# ...
239+
mailer.transport: sendmail
240+
241+
services:
242+
my_mailer:
243+
class: Mailer
244+
arguments: [@mailer]
245+
newsletter_manager:
246+
class: NewsletterManager
247+
calls:
248+
- [ setMailer, [ @mailer ] ]
249+
250+
.. code-block:: xml
251+
252+
<!-- src/Acme/HelloBundle/Resources/config/services.xml -->
253+
<parameters>
254+
<!-- ... -->
255+
<parameter key="mailer.transport">sendmail</parameter>
256+
</parameters>
257+
258+
<services>
259+
<service id="mailer" class="Mailer">
260+
<argument>%mailer.transport%</argument>
261+
</service>
262+
263+
<service id="newsletter_manager" class="NewsletterManager">
264+
<call method="setMailer">
265+
<argument type="service" id="mailer" />
266+
</call>
267+
</service>
268+
</services>
269+
270+
.. code-block:: php
271+
272+
use Symfony\Component\DependencyInjection\Reference;
273+
274+
// ...
275+
$sc->setParameter('mailer.transport', 'sendmail');
276+
$sc->register('mailer', 'Mailer')
277+
->addArgument('%mailer.transport%'));
278+
279+
$sc->register('newsletter_manager', 'NewsletterManager')
280+
->addMethodCall('setMailer', new Reference('mailer'));
281+
282+
283+
Learn more from the Cookbook
284+
----------------------------
285+
286+
* :doc:`/cookbook/service_container/factories`
287+
* :doc:`/cookbook/service_container/parentservices`

‎components/dom_crawler.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ form that the button lives in::
220220
));
221221

222222
The :class:`Symfony\\Component\\DomCrawler\\Form` object has lots of very
223-
useful methods for working with forms:
223+
useful methods for working with forms::
224224

225225
$uri = $form->getUri();
226226

‎components/http_foundation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -369,7 +369,7 @@ non-ASCII filenames is more involving. The
369369
:method:`:Symfony\\Component\\HttpFoundation\\Response:makeDisposition`
370370
abstracts the hard work behind a simple API::
371371

372-
use Symfony\\Component\\HttpFoundation\\ResponseHeaderBag;
372+
use Symfony\Component\HttpFoundation\ResponseHeaderBag;
373373

374374
$d = $response->headers->makeDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'foo.pdf');
375375

‎components/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ The Components
88
console
99
css_selector
1010
dom_crawler
11+
dependency_injection
1112
finder
1213
http_foundation
1314
locale

0 commit comments

Comments
 (0)
0