Version numbers with caret and tilde in composer.json

From the documentation you linked:

~1.2 is equivalent to >=1.2 <2.0.0, while ~1.2.3 is equivalent to >=1.2.3 <1.3.0

^1.2.3 is equivalent to >=1.2.3 <2.0.0

The tilde depends on how many digits in the version number are given. The last digit given can vary.

The caret is almost always the better choice because it acts similarly enough to be a direct replacement (~1.2 is the same as ^1.2 or ^1.2.0), but offer better flexibility when addressing non-zero patch versions (^1.2.3 is NOT the same as ~1.2.3, because the tilde version only allows updates below 1.3.0, the caret allows updates below 2.0.0).

The only reason why one would use the tilde as version requirement is if you have to deal with “zero” versions that get compatible updates. The tilde does not differ between ~0.1 and ~1.1, in both cases it will allow updates up to the next major version number (below 1.0 or 2.0 respectively). The caret operator will disallow minor updates in this range: ^0.1 does not allow updates to 0.2, because in semantic versioning a zero-dot-something version may introduce incompatible changes when going to zero-dot-something+1.

Summary:

• Prefer the caret operator – it’s the easiest way to force minimum patch versions.
• Prefer versions above 0.x (start with 1.0.0) and use semantic versioning for your own code.
• For the development phase, you can use alpha, beta or rc stability together with the intended final version, i.e. 1.0.0-alpha1 would be a rough outline of what 1.0.0 will be in the future.