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

reworking basic usage, added versions article

pull/4172/head
Rob Bast 2015-06-22 16:24:59 +02:00
parent eb98613672
commit 10b813fc40
3 changed files with 171 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/00-intro.md
View File

@ -77,15 +77,16 @@ The installer will just check a few PHP settings and then download
is a PHAR (PHP archive), which is an archive format for PHP which can be run on is a PHAR (PHP archive), which is an archive format for PHP which can be run on
the command line, amongst other things. the command line, amongst other things.
Now just run `php composer.phar` in order to run Composer.
You can install Composer to a specific directory by using the `--install-dir` You can install Composer to a specific directory by using the `--install-dir`
option and providing a target directory (it can be an absolute or relative option and additionally (re)name it as well using the `--filename` option:
path):
```sh ```sh
curl -sS https://getcomposer.org/installer | php -- --install-dir=bin curl -sS https://getcomposer.org/installer | php -- --install-dir=bin --filename=composer
``` ```
Now just run `php composer.phar` in order to run Composer. Now just run `php bin/composer` in order to run Composer.
#### Globally #### Globally

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

@ -1,8 +1,12 @@
# Basic usage # Basic usage
## Installing ## Introduction
If you have not yet installed Composer, refer to the [Intro](00-intro.md) chapter. If you have not yet installed Composer, refer to the [Intro](00-intro.md)
chapter. For our basic usage introduction, we will be installing
`monolog/monolog`, a logging library. Note that for the sake of simplicity,
this introduction will assume you have performed a [local](00-intro.md#locally)
install of Composer.
## `composer.json`: Project Setup ## `composer.json`: Project Setup
@ -10,9 +14,6 @@ To start using Composer in your project, all you need is a `composer.json`
file. This file describes the dependencies of your project and may contain file. This file describes the dependencies of your project and may contain
other metadata as well. other metadata as well.
The [JSON format](http://json.org/) is quite easy to write. It allows you to
define nested structures.
### The `require` Key ### The `require` Key
The first (and often only) thing you specify in `composer.json` is the The first (and often only) thing you specify in `composer.json` is the
@ -27,15 +28,15 @@ depends on.
} }
``` ```
As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`) As you can see, `require` takes an object that maps **package names**
to **package versions** (e.g. `1.0.*`). (e.g. `monolog/monolog`) to **version constraints** (e.g. `1.0.*`).
### Package Names ### Package Names
The package name consists of a vendor name and the project's name. Often these The package name consists of a vendor name and the project's name. Often these
will be identical - the vendor name just exists to prevent naming clashes. It allows will be identical - the vendor name just exists to prevent naming clashes. It
two different people to create a library named `json`, which would then just be allows two different people to create a library named `json`, which would then
named `igorw/json` and `seldaek/json`. just be named `igorw/json` and `seldaek/json`.
Here we are requiring `monolog/monolog`, so the vendor name is the same as the Here we are requiring `monolog/monolog`, so the vendor name is the same as the
project's name. For projects with a unique name this is recommended. It also project's name. For projects with a unique name this is recommended. It also
@ -45,53 +46,20 @@ smaller decoupled parts.
### Package Versions ### Package Versions
In the previous example we were requiring version [`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of monolog. This In the previous example we were requiring version
means any version in the `1.0` development branch. It would match `1.0.0`, [`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of
`1.0.2` or `1.0.20`. monolog. This means any version in the `1.0` development branch. It is the
equivalent of saying versions that match `>=1.0 <1.1`.
Version constraints can be specified in a few different ways. Version constraints can be specified in several ways, read
[versions](articles/versions.md) for more in-depth information on this topic.
Name | Example | Description
-------------- | ------------------------------------------------------------------------ | -----------
Exact version | `1.0.2` | You can specify the exact version of a package.
Range | `>=1.0` `>=1.0 <2.0` <code>&gt;=1.0 &lt;1.1 &#124;&#124; &gt;=1.2</code> | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`. <br />You can define multiple ranges. Ranges separated by a space (<code> </code>) or comma (`,`) will be treated as a **logical AND**. A double pipe (<code>&#124;&#124;</code>) will be treated as a **logical OR**. AND has higher precedence than OR.
Hyphen Range | `1.0 - 2.0` | Inclusive set of versions. Partial versions on the right include are completed with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the `2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to `>=1.0.0 <=2.1.0`.
Wildcard | `1.0.*` | You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0 <1.1`.
Tilde Operator | `~1.2` | Very useful for projects that follow semantic versioning. `~1.2` is equivalent to `>=1.2 <2.0`. For more details, read the next section below.
Caret Operator | `^1.2.3` | Very useful for projects that follow semantic versioning. `^1.2.3` is equivalent to `>=1.2.3 <2.0`. For more details, read the next section below.
### Next Significant Release (Tilde and Caret Operators)
The `~` operator is best explained by example: `~1.2` is equivalent to
`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see
it is mostly useful for projects respecting [semantic
versioning](http://semver.org/). A common usage would be to mark the minimum
minor version you depend on, like `~1.2` (which allows anything up to, but not
including, 2.0). Since in theory there should be no backwards compatibility
breaks until 2.0, that works well. Another way of looking at it is that using
`~` specifies a minimum version, but allows the last digit specified to go up.
The `^` operator behaves very similarly but it sticks closer to semantic
versioning, and will always allow non-breaking updates. For example `^1.2.3`
is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should
break backwards compatibility. For pre-1.0 versions it also acts with safety
in mind and treats `^0.3` as `>=0.3.0 <0.4.0`
> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint
> like `~1.2` would not install it. As said above `~1.2` only means the `.2`
> can change but the `1.` part is fixed.
> **Note:** The `~` operator has an exception on its behavior for the major
> release number. This means for example that `~1` is the same as `~1.0` as
> it will not allow the major number to increase trying to keep backwards
> compatibility.
### Stability ### Stability
By default only stable releases are taken into consideration. If you would like By default only stable releases are taken into consideration. If you would
to also get RC, beta, alpha or dev versions of your dependencies you can do like to also get RC, beta, alpha or dev versions of your dependencies you can
so using [stability flags](04-schema.md#package-links). To change that for all do so using [stability flags](04-schema.md#package-links). To change that for
packages instead of doing per dependency you can also use the all packages instead of doing per dependency you can also use the
[minimum-stability](04-schema.md#minimum-stability) setting. [minimum-stability](04-schema.md#minimum-stability) setting.
If you are using range comparisons when selecting non-stable packages, and you If you are using range comparisons when selecting non-stable packages, and you
@ -119,15 +87,15 @@ the `minimum-stability` setting and each package's stability flags.
### Test version constraints ### Test version constraints
You can test version constraints using [semver.mwl.be](http://semver.mwl.be). Fill in You can test version constraints using [semver.mwl.be](http://semver.mwl.be).
a package name and it will autofill the default version constraint which Composer would add Fill in a package name and it will autofill the default version constraint
to your `composer.json` file. You can adjust the version constraint and the tool will highlight which Composer would add to your `composer.json` file. You can adjust the
all releases that match. version constraint and the tool will highlight all releases that match.
## Installing Dependencies ## Installing Dependencies
To fetch the defined dependencies into your local project, just run the To install the defined dependencies for your project, just run the
`install` command of `composer.phar`. `install` command.
```sh ```sh
php composer.phar install php composer.phar install
@ -139,11 +107,10 @@ It's a convention to put third party code into a directory named `vendor`.
In case of monolog it will put it into `vendor/monolog/monolog`. In case of monolog it will put it into `vendor/monolog/monolog`.
> **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` into 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. > code to your repository.
Another thing that the `install` command does is it adds a `composer.lock` You will notice the `install` command also created a `composer.lock` file.
file into your project root.
## `composer.lock` - The Lock File ## `composer.lock` - The Lock File
@ -151,34 +118,35 @@ After installing the dependencies, Composer writes the list of the exact
versions it installed into a `composer.lock` file. This locks the project versions it installed into a `composer.lock` file. This locks the project
to those specific versions. to those specific versions.
**Commit your application's `composer.lock` (along with `composer.json`) into version control.** **Commit your application's `composer.lock` (along with `composer.json`)
into version control.**
This is important because the `install` command checks if a lock file is present, This is important because the `install` command checks if a lock file is
and if it is, it downloads the versions specified there (regardless of what `composer.json` present, and if it is, it downloads the versions specified there (regardless
says). of what `composer.json` says).
This means that anyone who sets up the project will download the exact This means that anyone who sets up the project will download the exact same
same version of the dependencies. Your CI server, production machines, other version of the dependencies. Your CI server, production machines, other
developers in your team, everything and everyone runs on the same dependencies, which developers in your team, everything and everyone runs on the same dependencies,
mitigates the potential for bugs affecting only some parts of the deployments. Even if you which mitigates the potential for bugs affecting only some parts of the
develop alone, in six months when reinstalling the project you can feel confident the deployments. Even if you develop alone, in six months when reinstalling the
dependencies installed are still working even if your dependencies released project you can feel confident the dependencies installed are still working even
many new versions since then. if your dependencies released many new versions since then.
If no `composer.lock` file exists, Composer will read the dependencies and If no `composer.lock` file exists, Composer will read the dependencies and
versions from `composer.json` and create the lock file after executing the `update` or the `install` versions from `composer.json` and create the lock file after executing the
command. `update` or the `install` command.
This means that if any of the dependencies get a new version, you won't get the updates This means that if any of the dependencies get a new version, you won't get the
automatically. To update to the new version, use the `update` command. This will fetch updates automatically. To update to the new version, use the `update` command.
the latest matching versions (according to your `composer.json` file) and also update This will fetch the latest matching versions (according to your `composer.json`
the lock file with the new version. file) and also update the lock file with the new version.
```sh ```sh
php composer.phar update php composer.phar update
``` ```
> **Note:** Composer will display a Warning when executing an `install` command if > **Note:** Composer will display a Warning when executing an `install` command
`composer.lock` and `composer.json` are not synchronized. > if `composer.lock` and `composer.json` are not synchronized.
If you only want to install or update one dependency, you can whitelist them: If you only want to install or update one dependency, you can whitelist them:
@ -186,37 +154,36 @@ If you only want to install or update one dependency, you can whitelist them:
php composer.phar update monolog/monolog [...] php composer.phar update monolog/monolog [...]
``` ```
> **Note:** For libraries it is not necessarily recommended to commit the lock file, > **Note:** For libraries it is not necessarily recommended to commit the lock
> see also: [Libraries - Lock file](02-libraries.md#lock-file). > file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
## Packagist ## Packagist
[Packagist](https://packagist.org/) is the main Composer repository. A Composer [Packagist](https://packagist.org/) is the main Composer repository. A Composer
repository is basically a package source: a place where you can get packages repository is basically a package source: a place where you can get packages
from. Packagist aims to be the central repository that everybody uses. This from. Packagist aims to be the central repository that everybody uses. This
means that you can automatically `require` any package that is available means that you can automatically `require` any package that is available there.
there.
If you go to the [packagist website](https://packagist.org/) (packagist.org), If you go to the [packagist website](https://packagist.org/) (packagist.org),
you can browse and search for packages. you can browse and search for packages.
Any open source project using Composer should publish their packages on Any open source project using Composer should publish their packages on
packagist. A library doesn't need to be on packagist to be used by Composer, packagist. A library doesn't need to be on packagist to be used by Composer, but
but it makes life quite a bit simpler. it makes life quite a bit simpler.
## 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 `vendor/autoload.php` file. You can simply include this file and you will get
will get autoloading for free. autoloading for free.
```php ```php
require 'vendor/autoload.php'; require 'vendor/autoload.php';
``` ```
This makes it really easy to use third party code. For example: If your This makes it really easy to use third party code. For example: If your project
project depends on monolog, you can just start using classes from it, and they depends on monolog, you can just start using classes from it, and they will be
will be autoloaded. autoloaded.
```php ```php
$log = new Monolog\Logger('name'); $log = new Monolog\Logger('name');
@ -243,8 +210,8 @@ You define a mapping from namespaces to directories. The `src` directory would
be in your project root, on the same level as `vendor` directory is. An example be in your project root, on the same level as `vendor` directory is. An example
filename would be `src/Foo.php` containing an `Acme\Foo` class. filename would be `src/Foo.php` containing an `Acme\Foo` class.
After adding the `autoload` field, you have to re-run `dump-autoload` to re-generate After adding the `autoload` field, you have to re-run `dump-autoload` to
the `vendor/autoload.php` file. re-generate the `vendor/autoload.php` file.
Including that file will also return the autoloader instance, so you can store Including that file will also return the autoloader instance, so you can store
the return value of the include call in a variable and add more namespaces. the return value of the include call in a variable and add more namespaces.
@ -256,11 +223,11 @@ $loader->add('Acme\\Test\\', __DIR__);
``` ```
In addition to PSR-4 autoloading, classmap is also supported. This allows In addition to PSR-4 autoloading, classmap is also supported. This allows
classes to be autoloaded even if they do not conform to PSR-4. See the classes to be autoloaded even if they do not conform to PSR-4. See the [autoload
[autoload reference](04-schema.md#autoload) for more details. reference](04-schema.md#autoload) for more details.
> **Note:** Composer provides its own autoloader. If you don't want to use > **Note:** Composer provides its own autoloader. If you don't want to use that
that one, you can just include `vendor/composer/autoload_*.php` files, > one, you can just include `vendor/composer/autoload_*.php` files, which return
which return associative arrays allowing you to configure your own autoloader. > associative arrays allowing you to configure your own autoloader.
&larr; [Intro](00-intro.md) | [Libraries](02-libraries.md) &rarr; &larr; [Intro](00-intro.md) | [Libraries](02-libraries.md) &rarr;

99
doc/articles/versions.md Normal file
View File

@ -0,0 +1,99 @@
<!--
tagline: The multitude of possibilities that are called version constraints.
-->
# Versions
## Basic Constraints
### Exact
You can specify the exact version of a package. This will tell Composer to
install this version and this version only. If other dependencies require
a different version, the solver will ultimately fail and abort any install
or update procedures.
Example: `1.0.2`
### Range
By using comparison operators you can specify ranges of valid versions. Valid
operators are `>`, `>=`, `<`, `<=`, `!=`. <br />You can define multiple ranges.
Ranges separated by a space (<code> </code>) or comma (`,`) will be treated as
a **logical AND**. A double pipe (<code>&#124;&#124;</code>) will be treated as
a **logical OR**. AND has higher precedence than OR.
Example: `>=1.0` `>=1.0 <2.0` `>=1.0 <1.1 || >=1.2`
### Range (Hyphen)
Inclusive set of versions. Partial versions on the right include are completed
with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the
`2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to
`>=1.0.0 <=2.1.0`.
Example: `1.0 - 2.0`
### Wildcard
You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of
`>=1.0 <1.1`.
Example: `1.0.*`
## Next Significant Release Operators
### Tilde
The `~` operator is best explained by example: `~1.2` is equivalent to
`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see
it is mostly useful for projects respecting [semantic
versioning](http://semver.org/). A common usage would be to mark the minimum
minor version you depend on, like `~1.2` (which allows anything up to, but not
including, 2.0). Since in theory there should be no backwards compatibility
breaks until 2.0, that works well. Another way of looking at it is that using
`~` specifies a minimum version, but allows the last digit specified to go up.
Example: `~1.2`
> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint
> like `~1.2` would not install it. As said above `~1.2` only means the `.2`
> can change but the `1.` part is fixed.
> **Note:** The `~` operator has an exception on its behavior for the major
> release number. This means for example that `~1` is the same as `~1.0` as
> it will not allow the major number to increase trying to keep backwards
> compatibility.
### Caret
The `^` operator behaves very similarly but it sticks closer to semantic
versioning, and will always allow non-breaking updates. For example `^1.2.3`
is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should
break backwards compatibility. For pre-1.0 versions it also acts with safety
in mind and treats `^0.3` as `>=0.3.0 <0.4.0`.
Example: `^1.2.3`
## Stability
If you are using a constraint that does not explicitly define a stability,
Composer will default interally to `-dev` or `-stable`, depending on the
operator(s) used. This happens transparently.
If you wish to explicitly consider only the stable release in the comparison,
add the suffix `-stable`.
Examples:
Constraint | Internally
----------------------------------------------
`1.2.3` | `=1.2.3.0-stable`
`>1.2` | `>1.2.0.0-stable`
`>=1.2` | `>=1.2.0.0-dev`
`>=1.2-stable` | `>=1.2.0.0-stable`
`<1.3` | `<1.3.0.0-dev`
`<=1.3` | `<=1.3.0.0-stable`
`1 - 2` | `>=1.0.0.0-dev <3.0.0.0-dev`
`~1.3` | `>=1.3.0.0-dev <2.0.0.0-dev`
`1.4.*` | `>=1.4.0.0-dev <1.5.0.0-dev`