8000 Merge branch '3.4' into 4.0 · symfony/symfony-docs@e06565d · GitHub
[go: up one dir, main page]
Skip to content

Commit e06565d

Browse files
wouterjwouterj
committed
Merge branch '3.4' into 4.0
2 parents 5080cfb + 931e6f6 commit e06565d

File tree

5 files changed

+217
-65
lines changed

5 files changed

+217
-65
lines changed

‎_build/redirection_map

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -386,3 +386,4 @@
386386
/request/load_balancer_reverse_proxy /deployment/proxies
387387
/quick_tour/the_controller /quick_tour/the_big_picture
388388
/quick_tour/the_view /quick_tour/flex_recipes
389+
/service_container/service_locators /service_container/service_subscribers_locators

‎components/var_dumper/advanced.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -319,7 +319,7 @@ being cloned in an array. They are callables that accept five arguments:
319319
* a :class:`Symfony\\Component\\VarDumper\\Cloner\\Stub` object
320320
representing the main properties of the object (class, type, etc.);
321321
* true/false when the caster is called nested in a structure or not;
322-
* A bit field of :class:`Symfony\\Component\\VarDumper\\Caster\\Caster```::EXCLUDE_*``
322+
* A bit field of :class:`Symfony\\Component\\VarDumper\\Caster\\Caster` ``::EXCLUDE_*``
323323
constants.
324324

325325
Here is a simple caster not doing anything::

‎frontend/encore/simple-example.rst

Lines changed: 38 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,20 @@ Imagine you have a simple project with one CSS and one JS file, organized into
55
an ``assets/`` directory:
66

77
* ``assets/js/app.js``
8-
* ``assets/css/app.scss``
8+
* ``assets/css/app.css``
99

1010
With Encore, you should think of CSS as a *dependency* of your JavaScript. This means,
1111
you will *require* whatever CSS you need from inside JavaScript:
1212

1313
.. code-block:: javascript
1414
1515
// assets/js/app.js
16-
require('../css/app.scss');
16+
require('../css/app.css');
1717
1818
// ...rest of JavaScript code here
1919
20-
With Encore, we can easily minify these files, pre-process ``app.scss``
21-
through Sass and a *lot* more.
20+
With Encore, we can easily minify these files, pre-process ``app.css``
21+
through PostCSS and a *lot* more.
2222

2323
Configuring Encore/Webpack
2424
--------------------------
@@ -41,12 +41,10 @@ Inside, use Encore to help generate your Webpack configuration.
4141
// will create public/build/app.js and public/build/app.css
4242
.addEntry('app', './assets/js/app.js')
4343
44-
// allow sass/scss files to be processed
45-
.enableSassLoader()
46-
4744
// allow legacy applications to use $/jQuery as a global variable
4845
.autoProvidejQuery()
4946
47+
// enable source maps during development
5048
.enableSourceMaps(!Encore.isProduction())
5149
5250
// empty the outputPath dir before each build
@@ -57,13 +55,16 @@ Inside, use Encore to help generate your Webpack configuration.
5755
5856
// create hashed filenames (e.g. app.abc123.css)
5957
// .enableVersioning()
58+
59+
// allow sass/scss files to be processed
60+
// .enableSassLoader()
6061
;
6162
6263
// export the final configuration
6364
module.exports = Encore.getWebpackConfig();
6465
65-
This is already a rich setup: it outputs 2 files, uses the Sass pre-processor and
66-
enables source maps to help debugging.
66+
This is already a rich setup: it outputs 2 files and enables source maps
67+
to help debugging.
6768

6869
.. _encore-build-assets:
6970

@@ -89,9 +90,6 @@ To build the assets, use the ``encore`` executable:
8990

9091
Re-run ``encore`` each time you update your ``webpack.config.js`` file.
9192

92-
Actually, to use ``enableSassLoader()``, you'll need to install a few
93-
more packages. But Encore will tell you *exactly* what you need.
94-
9593
After running one of these commands, you can now add ``script`` and ``link`` tags
9694
to the new, compiled assets (e.g. ``/build/app.css`` and ``/build/app.js``).
9795
In Symfony, use the ``asset()`` helper:
@@ -111,6 +109,34 @@ In Symfony, use the ``asset()`` helper:
111109
</body>
112110
</html>
113111
112+
Using Sass
113+
----------
114+
115+
Instead of using plain CSS you can also use Sass. In order to do so, change the
116+
extension of the ``app.css`` file to ``.sass`` or ``.scss`` (based on the syntax
117+
you want to use):
118+
119+
.. code-block:: diff
120+
121+
// assets/js/app.js
122+
- require('../css/app.css');
123+
+ require('../css/app.scss');
124+
125+
And enable the Sass pre-processor:
126+
127+
.. code-block:: diff
128+
129+
// webpack.config.js
130+
Encore
131+
// ...
132+
133+
// allow sass/scss files to be processed
134+
- // .enableSassLoader()
135+
+ .enableSassLoader()
136+
137+
Using ``enableSassLoader()`` requires to install additional packages, but Encore
138+
will tell you *exactly* which ones when running it.
139+
114140
Requiring JavaScript Modules
115141
----------------------------
116142

‎service_container/lazy_services.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Lazy Services
66

77
.. seealso::
88

9-
Another way to inject services lazily is via a :doc:`service locator </service_container/service_locators>`.
9+
Another way to inject services lazily is via a :doc:`service subscriber </service_container/service_subscribers_locators>`.
1010

1111
Why Lazy Services?
1212
------------------

‎service_container/service_locators.rst renamed to ‎service_container/service_subscribers_locators.rst

Lines changed: 176 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
.. index::
2-
single: DependencyInjection; Service Locators
2+
single: DependencyInjection; Service Subscribers
33

4-
Service Locators
5-
================
4+
Service Subscribers & Locators
5+
==============================
6+
7+
.. versionadded:: 3.3
8+
Service subscribers and locators were introduced in Symfony 3.3.
69

710
Sometimes, a service needs access to several other services without being sure
811
that all of them will actually be used. In those cases, you may want the
@@ -77,15 +80,178 @@ However, injecting the entire container is discouraged because it gives too
7780
broad access to existing services and it hides the actual dependencies of the
7881
services.
7982

80-
**Service Locators** are intended to solve this problem by giving access to a
81-
set of predefined services while instantiating them only when actually needed.
83+
**Service Subscribers** are intended to solve this problem by giving access to a
84+
set of predefined services while instantiating them only when actually needed
85+
through a **Service Locator**, a separate lazy-loaded container.
86+
87+
Defining a Service Subscriber
88+
-----------------------------
89+
90+
First, turn ``CommandBus`` into an implementation of :class:`Symfony\\Component\\DependencyInjection\\ServiceSubscriberInterface`.
91+
Use its ``getSubscribedServices()`` method to include as many services as needed
92+
in the service subscriber and change the type hint of the container to
93+
a PSR-11 ``ContainerInterface``::
94+
95+
// src/AppBundle/CommandBus.php
96+
namespace AppBundle;
97+
98+
use AppBundle\CommandHandler\BarHandler;
99+
use AppBundle\CommandHandler\FooHandler;
100+
use Psr\Container\ContainerInterface;
101+
use Symfony\Component\DependencyInjection\ServiceSubscriberInterface;
102+
103+
class CommandBus implements ServiceSubscriberInterface
104+
{
105+
private $locator;
106+
107+
public function __construct(ContainerInterface $locator)
108+
{
109+
$this->locator = $locator;
110+
}
111+
112+
public static function getSubscribedServices()
113+
{
114+
return [
115+
'AppBundle\FooCommand' => FooHandler::class,
116+
'AppBundle\BarCommand' => BarHandler::class,
117+
];
118+
}
119+
120+
public function handle(Command $command)
121+
{
122+
$commandClass = get_class($command);
123+
124+
if ($this->locator->has($commandClass)) {
125+
$handler = $this->locator->get($commandClass);
126+
127+
return $handler->handle($command);
128+
}
129+
}
130+
}
131+
132+
.. tip::
133+
134+
If the container does *not* contain the subscribed services, double-check
135+
that you have :ref:`autoconfigure <services-autoconfigure>` enabled. You
136+
can also manually add the ``container.service_subscriber`` tag.
137+
138+
The injected service is an instance of :class:`Symfony\\Component\\DependencyInjection\\ServiceLocator`
139+
which implements the PSR-11 ``ContainerInterface``, but it is also a callable::
140+
141+
// ...
142+
$locateHandler = $this->locator;
143+
$handler = $locateHandler($commandClass);
144+
145+
return $handler->handle($command);
146+
147+
Including Services
148+
------------------
149+
150+
In order to add a new dependency to the service subscriber, use the
151+
``getSubscribedServices()`` method to add service types to include in the
152+
service locator::
153+
154+
use Psr\Log\LoggerInterface;
155+
156+
public static function getSubscribedServices()
157+
{
158+
return [
159+
// ...
160+
LoggerInterface::class,
161+
];
162+
}
163+
164+
Service types can also be keyed by a service name for internal use::
165+
166+
use Psr\Log\LoggerInterface;
167+
168+
public static function getSubscribedServices()
169+
{
170+
return [
171+
// ...
172+
'logger' => LoggerInterface::class,
173+
];
174+
}
175+
176+
Optional Services
177+
~~~~~~~~~~~~~~~~~
178+
179+
For optional dependencies, prepend the service type with a ``?`` to prevent
180+
errors if there's no matching service found in the service container::
181+
182+
use Psr\Log\LoggerInterface;
183+
184+
public static function getSubscribedServices()
185+
{
186+
return [
187+
// ...
188+
'?'.LoggerInterface::class,
189+
];
190+
}
191+
192+
.. note::
193+
194+
Make sure an optional service exists by calling ``has()`` on the service
195+
locator before calling the service itself.
196+
197+
Aliased Services
198+
~~~~~~~~~~~~~~~~
199+
200+
By default, autowiring is used to match a service type to a service from the
201+
service container. If you don't use autowiring or need to add a non-traditional
202+
service as a dependency, use the ``container.service_subscriber`` tag to map a
203+
service type to a service.
204+
205+
.. configuration-block::
206+
207+
.. code-block:: yaml
208+
209+
// app/config/services.yml
210+
services:
211+
AppBundle\CommandBus:
212+
tags:
213+
- { name: 'container.service_subscriber', key: 'logger', id: 'monolog.logger.event' }
214+
215+
.. code-block:: xml
216+
217+
<!-- app/config/services.xml -->
218+
<?xml version="1.0" encoding="UTF-8" ?>
219+
<container xmlns="http://symfony.com/schema/dic/services"
220+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
221+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
222+
223+
<services>
224+
225+
<service id="AppBundle\CommandBus">
226+
<tag name="container.service_subscriber" key="logger" id="monolog.logger.event" />
227+
</service>
228+
229+
</services>
230+
</container>
231+
232+
.. code-block:: php
233+
234+
// app/config/services.php
235+
use AppBundle\CommandBus;
236+
237+
// ...
238+
239+
$container
240+
->register(CommandBus::class)
241+
->addTag('container.service_subscriber', array('key' => 'logger', 'id' => 'monolog.logger.event'))
242+
;
243+
244+
.. tip::
245+
246+
The ``key`` attribute can be omitted if the service name internally is the
247+
same as in the service container.
82248

83249
Defining a Service Locator
84250
--------------------------
85251

86-
First, define a new service for the service locator. Use its ``arguments``
87-
option to include as many services as needed to it and add the
88-
``container.service_locator`` tag to turn it into a service locator:
252+
To manually define a service locator, create a new service definition and add
253+
the ``container.service_locator`` tag to it. Use its ``arguments`` option to
254+
include as many services as needed in it.
89255

90256
.. configuration-block::
91257

@@ -128,7 +294,7 @@ option to include as many services as needed to it and add the
128294
use Symfony\Component\DependencyInjection\ServiceLocator;
129295
use Symfony\Component\DependencyInjection\Reference;
130296
131-
//...
297+
// ...
132298
133299
$container
134300
->register('app.command_handler_locator', ServiceLocator::class)
@@ -144,7 +310,7 @@ option to include as many services as needed to it and add the
144310
The services defined in the service locator argument must include keys,
145311
which later become their unique identifiers inside the locator.
146312

147-
Now you can use the service locator injecting it in any other service:
313+
Now you can use the service locator by injecting it in any other service:
148314

149315
.. configuration-block::
150316

@@ -188,45 +354,4 @@ Now you can use the service locator injecting it in any other service:
188354
If the service locator is not intended to be used by multiple services, it's
189355
better to create and inject it as an anonymous service.
190356

191-
Usage
192-
-----
193-
194-
Back to the previous ``CommandBus`` example, it looks like this when using the
195-
service locator::
196-
197-
// ...
198-
use Psr\Container\ContainerInterface;
199-
200-
class CommandBus
201-
{
202-
/**
203-
* @var ContainerInterface
204-
*/
205-
private $handlerLocator;
206-
207-
// ...
208-
209-
public function handle(Command $command)
210-
{
211-
$commandClass = get_class($command);
212-
213-
if (!$this->handlerLocator->has($commandClass)) {
214-
return;
215-
}
216-
217-
$handler = $this->handlerLocator->get($commandClass);
218-
219-
return $handler->handle($command);
220-
}
221-
}
222-
223-
The injected service is an instance of :class:`Symfony\\Component\\DependencyInjection\\ServiceLocator`
224-
which implements the PSR-11 ``ContainerInterface``, but it is also a callable::
225-
226-
// ...
227-
$locateHandler = $this->handlerLocator;
228-
$handler = $locateHandler($commandClass);
229-
230-
return $handler->handle($command);
231-
232357
.. _`Command pattern`: https://en.wikipedia.org/wiki/Command_pattern

0 commit comments

Comments
 (0)
0