Documentation should provide guidance on injecting ORM entity manager into a service

[thepurpleblob]

I would have thought that the number one use-case for a Service class would be to do 'stuff' in the database. In a different world you might want to call this the 'model'. However, I can find nowhere in the documentation that explains how to do this. The Service page in The Book is quite a lengthy read and I think it separates the bits most people will want (how to make a service and how to inject 'something') by a lot of more advanced discussion.

Anyway, as a reasonably new user, I would really have appreciated an early example of "Here's a simple Service that knows how to access the database". That is (unless I am missing something) completely absent. It had to go to StackOverflow to discover I needed to inject '@doctrine.orm.entity_manager' which is arcane to a newbie (and possibly non-newbies)

[wouterj]

I don't think we should document this. There are many services available right now: https://gist.github.com/WouterJ/4744739 If we document the doctrine.orm.entity_manager service, we should document others too. That means a lot of work which can change every day.

I think this issue is somewhat equal to #1824. It is a good idea, but it won't work for projects with this scale.

We can maybe add a note somewhere in the docs that tells you how to find out which services are available (you can do this by dumping $this->container->getServiceIds() in your controller.

[thepurpleblob]

I'm not really too fussy, but at the moment there is no clue whatsoever. I might argue that injecting the database 'connection' (for want of a better word) must be something 90%+ of users will want to do, surely?

Would you not even consider a couple of examples? "This is how you inject the Doctrine EM but there are lots of others you can find with.....". The link you gave above is actually very useful but how would one know?

Given that most of this is in "The Book" (as a newcomer to Symfony) it really struck me as much less of a tutorial (read immediately useful) than most of the rest. I'm struggling to see why.

However, thanks for your reply.

[wouterj]

@thepurpleblob, that link I gave is just a formatted output from var_dumping Container::getServiceIds(). I think it is a good idea to make people aware on how to see which services are available, I don't think we should give examples on how you do that.

But that is just me, some contributor to the docs, there are a lot more people which can see there thoughts about that. So let's wait what they think.

[thepurpleblob]

Yep - I only mention it because I found that page confusing from the point of view "but how do I access the database?". I did not find the solution in the documentation, I found it elsewhere. I'm far from the best qualified as to comment if that is a real problem. However, yes, I could just as easily have been saying "how do I access xxx?" assuming, of course, that I even knew xxx existed in the first place.

[richardmiller-zz]

@wouterj btw you can get a list of the services using the console command container:debug which is documented on the service container.

I agree that trying to document all the services available in the standard distribution as part of the service container page is not something that would be a good idea due to the large volume of them. However, I can see that there is a gap between the Doctrine page and knowing how to get an entity manager into a service. Often this is because on other pages they are shown within the context of controllers that extend the base controller and have shortcut methods, so there are lots of examples of using getDoctrine() in a controller but no explanation that it is the doctrine service that is returned. I think that it is worth documenting the service equivalent in a note block for any pages where the actual service used is hidden behind controller shortcut methods. Using a note and a link to the service container page should be enough to avoid it being confusing for someone who is reading the documentation for the first time whilst providing a reference for others.

[weaverryan]

Closing this issue as #2234 has been merged in, however as I mentioned there - I think we should indeed have quick notes here and there about what services we're working with explicitly. We could even perhaps have a reference for the most commonly-used services - i.e. doctrine, logger, mailer, templating, router, etc etc.

What do you guys this?

[wouterj]

Well, I don't think a reference is needed. When people want to log something in their bundles, they are searching for a log article in the documentation and they start reading cookbook/monolog/intro. The first code example shows their exactly how to get the logger.

It will be really usefull to add some notes in the articles, for instance book/templating and book/forms.

PS: I don't think the router is commonly-used?