Documentation for the DI container

[mnapoli]

I don't know if it's the right time to start documenting it. Feedback on the content is appreciated too.

[mattab]

our developer guide would only showcase those classes tagged with @api, maybe we are ready to tag Container and StaticContainer with @api ?

in any case this guide would be very useful even for anyone contributing to Piwik core or plugins, and of course to community when writing custom plugins.

[mnapoli]

Your comment made me think about this and I actually wrote this doc for Piwik developers, not plugin developers.

I think we should hold off as long as we can exposing this to plugins, because as soon as it's exposed we have to keep BC. If it's only used in Piwik (and not 3rd party plugins) it leaves us some times to define best practices on naming container entries (in config files), on how to define entries, etc... We are just starting to use the container with plugins, we should gain more experience before freezing it with BC.

Also, ContainerInterface is a standard interface, not included in Piwik (and not related to PHP-DI). It doesn't make sense to tag it with @api since it's already an standard API (and it's not Piwik code anyway). StaticContainer is very bad practice, I don't want people using it, but at the same time Piwik's architecture doesn't leave us much of a choice… I'm conflicted.

So in conclusion, if we want the doc only for core developers we shouldn't merge it yet right?

[mattab]

So in conclusion, if we want the doc only for core developers we shouldn't merge it yet right?

Correct, the developer.piwik.org is for Piwik users and plugin developers, so let's not merge it for now

[tsteur]

Now that we have a "Core Development" and a "Plugins / Develop" section can we write one guide for plugin developers under /develop Utils section that explains config and maybe DI to plugin developers. The guide should only contain information that is needed for plugin developers. And then an extended guide for core developers under /core? We could link from the short plugin guide to the extended guide if they want to know more.

[diosmosis]

I updated the PR. @mattab @tsteur please review and let me know if you have questions/comments.

[tsteur]

I think all the part above this section should go into a different page under http://developer.piwik.org/piwik-in-depth as it is quite complicated and not really super relevant for plugin developers.

[tsteur]

documented in #356 and targeted for plugin developers