Composer version constraints you must know

If you don’t know composer yet, please go to composer usage tutorialcolumn and start reading.

I've seen many people struggle with constraints on dependencies between the composer packages they use. Hopefully this article will point out the causes of some problems and provide ways to avoid them. I'll start with the worst case scenario and improve the constraints step by step.

Almighty asterisk: *

Composer has a dependency parser, so it can automatically find out what I want, right ? wrong.

Declaring a version constraint with * is probably one of the worst practices. Because you have absolutely no control over what you get. It may be any version matching minimum-stability and other constraints.

You're basically playing a game of Russian roulette with Composer, and it will eventually hurt you. Then you might blame the tool for disappointing you.

If you continue to be careless, please at least rely on the latest development version, usually labeled dev-master.

The hard-coded branch name

So you are now using dev-master. The problem is that the code pointed to by dev-master may change. At least, what you get is always an unstable package (unstable according to the stability flag represented by composer). The bigger problem, however, is that the meaning of dev-master can change at any time.

For example, now it represents the latest 1.0 development version. When developers say they are going to start developing version 1.1, the branch name dev-master no longer points to the 1.0 branch, it starts pointing to the latest 1.1 development branch.

Unless you follow the development of this library closely, it won't be until you run the composer update command that the problem will show up to you and ruin your day. Therefore, directly referencing the branch's name is not a sustainable solution. Fortunately, composer can help when it comes to aliases.

Branch Alias

The branch alias is an attribute that package maintainers can put into their composer.json to allow these branches Names map to versions.

Branch names like 1.0, 2.1, etc. are not necessary, Composer has already processed these.

But a branch name like master will produce a version named dev-master , and you must give it an alias. Composer The documentation has a good article about aliases, which explains how to define branch aliases:

{
    "extra": {
        "branch-alias": {
            "dev-master": "1.0.x-dev"
        }
    }
}

dev-master The version will be mapped to a On the alias of 1.0.x-dev ,

this basically means you can require the package with a 1.0.*@dev constraint. The advantage of this is that the meaning of 1.0 will be defined and will not change. It will also make switching to stable releases easier.

Warnings for branch aliases require package maintainers to put them in. If you are using libraries that don't have branch aliases, send them a pull request adding the extra section above to their composer.json.

Stable version

1.0.*@dev This constraint is already very good. But the problem is that so far, there is still no stable version. There's nothing wrong with your code other than the fact that you're still running an unstable version.

But if other people's projects depend on your package, then your users need to explicitly use the @dev flag to allow Composer to install unstable versions, or simply reduce the project's minimum-stability Level , which means they will get unstable versions of all dependent packages.

The best way to avoid instability in the development version is to label it with a release tag (referring to releasing a stable version). If you are using a library that is not tagged release , alert its maintainer until it is tagged. Do it now!

As a member of the Composer community, we must be responsible. We must release stable versions and should maintain a CHANGELOG (change log). It won’t be easy, but it will make a huge difference to the entire ecosystem. Remember to label things truthfully and semantically.

When you release a stable version, you can remove the @dev identifier and change your constraints to 1.0.*.

The next major version

If every release node of the package you depend on adheres to the rules of semantic versioning and is strictly backwards compatible, then you You can gradually increase the constraints.

Now 1.0.* The version has some potential compatibility issues and a 1.1 version will be released soon. If your constraint is 1.0 , but someone else needs the new features of the 1.1 version (remember backwards compatibility?), they can't install the 1.1 version. So you need to rewrite your constraints, like: 1.*.

Great, unless you start relying on the new features of the 1.1 version, you don't have to modify the constraint and it will still match 1.0 This version has no new features .

Next, you modify the constraints to >=1.1,<2.0 , but this way of writing is more troublesome. Using the tilde operator allows you to express the above expression in a concise way: ~1.1. This means any 1.* version above 1.1. Now you know that semantic versions are encouraged to use the tilde operator and maximize package compatibility.

TLDR

Use branch-alias.

Label publishing to make publishing more reliable and semantic.

Use the ~ operator.

The above is the detailed content of Composer version constraints you must know. For more information, please follow other related articles on the PHP Chinese website!