public-mirrors
/
composer
mirror of https://github.com/composer/composer
1
0
Fork 0
Code

Updated basic usage and versions pages to clarify how versioning and package resolution works (refs #6088)

pull/6097/head
Kael Shipman 2017-01-20 11:49:29 -06:00
parent 7a9f24b913
commit a0d2934946
2 changed files with 150 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
doc/01-basic-usage.md
View File

@ -36,9 +36,10 @@ As you can see, [`require`](04-schema.md#require) takes an object that maps
It uses this information to search for the right set of files in package It uses this information to search for the right set of files in package
"repositories" that you register using the [`repositories`](04-schema.md#repositories) "repositories" that you register using the [`repositories`](04-schema.md#repositories)
key, or in Packagist, the default package respository. In the above example, key, or in Packagist, the default package respository. In the above example,
since no other repository is registered in the file, it is assumed that the since no other repository has been registered in the `composer.json` file, it is
`monolog/monolog` package is registered on Packagist. (See more about Packagist assumed that the `monolog/monolog` package is registered on Packagist. (See more
[below](#packagist), or read more about repositories [here](05-repositories.md). about Packagist [below](#packagist), or read more about repositories
[here](05-repositories.md).
### Package Names ### Package Names
@ -49,15 +50,15 @@ One might be named `igorw/json` while the other might be `seldaek/json`.
Read more about publishing packages and package naming [here](02-libraries.md) Read more about publishing packages and package naming [here](02-libraries.md)
### Package Versions ### Package Version Constraints
In the previous example we were requiring version In our example, we're requesting the Monolog package with the version constraint
[`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of [`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*).
Monolog. This means any version in the `1.0` development branch. It is the This means any version in the `1.0` development branch, or any version that is
equivalent of saying versions that match `>=1.0 <1.1`. greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`).
Version constraints can be specified in several ways; please read Version can be a little confusing in Composer, and version constraints can be specified
[versions](articles/versions.md) for more in-depth information on this topic. in several ways. Please read [versions](articles/versions.md) for more in-depth information.
> **How does Composer download the right files?** When you specify a dependency in > **How does Composer download the right files?** When you specify a dependency in
> `composer.json`, Composer, first takes the name of the package that you've requested > `composer.json`, Composer, first takes the name of the package that you've requested
@ -67,15 +68,14 @@ Version constraints can be specified in several ways; please read
> repositories you've specified, it falls back to Packagist (more [below](#packagist)). > repositories you've specified, it falls back to Packagist (more [below](#packagist)).
> >
> When it finds the right package, either in Packagist or in a repo you've specified, > When it finds the right package, either in Packagist or in a repo you've specified,
> it then uses the versioning features of the package's VCS to attempt to find the > it then uses the versioning features of the package's VCS (i.e., branches and tags)
> best match for the version you've specified. Read more on package resolution > to attempt to find the best match for the version you've specified. Be sure to read
> [here](articles/versions.md). > about versions and package resolution in the [versions article](articles/versions.md).
> **Note:** If you're trying to require a package but Composer throws an error > **Note:** If you're trying to require a package but Composer throws an error
> regarding package stability, the version you've specified may not meet the > regarding package stability, the version you've specified may not meet your
> default minimum stability requirements that Composer establishes. By default > default minimum stability requirements. By default only stable releases are taken
> only stable releases are taken into consideration when searching for package > into consideration when searching for valid package versions in your VCS.
> versions in your VCS.
> >
> You might run into this if you're trying to require dev, alpha, beta, or RC > You might run into this if you're trying to require dev, alpha, beta, or RC
> versions of a package. Read more about stability flags and the `minimum-stability` > versions of a package. Read more about stability flags and the `minimum-stability`
@ -90,32 +90,46 @@ To install the defined dependencies for your project, just run the
php composer.phar install php composer.phar install
``` ```
This will find the latest version of `monolog/monolog` that matches the When you run this command, one of two things may happen:
supplied version constraint and download it into the `vendor` directory.
It's a convention to put third party code into a directory named `vendor`. ### Installing Without `composer.lock`
In the case of Monolog it will put it into `vendor/monolog/monolog`.
If you've never run the command before and there is also no `composer.lock` file present,
Composer simply resolves all dependencies listed in your `composer.json` file and downloads
the latest version of their files into the `vendor` directory in your project. (The `vendor`
directory is the conventional location for all third-party code in a project). In our
example from above, you would end up with the Monolog source files in
`vendor/monolog/monolog/`. If Monolog listed any dependencies, those would also be in
folders under `vendor/`.
> **Tip:** If you are using git for your project, you probably want to add > **Tip:** If you are using git for your project, you probably want to add
> `vendor` in your `.gitignore`. You really don't want to add all of that > `vendor` in your `.gitignore`. You really don't want to add all of that
> code to your repository. > third-party code to your versioned repository.
You will notice the [`install`](03-cli.md#install) command also created a When Composer has finished installing, it writes all of the packages and the exact versions
`composer.lock` file. of them that it downloaded to the `composer.lock` file, locking the project to those specific
versions.
## `composer.lock` - The Lock File ### Installing With `composer.lock`
After installing the dependencies, Composer writes the list of the exact This brings us to the second scenario. If there's already a `composer.lock` file as well as a
versions it installed into a `composer.lock` file. This locks the project `composer.json` file when you run `composer install`, it means that either you've run the
to those specific versions. `install` command before, or someone else on the project has run the `install` command and
committed the `composer.lock` file to the project (which is good).
**Commit your application's `composer.lock` (along with `composer.json`) Either way, running `install` when a `composer.lock` file is present simply resolves and installs
into version control.** all dependencies that you've listed in `composer.json`, but it uses the version constraints
that it finds in `composer.lock` to ensure that the package versions are consistent for everyone
working on your project. The result is that you have all dependencies requested by your
`composer.json` file, but that they may not all be at the very latest available versions (since
some of the dependencies listed in the `composer.lock` file may have released new versions since
the file was created). This is by design, as it ensures that your project never breaks because of
unexpected changes in dependencies.
This is important because the [`install`](03-cli.md#install) command checks ### Commit Your `composer.lock` File to Version Control
if a lock file is present, and if it is, it downloads the versions specified
there (regardless of what `composer.json` says).
This means that anyone who sets up the project will download the exact same Committing this file to VC is important because it will cause anyone who sets
up the project to use the exact same
versions of the dependencies that you're using. Your CI server, production versions of the dependencies that you're using. Your CI server, production
machines, other developers in your team, everything and everyone runs on the machines, other developers in your team, everything and everyone runs on the
same dependencies, which mitigates the potential for bugs affecting only some same dependencies, which mitigates the potential for bugs affecting only some
@ -124,14 +138,13 @@ reinstalling the project you can feel confident the dependencies installed are
still working even if your dependencies released many new versions since then. still working even if your dependencies released many new versions since then.
(See note below about using the `update` command.) (See note below about using the `update` command.)
If no `composer.lock` file exists, Composer will read the dependencies and ## Updating Dependencies to their Latest Versions
versions from `composer.json` and create the lock file after executing.
This means that if any of the dependencies get a new version, you won't get the As mentioned above, the `composer.lock` file prevents you from automatically getting
updates automatically. To update to the new version, use the the latest versions of your dependencies. To update to the latest versions, use the
[`update`](03-cli.md#update) command. This will fetch the latest matching [`update`](03-cli.md#update) command. This will fetch the latest matching
versions (according to your `composer.json` file) and also update the lock file versions (according to your `composer.json` file) and also update the lock file
with the new version. with the new version. (This is equivalent to simply deleting the `composer.lock` file.)
```sh ```sh
php composer.phar update php composer.phar update
@ -166,18 +179,12 @@ but it enables discovery and adoption by other developers more quickly.
## Autoloading ## Autoloading
For libraries that specify autoload information, Composer generates a For libraries that specify autoload information, Composer generates a
`vendor/autoload.php` file. You can simply include this file and you will get `vendor/autoload.php` file. You can simply include this file and start
autoloading for free. using the classes that those libraries provide without any extra work:
```php ```php
require __DIR__ . '/vendor/autoload.php'; require __DIR__ . '/vendor/autoload.php';
```
This makes it really easy to use third party code. For example: If your project
depends on Monolog, you can just start using classes from it, and they will be
autoloaded.
```php
$log = new Monolog\Logger('name'); $log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->addWarning('Foo'); $log->addWarning('Foo');

101
doc/articles/versions.md
View File

@ -1,10 +1,100 @@
<!-- <!--
tagline: Version constraints explained. tagline: Versions explained.
--> -->
# Versions # Versions
## Basic Constraints ## Composer Versions vs VCS Versions
Because Composer is heavily geared toward utilizing version control systems
like git, the term "version" can be a little ambiguous. In the sense of a
version control system, a "version" is a specific set of files that contain
specific data. In git terminology, this is a "ref", or a specific commit,
which may be represented by a branch HEAD or a tag. When you check out that
version in your VCS -- for example, tag `v1.1` or commit `e35fa0d` --, you're
asking for a single, known set of files, and you always get the same files back.
In Composer, what's usually referred to casually as a version -- that is,
the string that follows the package name in a require line (e.g., `~1.1` or
`1.2.*`) -- is actually more specifically a version constraint. Composer
uses version constraints to figure out which refs in a VCS it should be
checking out.
### Tags vs Branches
Normally, Composer deals with tags (as opposed to branches -- if you don't
know what this means, read up on
[version control systems](https://en.wikipedia.org/wiki/Version_control#Common_vocabulary)).
When referencing a tag, it may reference a specific tag (e.g., `1.1`) or it
may reference a valid range of tags (e.g., `>=1.1 <2.0`). Furthermore, you
can add "stability specifiers" to let Composer know that you are or aren't
interested in certain tags, like alpha releases, beta releases, or release
candidates, even if they're technically within the numeric range specified
by the version constraint (these releases are usually considered "unstable",
hence the term "stability specifier").
If you want Composer to check out a branch instead of a tag, you use the
special syntax described [here](02-libraries.md#branches). In short, if
you're checking out a branch, it's assumed that you want to *work* on the
branch and Composer simply clones the repo into the correct place in your
`vendor` directory. (For tags, it just copies the right files without actually
cloning the repo.) This can be very convenient for libraries under development,
as you can make changes to the dependency files your project is actually using
and still commit them to their respective repos as patches or other updates.
Let's look at an example. Suppose you've published a library whose git repo
looks like this:
```sh
$ git branch
$
$ v1
$ v2
$ my-feature
$ nother-feature
$
$ git tag
$
$ v1.0
$ v1.0.1
$ v1.0.2
$ v1.1-BETA
$ v1.1-RC1
$ v1.1-RC2
$ v1.1
$ v1.1.1
$ v2.0-BETA
$ v2.0-RC1
$ v2.0
$ v2.0.1
$ v2.0.2
```
Now assume you've got a project that depends on this library and you've been
running `composer update` in that project since the `v1.0` release. If you
specified `~1.0` in Composer (the tilde modifier, among others, is detailed
below), and you don't add a [`minimum-stability`](04-schema.md#minimum-stability)
key elsewhere in the file, then Composer will default to "stable" as a minimum
stability setting and you will receive only the `v1.0`, `v1.0.1`, `v1.0.2`,
`v1.1` and `v1.1.1` tags as the tags are created in your VCS. If you set the
`minimum-stability` key to `RC`, you would receive the aforementioned tags as
they're released, plus the `v1.1-RC1` and `v1.1-RC2` tags, but not `v1.1-BETA`.
(You can see the available stability constraints in order on the
[schema page](04-schema.md#minimum-stability).
The final important detail here is how branches are handled. In git, a branch
simply represents a series of commits, with the current "HEAD" of the branch
pointing at the most recent in the chain. A tag is a specific commit, independent
of branch. By default composer checks out the tag that best matches the version
constraint you've specified. However, if you specify the version constraint as
"v1-dev" (or sometimes "dev-my-branch" -- see the [libraries page](02-libraries.md#branches)
for syntax details), then Composer will clone the repo into your `vendor`
directory, checking out the `v1` branch.
## Basic Version Constraints
Now that you have an idea of how Composer sees versions, let's talk about how
to specify version constraints for your project dependencies.
### Exact ### Exact
@ -87,7 +177,7 @@ library code.
Example: `^1.2.3` Example: `^1.2.3`
## Stability ## Stability Constraints
If you are using a constraint that does not explicitly define a stability, If you are using a constraint that does not explicitly define a stability,
Composer will default internally to `-dev` or `-stable`, depending on the Composer will default internally to `-dev` or `-stable`, depending on the
@ -113,8 +203,9 @@ Examples:
To allow various stabilities without enforcing them at the constraint level To allow various stabilities without enforcing them at the constraint level
however, you may use [stability-flags](../04-schema.md#package-links) like however, you may use [stability-flags](../04-schema.md#package-links) like
`@<stability>` (e.g. `@dev`) to let composer know that a given package `@<stability>` (e.g. `@dev`) to let composer know that a given package
can be installed in a different stability than your default can be installed in a different stability than your default minimum-stability
[minimum-stability](../04-schema.md#minimum-stability) setting. setting. All available stability flags are listed on the minimum-stability
section of the [schema page](../04-schema.md#minimum-stability).
## Test version constraints ## Test version constraints