Can't get composer "path" repository to work
When setting up a local monorepo or testing a package within the same project, developers often turn to Composer's type: path repositories. The goal is straightforward: point Composer at a directory on your filesystem so it treats it as an external dependency without needing to publish it to Packagist first. However, getting this configuration to resolve correctly can be surprisingly fragile if the URL syntax doesn't match the actual directory structure.
In the scenario provided, the developer has organized their files into a packages root with specific subdirectories for individual packages:
composer.json (Main)
packages/
balunker/
testpackage/
composer.json (Package)
src/
TestPackage.php
The main composer.json attempts to define a repository using a wildcard URL:
{
"name": "vagrant/composer-test",
"repositories": [
{
"type": "path",
"url": "packages/*/*"
}
],
"require": {
"balunker/testpackage": "*"
}
}
Despite this setup, running composer update results in the package being unresolvable, with no symlinks created and no installation occurring. The root cause lies in how Composer interprets the URL within a path repository versus how wildcards are handled in that specific context.
Composer's path repository expects an exact directory path to resolve against. While wildcards like packages/*/* might seem intuitive for matching patterns, they generally do not function as intended when defining the source URL for a path repository. Composer does not perform glob expansion on these URLs to find the package; instead, it looks for a literal directory named packages containing a subdirectory literally named *, which obviously doesn't exist in the file system.
To fix this, you must specify the exact relative path to the package's root directory. In this specific structure, since the package resides at packages/balunker/testpackage, the repository definition should change from:
"url": "packages/*/*"
to:
"url": "packages/balunker/testpackage"
This adjustment tells Composer to look directly inside packages/balunker/testpackage for a composer.json file. Once that exact path is provided, the wildcard in the require statement ("balunker/testpackage": "*") will correctly match against the version specified in the package's own composer.json.
It is also important to note where this configuration is applied. The repositories and require blocks must exist in the root composer.json of the main project, not in the package itself. If you are developing locally and want to treat your code as a dependency without publishing it, using an exact path is the standard approach.
If you frequently need to reference multiple packages from different directories within the same repository structure, manually updating the url for each new package can become tedious. In such cases, consider using the packages-dev or autoload-dev configurations if your use case fits, or look into tooling that manages local package aliases. However, for a single development cycle, hardcoding the exact relative path remains the most reliable method to ensure Composer can locate and install the local vendor without ambiguity.