I'm 👎 on this. It is explained in detail in the referenced installation instructions how to install new components.

The part missing from the docs is actually the autoload -- or is mentioned in another place?

The autoload of the required packages already handled by Composer. You don't need to do anything else. This autoload config sets up an autoloader for the classes of the app/library itself. That's not in the scope of using the component and it is already explained perfectly in the Composer documentation.

1. So if we remove the "autoload" where should the GreetCommand.php be created?
2. Also we'd still need to require_once './vendor/autoload.php'; from the application.php, right?

Where you want it to be. The point is, you need to define the autoload, but that's not the scope of this article. In documentation, each article and section has its own scope. The Components documentation explains you how to use the components in a standalone PHP project. Telling you how to set-up such a project and how to organize your files and autoloading is not in the scope of these articles. That is a perfect topic for a blog post or the Composer documentation.

The docs for the SE as great, since that's the goal of the Symfony docs. The complete SE is in the scope of the Symfony documentation.

Structuring a project and setting up one isn't. So yeah, you have to search for it. Not sure if it's something we should improve.

Fortunate for you, I'm not the only guy who decideds these things. I'll wait for their comments too. /cc @weaverryan

Hmm, all great points!

When I was updating some component docs the other day, it did occur to me that we're leaving out the detail of requiring the autoloader (so making the docs not really copy-pastable). So that does seem like a small detail we could add to help people. For example, if you look at the Finder component, we would just need to add the require for the autoload.php in the first code block and maybe just a few others http://symfony.com/doc/current/components/finder.html. I'm thinking whenever we show a full example (i.e. include the use statement), we could also include the require line and a little // foo.php filename comment at the top. What do you guys think about this part?

Second, there is this autoloading proposal. The good news is, I don't think this affects most component docs (we don't ever create any objects in the Finder docs, for example). If I do a git grep "namespace ", it only shows 7 of the components. For these, I think it might be nice to add a quick note near-ish the first related code example that mentions this autoloader code. So, what do you guys think about this part?

Thanks!

@weaverryan both suggestions sound good to me, as they will assure the a dev will be able to get a working code with the component without leaving the page.

@weaverryan let's decide the target audience for the components docs. That always makes a discussion easier than discussing with people all different target audiences in mind.

My target audience for the components docs is 3 people:

• First there are people who are linked to some related usage article (for instance, the Translation usage). These people use the fullstack framework and just want to know usage
• Secondly, the components page attracks people who want to use the component standalone.
• At last, people who want to know more about Symfony internals visit the components articles.

(1) and (3) use the full-stack framework, these autoloading things aren't targeted for one.

Then we are left with (2). I always imagine these people to either already have a project or are at the start of bootstrapping one. They just go to the component docs because they know/found that this component will solve the problem they have.
I think there are almost none users who go the components docs, find a nice component and create a project from it.

The means that these docs are solving the problem of "how to use the component to solve the problem"? That excludes anything related to "how to bootstrap a project?", "what is the best library structure?" and "how to use Composer?".

@wouterj Very nice breakdown - I couldn't have thought of it better! And I agree that we have all 3 audiences and also that we don't need to teach people how to bootstrap a project, structure things or use Composer.

So, where does that leave us? I think:

A) We show a require of the autoload.php at the very top of every component docs in the installation section. I'm basing this off of Guzzle, which is a library that a lot of people use: http://guzzle.readthedocs.org/en/latest/overview.html#installation

B) We include a patch like this one for the rare case where we're assuming you have some auto-loading setup. We do this in the installation section.

For the 3 groups:

1. Full-stack FW users will not (hopefully) bother with the installation. So they hit no new problems
2. People wanting to include this in their non-FW project will have the autoloader and autoloading details if they need them.
3. People wanting to learn more about the internals will skip past installation as well.

Cheers!