8000 [#10824] Applied some of @HeahDudes comments and added missing comments · symfony/symfony-docs@2a5b114 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2a5b114

Browse files
wouterjwouterj
committed
[#10824] Applied some of @HeahDudes comments and added missing comments
1 parent 3ccce23 commit 2a5b114

19 files changed

+356
-218
lines changed

‎components/dependency_injection.rst

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -292,15 +292,19 @@ config files:
292292
293293
return function(ContainerConfigurator $configurator) {
294294
$configurator->parameters()
295-
->set('mailer.transport', 'sendmail');
295+
// ...
296+
->set('mailer.transport', 'sendmail')
297+
;
296298
297-
$container = $configurator->services();
299+
$services = $configurator->services();
298300
299-
$container->set('mailer', 'Mailer')
300-
->args(['%mailer.transport%']);
301+
$services->set('mailer', 'Mailer')
302+
->args(['%mailer.transport%'])
303+
;
301304
302-
$container->set('newsletter_manager', 'NewsletterManager')
303-
->call('setMailer', [ref('mailer')]);
305+
$services->set('newsletter_manager', 'NewsletterManager')
306+
->call('setMailer', [ref('mailer')])
307+
;
304308
};
305309
306310

‎service_container.rst

Lines changed: 66 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -185,13 +185,16 @@ each time you ask for it.
185185
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
186186
187187
return function(ContainerConfigurator $configurator) {
188-
$container = $configurator->services()
188+
// default configuration for services in *this* file
189+
$services = $configurator->services()
189190
->defaults()
190-
->autowire()
191-
->autoconfigure()
192-
->private();
193-
194-
$container->load('App\\', '../src/*')
191+
->autowire() // Automatically injects dependencies in your services.
192+
->autoconfigure() // Automatically registers your services as commands, event subscribers, etc.
193+
;
194+
195+
// makes classes in src/ available to be used as services
196+
// this creates a service per class whose id is the fully-qualified class name
197+
$services->load('App\\', '../src/*')
195198
->exclude('../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}');
196199
};
197200
@@ -416,7 +419,7 @@ pass here. No problem! In your configuration, you can explicitly set this argume
416419
417420
<!-- Same as before -->
418421
419-
<prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}"/>
422+
<prototype namespace="App\" resource="../src/*" exclude="../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}"/>
420423
421424
<!-- Explicitly configure the service -->
422425
<service id="App\Updates\SiteUpdateManager">
@@ -433,16 +436,15 @@ pass here. No problem! In your configuration, you can explicitly set this argume
433436
use App\Updates\SiteUpdateManager;
434437
435438
return function(ContainerConfigurator $configurator) {
436-
$container = $configurator->services()
437-
->defaults()
438-
->autowire()
439-
->autoconfigure()
440-
->private();
439+
// ...
441440
442-
$container->load('App\\', '../src/*')
443-
->exclude('../src/{Entity,Migrations,Tests}');
441+
// same as before
442+
$services->load('App\\', '../src/*')
443+
->exclude('../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}');
444444
445-
$container->set(SiteUpdateManager::class)->arg('$adminEmail', 'manager@example.com');
445+
$services->set(SiteUpdateManager::class)
446+
->arg('$adminEmail', 'manager@example.com')
447+
;
446448
};
447449
448450
@@ -508,10 +510,11 @@ parameter and in PHP config use the ``Reference`` class:
508510
use App\Service\MessageGenerator;
509511
510512
return function(ContainerConfigurator $configurator) {
511-
$container = $configurator->services();
512-
$container->set(MessageGenerator::class)
513-
->autoconfigure()
514-
->args([ref('logger')]]);
513+
$services = $configurator->services();
514+
515+
$services->set(MessageGenerator::class)
516+
->args([ref('logger')])
517+
;
515518
};
516519
517520
Working with container parameters is straightforward using the container's
@@ -613,12 +616,12 @@ But, you can control this and pass in a different logger:
613616
use App\Service\MessageGenerator;
614617
615618
return function(ContainerConfigurator $configurator) {
616-
$container = $configurator->services();
617-
$container->set(SiteUpdateManager::class)
618-
->autowire()
619-
->autoconfigure()
620-
->private();
621-
->arg('$logger', ref('monolog.logger.request'));
619+
// ... same code as before
620+
621+
// explicitly configure the service
622+
$services->set(SiteUpdateManager::class)
623+
->arg('$logger', ref('monolog.logger.request'))
624+
;
622625
};
623626
624627
This tells the container that the ``$logger`` argument to ``__construct`` should use
@@ -708,12 +711,24 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type
708711
use Symfony\Component\DependencyInjection\Reference;
709712
710713
return function(ContainerConfigurator $configurator) {
711-
$container = $configurator->services()->defaults()
712-
->bind('$adminEmail', 'manager@example.com')
713-
->bind('$requestLogger', ref('monolog.logger.request'))
714-
->bind(LoggerInterface::class, ref('monolog.logger.request'))
715-
->bind('string $adminEmail', 'manager@example.com')
716-
->bind(LoggerInterface::class.' $requestLogger', ref('monolog.logger.request'));
714+
$services = $configurator->services()
715+
->defaults()
716+
// pass this value to any $adminEmail argument for any service
717+
// that's defined in this file (including controller arguments)
718+
->bind('$adminEmail', 'manager@example.com')
719+
720+
// pass this service to any $requestLogger argument for any
721+
// service that's defined in this file
722+
->bind('$requestLogger', ref('monolog.logger.request'))
723+
724+
// pass this service for any LoggerInterface type-hint for any
725+
// service that's defined in this file
726+
->bind(LoggerInterface::class, ref('monolog.logger.request'))
727+
728+
// optionally you can define both the name and type of the argument to match
729+
->bind('string $adminEmail', 'manager@example.com')
730+
->bind(LoggerInterface::class.' $requestLogger', ref('monolog.logger.request'))
731+
;
717732
718733
// ...
719734
};
@@ -828,8 +843,10 @@ But, if you *do* need to make a service public, override the ``public`` setting:
828843
return function(ContainerConfigurator $configurator) {
829844
// ... same as code before
830845
831-
$container->set(MessageGenerator::class)
832-
->public();
846+
// explicitly configure the service
847+
$services->set(MessageGenerator::class)
848+
->public()
849+
;
833850
};
834851
835852
.. _service-psr4-loader:
@@ -866,7 +883,7 @@ key. For example, the default Symfony configuration contains this:
866883
<services>
867884
<!-- ... -->
868885
869-
<prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}"/>
886+
<prototype namespace="App\" resource="../src/*" exclude="../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}"/>
870887
</services>
871888
</container>
872889
@@ -878,7 +895,9 @@ key. For example, the default Symfony configuration contains this:
878895
return function(ContainerConfigurator $configurator) {
879896
// ...
880897
881-
$container->load('App\\', '../src/*')
898+
// makes classes in src/ available to be used as services
899+
// this creates a service per class whose id is the fully-qualified class name
900+
$services->load('App\\', '../src/*')
882901
->exclude('../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}');
883902
};
884903
@@ -1025,21 +1044,28 @@ admin email. In this case, each needs to have a unique service id:
10251044
return function(ContainerConfigurator $configurator) {
10261045
// ...
10271046
1028-
$container->set('site_update_manager.superadmin', SiteUpdateManager::class)
1047+
// site_update_manager.superadmin is the service's id
1048+
$services->set('site_update_manager.superadmin', SiteUpdateManager::class)
1049+
// you CAN still use autowiring: we just want to show what it looks like without
10291050
->autowire(false)
1051+
// manually wire all arguments
10301052
->args([
10311053
ref(MessageGenerator::class),
10321054
ref('mailer'),
1033-
'superadmin@example.com'
1055+
'superadmin@example.com',
10341056
]);
1035-
$container->set('site_update_manager.normal_users', SiteUpdateManager::class)
1057+
1058+
$services->set('site_update_manager.normal_users', SiteUpdateManager::class)
10361059
->autowire(false)
10371060
->args([
10381061
ref(MessageGenerator::class),
10391062
ref('mailer'),
1040-
'contact@example.com'
1063+
'contact@example.com',
10411064
]);
1042-
$container->alias(SiteUpdateManager::class, 'site_update_manager.superadmin');
1065+
1066+
// Create an alias, so that - by default - if you type-hint SiteUpdateManager,
1067+
// the site_update_manager.superadmin will be used
1068+
$services->alias(SiteUpdateManager::class, 'site_update_manager.superadmin');
10431069
};
10441070
10451071
In this case, *two* services are registered: ``site_update_manager.superadmin``

‎service_container/3.3-di-changes.rst

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -87,17 +87,25 @@ what the file looks like in Symfony 4):
8787
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
8888
8989
return function(ContainerConfigurator $configurator) {
90-
$container = $configurator->services()
90+
// default configuration for services in *this* file
91+
$services = $configurator->services()
9192
->defaults()
92-
->autowire()
93-
->autoconfigure()
94-
->private();
93+
->autowire() // Automatically injects dependencies in your services.
94+
->autoconfigure() // Automatically registers your services as commands, event subscribers, etc.
95+
;
9596
96-
$container->load('App\\', '../src/*')
97+
// makes classes in src/ available to be used as services
98+
// this creates a service per class whose id is the fully-qualified class name
99+
$services->load('App\\', '../src/*')
97100
->exclude('../src/{Entity,Migrations,Tests}');
98101
99-
$container->load('App\\Controller\\', '../src/Controller')
102+
// controllers are imported separately to make sure services can be injected
103+
// as action arguments even if you don't extend any base controller class
104+
$services->load('App\\Controller\\', '../src/Controller')
100105
->tag('controller.service_arguments');
106+
107+
// add more service definitions when explicit configuration is needed
108+
// please note that last definitions always *replace* previous ones
101109
};
102110
103111
This small bit of configuration contains a paradigm shift of how services
@@ -153,7 +161,9 @@ thanks to the following config:
153161
return function(ContainerConfigurator $configurator) {
154162
// ...
155163
156-
$container->load('App\\', '../src/*')
164+
// makes classes in src/ available to be used as services
165+
// this creates a service per class whose id is the fully-qualified class name
166+
$services->load('App\\', '../src/*')
157167
->exclude('../src/{Entity,Migrations,Tests}');
158168
};
159169
@@ -355,7 +365,9 @@ The third big change is that, in a new Symfony 3.3 project, your controllers are
355365
return function(ContainerConfigurator $configurator) {
356366
// ...
357367
358-
$container->load('App\\Controller\\', '../src/Controller')
368+
// controllers are imported separately to make sure they're public
369+
// and have a tag that allows actions to type-hint services
370+
$services->load('App\\Controller\\', '../src/Controller')
359371
->tag('controller.service_arguments');
360372
};
361373
@@ -509,7 +521,7 @@ inherited from an abstract definition:
509521
return function(ContainerConfigurator $configurator) {
510522
// ...
511523
512-
$container->instanceof(LoaderInterface::class
524+
$services->instanceof(LoaderInterface::class)
513525
->public()
514526
->tag('app.domain_loader');
515527
};

‎service_container/alias_private.rst

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,9 @@ You can also control the ``public`` option on a service-by-service basis:
6060
use App\Service\Foo;
6161
6262
return function(ContainerConfigurator $configurator) {
63-
$container = $configurator->services();
64-
$container->set(Foo::class)
63+
$services = $configurator->services();
64+
65+
$services->set(Foo::class)
6566
->private();
6667
};
6768
@@ -133,10 +134,12 @@ services.
133134
use App\Mail\PhpMailer;
134135
135136
return function(ContainerConfigurator $configurator) {
136-
$container = $configurator->services();
137-
$container->set(PhpMailer::class)
137+
$services = $configurator->services();
138+
139+
$services->set(PhpMailer::class)
138140
->private();
139-
$container->alias('app.mailer', PhpMailer::class);
141+
142+
$services->alias('app.mailer', PhpMailer::class);
140143
};
141144
142145
This means that when using the container directly, you can access the
@@ -221,10 +224,6 @@ one occurrence of the ``%alias_id%`` placeholder in your template.
221224
Anonymous Services
222225
------------------
223226

224-
.. note::
225-
226-
Anonymous services are only supported by the XML, YAML, and PHP Fluent configuration formats.
227-
228227
In some cases, you may want to prevent a service being used as a dependency of
229228
other services. This can be achieved by creating an anonymous service. These
230229
services are like regular services but they don't define an ID and they are
@@ -270,16 +269,18 @@ The following example shows how to inject an anonymous service into another serv
270269
use App\Foo;
271270
272271
return function(ContainerConfigurator $configurator) {
273-
$container = $configurator->services();
272+
$services = $configurator->services();
274273
275-
$container->set(Foo::class)
274+
$services->set(Foo::class)
276275
->args([inline(AnonymousBar::class)])
277276
};
278277
279278
.. note::
280279

281-
Anonymous services do *NOT* inherit the definitions provided from the defaults defined in the configuration. So you'll
282-
need to explicitly mark service as autowired or autoconfigured when doing an anonymous service e.g.: `inline(Foo::class)->autowire()->autoconfigure()`.
280+
Anonymous services do *NOT* inherit the definitions provided from the
281+
defaults defined in the configuration. So you'll need to explicitly mark
282+
service as autowired or autoconfigured when doing an anonymous service
283+
e.g.: ``inline(Foo::class)->autowire()->autoconfigure()``.
283284

284285
Using an anonymous service as a factory looks like this:
285286

@@ -319,9 +320,9 @@ Using an anonymous service as a factory looks like this:
319320
use App\Foo;
320321
321322
return function(ContainerConfigurator $configurator) {
322-
$container = $configurator->services();
323+
$services = $configurator->services();
323324
324-
$container->set(Foo::class)
325+
$services->set(Foo::class)
325326
->factory([inline(AnonymousBar::class), 'constructFoo'])
326327
};
327328
@@ -362,9 +363,9 @@ or you decided not to maintain it anymore), you can deprecate its definition:
362363
use App\Service\OldService;
363364
364365
return function(ContainerConfigurator $configurator) {
365-
$container = $configurator->services();
366+
$services = $configurator->services();
366367
367-
$container->set(OldService::class)
368+
$services->set(OldService::class)
368369
->deprecate('The "%service_id%" service is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0.');
369370
};
370371

0 commit comments

Comments
 (0)
0