[DependencyInjection] Improved "optional argument" documentation

[dantleech]

Q	A
Doc fix?	yes
New docs?	yes
Applies to	2.3+/master

The on-ignore=null behavior of the DI container arguments is currently undocumented.

TODO:

• Add - When used on a collection argument, the argument will be removed. list item in master.

[dantleech]

Not sure if this should be expanded into a code block showing the on null configuration for XML, YAML and PHP.

[xabbuh]

Didn't you mean on-invalid instead of on-ignore? I think we would then also need to clarify the difference between IGNORE_ON_INVALID_REFERENCE and NULL_ON_INVALID_REFERENCE.

[dantleech]

@xabbuh yeah that is what i meant - should this be expanded into a new section with a new set of code examples? or shall i just expand the note?

[xabbuh]

I think a new section with a dedicated example (e.g. a collection argument) that shows the difference would be a good idea.

[dantleech]

This is only in Symfony 3.0 master

[xabbuh]

Yeah, I think we should omit it here and add it after merging your PR up to master.

[xabbuh]

Setting Missing Dependencies to null (not sure if we should use literals for null here)

[xabbuh]

I think I would move the "ignoring" strategy after the "set null" strategy. This way, you could say that it's basically the same strategy, but with the following differences (and then lists these differences).

[dantleech]

Updated, reworded, rearanged and changed the "ignore" example to use a method call.

[OskarStark]

code block with yaml is missing

[dantleech]

this feature isn't supported with YAML afaict.

[OskarStark]

really? if yes, sorry, i didn't know that, but then this would be a good information here ;-)

what do you think?

[dantleech]

Its given just below the code examples :)

On Fri, Apr 29, 2016 at 06:09:01AM -0700, Oskar Stark wrote:

In [1]book/service_container.rst:

---

Sometimes, one of your services may have an optional dependency, meaning
that the dependency is not required for your service to work properly. In
the example above, the app.mailer service must exist, otherwise an exception
will be thrown. By modifying the app.newsletter_manager service definition,
-you can make this reference optional. The container will then inject it if
-it exists and do nothing if it doesn't:
+you can make this reference optional, there are two strategies for doing this.
+
+Setting Missing Dependencies to null
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to explicitly set the argument to null in the event that the
+service does not exist then you may use the null strategy as follows:
+
+.. configuration-block::
+

really? if yes, sorry, i didn't know that, but then this would be a good
information here ;-)

what do you think?

—
You are receiving this because you authored the thread.
Reply to this email directly or [2]view it on GitHub

Reverse link: [3]unknown

References

Visible links

1. [DependencyInjection] Improved "optional argument" documentation #6511 (comment)
2. https://github.com/symfony/symfony-docs/pull/6511/files/0cf3bab63f400c6d04ff7baa1664c6f2b0f66d73#r61573614
3. https://github.com/symfony/symfony-docs/pull/6511/files/0cf3bab63f400c6d04ff7baa1664c6f2b0f66d73#r61573614

[wouterj]

This is the first time I understand the difference, thanks for submitting this patch!

👍

[dantleech]

Updated

[xabbuh]

Thank you @dantleech for adding this missing piece of information. I also opened #6550 so that we do not forget to update the docs for Symfony 3.1 with the changes made for invalid reference collection arguments.