Improve "Controllers as Services" article (+ interlinking)

[wouterj]

As you can see in this transcript, some code examples are confusing and that causes people to think we use Service Locators in our examples.

We should improve the documentation to make sure people don't get confused. To do this, some things are needed:

1. Improve the "Controllers as Services" article (cookbook/controller/services).

   We should use this blogpost by @richardmiller as an example how this article should look like. We need to add some use-cases and provide some better information.

2. Interlink to the "Controllers as Services" article

   Currently, the only interlink to this document is at the bottom of book/service_container. We need to add some more links to this article on important places in our documentation

[richardmiller-zz]

It will be difficult to dissuade people that the container is being used a service locator in such examples since it is and this is the way it is typically shown as being used in a lot of the documentation. This is not simply a documentation issue though but goes back to whether controllers should be services or not.

Extending from the base controller rather than forcing users to make controllers services makes it considerably easier to get started using Symfony2 often without even using the Controller::get() method to access service since the most commonly used are hidden behind the helper methods. Unfortunately the downside of this is that it often misleads people into thinking that using the container as a service locator is the correct way to use it through out an application. I think this is where documentation changes such as those suggested here would be good. I will have a look at improving the Controller as services cookbook.

In terms of avoiding people who are already knowledgable about DI and service containers from saying it is being used as service locator in the controllers then there is not much we can do about that since it is the case.

[wouterj]

I don't think we use a service locator in Symfony2.
When controllers extends the base Controller class, they are no services, but classes instead. That means that injecting the Service Container into them is not a service locator.

If you are going to use controllers as services, you should no longer extend from the base Controller class and inject only the services that are needed. That means there is no Service locator in here too.

[igorw]

In terms of avoiding people who are already knowledgable about DI and service containers from saying it is being used as service locator in the controllers then there is not much we can do about that since it is the case.

It's very important to emphasise that you aren't forced to inject the container and that the base controller is optional.

I definitely see the value of the base controller for newcomers, and I'm not suggesting we get rid of it. But the docs should make it clear that the clean way is also supported. Otherwise they will continue to be misinformed and bitch about the sf2 DIC.

When controllers extends the base Controller class, they are no services, but classes instead. That means that injecting the Service Container into them is not a service locator.

Injecting the container is by definition turning it into a service locator.

[richardmiller-zz]

I agree that more should be done to emphasise that the container does need to be used in that way. Not sure it will prevent people bitching about it though :)

[wouterj]

@igorw thanks for the clearification. I thought a Service Locator was only meaned for injecting the container in services. (need to do some research before saying something the next time...)

[igorw]

Just came across #457, which is relevant.

[weaverryan]

Hey guys!

I'm closing this issue now after #2538 and some other commits that I made related to this (which I list in my comments there). This is a tough issue, and ultimately not everyone will look into things far enough to actually know what's really going on, but I feel that we've enhanced things and added some interlinking between chapters to hopefully make it more obvious that your controller can be defined as a service and therefore your dependencies injected in specifically.

Thanks!