How does the “replace” property work with composer?

Question

So how does the \"replace\" property work with composer? I have read the composer document but still not understand it. Searching for more info hasn\'t answered my questions.

Answer 1

The Composer documentation gives two basic examples. I'll try to explain:

Lists packages that are replaced by this package. This allows you to fork a package, publish it under a different name with its own version numbers, while packages requiring the original package continue to work with your fork because it replaces the original package.

Suppose your software uses original/library and other/package, which itself also requires original/library.

Now you think that original/library needs to integrate a feature, but the maintainers won't let your suggestion happen in their package. You decide to fork that library under the name better/library, and tag a new release.

Back to your software. Of course it should start using better/library, so you require that instead, but that other/package still requires the original/library - code duplication! How can you make that other package to use your better/library instead without also forking it and only changing the composer.json (you are still compatible to that original/library, so it should work)?

You add a replace key to your composer.json:

"replace": {
    "original/library":"1.0.2"
}

Now Composer knows that any package from your better/library is equally good as the original/library when it comes to resolving the dependencies of the other/package.

This is also useful for packages that contain sub-packages, for example the main symfony/symfony package contains all the Symfony Components which are also available as individual packages. If you require the main package it will automatically fulfill any requirement of one of the individual components, since it replaces them.

The same rules, a slightly different angle: Requiring components of a framework is a good approach for any other component that needs some feature. But if you require the full framework in your software, and another library, which subsequently also requires a component of that framework, the replace declaration of the framework allows Composer to not have to install that single component twice, because it is already included in the full framework.

Beware: Placeholders in replaced versions are usually bad

In my original answer I suggested:

"replace": {
    "original/library":"1.*"
}

This has consequences: Composer will now treat your library version 1.0.0 to be as good as ANY version 1.x of the original library, even if they fix stuff or add features and release version 1.2.34 some day. This also means that if your other/package some day gets an update and requires original/library:^1.1, the replacement in YOUR library is still active and states that it can replace ANY version 1.*, even without you updating anything inside - which it can not, your old code will never implement new features of the original library without you doing some work, but the replacement states exactly this.

So in essence: Avoid wildcard versions in the replacement version! If you use them, you make a statement about the future that you cannot know or predict (unless you can control original/library, but even then be very careful). Always use a specific version of the original/library that you know and can re-implement completely.

Answer 2

When you create your own package, you define in your composer.json what kind of packages does it provide which basically tells Composer that your package has it already installed, so no need to install it again.

If you use replace property, it tells Composer that your package wants to replace the original package with your own fork, so other packages don't need to install it.

For example if a/a package requires b/b and you tell to replace b/b, it won't be downloaded on Composer install/update.

This is explained in more details in here: How does the “replace” property work in Composer?