Ref #11635

Motivation

Some packages propose optional dependencies to add optional features to their library.

This is actually mainly implemented by :

• Having suggest in your composer.json (but from what i remember this will be deprecated ? maybe i'm wrong there)
• Having the dependencies in "require-dev"
• Adding a conflict rule if necessary to avoid bad versions of the needed library
• Adding documentation to tell user to "require" this dependency (or maybe multiple one) if he needs a specific feature
• Add checks in your code to determine if library is present (either by looking if a class exists or by using the InstalledVersions file of composer to see if the dependency is installed)

Also when feature may require multiple dependencies some library author prefer to propose a intermediate package that have the necessary requires in order to offer a better DX for end user (no need to require multiple packages, better handling of versions, ...)

When doing this, library author often prefers to have a monolith repository and splitting directory into multiple git repository which allows to create PR that can update both the main library and the optional dependency without too much hassle

Let's be honest, the current way is complicated and add a lot of maintenance for library authors, this PR aims to add a new way in composer to handle this use case.

Goals

• Allowing a library author to declare features on its package by telling : this feature require those packages in those versions
• Allow a library user to declare which feature he want to use
• Allowing a library author to better detect if a feature is enabled: a dependency may be installed but maybe it was done by another library and not because the user want this specific feature

Declaring features

In order for the author of a library to declare features he will now have to do add this lines in its composer.json file :

"feature": {
    "my-awesome-feature": {
        "description": "An optional description describing the feature",
        "require": {
             "vendor/packageA": "1.0",
             "vendor/packageB": "^2.0",
             ...
        }
    }
}

Using features

In order for a user to use a feature of a library he will now have to add this lines in its composer.json file :

"require": {
    "vendor/library": "^1.0",
},
"require-feature": {
    "vendor/library": ["my-awesome-feature"]
}

Detecting features

When the library want to detect if a feature is enabled it will now be able to do this in PHP :

<?php

use Composer\InstalledVersions;

// method exists check to avoid bc break old composer version
if (method_exists(InstalledVersions::class, 'hasFeature') && InstalledVersions::hasFeature("vendor/library", "my-awesome-feature")) {
   // handling my awesome feature
}

Testing features

New arguments are provided to the install and update commands in order for library authors to test their features.

Features dependencies of the root package (not of others packages unless required) are always resolved in the composer.lock file.

This ensure that given any combination the set of dependencies is always correct, like require-dev dependencies

However, like require-dev it is possible to avoid installing the package link to a feature

Some examples :

• Will install require / require-dev / and all features packages

composer install

• Will install require and all features packages

composer install --no-dev

• Will install require and require-dev package (but no packages required by features)

composer install --no-features

• Will install require, require-dev and packages of feature "my-awesome-feature"

composer install --feature my-awesome-feature

In order to achieve that packages are now splitted like this in the composer.lock files :

"packages": [...]
"packages-dev": [...]
"packages-feature": {
    "my-awesome-feature": [...],
    "other-feature": [...]
}

This allow library authors to install and test their packages with any possible combination of features :

• testing without features
• testing with only one of the features
• testing with a specific set of features
• etc ....

Errors

In order to provider better information for end user some rules where added to the SAT resolution :

• Require a inexistant feature : It will throw an error where it tells user that this feature does not exist on the wanted library
• Require a feature on a library that is not present : It will create a new error where it tells the user that the package is not present in its requirements

None goals

To keep this first version simple, some changes are not considered in this PR :

• Having a feature that require another feature
• Having a feature that provides other packages (would be nice, but can be done in another PR)
• A default feature set and avoiding requiring default features
• SAT resolution depending on feature (if i require a feature that is only available in a specific version it would be nice to restrict the version or tell user why its current set of dependencies is not possible). There is some rules for feature and SAT but right now the implementation is "stupid" (This has been done finally)
• Simpler syntax for feature requirements, it would be nice to be able to declare feature requirement directly in the require section like the following :

"require": {
    "vendor/package": { "version": "^1.0", "features": ["my-awesome-feature"] },
}

However this syntax would bring a too big BC break (older versions of composer would not be able to understand this).

Things to do in this PR :

• More tests, i added some but it definitely does not cover all uses cases
• Add the hasFeature method in InstalledVersions
• Fixing phpstan 😭