Adding lazy services documentation as of symfony/symfony#7890 #2619
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,5 +14,6 @@ | |
| configurators | ||
| parentservices | ||
| advanced | ||
| lazy_services | ||
| workflow | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| .. index:: | ||
| single: Dependency Injection; Lazy Services | ||
|
|
||
| Lazy Services | ||
| ============= | ||
|
|
||
| .. versionadded:: 2.3 | ||
| Lazy services were added in Symfony 2.3. | ||
|
|
||
| Configuring lazy services | ||
| ------------------------- | ||
|
|
||
| In some particular cases where a very heavy service is always requested, | ||
| but not always used, you may want to mark it as ``lazy`` to delay its instantiation. | ||
|
|
||
| In order to have services to lazily instantiate, you will first need to install | ||
| the `ProxyManager bridge`_: | ||
|
|
||
| .. code-block:: bash | ||
| $ php composer.phar require symfony/proxy-manager-bridge:2.3.* | ||
|
|
||
| You can mark the service as ``lazy`` by manipulating its definitions: | ||
|
|
||
| .. configuration-block:: | ||
|
|
||
| .. code-block:: yaml | ||
|
|
||
| services: | ||
| foo: | ||
| class: Acme\Foo | ||
| lazy: true | ||
|
|
||
| .. code-block:: xml | ||
|
|
||
| <service id="foo" class="Acme\Foo" lazy="true" /> | ||
|
|
||
| .. code-block:: php | ||
|
|
||
| $definition = new Definition('Acme\Foo'); | ||
| $definition->setLazy(true); | ||
| $container->setDefinition('foo', $definition); | ||
|
There was a problem hiding this comment. I prefer $container->register('foo', 'Acme\Foo')
->setLazy(true); |
||
|
|
||
| You can then require the service from the container:: | ||
|
|
||
| $service = $container->get('foo'); | ||
|
|
||
| At this point the retrieved ``$service`` should be a virtual `proxy`_ with the same | ||
| signature of the class representing the service. | ||
|
|
||
| .. note:: | ||
|
|
||
| If you don't install the `ProxyManager bridge`_, the container will just skip | ||
| over the ``lazy`` flag and simply instantiate the service as it would normally do. | ||
|
|
||
| The proxy gets initialized and the actual service is instantiated as soon as you interact | ||
| in any way with this object. | ||
|
|
||
| Additional Resources | ||
| -------------------- | ||
|
|
||
| You can read more about how proxies are instantiated, generated and initialized in | ||
| the `documentation of ProxyManager`_. | ||
|
|
||
|
|
||
| .. _`ProxyManager bridge`: https://github.com/symfony/symfony/tree/2.3/src/Symfony/Bridge/ProxyManager | ||
| .. _`proxy`: http://en.wikipedia.org/wiki/Proxy_pattern | ||
| .. _`documentation of ProxyManager`: https://github.com/Ocramius/ProxyManager/blob/master/docs/lazy-loading-value-holder.md | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This will be useless for people using the fullstack repo (as they already have the bridge in it). however, they need to require ProxyManager.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are you sure? You are aware it's a components article? As far as I can see, this package is part of the the 'suggested' packages in de di component, it's not a required package.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ah sorry, I forgot we are in the component section.
but this should still be noted IMO. Because for people installing the full symfony package, they need to require ProxyManager to get it
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@stof the bridge explicitly requires proxy-manager though: https://github.com/symfony/symfony/blob/78e3710de8fbc1bd09e290d0f94c758afb9fbb1b/src/Symfony/Bridge/ProxyManager/composer.json#L21
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, but people having the full stack repo don't have a requirement on it as
symfony/symfonydoes not define it as a requirement (it is not a mandatory dependency of the full repo as we don't want to force everyone to get it)There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@stof wondering how composer behaves here... Guess it marks it as already installed. Forcing installation of
ocramius/proxy-manager:*is kinda "meh" here (because of*), and keeping this document up to date with the correct supported version is meh too ;)