"How do I locate files in composer packages?"

This is a common question on any project that wasn't built using one of the large, mainstream frameworks - which offer concepts like "bundles" etc. to answer this question in various ways.

I personally build all my projects using an IOC container and hand-picked composer packages. I don't want a full framework.

Some people just hard-code the base-paths - and answer you tend to find on StackOverflow - but this creates problems, for one, the path is obviously different when the package is the root package (when you're running tests, etc.) and when it's installed in the vendor folder. Composer installer plugins can alter package paths, composer.json can change the vendor folder name, etc.

There are packages available to deal with this problem as well - on the light end, my own package mindplay/composer-locator accounts for these problems; and on the heavy end (now dead?) packages like Puli basically built their own virtual file-systems to replace the native file-system.

Now, every template engine, markdown renderer, really anything that accepts a file path, generally uses file_get_contents or fopen or other standard functions - and so, they already support PHP-style URIs, and thereby support stream-wrappers.

So I can make this work - by choosing a package (mindplay/composer-locator or something like it) I can find the physical path, and then pass that path to library X.

But I'm introducing another dependency, at the source-code level, just to locate the file. This is all information that Composer has - packages like mindplay/composer-locator really just take the information from Composer and exposes it. I already have composer, I have the file installed, but now I need to pick a library and write code just to locate the file...

What I'd really like is to be able to just do this:

$readme = file_get_contents("composer://vendor/package/path/to/readme.txt");

The composer:// stream-wrapper would resolve the base path vendor/package to the installed package root-folder, and the rest of the path is simply appended to that physical path.

So I went ahead and added that to mindplay/composer-locator.

It passes all of the following tests, where ok asserts true, and eq is a strict equality assertion:

https://github.com/mindplay-dk/composer-locator/pull/9/files#diff-0e9f7e9fab2837fcff42dfc571491aeae61f1090a8c6351b93a49c30f0927e21

So this very simply virtualizes the logical Composer package hierarchy into a logical file-system - you can open files using standard file-system functions, and you can use readdir or DirectoryIterator etc. to iterate over the root composer:// folder, which will give you vendor-names, you can iterate over e.g. composer://mindplay to find packages from a specific vendor, etc.

It "just works" with any old PHP library, and it's all pretty intuitive, I think.

To the point where I'm wondering why this feature isn't just built into Composer. 🤔

I know it's always been a policy to never introduce actual APIs, and thereby source-code dependencies, in Composer - I've asked in the past for an API to locate package paths and gotten a solid "no", and I understand why.

But our projects do depend on Composer for the generated autoloader - it's not a source-code level dependency, but it is a dependency, as otherwise nothing would be able to load, right?

If somebody wanted to create a competing loader, they could - it would just have to parse standard JSON and support standard PSR-4 paths, etc.

This doesn't seem that different.

Granted, there would be things to consider and discuss first. For example, is composer:// an appropriate name? It might not be - something like packages:// might be more neutral territory? And would the packages scheme need to be a PSR standard?

I think it's worth discussing? 🙂