Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Improve "Controllers as Services" article (+ interlinking) #2433

Closed
wouterj opened this Issue Mar 30, 2013 · 7 comments

Comments

Projects
None yet
4 participants
Member

wouterj commented Mar 30, 2013

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

Contributor

richardmiller commented Mar 31, 2013

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.

Member

wouterj commented Mar 31, 2013

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.

Contributor

igorw commented Mar 31, 2013

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.

Contributor

richardmiller commented Apr 2, 2013

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 :)

Member

wouterj commented Apr 2, 2013

@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...)

Contributor

igorw commented May 2, 2013

Just came across #457, which is relevant.

@weaverryan weaverryan added a commit that referenced this issue Jun 30, 2013

@weaverryan weaverryan [#2538][#2433] Adding a note to the service container chapter about h…
…ow a controller can be defined as a service
1a79edd

@weaverryan weaverryan added a commit that referenced this issue Jun 30, 2013

@weaverryan weaverryan [#2433][#457] Adding more emphasis to the note about controllers as s…
…ervices in the controllers chapter
1fbd278
Member

weaverryan commented Jun 30, 2013

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!

@weaverryan weaverryan closed this Jun 30, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment