I'm happy to merge the fix if I can establish why, but can you please supply more details about what doesn't work and why files is a better choice? I don't seem to be able to replicate the problem.

I create the following composer.json:

{
    "require": {
        "docopt/docopt": "0.6.*"
    }
}

Then the following PHP:

<?php
require __DIR__.'/vendor/autoload.php';
var_dump(class_exists('Docopt\Handler', false));
$h = new Docopt\Handler();
var_dump(class_exists('Docopt\Handler', false));

The output is this:

bool(false)
bool(true)

Classmap only works for classes. Since the file also contains functions, files will make sure those functions can be used as well, without requiring the class to be instantiated first.

In particular the Docopt\docopt() function.

Ahh, cheers, I understand now. Thanks for reporting. The files autoloader requires the docopt file on every request, which I don't think is a good fit for projects which share a vendor directory between a web app and a CLI.

I think the interim solution is to recommend that you use the Docopt\Handler class with composer, and the long-term solution is to clean up the API so that Docopt\docopt() becomes a static function of a class, thus allowing autoloaders to work properly.

I'm not overly fond of the verbosity of Docopt\Handler::docopt(), but I'd like to minimise the BC breaks as much as I can. At the moment, I'm looking at creating the class Docopt in the global namespace and changing Docopt\docopt to Docopt::handle() (Docopt::docopt() throws a wobbly because it thinks it's the constructor). I'll see if I can come up with something better, but that's where I think it should go.

It's a known limitation of PHP autoloading that you cannot autoload functions. Which is unfortunate. I still think a function is more correct than a static method, and worth the small penalty of loading the file.

But the static method solution works as well, so if you want to go with that, that's fine with me.