sync for new version
This commit is contained in:
parent
f97aae1819
commit
e16fcb9e19
|
@ -1,54 +1,41 @@
|
||||||
# Introduction
|
# Introduction
|
||||||
|
|
||||||
Composer is a tool for dependency management in PHP. It allows you to declare
|
Composer is a tool for dependency management in PHP. It allows you to declare
|
||||||
the dependent libraries your project needs and it will install them in your
|
the libraries your project depends on and it will manage (install/update) them
|
||||||
project for you.
|
for you.
|
||||||
|
|
||||||
## Dependency management
|
## Dependency management
|
||||||
|
|
||||||
Composer is not a package manager. Yes, it deals with "packages" or libraries, but
|
Composer is **not** a package manager in the same sense as Yum or Apt are. Yes,
|
||||||
it manages them on a per-project basis, installing them in a directory (e.g. `vendor`)
|
it deals with "packages" or libraries, but it manages them on a per-project
|
||||||
inside your project. By default it will never install anything globally. Thus,
|
basis, installing them in a directory (e.g. `vendor`) inside your project. By
|
||||||
it is a dependency manager.
|
default it will never install anything globally. Thus, it is a dependency
|
||||||
|
manager.
|
||||||
|
|
||||||
This idea is not new and Composer is strongly inspired by node's [npm](http://npmjs.org/)
|
This idea is not new and Composer is strongly inspired by node's
|
||||||
and ruby's [bundler](http://gembundler.com/). But there has not been such a tool
|
[npm](https://npmjs.org/) and ruby's [bundler](http://bundler.io/).
|
||||||
for PHP.
|
|
||||||
|
|
||||||
The problem that Composer solves is this:
|
Suppose:
|
||||||
|
|
||||||
a) You have a project that depends on a number of libraries.
|
a) You have a project that depends on a number of libraries.
|
||||||
|
|
||||||
b) Some of those libraries depend on other libraries.
|
b) Some of those libraries depend on other libraries.
|
||||||
|
|
||||||
c) You declare the things you depend on.
|
Composer:
|
||||||
|
|
||||||
d) Composer finds out which versions of which packages need to be installed, and
|
c) Enables you to declare the libraries you depend on.
|
||||||
|
|
||||||
|
d) Finds out which versions of which packages can and need to be installed, and
|
||||||
installs them (meaning it downloads them into your project).
|
installs them (meaning it downloads them into your project).
|
||||||
|
|
||||||
## Declaring dependencies
|
See the [Basic usage](01-basic-usage.md) chapter for more details on declaring
|
||||||
|
dependencies.
|
||||||
Let's say you are creating a project, and you need a library that does logging.
|
|
||||||
You decide to use [monolog](https://github.com/Seldaek/monolog). In order to
|
|
||||||
add it to your project, all you need to do is create a `composer.json` file
|
|
||||||
which describes the project's dependencies.
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"require": {
|
|
||||||
"monolog/monolog": "1.2.*"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
We are simply stating that our project requires some `monolog/monolog` package,
|
|
||||||
any version beginning with `1.2`.
|
|
||||||
|
|
||||||
## System Requirements
|
## System Requirements
|
||||||
|
|
||||||
Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile
|
Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile
|
||||||
flags are also required, but the installer will warn you about any
|
flags are also required, but when using the installer you will be warned about
|
||||||
incompatibilities.
|
any incompatibilities.
|
||||||
|
|
||||||
To install packages from sources instead of simple zip archives, you will need
|
To install packages from sources instead of simple zip archives, you will need
|
||||||
git, svn or hg depending on how the package is version-controlled.
|
git, svn or hg depending on how the package is version-controlled.
|
||||||
|
@ -56,14 +43,23 @@ git, svn or hg depending on how the package is version-controlled.
|
||||||
Composer is multi-platform and we strive to make it run equally well on Windows,
|
Composer is multi-platform and we strive to make it run equally well on Windows,
|
||||||
Linux and OSX.
|
Linux and OSX.
|
||||||
|
|
||||||
## Installation - *nix
|
## Installation - Linux / Unix / OSX
|
||||||
|
|
||||||
### Downloading the Composer Executable
|
### Downloading the Composer Executable
|
||||||
|
|
||||||
|
Composer offers a convenient installer that you can execute directly from the
|
||||||
|
commandline. Feel free to [download this file](https://getcomposer.org/installer)
|
||||||
|
or review it on [GitHub](https://github.com/composer/getcomposer.org/blob/master/web/installer)
|
||||||
|
if you wish to know more about the inner workings of the installer. The source
|
||||||
|
is plain PHP.
|
||||||
|
|
||||||
|
There are in short, two ways to install Composer. Locally as part of your
|
||||||
|
project, or globally as a system wide executable.
|
||||||
|
|
||||||
#### Locally
|
#### Locally
|
||||||
|
|
||||||
To actually get Composer, we need to do two things. The first one is installing
|
Installing Composer locally is a matter of just running the installer in your
|
||||||
Composer (again, this means downloading it into your project):
|
project directory:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
curl -sS https://getcomposer.org/installer | php
|
curl -sS https://getcomposer.org/installer | php
|
||||||
|
@ -76,69 +72,81 @@ curl -sS https://getcomposer.org/installer | php
|
||||||
php -r "readfile('https://getcomposer.org/installer');" | php
|
php -r "readfile('https://getcomposer.org/installer');" | php
|
||||||
```
|
```
|
||||||
|
|
||||||
This will just check a few PHP settings and then download `composer.phar` to
|
The installer will just check a few PHP settings and then download
|
||||||
your working directory. This file is the Composer binary. It is a PHAR (PHP
|
`composer.phar` to your working directory. This file is the Composer binary. It
|
||||||
archive), which is an archive format for PHP which can be run on the command
|
is a PHAR (PHP archive), which is an archive format for PHP which can be run on
|
||||||
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 path):
|
option and additionally (re)name it as well using the `--filename` option:
|
||||||
|
|
||||||
```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 bin/composer` in order to run Composer.
|
||||||
|
|
||||||
#### Globally
|
#### Globally
|
||||||
|
|
||||||
You can place this file anywhere you wish. If you put it in your `PATH`,
|
You can place the Composer PHAR anywhere you wish. If you put it in a directory
|
||||||
you can access it globally. On unixy systems you can even make it
|
that is part of your `PATH`, you can access it globally. On unixy systems you
|
||||||
executable and invoke it without `php`.
|
can even make it executable and invoke it without directly using the `php`
|
||||||
|
interpreter.
|
||||||
|
|
||||||
You can run these commands to easily access `composer` from anywhere on your system:
|
Run these commands to globally install `composer` on your system:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
curl -sS https://getcomposer.org/installer | php
|
curl -sS https://getcomposer.org/installer | php
|
||||||
mv composer.phar /usr/local/bin/composer
|
mv composer.phar /usr/local/bin/composer
|
||||||
```
|
```
|
||||||
|
|
||||||
> **Note:** If the above fails due to permissions, run the `mv` line
|
> **Note:** If the above fails due to permissions, run the `mv` line again
|
||||||
> again with sudo.
|
> with sudo.
|
||||||
|
|
||||||
Then, just run `composer` in order to run Composer instead of `php composer.phar`.
|
A quick copy-paste version including sudo:
|
||||||
|
|
||||||
#### Globally (on OSX via homebrew)
|
|
||||||
|
|
||||||
Composer is part of the homebrew-php project.
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
brew update
|
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
|
||||||
brew tap josegonzalez/homebrew-php
|
|
||||||
brew tap homebrew/versions
|
|
||||||
brew install php55-intl
|
|
||||||
brew install josegonzalez/php/composer
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> **Note:** On some versions of OSX the `/usr` directory does not exist by
|
||||||
|
> default. If you receive the error "/usr/local/bin/composer: No such file or
|
||||||
|
> directory" then you must create the directory manually before proceeding:
|
||||||
|
> `mkdir -p /usr/local/bin`.
|
||||||
|
|
||||||
|
> **Note:** For information on changing your PATH, please read the
|
||||||
|
> [Wikipedia article](https://en.wikipedia.org/wiki/PATH_(variable)) and/or use Google.
|
||||||
|
|
||||||
|
Now just run `composer` in order to run Composer instead of `php composer.phar`.
|
||||||
|
|
||||||
## Installation - Windows
|
## Installation - Windows
|
||||||
|
|
||||||
### Using the Installer
|
### Using the Installer
|
||||||
|
|
||||||
This is the easiest way to get Composer set up on your machine.
|
This is the easiest way to get Composer set up on your machine.
|
||||||
|
|
||||||
Download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe),
|
Download and run
|
||||||
it will install the latest Composer version and set up your PATH so that you can
|
[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will
|
||||||
just call `composer` from any directory in your command line.
|
install the latest Composer version and set up your PATH so that you can just
|
||||||
|
call `composer` from any directory in your command line.
|
||||||
|
|
||||||
|
> **Note:** Close your current terminal. Test usage with a new terminal: This is
|
||||||
|
> important since the PATH only gets loaded when the terminal starts.
|
||||||
|
|
||||||
### Manual Installation
|
### Manual Installation
|
||||||
|
|
||||||
Change to a directory on your `PATH` and run the install snippet to download
|
Change to a directory on your `PATH` and run the install snippet to download
|
||||||
composer.phar:
|
`composer.phar`:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
C:\Users\username>cd C:\bin
|
C:\Users\username>cd C:\bin
|
||||||
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
|
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
|
||||||
```
|
```
|
||||||
|
|
||||||
> **Note:** If the above fails due to readfile, use the `http` url or enable php_openssl.dll in php.ini
|
> **Note:** If the above fails due to readfile, use the `http` url or enable
|
||||||
|
> php_openssl.dll in php.ini
|
||||||
|
|
||||||
Create a new `composer.bat` file alongside `composer.phar`:
|
Create a new `composer.bat` file alongside `composer.phar`:
|
||||||
|
|
||||||
|
@ -146,6 +154,8 @@ Create a new `composer.bat` file alongside `composer.phar`:
|
||||||
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
|
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Add the directory to your PATH environment variable if it isn't already.
|
||||||
|
|
||||||
Close your current terminal. Test usage with a new terminal:
|
Close your current terminal. Test usage with a new terminal:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
@ -155,38 +165,7 @@ Composer version 27d8904
|
||||||
|
|
||||||
## Using Composer
|
## Using Composer
|
||||||
|
|
||||||
We will now use Composer to install the dependencies of the project. If you
|
Now that you've installed Composer, you are ready to use it! Head on over to the
|
||||||
don't have a `composer.json` file in the current directory please skip to the
|
next chapter for a short and simple demonstration.
|
||||||
[Basic Usage](01-basic-usage.md) chapter.
|
|
||||||
|
|
||||||
To resolve and download dependencies, run the `install` command:
|
[Basic usage](01-basic-usage.md) →
|
||||||
|
|
||||||
```sh
|
|
||||||
php composer.phar install
|
|
||||||
```
|
|
||||||
|
|
||||||
If you did a global install and do not have the phar in that directory
|
|
||||||
run this instead:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
composer install
|
|
||||||
```
|
|
||||||
|
|
||||||
Following the [example above](#declaring-dependencies), this will download
|
|
||||||
monolog into the `vendor/monolog/monolog` directory.
|
|
||||||
|
|
||||||
## Autoloading
|
|
||||||
|
|
||||||
Besides downloading the library, Composer also prepares an autoload file that's
|
|
||||||
capable of autoloading all of the classes in any of the libraries that it
|
|
||||||
downloads. To use it, just add the following line to your code's bootstrap
|
|
||||||
process:
|
|
||||||
|
|
||||||
```php
|
|
||||||
require 'vendor/autoload.php';
|
|
||||||
```
|
|
||||||
|
|
||||||
Woah! Now start using monolog! To keep learning more about Composer, keep
|
|
||||||
reading the "Basic Usage" chapter.
|
|
||||||
|
|
||||||
[Basic Usage](01-basic-usage.md) →
|
|
||||||
|
|
|
@ -1,29 +1,13 @@
|
||||||
# Basic usage
|
# Basic usage
|
||||||
|
|
||||||
## Installation
|
## Introduction
|
||||||
|
|
||||||
To install Composer, you just need to download the `composer.phar` executable.
|
For our basic usage introduction, we will be installing `monolog/monolog`,
|
||||||
|
a logging library. If you have not yet installed Composer, refer to the
|
||||||
|
[Intro](00-intro.md) chapter.
|
||||||
|
|
||||||
```sh
|
> **Note:** for the sake of simplicity, this introduction will assume you
|
||||||
curl -sS https://getcomposer.org/installer | php
|
> have performed a [local](00-intro.md#locally) install of Composer.
|
||||||
```
|
|
||||||
|
|
||||||
For the details, see the [Introduction](00-intro.md) chapter.
|
|
||||||
|
|
||||||
To check if Composer is working, just run the PHAR through `php`:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
php composer.phar
|
|
||||||
```
|
|
||||||
|
|
||||||
This should give you a list of available commands.
|
|
||||||
|
|
||||||
> **Note:** You can also perform the checks only without downloading Composer
|
|
||||||
> by using the `--check` option. For more information, just use `--help`.
|
|
||||||
>
|
|
||||||
> ```sh
|
|
||||||
> curl -sS https://getcomposer.org/installer | php -- --help
|
|
||||||
> ```
|
|
||||||
|
|
||||||
## `composer.json`: Project Setup
|
## `composer.json`: Project Setup
|
||||||
|
|
||||||
|
@ -31,14 +15,11 @@ 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
|
||||||
`require` key. You're simply telling Composer which packages your project
|
[`require`](04-schema.md#require) key. You're simply telling Composer which
|
||||||
depends on.
|
packages your project depends on.
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
@ -48,15 +29,16 @@ depends on.
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`)
|
As you can see, [`require`](04-schema.md#require) takes an object that maps
|
||||||
to **package versions** (e.g. `1.0.*`).
|
**package names** (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
|
||||||
|
@ -66,46 +48,26 @@ smaller decoupled parts.
|
||||||
|
|
||||||
### Package Versions
|
### Package Versions
|
||||||
|
|
||||||
In the previous example we were requiring 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` `>=1.0,<1.1 | >=1.2` | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`. <br />You can define multiple ranges, separated by a comma, which will be treated as a **logical AND**. A pipe symbol `|` will be treated as a **logical OR**. <br />AND has higher precedence than OR.
|
|
||||||
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.
|
|
||||||
|
|
||||||
### Next Significant Release (Tilde Operator)
|
|
||||||
|
|
||||||
The `~` operator is best explained by example: `~1.2` is equivalent to
|
|
||||||
`>=1.2,<2.0`, while `~1.2.3` is equivalent to `>=1.2.3,<1.3`. 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.
|
|
||||||
|
|
||||||
> **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.
|
|
||||||
|
|
||||||
### 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.
|
||||||
|
|
||||||
## 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`](03-cli.md#install) command.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
php composer.phar install
|
php composer.phar install
|
||||||
|
@ -114,14 +76,14 @@ php composer.phar install
|
||||||
This will find the latest version of `monolog/monolog` that matches the
|
This will find the latest version of `monolog/monolog` that matches the
|
||||||
supplied version constraint and download it into the `vendor` directory.
|
supplied version constraint and download it into the `vendor` directory.
|
||||||
It's a convention to put third party code into a directory named `vendor`.
|
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`](03-cli.md#install) command also created a
|
||||||
file into your project root.
|
`composer.lock` file.
|
||||||
|
|
||||||
## `composer.lock` - The Lock File
|
## `composer.lock` - The Lock File
|
||||||
|
|
||||||
|
@ -129,31 +91,36 @@ 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`](03-cli.md#install) command checks
|
||||||
and if it is, it downloads the versions specified there (regardless of what `composer.json`
|
if a lock file is present, and if it is, it downloads the versions specified
|
||||||
says).
|
there (regardless 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.
|
versions from `composer.json` and create the lock file after executing the
|
||||||
|
[`update`](03-cli.md#update) or the [`install`](03-cli.md#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 `update` command. This will fetch
|
updates automatically. To update to the new version, use the
|
||||||
the latest matching versions (according to your `composer.json` file) and also update
|
[`update`](03-cli.md#update) command. This will fetch the latest matching
|
||||||
the lock file with the new version.
|
versions (according to your `composer.json` 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 `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:
|
||||||
|
|
||||||
|
@ -161,47 +128,45 @@ 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 necessary 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 is recommended to publish their packages
|
||||||
packagist. A library doesn't need to be on packagist to be used by Composer,
|
on Packagist. A library doesn't need to be on Packagist to be used by Composer,
|
||||||
but it makes life quite a bit simpler.
|
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
|
`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 __DIR__ . '/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');
|
||||||
$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');
|
||||||
```
|
```
|
||||||
|
|
||||||
You can even add your own code to the autoloader by adding an `autoload` field
|
You can even add your own code to the autoloader by adding an
|
||||||
to `composer.json`.
|
[`autoload`](04-schema.md#autoload) field to `composer.json`.
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
@ -218,24 +183,25 @@ 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 `install` to re-generate
|
After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run
|
||||||
the `vendor/autoload.php` file.
|
[`dump-autoload`](03-cli.md#dump-autoload) to 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.
|
||||||
This can be useful for autoloading classes in a test suite, for example.
|
This can be useful for autoloading classes in a test suite, for example.
|
||||||
|
|
||||||
```php
|
```php
|
||||||
$loader = require 'vendor/autoload.php';
|
$loader = require __DIR__ . '/vendor/autoload.php';
|
||||||
$loader->add('Acme\\Test\\', __DIR__);
|
$loader->add('Acme\\Test\\', __DIR__);
|
||||||
```
|
```
|
||||||
|
|
||||||
In addition to PSR-4 autoloading, classmap is also supported. This allows
|
In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and
|
||||||
classes to be autoloaded even if they do not conform to PSR-4. See the
|
files autoloading. See the [`autoload`](04-schema.md#autoload) reference for
|
||||||
[autoload reference](04-schema.md#autoload) for more details.
|
more information.
|
||||||
|
|
||||||
> **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.
|
||||||
|
|
||||||
← [Intro](00-intro.md) | [Libraries](02-libraries.md) →
|
← [Intro](00-intro.md) | [Libraries](02-libraries.md) →
|
||||||
|
|
|
@ -1,16 +1,17 @@
|
||||||
# Libraries
|
# Libraries
|
||||||
|
|
||||||
This chapter will tell you how to make your library installable through Composer.
|
This chapter will tell you how to make your library installable through
|
||||||
|
Composer.
|
||||||
|
|
||||||
## Every project is a package
|
## Every project is a package
|
||||||
|
|
||||||
As soon as you have a `composer.json` in a directory, that directory is a
|
As soon as you have a `composer.json` in a directory, that directory is a
|
||||||
package. When you add a `require` to a project, you are making a package that
|
package. When you add a [`require`](04-schema.md#require) to a project, you are
|
||||||
depends on other packages. The only difference between your project and
|
making a package that depends on other packages. The only difference between
|
||||||
libraries is that your project is a package without a name.
|
your project and libraries is that your project is a package without a name.
|
||||||
|
|
||||||
In order to make that package installable you need to give it a name. You do
|
In order to make that package installable you need to give it a name. You do
|
||||||
this by adding a `name` to `composer.json`:
|
this by adding the [`name`](04-schema.md#name) property in `composer.json`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
@ -21,12 +22,12 @@ this by adding a `name` to `composer.json`:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
In this case the project name is `acme/hello-world`, where `acme` is the
|
In this case the project name is `acme/hello-world`, where `acme` is the vendor
|
||||||
vendor name. Supplying a vendor name is mandatory.
|
name. Supplying a vendor name is mandatory.
|
||||||
|
|
||||||
> **Note:** If you don't know what to use as a vendor name, your GitHub
|
> **Note:** If you don't know what to use as a vendor name, your GitHub
|
||||||
username is usually a good bet. While package names are case insensitive, the
|
> username is usually a good bet. While package names are case insensitive, the
|
||||||
convention is all lowercase and dashes for word separation.
|
> convention is all lowercase and dashes for word separation.
|
||||||
|
|
||||||
## Platform packages
|
## Platform packages
|
||||||
|
|
||||||
|
@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries.
|
||||||
PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
|
PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
|
||||||
`openssl`, `pcre`, `uuid`, `xsl`.
|
`openssl`, `pcre`, `uuid`, `xsl`.
|
||||||
|
|
||||||
You can use `composer show --platform` to get a list of your locally available
|
You can use [`show --platform`](03-cli.md#show) to get a list of your locally
|
||||||
platform packages.
|
available platform packages.
|
||||||
|
|
||||||
## Specifying the version
|
## Specifying the version
|
||||||
|
|
||||||
You need to specify the package's version some way. When you publish your
|
When you publish your package on Packagist, it is able to infer the version
|
||||||
package on Packagist, it is able to infer the version from the VCS (git, svn,
|
from the VCS (git, svn, hg) information. This means you don't have to
|
||||||
hg) information, so in that case you do not have to specify it, and it is
|
explicitly declare it. Read [tags](#tags) and [branches](#branches) to see how
|
||||||
recommended not to. See [tags](#tags) and [branches](#branches) to see how
|
|
||||||
version numbers are extracted from these.
|
version numbers are extracted from these.
|
||||||
|
|
||||||
If you are creating packages by hand and really have to specify it explicitly,
|
If you are creating packages by hand and really have to specify it explicitly,
|
||||||
|
@ -76,32 +76,33 @@ you can just add a `version` field:
|
||||||
### Tags
|
### Tags
|
||||||
|
|
||||||
For every tag that looks like a version, a package version of that tag will be
|
For every tag that looks like a version, a package version of that tag will be
|
||||||
created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix
|
created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix of
|
||||||
of `-patch`, `-alpha`, `-beta` or `-RC`. The suffixes can also be followed by
|
`-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffix can also
|
||||||
a number.
|
be followed by a number.
|
||||||
|
|
||||||
Here are a few examples of valid tag names:
|
Here are a few examples of valid tag names:
|
||||||
|
|
||||||
- 1.0.0
|
- 1.0.0
|
||||||
- v1.0.0
|
- v1.0.0
|
||||||
- 1.10.5-RC1
|
- 1.10.5-RC1
|
||||||
- v4.4.4beta2
|
- v4.4.4-beta2
|
||||||
- v2.0.0-alpha
|
- v2.0.0-alpha
|
||||||
- v2.0.4-p1
|
- v2.0.4-p1
|
||||||
|
|
||||||
> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions)
|
> **Note:** Even if your tag is prefixed with `v`, a
|
||||||
> in a `require` statement has to be specified without prefix
|
> [version constraint](01-basic-usage.md#package-versions) in a `require`
|
||||||
> (e.g. tag `v1.0.0` will result in version `1.0.0`).
|
> statement has to be specified without prefix (e.g. tag `v1.0.0` will result
|
||||||
|
> in version `1.0.0`).
|
||||||
|
|
||||||
### Branches
|
### Branches
|
||||||
|
|
||||||
For every branch, a package development version will be created. If the branch
|
For every branch, a package development version will be created. If the branch
|
||||||
name looks like a version, the version will be `{branchname}-dev`. For example
|
name looks like a version, the version will be `{branchname}-dev`. For example,
|
||||||
a branch `2.0` will get a version `2.0.x-dev` (the `.x` is added for technical
|
the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for
|
||||||
reasons, to make sure it is recognized as a branch, a `2.0.x` branch would also
|
technical reasons, to make sure it is recognized as a branch). The `2.0.x`
|
||||||
be valid and be turned into `2.0.x-dev` as well. If the branch does not look
|
branch would also be valid and be turned into `2.0.x-dev` as well. If the
|
||||||
like a version, it will be `dev-{branchname}`. `master` results in a
|
branch does not look like a version, it will be `dev-{branchname}`. `master`
|
||||||
`dev-master` version.
|
results in a `dev-master` version.
|
||||||
|
|
||||||
Here are some examples of version branch names:
|
Here are some examples of version branch names:
|
||||||
|
|
||||||
|
@ -116,8 +117,8 @@ Here are some examples of version branch names:
|
||||||
### Aliases
|
### Aliases
|
||||||
|
|
||||||
It is possible to alias branch names to versions. For example, you could alias
|
It is possible to alias branch names to versions. For example, you could alias
|
||||||
`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all
|
`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in
|
||||||
the packages.
|
all the packages.
|
||||||
|
|
||||||
See [Aliases](articles/aliases.md) for more information.
|
See [Aliases](articles/aliases.md) for more information.
|
||||||
|
|
||||||
|
@ -133,7 +134,7 @@ the `.gitignore`.
|
||||||
|
|
||||||
## Publishing to a VCS
|
## Publishing to a VCS
|
||||||
|
|
||||||
Once you have a vcs repository (version control system, e.g. git) containing a
|
Once you have a VCS repository (version control system, e.g. git) containing a
|
||||||
`composer.json` file, your library is already composer-installable. In this
|
`composer.json` file, your library is already composer-installable. In this
|
||||||
example we will publish the `acme/hello-world` library on GitHub under
|
example we will publish the `acme/hello-world` library on GitHub under
|
||||||
`github.com/username/hello-world`.
|
`github.com/username/hello-world`.
|
||||||
|
@ -180,31 +181,32 @@ For more details on how package repositories work and what other types are
|
||||||
available, see [Repositories](05-repositories.md).
|
available, see [Repositories](05-repositories.md).
|
||||||
|
|
||||||
That's all. You can now install the dependencies by running Composer's
|
That's all. You can now install the dependencies by running Composer's
|
||||||
`install` command!
|
[`install`](03-cli.md#install) command!
|
||||||
|
|
||||||
**Recap:** Any git/svn/hg repository containing a `composer.json` can be added
|
**Recap:** Any git/svn/hg repository containing a `composer.json` can be added
|
||||||
to your project by specifying the package repository and declaring the
|
to your project by specifying the package repository and declaring the
|
||||||
dependency in the `require` field.
|
dependency in the [`require`](04-schema.md#require) field.
|
||||||
|
|
||||||
## Publishing to packagist
|
## Publishing to packagist
|
||||||
|
|
||||||
Alright, so now you can publish packages. But specifying the vcs repository
|
Alright, so now you can publish packages. But specifying the VCS repository
|
||||||
every time is cumbersome. You don't want to force all your users to do that.
|
every time is cumbersome. You don't want to force all your users to do that.
|
||||||
|
|
||||||
The other thing that you may have noticed is that we did not specify a package
|
The other thing that you may have noticed is that we did not specify a package
|
||||||
repository for `monolog/monolog`. How did that work? The answer is packagist.
|
repository for `monolog/monolog`. How did that work? The answer is Packagist.
|
||||||
|
|
||||||
[Packagist](https://packagist.org/) is the main package repository for
|
[Packagist](https://packagist.org/) is the main package repository for
|
||||||
Composer, and it is enabled by default. Anything that is published on
|
Composer, and it is enabled by default. Anything that is published on
|
||||||
packagist is available automatically through Composer. Since monolog
|
Packagist is available automatically through Composer. Since
|
||||||
[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend
|
[Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we
|
||||||
on it without having to specify any additional repositories.
|
can depend on it without having to specify any additional repositories.
|
||||||
|
|
||||||
If we wanted to share `hello-world` with the world, we would publish it on
|
If we wanted to share `hello-world` with the world, we would publish it on
|
||||||
packagist as well. Doing so is really easy.
|
Packagist as well. Doing so is really easy.
|
||||||
|
|
||||||
You simply hit the big "Submit Package" button and sign up. Then you submit
|
You simply visit [Packagist](https://packagist.org) and hit the "Submit". This
|
||||||
the URL to your VCS repository, at which point packagist will start crawling
|
will prompt you to sign up if you haven't already, and then allows you to
|
||||||
it. Once it is done, your package will be available to anyone.
|
submit the URL to your VCS repository, at which point Packagist will start
|
||||||
|
crawling it. Once it is done, your package will be available to anyone!
|
||||||
|
|
||||||
← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) →
|
← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) →
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# Command-line interface
|
# Command-line interface / Commands
|
||||||
|
|
||||||
You've already learned how to use the command-line interface to do some
|
You've already learned how to use the command-line interface to do some
|
||||||
things. This chapter documents all the available commands.
|
things. This chapter documents all the available commands.
|
||||||
|
@ -64,27 +64,32 @@ If there is a `composer.lock` file in the current directory, it will use the
|
||||||
exact versions from there instead of resolving them. This ensures that
|
exact versions from there instead of resolving them. This ensures that
|
||||||
everyone using the library will get the same versions of the dependencies.
|
everyone using the library will get the same versions of the dependencies.
|
||||||
|
|
||||||
If there is no `composer.lock` file, composer will create one after dependency
|
If there is no `composer.lock` file, Composer will create one after dependency
|
||||||
resolution.
|
resolution.
|
||||||
|
|
||||||
### Options
|
### Options
|
||||||
|
|
||||||
* **--prefer-source:** There are two ways of downloading a package: `source`
|
* **--prefer-source:** There are two ways of downloading a package: `source`
|
||||||
and `dist`. For stable versions composer will use the `dist` by default.
|
and `dist`. For stable versions Composer will use the `dist` by default.
|
||||||
The `source` is a version control repository. If `--prefer-source` is
|
The `source` is a version control repository. If `--prefer-source` is
|
||||||
enabled, composer will install from `source` if there is one. This is
|
enabled, Composer will install from `source` if there is one. This is
|
||||||
useful if you want to make a bugfix to a project and get a local git
|
useful if you want to make a bugfix to a project and get a local git
|
||||||
clone of the dependency directly.
|
clone of the dependency directly.
|
||||||
* **--prefer-dist:** Reverse of `--prefer-source`, composer will install
|
* **--prefer-dist:** Reverse of `--prefer-source`, Composer will install
|
||||||
from `dist` if possible. This can speed up installs substantially on build
|
from `dist` if possible. This can speed up installs substantially on build
|
||||||
servers and other use cases where you typically do not run updates of the
|
servers and other use cases where you typically do not run updates of the
|
||||||
vendors. It is also a way to circumvent problems with git if you do not
|
vendors. It is also a way to circumvent problems with git if you do not
|
||||||
have a proper setup.
|
have a proper setup.
|
||||||
|
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||||
|
requirements and force the installation even if the local machine does not
|
||||||
|
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||||
* **--dry-run:** If you want to run through an installation without actually
|
* **--dry-run:** If you want to run through an installation without actually
|
||||||
installing a package, you can use `--dry-run`. This will simulate the
|
installing a package, you can use `--dry-run`. This will simulate the
|
||||||
installation and show you what would happen.
|
installation and show you what would happen.
|
||||||
* **--dev:** Install packages listed in `require-dev` (this is the default behavior).
|
* **--dev:** Install packages listed in `require-dev` (this is the default behavior).
|
||||||
* **--no-dev:** Skip installing packages listed in `require-dev`.
|
* **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader
|
||||||
|
generation skips the `autoload-dev` rules.
|
||||||
|
* **--no-autoloader:** Skips autoloader generation.
|
||||||
* **--no-scripts:** Skips execution of scripts defined in `composer.json`.
|
* **--no-scripts:** Skips execution of scripts defined in `composer.json`.
|
||||||
* **--no-plugins:** Disables plugins.
|
* **--no-plugins:** Disables plugins.
|
||||||
* **--no-progress:** Removes the progress display that can mess with some
|
* **--no-progress:** Removes the progress display that can mess with some
|
||||||
|
@ -92,6 +97,8 @@ resolution.
|
||||||
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
|
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
|
||||||
autoloader. This is recommended especially for production, but can take
|
autoloader. This is recommended especially for production, but can take
|
||||||
a bit of time to run so it is currently not done by default.
|
a bit of time to run so it is currently not done by default.
|
||||||
|
* **--classmap-authoritative (-a):** Autoload classes from the classmap only.
|
||||||
|
Implicitly enables `--optimize-autoloader`.
|
||||||
|
|
||||||
## update
|
## update
|
||||||
|
|
||||||
|
@ -121,9 +128,13 @@ php composer.phar update vendor/*
|
||||||
|
|
||||||
* **--prefer-source:** Install packages from `source` when available.
|
* **--prefer-source:** Install packages from `source` when available.
|
||||||
* **--prefer-dist:** Install packages from `dist` when available.
|
* **--prefer-dist:** Install packages from `dist` when available.
|
||||||
|
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||||
|
requirements and force the installation even if the local machine does not
|
||||||
|
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||||
* **--dry-run:** Simulate the command without actually doing anything.
|
* **--dry-run:** Simulate the command without actually doing anything.
|
||||||
* **--dev:** Install packages listed in `require-dev` (this is the default behavior).
|
* **--dev:** Install packages listed in `require-dev` (this is the default behavior).
|
||||||
* **--no-dev:** Skip installing packages listed in `require-dev`.
|
* **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader generation skips the `autoload-dev` rules.
|
||||||
|
* **--no-autoloader:** Skips autoloader generation.
|
||||||
* **--no-scripts:** Skips execution of scripts defined in `composer.json`.
|
* **--no-scripts:** Skips execution of scripts defined in `composer.json`.
|
||||||
* **--no-plugins:** Disables plugins.
|
* **--no-plugins:** Disables plugins.
|
||||||
* **--no-progress:** Removes the progress display that can mess with some
|
* **--no-progress:** Removes the progress display that can mess with some
|
||||||
|
@ -131,15 +142,19 @@ php composer.phar update vendor/*
|
||||||
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
|
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
|
||||||
autoloader. This is recommended especially for production, but can take
|
autoloader. This is recommended especially for production, but can take
|
||||||
a bit of time to run so it is currently not done by default.
|
a bit of time to run so it is currently not done by default.
|
||||||
|
* **--classmap-authoritative (-a):** Autoload classes from the classmap only.
|
||||||
|
Implicitly enables `--optimize-autoloader`.
|
||||||
* **--lock:** Only updates the lock file hash to suppress warning about the
|
* **--lock:** Only updates the lock file hash to suppress warning about the
|
||||||
lock file being out of date.
|
lock file being out of date.
|
||||||
* **--with-dependencies** Add also all dependencies of whitelisted packages to the whitelist.
|
* **--with-dependencies:** Add also all dependencies of whitelisted packages to the whitelist.
|
||||||
So all packages with their dependencies are updated recursively.
|
* **--prefer-stable:** Prefer stable versions of dependencies.
|
||||||
|
* **--prefer-lowest:** Prefer lowest versions of dependencies. Useful for testing minimal
|
||||||
|
versions of requirements, generally used with `--prefer-stable`.
|
||||||
|
|
||||||
## require
|
## require
|
||||||
|
|
||||||
The `require` command adds new packages to the `composer.json` file from
|
The `require` command adds new packages to the `composer.json` file from
|
||||||
the current directory.
|
the current directory. If no file exists one will be created on the fly.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
php composer.phar require
|
php composer.phar require
|
||||||
|
@ -159,12 +174,50 @@ php composer.phar require vendor/package:2.* vendor/package2:dev-master
|
||||||
|
|
||||||
* **--prefer-source:** Install packages from `source` when available.
|
* **--prefer-source:** Install packages from `source` when available.
|
||||||
* **--prefer-dist:** Install packages from `dist` when available.
|
* **--prefer-dist:** Install packages from `dist` when available.
|
||||||
|
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||||
|
requirements and force the installation even if the local machine does not
|
||||||
|
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||||
* **--dev:** Add packages to `require-dev`.
|
* **--dev:** Add packages to `require-dev`.
|
||||||
* **--no-update:** Disables the automatic update of the dependencies.
|
* **--no-update:** Disables the automatic update of the dependencies.
|
||||||
* **--no-progress:** Removes the progress display that can mess with some
|
* **--no-progress:** Removes the progress display that can mess with some
|
||||||
terminals or scripts which don't handle backspace characters.
|
terminals or scripts which don't handle backspace characters.
|
||||||
* **--update-with-dependencies** Also update dependencies of the newly
|
* **--update-no-dev:** Run the dependency update with the `--no-dev` option.
|
||||||
|
* **--update-with-dependencies:** Also update dependencies of the newly
|
||||||
required packages.
|
required packages.
|
||||||
|
* **--sort-packages:** Keep packages sorted in `composer.json`.
|
||||||
|
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to
|
||||||
|
get a faster autoloader. This is recommended especially for production, but
|
||||||
|
can take a bit of time to run so it is currently not done by default.
|
||||||
|
* **--classmap-authoritative (-a):** Autoload classes from the classmap only.
|
||||||
|
Implicitly enables `--optimize-autoloader`.
|
||||||
|
|
||||||
|
## remove
|
||||||
|
|
||||||
|
The `remove` command removes packages from the `composer.json` file from
|
||||||
|
the current directory.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
php composer.phar remove vendor/package vendor/package2
|
||||||
|
```
|
||||||
|
|
||||||
|
After removing the requirements, the modified requirements will be
|
||||||
|
uninstalled.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||||
|
requirements and force the installation even if the local machine does not
|
||||||
|
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||||
|
* **--dev:** Remove packages from `require-dev`.
|
||||||
|
* **--no-update:** Disables the automatic update of the dependencies.
|
||||||
|
* **--no-progress:** Removes the progress display that can mess with some
|
||||||
|
terminals or scripts which don't handle backspace characters.
|
||||||
|
* **--update-no-dev:** Run the dependency update with the --no-dev option.
|
||||||
|
* **--update-with-dependencies:** Also update dependencies of the removed packages.
|
||||||
|
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to
|
||||||
|
get a faster autoloader. This is recommended especially for production, but
|
||||||
|
can take a bit of time to run so it is currently not done by default.
|
||||||
|
* **--classmap-authoritative (-a):** Autoload classes from the classmap only.
|
||||||
|
Implicitly enables `--optimize-autoloader`.
|
||||||
|
|
||||||
## global
|
## global
|
||||||
|
|
||||||
|
@ -222,8 +275,8 @@ name : monolog/monolog
|
||||||
versions : master-dev, 1.0.2, 1.0.1, 1.0.0, 1.0.0-RC1
|
versions : master-dev, 1.0.2, 1.0.1, 1.0.0, 1.0.0-RC1
|
||||||
type : library
|
type : library
|
||||||
names : monolog/monolog
|
names : monolog/monolog
|
||||||
source : [git] http://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
source : [git] https://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
||||||
dist : [zip] http://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
dist : [zip] https://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
||||||
license : MIT
|
license : MIT
|
||||||
|
|
||||||
autoload
|
autoload
|
||||||
|
@ -246,6 +299,28 @@ php composer.phar show monolog/monolog 1.0.2
|
||||||
* **--installed (-i):** List the packages that are installed.
|
* **--installed (-i):** List the packages that are installed.
|
||||||
* **--platform (-p):** List only platform packages (php & extensions).
|
* **--platform (-p):** List only platform packages (php & extensions).
|
||||||
* **--self (-s):** List the root package info.
|
* **--self (-s):** List the root package info.
|
||||||
|
* **--tree (-t):** List the dependencies as a tree. Only usable when giving a single package name or combined with `-i`.
|
||||||
|
|
||||||
|
## browse / home
|
||||||
|
|
||||||
|
The `browse` (aliased to `home`) opens a package's repository URL or homepage
|
||||||
|
in your browser.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
* **--homepage (-H):** Open the homepage instead of the repository URL.
|
||||||
|
|
||||||
|
## suggests
|
||||||
|
|
||||||
|
Lists all packages suggested by currently installed set of packages. You can
|
||||||
|
optionally pass one or multiple package names in the format of `vendor/package`
|
||||||
|
to limit output to suggestions made by those packages only.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
* **--no-dev:** Excludes suggestions from `require-dev` packages.
|
||||||
|
* **--verbose (-v):** Increased verbosity adds suggesting package name and
|
||||||
|
reason for suggestion.
|
||||||
|
|
||||||
## depends
|
## depends
|
||||||
|
|
||||||
|
@ -256,11 +331,11 @@ should be included in the listing. By default both are used.
|
||||||
```sh
|
```sh
|
||||||
php composer.phar depends --link-type=require monolog/monolog
|
php composer.phar depends --link-type=require monolog/monolog
|
||||||
|
|
||||||
nrk/monolog-fluent
|
nrk/monolog-fluent requires monolog/monolog (~1.8)
|
||||||
poc/poc
|
poc/poc requires monolog/monolog (^1.6)
|
||||||
propel/propel
|
propel/propel requires monolog/monolog (1.*)
|
||||||
symfony/monolog-bridge
|
symfony/monolog-bridge requires monolog/monolog (>=1.2)
|
||||||
symfony/symfony
|
symfony/symfony requires monolog/monolog (~1)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Options
|
### Options
|
||||||
|
@ -280,7 +355,9 @@ php composer.phar validate
|
||||||
|
|
||||||
### Options
|
### Options
|
||||||
|
|
||||||
* **--no-check-all:** Wether or not composer do a complete validation.
|
* **--no-check-all:** Do not emit a warning if requirements in `composer.json` use unbound version constraints.
|
||||||
|
* **--no-check-lock:** Do not emit an error if `composer.lock` exists and is not up to date.
|
||||||
|
* **--no-check-publish:** Do not emit an error if `composer.json` is unsuitable for publishing as a package on Packagist but is otherwise valid.
|
||||||
|
|
||||||
## status
|
## status
|
||||||
|
|
||||||
|
@ -305,7 +382,7 @@ vendor/seld/jsonlint:
|
||||||
|
|
||||||
## self-update
|
## self-update
|
||||||
|
|
||||||
To update composer itself to the latest version, just run the `self-update`
|
To update Composer itself to the latest version, just run the `self-update`
|
||||||
command. It will replace your `composer.phar` with the latest version.
|
command. It will replace your `composer.phar` with the latest version.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
@ -318,7 +395,7 @@ If you would like to instead update to a specific release simply specify it:
|
||||||
php composer.phar self-update 1.0.0-alpha7
|
php composer.phar self-update 1.0.0-alpha7
|
||||||
```
|
```
|
||||||
|
|
||||||
If you have installed composer for your entire system (see [global installation](00-intro.md#globally)),
|
If you have installed Composer for your entire system (see [global installation](00-intro.md#globally)),
|
||||||
you may have to run the command with `root` privileges
|
you may have to run the command with `root` privileges
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
@ -328,11 +405,12 @@ sudo composer self-update
|
||||||
### Options
|
### Options
|
||||||
|
|
||||||
* **--rollback (-r):** Rollback to the last version you had installed.
|
* **--rollback (-r):** Rollback to the last version you had installed.
|
||||||
* **--clean-backups:** Delete old backups during an update. This makes the current version of composer the only backup available after the update.
|
* **--clean-backups:** Delete old backups during an update. This makes the
|
||||||
|
current version of Composer the only backup available after the update.
|
||||||
|
|
||||||
## config
|
## config
|
||||||
|
|
||||||
The `config` command allows you to edit some basic composer settings in either
|
The `config` command allows you to edit some basic Composer settings in either
|
||||||
the local composer.json file or the global config.json file.
|
the local composer.json file or the global config.json file.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
@ -347,8 +425,7 @@ php composer.phar config --list
|
||||||
configuration value. For settings that can take an array of values (like
|
configuration value. For settings that can take an array of values (like
|
||||||
`github-protocols`), more than one setting-value arguments are allowed.
|
`github-protocols`), more than one setting-value arguments are allowed.
|
||||||
|
|
||||||
See the [config schema section](04-schema.md#config) for valid configuration
|
See the [Config](06-config.md) chapter for valid configuration options.
|
||||||
options.
|
|
||||||
|
|
||||||
### Options
|
### Options
|
||||||
|
|
||||||
|
@ -363,6 +440,8 @@ the global config file.
|
||||||
option this lists the global configuration only.
|
option this lists the global configuration only.
|
||||||
* **--file="..." (-f):** Operate on a specific file instead of composer.json. Note
|
* **--file="..." (-f):** Operate on a specific file instead of composer.json. Note
|
||||||
that this cannot be used in conjunction with the `--global` option.
|
that this cannot be used in conjunction with the `--global` option.
|
||||||
|
* **--absolute:** Returns absolute paths when fetching *-dir config values
|
||||||
|
instead of relative.
|
||||||
|
|
||||||
### Modifying Repositories
|
### Modifying Repositories
|
||||||
|
|
||||||
|
@ -370,13 +449,13 @@ In addition to modifying the config section, the `config` command also supports
|
||||||
changes to the repositories section by using it the following way:
|
changes to the repositories section by using it the following way:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
php composer.phar config repositories.foo vcs http://github.com/foo/bar
|
php composer.phar config repositories.foo vcs https://github.com/foo/bar
|
||||||
```
|
```
|
||||||
|
|
||||||
## create-project
|
## create-project
|
||||||
|
|
||||||
You can use Composer to create new projects from an existing package. This is
|
You can use Composer to create new projects from an existing package. This is
|
||||||
the equivalent of doing a git clone/svn checkout followed by a composer install
|
the equivalent of doing a git clone/svn checkout followed by a "composer install"
|
||||||
of the vendors.
|
of the vendors.
|
||||||
|
|
||||||
There are several applications for this:
|
There are several applications for this:
|
||||||
|
@ -386,7 +465,7 @@ There are several applications for this:
|
||||||
3. Projects with multiple developers can use this feature to bootstrap the
|
3. Projects with multiple developers can use this feature to bootstrap the
|
||||||
initial application for development.
|
initial application for development.
|
||||||
|
|
||||||
To create a new project using composer you can use the "create-project" command.
|
To create a new project using Composer you can use the "create-project" command.
|
||||||
Pass it a package name, and the directory to create the project in. You can also
|
Pass it a package name, and the directory to create the project in. You can also
|
||||||
provide a version as third argument, otherwise the latest version is used.
|
provide a version as third argument, otherwise the latest version is used.
|
||||||
|
|
||||||
|
@ -419,6 +498,9 @@ By default the command checks for the packages on packagist.org.
|
||||||
* **--keep-vcs:** Skip the deletion of the VCS metadata for the created
|
* **--keep-vcs:** Skip the deletion of the VCS metadata for the created
|
||||||
project. This is mostly useful if you run the command in non-interactive
|
project. This is mostly useful if you run the command in non-interactive
|
||||||
mode.
|
mode.
|
||||||
|
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||||
|
requirements and force the installation even if the local machine does not
|
||||||
|
fulfill these.
|
||||||
|
|
||||||
## dump-autoload
|
## dump-autoload
|
||||||
|
|
||||||
|
@ -438,17 +520,33 @@ performance.
|
||||||
* **--optimize (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
|
* **--optimize (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
|
||||||
autoloader. This is recommended especially for production, but can take
|
autoloader. This is recommended especially for production, but can take
|
||||||
a bit of time to run so it is currently not done by default.
|
a bit of time to run so it is currently not done by default.
|
||||||
|
* **--classmap-authoritative (-a):** Autoload classes from the classmap only.
|
||||||
|
Implicitly enables `--optimize`.
|
||||||
* **--no-dev:** Disables autoload-dev rules.
|
* **--no-dev:** Disables autoload-dev rules.
|
||||||
|
|
||||||
|
## clear-cache
|
||||||
|
|
||||||
|
Deletes all content from Composer's cache directories.
|
||||||
|
|
||||||
## licenses
|
## licenses
|
||||||
|
|
||||||
Lists the name, version and license of every package installed. Use
|
Lists the name, version and license of every package installed. Use
|
||||||
`--format=json` to get machine readable output.
|
`--format=json` to get machine readable output.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
* **--no-dev:** Remove dev dependencies from the output
|
||||||
|
* **--format:** Format of the output: text or json (default: "text")
|
||||||
|
|
||||||
## run-script
|
## run-script
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
* **--no-dev:** Disable dev mode
|
||||||
|
* **--list:** List user defined scripts
|
||||||
|
|
||||||
To run [scripts](articles/scripts.md) manually you can use this command,
|
To run [scripts](articles/scripts.md) manually you can use this command,
|
||||||
just give it the script name and optionally --no-dev to disable the dev mode.
|
just give it the script name and optionally any required arguments.
|
||||||
|
|
||||||
## diagnose
|
## diagnose
|
||||||
|
|
||||||
|
@ -502,6 +600,8 @@ For example:
|
||||||
COMPOSER=composer-other.json php composer.phar install
|
COMPOSER=composer-other.json php composer.phar install
|
||||||
```
|
```
|
||||||
|
|
||||||
|
The generated lock file will use the same name: `composer-other.lock` in this example.
|
||||||
|
|
||||||
### COMPOSER_ROOT_VERSION
|
### COMPOSER_ROOT_VERSION
|
||||||
|
|
||||||
By setting this var you can specify the version of the root package, if it can
|
By setting this var you can specify the version of the root package, if it can
|
||||||
|
@ -509,7 +609,7 @@ not be guessed from VCS info and is not present in `composer.json`.
|
||||||
|
|
||||||
### COMPOSER_VENDOR_DIR
|
### COMPOSER_VENDOR_DIR
|
||||||
|
|
||||||
By setting this var you can make composer install the dependencies into a
|
By setting this var you can make Composer install the dependencies into a
|
||||||
directory other than `vendor`.
|
directory other than `vendor`.
|
||||||
|
|
||||||
### COMPOSER_BIN_DIR
|
### COMPOSER_BIN_DIR
|
||||||
|
@ -519,7 +619,7 @@ directory to something other than `vendor/bin`.
|
||||||
|
|
||||||
### http_proxy or HTTP_PROXY
|
### http_proxy or HTTP_PROXY
|
||||||
|
|
||||||
If you are using composer from behind an HTTP proxy, you can use the standard
|
If you are using Composer from behind an HTTP proxy, you can use the standard
|
||||||
`http_proxy` or `HTTP_PROXY` env vars. Simply set it to the URL of your proxy.
|
`http_proxy` or `HTTP_PROXY` env vars. Simply set it to the URL of your proxy.
|
||||||
Many operating systems already set this variable for you.
|
Many operating systems already set this variable for you.
|
||||||
|
|
||||||
|
@ -541,18 +641,18 @@ can also set it to `*` to ignore the proxy for all HTTP requests.
|
||||||
### HTTP_PROXY_REQUEST_FULLURI
|
### HTTP_PROXY_REQUEST_FULLURI
|
||||||
|
|
||||||
If you use a proxy but it does not support the request_fulluri flag, then you
|
If you use a proxy but it does not support the request_fulluri flag, then you
|
||||||
should set this env var to `false` or `0` to prevent composer from setting the
|
should set this env var to `false` or `0` to prevent Composer from setting the
|
||||||
request_fulluri option.
|
request_fulluri option.
|
||||||
|
|
||||||
### HTTPS_PROXY_REQUEST_FULLURI
|
### HTTPS_PROXY_REQUEST_FULLURI
|
||||||
|
|
||||||
If you use a proxy but it does not support the request_fulluri flag for HTTPS
|
If you use a proxy but it does not support the request_fulluri flag for HTTPS
|
||||||
requests, then you should set this env var to `false` or `0` to prevent composer
|
requests, then you should set this env var to `false` or `0` to prevent Composer
|
||||||
from setting the request_fulluri option.
|
from setting the request_fulluri option.
|
||||||
|
|
||||||
### COMPOSER_HOME
|
### COMPOSER_HOME
|
||||||
|
|
||||||
The `COMPOSER_HOME` var allows you to change the composer home directory. This
|
The `COMPOSER_HOME` var allows you to change the Composer home directory. This
|
||||||
is a hidden, global (per-user on the machine) directory that is shared between
|
is a hidden, global (per-user on the machine) directory that is shared between
|
||||||
all projects.
|
all projects.
|
||||||
|
|
||||||
|
@ -566,32 +666,36 @@ You may put a `config.json` file into the location which `COMPOSER_HOME` points
|
||||||
to. Composer will merge this configuration with your project's `composer.json`
|
to. Composer will merge this configuration with your project's `composer.json`
|
||||||
when you run the `install` and `update` commands.
|
when you run the `install` and `update` commands.
|
||||||
|
|
||||||
This file allows you to set [configuration](04-schema.md#config) and
|
This file allows you to set [repositories](05-repositories.md) and
|
||||||
[repositories](05-repositories.md) for the user's projects.
|
[configuration](06-config.md) for the user's projects.
|
||||||
|
|
||||||
In case global configuration matches _local_ configuration, the _local_
|
In case global configuration matches _local_ configuration, the _local_
|
||||||
configuration in the project's `composer.json` always wins.
|
configuration in the project's `composer.json` always wins.
|
||||||
|
|
||||||
### COMPOSER_CACHE_DIR
|
### COMPOSER_CACHE_DIR
|
||||||
|
|
||||||
The `COMPOSER_CACHE_DIR` var allows you to change the composer cache directory,
|
The `COMPOSER_CACHE_DIR` var allows you to change the Composer cache directory,
|
||||||
which is also configurable via the [`cache-dir`](04-schema.md#config) option.
|
which is also configurable via the [`cache-dir`](06-config.md#cache-dir) option.
|
||||||
|
|
||||||
By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and
|
By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and
|
||||||
`C:\Users\<user>\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows.
|
`C:\Users\<user>\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows.
|
||||||
|
|
||||||
### COMPOSER_PROCESS_TIMEOUT
|
### COMPOSER_PROCESS_TIMEOUT
|
||||||
|
|
||||||
This env var controls the time composer waits for commands (such as git
|
This env var controls the time Composer waits for commands (such as git
|
||||||
commands) to finish executing. The default value is 300 seconds (5 minutes).
|
commands) to finish executing. The default value is 300 seconds (5 minutes).
|
||||||
|
|
||||||
### COMPOSER_DISCARD_CHANGES
|
### COMPOSER_DISCARD_CHANGES
|
||||||
|
|
||||||
This env var controls the discard-changes [config option](04-schema.md#config).
|
This env var controls the [`discard-changes`](06-config.md#discard-changes) config option.
|
||||||
|
|
||||||
### COMPOSER_NO_INTERACTION
|
### COMPOSER_NO_INTERACTION
|
||||||
|
|
||||||
If set to 1, this env var will make composer behave as if you passed the
|
If set to 1, this env var will make Composer behave as if you passed the
|
||||||
`--no-interaction` flag to every command. This can be set on build boxes/CI.
|
`--no-interaction` flag to every command. This can be set on build boxes/CI.
|
||||||
|
|
||||||
|
### COMPOSER_DISABLE_XDEBUG_WARN
|
||||||
|
|
||||||
|
If set to 1, this env disables the warning about having xdebug enabled.
|
||||||
|
|
||||||
← [Libraries](02-libraries.md) | [Schema](04-schema.md) →
|
← [Libraries](02-libraries.md) | [Schema](04-schema.md) →
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# composer.json
|
# The composer.json Schema
|
||||||
|
|
||||||
This chapter will explain all of the fields available in `composer.json`.
|
This chapter will explain all of the fields available in `composer.json`.
|
||||||
|
|
||||||
|
@ -20,9 +20,6 @@ this is the `config` field. Only the root package can define configuration.
|
||||||
The config of dependencies is ignored. This makes the `config` field
|
The config of dependencies is ignored. This makes the `config` field
|
||||||
`root-only`.
|
`root-only`.
|
||||||
|
|
||||||
If you clone one of those dependencies to work on it, then that package is the
|
|
||||||
root package. The `composer.json` is identical, but the context is different.
|
|
||||||
|
|
||||||
> **Note:** A package can be the root package or not, depending on the context.
|
> **Note:** A package can be the root package or not, depending on the context.
|
||||||
> For example, if your project depends on the `monolog` library, your project
|
> For example, if your project depends on the `monolog` library, your project
|
||||||
> is the root package. However, if you clone `monolog` from GitHub in order to
|
> is the root package. However, if you clone `monolog` from GitHub in order to
|
||||||
|
@ -54,8 +51,8 @@ The version of the package. In most cases this is not required and should
|
||||||
be omitted (see below).
|
be omitted (see below).
|
||||||
|
|
||||||
This must follow the format of `X.Y.Z` or `vX.Y.Z` with an optional suffix
|
This must follow the format of `X.Y.Z` or `vX.Y.Z` with an optional suffix
|
||||||
of `-dev`, `-patch`, `-alpha`, `-beta` or `-RC`. The patch, alpha, beta and
|
of `-dev`, `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`.
|
||||||
RC suffixes can also be followed by a number.
|
The patch, alpha, beta and RC suffixes can also be followed by a number.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
|
|
||||||
|
@ -67,6 +64,7 @@ Examples:
|
||||||
- 1.0.0-alpha3
|
- 1.0.0-alpha3
|
||||||
- 1.0.0-beta2
|
- 1.0.0-beta2
|
||||||
- 1.0.0-RC5
|
- 1.0.0-RC5
|
||||||
|
- v2.0.4-p1
|
||||||
|
|
||||||
Optional if the package repository can infer the version from somewhere, such
|
Optional if the package repository can infer the version from somewhere, such
|
||||||
as the VCS tag name in the VCS repository. In that case it is also recommended
|
as the VCS tag name in the VCS repository. In that case it is also recommended
|
||||||
|
@ -86,7 +84,7 @@ that needs some special logic, you can define a custom type. This could be a
|
||||||
all be specific to certain projects, and they will need to provide an
|
all be specific to certain projects, and they will need to provide an
|
||||||
installer capable of installing packages of that type.
|
installer capable of installing packages of that type.
|
||||||
|
|
||||||
Out of the box, composer supports four types:
|
Out of the box, Composer supports four types:
|
||||||
|
|
||||||
- **library:** This is the default. It will simply copy the files to `vendor`.
|
- **library:** This is the default. It will simply copy the files to `vendor`.
|
||||||
- **project:** This denotes a project rather than a library. For example
|
- **project:** This denotes a project rather than a library. For example
|
||||||
|
@ -156,7 +154,7 @@ The recommended notation for the most common licenses is (alphabetical):
|
||||||
- MIT
|
- MIT
|
||||||
|
|
||||||
Optional, but it is highly recommended to supply this. More identifiers are
|
Optional, but it is highly recommended to supply this. More identifiers are
|
||||||
listed at the [SPDX Open Source License Registry](http://www.spdx.org/licenses/).
|
listed at the [SPDX Open Source License Registry](https://www.spdx.org/licenses/).
|
||||||
|
|
||||||
For closed-source software, you may use `"proprietary"` as the license identifier.
|
For closed-source software, you may use `"proprietary"` as the license identifier.
|
||||||
|
|
||||||
|
@ -234,11 +232,12 @@ Various information to get support about the project.
|
||||||
Support information includes the following:
|
Support information includes the following:
|
||||||
|
|
||||||
* **email:** Email address for support.
|
* **email:** Email address for support.
|
||||||
* **issues:** URL to the Issue Tracker.
|
* **issues:** URL to the issue tracker.
|
||||||
* **forum:** URL to the Forum.
|
* **forum:** URL to the forum.
|
||||||
* **wiki:** URL to the Wiki.
|
* **wiki:** URL to the wiki.
|
||||||
* **irc:** IRC channel for support, as irc://server/channel.
|
* **irc:** IRC channel for support, as irc://server/channel.
|
||||||
* **source:** URL to browse or download the sources.
|
* **source:** URL to browse or download the sources.
|
||||||
|
* **docs:** URL to the documentation.
|
||||||
|
|
||||||
An example:
|
An example:
|
||||||
|
|
||||||
|
@ -270,7 +269,7 @@ Example:
|
||||||
|
|
||||||
All links are optional fields.
|
All links are optional fields.
|
||||||
|
|
||||||
`require` and `require-dev` additionally support stability flags (root-only).
|
`require` and `require-dev` additionally support stability flags ([root-only](04-schema.md#root-package)).
|
||||||
These allow you to further restrict or expand the stability of a package beyond
|
These allow you to further restrict or expand the stability of a package beyond
|
||||||
the scope of the [minimum-stability](#minimum-stability) setting. You can apply
|
the scope of the [minimum-stability](#minimum-stability) setting. You can apply
|
||||||
them to a constraint, or just apply them to an empty constraint if you want to
|
them to a constraint, or just apply them to an empty constraint if you want to
|
||||||
|
@ -328,12 +327,26 @@ It is also possible to inline-alias a package constraint so that it matches
|
||||||
a constraint that it otherwise would not. For more information [see the
|
a constraint that it otherwise would not. For more information [see the
|
||||||
aliases article](articles/aliases.md).
|
aliases article](articles/aliases.md).
|
||||||
|
|
||||||
|
`require` and `require-dev` also support references to specific PHP versions
|
||||||
|
and PHP extensions your project needs to run successfully.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"require" : {
|
||||||
|
"php" : "^5.5 || ^7.0",
|
||||||
|
"ext-mbstring": "*"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
#### require
|
#### require
|
||||||
|
|
||||||
Lists packages required by this package. The package will not be installed
|
Lists packages required by this package. The package will not be installed
|
||||||
unless those requirements can be met.
|
unless those requirements can be met.
|
||||||
|
|
||||||
#### require-dev <span>(root-only)</span>
|
#### require-dev <span>([root-only](04-schema.md#root-package))</span>
|
||||||
|
|
||||||
Lists packages required for developing this package, or running
|
Lists packages required for developing this package, or running
|
||||||
tests, etc. The dev requirements of the root package are installed by default.
|
tests, etc. The dev requirements of the root package are installed by default.
|
||||||
|
@ -345,7 +358,7 @@ dependencies from being installed.
|
||||||
Lists packages that conflict with this version of this package. They
|
Lists packages that conflict with this version of this package. They
|
||||||
will not be allowed to be installed together with your package.
|
will not be allowed to be installed together with your package.
|
||||||
|
|
||||||
Note that when specifying ranges like `<1.0, >= 1.1` in a `conflict` link,
|
Note that when specifying ranges like `<1.0 >=1.1` in a `conflict` link,
|
||||||
this will state a conflict with all versions that are less than 1.0 *and* equal
|
this will state a conflict with all versions that are less than 1.0 *and* equal
|
||||||
or newer than 1.1 at the same time, which is probably not what you want. You
|
or newer than 1.1 at the same time, which is probably not what you want. You
|
||||||
probably want to go for `<1.0 | >=1.1` in this case.
|
probably want to go for `<1.0 | >=1.1` in this case.
|
||||||
|
@ -375,7 +388,7 @@ useful for common interfaces. A package could depend on some virtual
|
||||||
`logger` package, any library that implements this logger interface would
|
`logger` package, any library that implements this logger interface would
|
||||||
simply list it in `provide`.
|
simply list it in `provide`.
|
||||||
|
|
||||||
### suggest
|
#### suggest
|
||||||
|
|
||||||
Suggested packages that can enhance or work well with this package. These are
|
Suggested packages that can enhance or work well with this package. These are
|
||||||
just informational and are displayed after the package is installed, to give
|
just informational and are displayed after the package is installed, to give
|
||||||
|
@ -553,7 +566,27 @@ Example:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### autoload-dev <span>(root-only)</span>
|
#### Exclude files from classmaps
|
||||||
|
|
||||||
|
If you want to exclude some files or folders from the classmap you can use the 'exclude-from-classmap' property.
|
||||||
|
This might be useful to exclude test classes in your live environment, for example, as those will be skipped
|
||||||
|
from the classmap even when building an optimized autoloader.
|
||||||
|
|
||||||
|
The classmap generator will ignore all files in the paths configured here. The paths are absolute from the package
|
||||||
|
root directory (i.e. composer.json location), and support `*` to match anything but a slash, and `**` to
|
||||||
|
match anything. `**` is implicitly added to the end of the paths.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"autoload": {
|
||||||
|
"exclude-from-classmap": ["/Tests/", "/test/", "/tests/"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### autoload-dev <span>([root-only](04-schema.md#root-package))</span>
|
||||||
|
|
||||||
This section allows to define autoload rules for development purposes.
|
This section allows to define autoload rules for development purposes.
|
||||||
|
|
||||||
|
@ -626,7 +659,7 @@ To do that, `autoload` and `target-dir` are defined as follows:
|
||||||
|
|
||||||
Optional.
|
Optional.
|
||||||
|
|
||||||
### minimum-stability <span>(root-only)</span>
|
### minimum-stability <span>([root-only](04-schema.md#root-package))</span>
|
||||||
|
|
||||||
This defines the default behavior for filtering packages by stability. This
|
This defines the default behavior for filtering packages by stability. This
|
||||||
defaults to `stable`, so if you rely on a `dev` package, you should specify
|
defaults to `stable`, so if you rely on a `dev` package, you should specify
|
||||||
|
@ -641,7 +674,7 @@ a given package can be done in `require` or `require-dev` (see
|
||||||
Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`,
|
Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`,
|
||||||
and `stable`.
|
and `stable`.
|
||||||
|
|
||||||
### prefer-stable <span>(root-only)</span>
|
### prefer-stable <span>([root-only](04-schema.md#root-package))</span>
|
||||||
|
|
||||||
When this is enabled, Composer will prefer more stable packages over unstable
|
When this is enabled, Composer will prefer more stable packages over unstable
|
||||||
ones when finding compatible stable packages is possible. If you require a
|
ones when finding compatible stable packages is possible. If you require a
|
||||||
|
@ -650,11 +683,11 @@ selected granted that the minimum-stability allows for it.
|
||||||
|
|
||||||
Use `"prefer-stable": true` to enable.
|
Use `"prefer-stable": true` to enable.
|
||||||
|
|
||||||
### repositories <span>(root-only)</span>
|
### repositories <span>([root-only](04-schema.md#root-package))</span>
|
||||||
|
|
||||||
Custom package repositories to use.
|
Custom package repositories to use.
|
||||||
|
|
||||||
By default composer just uses the packagist repository. By specifying
|
By default Composer just uses the packagist repository. By specifying
|
||||||
repositories you can get packages from elsewhere.
|
repositories you can get packages from elsewhere.
|
||||||
|
|
||||||
Repositories are not resolved recursively. You can only add them to your main
|
Repositories are not resolved recursively. You can only add them to your main
|
||||||
|
@ -663,14 +696,14 @@ ignored.
|
||||||
|
|
||||||
The following repository types are supported:
|
The following repository types are supported:
|
||||||
|
|
||||||
* **composer:** A composer repository is simply a `packages.json` file served
|
* **composer:** A Composer repository is simply a `packages.json` file served
|
||||||
via the network (HTTP, FTP, SSH), that contains a list of `composer.json`
|
via the network (HTTP, FTP, SSH), that contains a list of `composer.json`
|
||||||
objects with additional `dist` and/or `source` information. The `packages.json`
|
objects with additional `dist` and/or `source` information. The `packages.json`
|
||||||
file is loaded using a PHP stream. You can set extra options on that stream
|
file is loaded using a PHP stream. You can set extra options on that stream
|
||||||
using the `options` parameter.
|
using the `options` parameter.
|
||||||
* **vcs:** The version control system repository can fetch packages from git,
|
* **vcs:** The version control system repository can fetch packages from git,
|
||||||
svn and hg repositories.
|
svn and hg repositories.
|
||||||
* **pear:** With this you can import any pear repository into your composer
|
* **pear:** With this you can import any pear repository into your Composer
|
||||||
project.
|
project.
|
||||||
* **package:** If you depend on a project that does not have any support for
|
* **package:** If you depend on a project that does not have any support for
|
||||||
composer whatsoever you can define the package inline using a `package`
|
composer whatsoever you can define the package inline using a `package`
|
||||||
|
@ -702,7 +735,7 @@ Example:
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"type": "pear",
|
"type": "pear",
|
||||||
"url": "http://pear2.php.net"
|
"url": "https://pear2.php.net"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"type": "package",
|
"type": "package",
|
||||||
|
@ -714,7 +747,7 @@ Example:
|
||||||
"type": "zip"
|
"type": "zip"
|
||||||
},
|
},
|
||||||
"source": {
|
"source": {
|
||||||
"url": "http://smarty-php.googlecode.com/svn/",
|
"url": "https://smarty-php.googlecode.com/svn/",
|
||||||
"type": "svn",
|
"type": "svn",
|
||||||
"reference": "tags/Smarty_3_1_7/distribution/"
|
"reference": "tags/Smarty_3_1_7/distribution/"
|
||||||
}
|
}
|
||||||
|
@ -729,80 +762,12 @@ will look from the first to the last repository, and pick the first match.
|
||||||
By default Packagist is added last which means that custom repositories can
|
By default Packagist is added last which means that custom repositories can
|
||||||
override packages from it.
|
override packages from it.
|
||||||
|
|
||||||
### config <span>(root-only)</span>
|
### config <span>([root-only](04-schema.md#root-package))</span>
|
||||||
|
|
||||||
A set of configuration options. It is only used for projects.
|
A set of configuration options. It is only used for projects. See
|
||||||
|
[Config](06-config.md) for a description of each individual option.
|
||||||
|
|
||||||
The following options are supported:
|
### scripts <span>([root-only](04-schema.md#root-package))</span>
|
||||||
|
|
||||||
* **process-timeout:** Defaults to `300`. The duration processes like git clones
|
|
||||||
can run before Composer assumes they died out. You may need to make this
|
|
||||||
higher if you have a slow connection or huge vendors.
|
|
||||||
* **use-include-path:** Defaults to `false`. If true, the Composer autoloader
|
|
||||||
will also look for classes in the PHP include path.
|
|
||||||
* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or
|
|
||||||
`auto`. This option allows you to set the install method Composer will prefer to
|
|
||||||
use.
|
|
||||||
* **github-protocols:** Defaults to `["git", "https", "ssh"]`. A list of protocols to
|
|
||||||
use when cloning from github.com, in priority order. You can reconfigure it to
|
|
||||||
for example prioritize the https protocol if you are behind a proxy or have somehow
|
|
||||||
bad performances with the git protocol.
|
|
||||||
* **github-oauth:** A list of domain names and oauth keys. For example using
|
|
||||||
`{"github.com": "oauthtoken"}` as the value of this option will use `oauthtoken`
|
|
||||||
to access private repositories on github and to circumvent the low IP-based
|
|
||||||
rate limiting of their API.
|
|
||||||
[Read more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
|
|
||||||
on how to get an OAuth token for GitHub.
|
|
||||||
* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a
|
|
||||||
different directory if you want to.
|
|
||||||
* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they
|
|
||||||
will be symlinked into this directory.
|
|
||||||
* **cache-dir:** Defaults to `$home/cache` on unix systems and
|
|
||||||
`C:\Users\<user>\AppData\Local\Composer` on Windows. Stores all the caches
|
|
||||||
used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home).
|
|
||||||
* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives
|
|
||||||
of packages.
|
|
||||||
* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata
|
|
||||||
for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`.
|
|
||||||
* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for
|
|
||||||
loading VCS repository metadata for the `git`/`hg` types and to speed up installs.
|
|
||||||
* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all
|
|
||||||
dist (zip, tar, ..) packages that it downloads. Those are purged after six
|
|
||||||
months of being unused by default. This option allows you to tweak this
|
|
||||||
duration (in seconds) or disable it completely by setting it to 0.
|
|
||||||
* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all
|
|
||||||
dist (zip, tar, ..) packages that it downloads. When the garbage collection
|
|
||||||
is periodically ran, this is the maximum size the cache will be able to use.
|
|
||||||
Older (less used) files will be removed first until the cache fits.
|
|
||||||
* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader
|
|
||||||
will not be prepended to existing autoloaders. This is sometimes required to fix
|
|
||||||
interoperability issues with other autoloaders.
|
|
||||||
* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for
|
|
||||||
the generated Composer autoloader. When null a random one will be generated.
|
|
||||||
* **optimize-autoloader** Defaults to `false`. Always optimize when dumping
|
|
||||||
the autoloader.
|
|
||||||
* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in
|
|
||||||
github mode. This is used for GitHub Enterprise setups.
|
|
||||||
* **notify-on-install:** Defaults to `true`. Composer allows repositories to
|
|
||||||
define a notification URL, so that they get notified whenever a package from
|
|
||||||
that repository is installed. This option allows you to disable that behaviour.
|
|
||||||
* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or
|
|
||||||
`"stash"`. This option allows you to set the default style of handling dirty
|
|
||||||
updates when in non-interactive mode. `true` will always discard changes in
|
|
||||||
vendors, while `"stash"` will try to stash and reapply. Use this for CI
|
|
||||||
servers or deploy scripts if you tend to have modified vendors.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"config": {
|
|
||||||
"bin-dir": "bin"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### scripts <span>(root-only)</span>
|
|
||||||
|
|
||||||
Composer allows you to hook into various parts of the installation process
|
Composer allows you to hook into various parts of the installation process
|
||||||
through the use of scripts.
|
through the use of scripts.
|
||||||
|
@ -858,4 +823,39 @@ The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`,
|
||||||
|
|
||||||
Optional.
|
Optional.
|
||||||
|
|
||||||
|
### non-feature-branches
|
||||||
|
|
||||||
|
A list of regex patterns of branch names that are non-numeric (e.g. "latest" or something),
|
||||||
|
that will NOT be handled as feature branches. This is an array of strings.
|
||||||
|
|
||||||
|
If you have non-numeric branch names, for example like "latest", "current", "latest-stable"
|
||||||
|
or something, that do not look like a version number, then Composer handles such branches
|
||||||
|
as feature branches. This means it searches for parent branches, that look like a version
|
||||||
|
or ends at special branches (like master) and the root package version number becomes the
|
||||||
|
version of the parent branch or at least master or something.
|
||||||
|
|
||||||
|
To handle non-numeric named branches as versions instead of searching for a parent branch
|
||||||
|
with a valid version or special branch name like master, you can set patterns for branch
|
||||||
|
names, that should be handled as dev version branches.
|
||||||
|
|
||||||
|
This is really helpful when you have dependencies using "self.version", so that not dev-master,
|
||||||
|
but the same branch is installed (in the example: latest-testing).
|
||||||
|
|
||||||
|
An example:
|
||||||
|
|
||||||
|
If you have a testing branch, that is heavily maintained during a testing phase and is
|
||||||
|
deployed to your staging environment, normally "composer show -s" will give you `versions : * dev-master`.
|
||||||
|
|
||||||
|
If you configure `latest-.*` as a pattern for non-feature-branches like this:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"non-feature-branches": ["latest-.*"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Then "composer show -s" will give you `versions : * dev-latest-testing`.
|
||||||
|
|
||||||
|
Optional.
|
||||||
|
|
||||||
← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) →
|
← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) →
|
||||||
|
|
|
@ -6,7 +6,7 @@ of repositories are available, and how they work.
|
||||||
## Concepts
|
## Concepts
|
||||||
|
|
||||||
Before we look at the different types of repositories that exist, we need to
|
Before we look at the different types of repositories that exist, we need to
|
||||||
understand some of the basic concepts that composer is built on.
|
understand some of the basic concepts that Composer is built on.
|
||||||
|
|
||||||
### Package
|
### Package
|
||||||
|
|
||||||
|
@ -16,8 +16,8 @@ code, but in theory it could be anything. And it contains a package
|
||||||
description which has a name and a version. The name and the version are used
|
description which has a name and a version. The name and the version are used
|
||||||
to identify the package.
|
to identify the package.
|
||||||
|
|
||||||
In fact, internally composer sees every version as a separate package. While
|
In fact, internally Composer sees every version as a separate package. While
|
||||||
this distinction does not matter when you are using composer, it's quite
|
this distinction does not matter when you are using Composer, it's quite
|
||||||
important when you want to change it.
|
important when you want to change it.
|
||||||
|
|
||||||
In addition to the name and the version, there is useful metadata. The information
|
In addition to the name and the version, there is useful metadata. The information
|
||||||
|
@ -103,7 +103,7 @@ It may include any of the other fields specified in the [schema](04-schema.md).
|
||||||
|
|
||||||
#### notify-batch
|
#### notify-batch
|
||||||
|
|
||||||
The `notify-batch` field allows you to specify an URL that will be called
|
The `notify-batch` field allows you to specify a URL that will be called
|
||||||
every time a user installs a package. The URL can be either an absolute path
|
every time a user installs a package. The URL can be either an absolute path
|
||||||
(that will use the same domain as the repository) or a fully qualified URL.
|
(that will use the same domain as the repository) or a fully qualified URL.
|
||||||
|
|
||||||
|
@ -122,7 +122,7 @@ JSON request body:
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"downloads": [
|
"downloads": [
|
||||||
{"name": "monolog/monolog", "version": "1.2.1.0"},
|
{"name": "monolog/monolog", "version": "1.2.1.0"}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
@ -216,7 +216,7 @@ repository.
|
||||||
|
|
||||||
The `packages.json` file is loaded using a PHP stream. You can set extra options
|
The `packages.json` file is loaded using a PHP stream. You can set extra options
|
||||||
on that stream using the `options` parameter. You can set any valid PHP stream
|
on that stream using the `options` parameter. You can set any valid PHP stream
|
||||||
context option. See [Context options and parameters](http://php.net/manual/en/context.php)
|
context option. See [Context options and parameters](https://php.net/manual/en/context.php)
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
### VCS
|
### VCS
|
||||||
|
@ -234,7 +234,7 @@ project to use the patched version. If the library is on GitHub (this is the
|
||||||
case most of the time), you can simply fork it there and push your changes to
|
case most of the time), you can simply fork it there and push your changes to
|
||||||
your fork. After that you update the project's `composer.json`. All you have
|
your fork. After that you update the project's `composer.json`. All you have
|
||||||
to do is add your fork as a repository and update the version constraint to
|
to do is add your fork as a repository and update the version constraint to
|
||||||
point to your custom branch. For version constraint naming conventions see
|
point to your custom branch. Your custom branch name must be prefixed with `"dev-"`. For version constraint naming conventions see
|
||||||
[Libraries](02-libraries.md) for more information.
|
[Libraries](02-libraries.md) for more information.
|
||||||
|
|
||||||
Example assuming you patched monolog to fix a bug in the `bugfix` branch:
|
Example assuming you patched monolog to fix a bug in the `bugfix` branch:
|
||||||
|
@ -263,6 +263,10 @@ custom repository has priority over packagist. If you want to rename the
|
||||||
package, you should do so in the default (often master) branch and not in a
|
package, you should do so in the default (often master) branch and not in a
|
||||||
feature branch, since the package name is taken from the default branch.
|
feature branch, since the package name is taken from the default branch.
|
||||||
|
|
||||||
|
Also note that the override will not work if you change the `name` property
|
||||||
|
in your forked repository's composer.json file as this needs to match the
|
||||||
|
original for the override to work.
|
||||||
|
|
||||||
If other dependencies rely on the package you forked, it is possible to
|
If other dependencies rely on the package you forked, it is possible to
|
||||||
inline-alias it so that it matches a constraint that it otherwise would not.
|
inline-alias it so that it matches a constraint that it otherwise would not.
|
||||||
For more information [see the aliases article](articles/aliases.md).
|
For more information [see the aliases article](articles/aliases.md).
|
||||||
|
@ -293,8 +297,8 @@ The only requirement is the installation of SSH keys for a git client.
|
||||||
Git is not the only version control system supported by the VCS repository.
|
Git is not the only version control system supported by the VCS repository.
|
||||||
The following are supported:
|
The following are supported:
|
||||||
|
|
||||||
* **Git:** [git-scm.com](http://git-scm.com)
|
* **Git:** [git-scm.com](https://git-scm.com)
|
||||||
* **Subversion:** [subversion.apache.org](http://subversion.apache.org)
|
* **Subversion:** [subversion.apache.org](https://subversion.apache.org)
|
||||||
* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com)
|
* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com)
|
||||||
|
|
||||||
To get packages from these systems you need to have their respective clients
|
To get packages from these systems you need to have their respective clients
|
||||||
|
@ -312,7 +316,7 @@ should you need to specify one for whatever reason, you can use `git`, `svn` or
|
||||||
|
|
||||||
If you set the `no-api` key to `true` on a github repository it will clone the
|
If you set the `no-api` key to `true` on a github repository it will clone the
|
||||||
repository as it would with any other git repository instead of using the
|
repository as it would with any other git repository instead of using the
|
||||||
GitHub API. But unlike using the `git` driver directly, composer will still
|
GitHub API. But unlike using the `git` driver directly, Composer will still
|
||||||
attempt to use github's zip files.
|
attempt to use github's zip files.
|
||||||
|
|
||||||
#### Subversion Options
|
#### Subversion Options
|
||||||
|
@ -341,10 +345,41 @@ If you have no branches or tags directory you can disable them entirely by
|
||||||
setting the `branches-path` or `tags-path` to `false`.
|
setting the `branches-path` or `tags-path` to `false`.
|
||||||
|
|
||||||
If the package is in a sub-directory, e.g. `/trunk/foo/bar/composer.json` and
|
If the package is in a sub-directory, e.g. `/trunk/foo/bar/composer.json` and
|
||||||
`/tags/1.0/foo/bar/composer.json`, then you can make composer access it by
|
`/tags/1.0/foo/bar/composer.json`, then you can make Composer access it by
|
||||||
setting the `"package-path"` option to the sub-directory, in this example it
|
setting the `"package-path"` option to the sub-directory, in this example it
|
||||||
would be `"package-path": "foo/bar/"`.
|
would be `"package-path": "foo/bar/"`.
|
||||||
|
|
||||||
|
If you have a private Subversion repository you can save credentials in the
|
||||||
|
http-basic section of your config (See [Schema](04-schema.md)):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"http-basic": {
|
||||||
|
"svn.example.org": {
|
||||||
|
"username": "username",
|
||||||
|
"password": "password"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If your Subversion client is configured to store credentials by default these
|
||||||
|
credentials will be saved for the current user and existing saved credentials
|
||||||
|
for this server will be overwritten. To change this behavior by setting the
|
||||||
|
`"svn-cache-credentials"` option in your repository configuration:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"repositories": [
|
||||||
|
{
|
||||||
|
"type": "vcs",
|
||||||
|
"url": "http://svn.example.org/projectA/",
|
||||||
|
"svn-cache-credentials": false
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
### PEAR
|
### PEAR
|
||||||
|
|
||||||
It is possible to install packages from any PEAR channel by using the `pear`
|
It is possible to install packages from any PEAR channel by using the `pear`
|
||||||
|
@ -358,7 +393,7 @@ Example using `pear2.php.net`:
|
||||||
"repositories": [
|
"repositories": [
|
||||||
{
|
{
|
||||||
"type": "pear",
|
"type": "pear",
|
||||||
"url": "http://pear2.php.net"
|
"url": "https://pear2.php.net"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"require": {
|
"require": {
|
||||||
|
@ -431,7 +466,7 @@ and `IntermediatePackage` from a Github repository:
|
||||||
|
|
||||||
### Package
|
### Package
|
||||||
|
|
||||||
If you want to use a project that does not support composer through any of the
|
If you want to use a project that does not support Composer through any of the
|
||||||
means above, you still can define the package yourself by using a `package`
|
means above, you still can define the package yourself by using a `package`
|
||||||
repository.
|
repository.
|
||||||
|
|
||||||
|
@ -486,7 +521,7 @@ Typically you would leave the source part off, as you don't really need it.
|
||||||
While you will probably want to put your packages on packagist most of the time,
|
While you will probably want to put your packages on packagist most of the time,
|
||||||
there are some use cases for hosting your own repository.
|
there are some use cases for hosting your own repository.
|
||||||
|
|
||||||
* **Private company packages:** If you are part of a company that uses composer
|
* **Private company packages:** If you are part of a company that uses Composer
|
||||||
for their packages internally, you might want to keep those packages private.
|
for their packages internally, you might want to keep those packages private.
|
||||||
|
|
||||||
* **Separate ecosystem:** If you have a project which has its own ecosystem,
|
* **Separate ecosystem:** If you have a project which has its own ecosystem,
|
||||||
|
@ -502,19 +537,22 @@ There are a few tools that can help you create a `composer` repository.
|
||||||
### Packagist
|
### Packagist
|
||||||
|
|
||||||
The underlying application used by packagist is open source. This means that you
|
The underlying application used by packagist is open source. This means that you
|
||||||
can just install your own copy of packagist, re-brand, and use it. It's really
|
can technically install your own copy of packagist. However it is not a
|
||||||
quite straight-forward to do. However due to its size and complexity, for most
|
supported use case and changes will happen without caring for third parties
|
||||||
small and medium sized companies willing to track a few packages will be better
|
using the code.
|
||||||
off using Satis.
|
|
||||||
|
|
||||||
Packagist is a Symfony2 application, and it is [available on
|
Packagist is a Symfony2 application, and it is [available on
|
||||||
GitHub](https://github.com/composer/packagist). It uses composer internally and
|
GitHub](https://github.com/composer/packagist). It uses Composer internally and
|
||||||
acts as a proxy between VCS repositories and the composer users. It holds a list
|
acts as a proxy between VCS repositories and the Composer users. It holds a list
|
||||||
of all VCS packages, periodically re-crawls them, and exposes them as a composer
|
of all VCS packages, periodically re-crawls them, and exposes them as a Composer
|
||||||
repository.
|
repository.
|
||||||
|
|
||||||
To set your own copy, simply follow the instructions from the [packagist
|
### Toran Proxy
|
||||||
github repository](https://github.com/composer/packagist).
|
|
||||||
|
[Toran Proxy](https://toranproxy.com/) is a web app much like Packagist but
|
||||||
|
providing private package hosting as well as mirroring/proxying of GitHub and
|
||||||
|
packagist.org. Check its homepage and the [Satis/Toran Proxy article](articles/handling-private-packages-with-satis.md)
|
||||||
|
for more information.
|
||||||
|
|
||||||
### Satis
|
### Satis
|
||||||
|
|
||||||
|
@ -568,6 +606,49 @@ imported. When an archive with a newer version is added in the artifact folder
|
||||||
and you run `update`, that version will be imported as well and Composer will
|
and you run `update`, that version will be imported as well and Composer will
|
||||||
update to the latest version.
|
update to the latest version.
|
||||||
|
|
||||||
|
### Path
|
||||||
|
|
||||||
|
In addition to the artifact repository, you can use the path one, which allows
|
||||||
|
you to depend on a relative directory. This can be especially useful when dealing
|
||||||
|
with monolith repositories.
|
||||||
|
|
||||||
|
For instance, if you have the following directory structure in your repository:
|
||||||
|
```
|
||||||
|
- apps
|
||||||
|
\_ my-app
|
||||||
|
\_ composer.json
|
||||||
|
- packages
|
||||||
|
\_ my-package
|
||||||
|
\_ composer.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, to add the package `my/package` as a dependency, in your `apps/my-app/composer.json`
|
||||||
|
file, you can use the following configuration:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"repositories": [
|
||||||
|
{
|
||||||
|
"type": "path",
|
||||||
|
"url": "../../packages/my-package"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"require": {
|
||||||
|
"my/package": "*"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The local package will be symlinked if possible, in which case the output in
|
||||||
|
the console will read `Symlinked from ../../packages/my-package`. If symlinking
|
||||||
|
is _not_ possible the package will be copied. In that case, the console will
|
||||||
|
output `Mirrored from ../../packages/my-package`.
|
||||||
|
|
||||||
|
Instead of using a relative path, an absolute path can also be used.
|
||||||
|
|
||||||
|
> **Note:** Repository paths can also contain wildcards like ``*`` and ``?``.
|
||||||
|
> For details, see the [PHP glob function](http://php.net/glob).
|
||||||
|
|
||||||
## Disabling Packagist
|
## Disabling Packagist
|
||||||
|
|
||||||
You can disable the default Packagist repository by adding this to your
|
You can disable the default Packagist repository by adding this to your
|
||||||
|
@ -583,4 +664,4 @@ You can disable the default Packagist repository by adding this to your
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
← [Schema](04-schema.md) | [Community](06-community.md) →
|
← [Schema](04-schema.md) | [Config](06-config.md) →
|
||||||
|
|
|
@ -0,0 +1,189 @@
|
||||||
|
# Config
|
||||||
|
|
||||||
|
This chapter will describe the `config` section of the `composer.json`
|
||||||
|
[schema](04-schema.md).
|
||||||
|
|
||||||
|
## process-timeout
|
||||||
|
|
||||||
|
Defaults to `300`. The duration processes like git clones can run before
|
||||||
|
Composer assumes they died out. You may need to make this higher if you have a
|
||||||
|
slow connection or huge vendors.
|
||||||
|
|
||||||
|
## use-include-path
|
||||||
|
|
||||||
|
Defaults to `false`. If `true`, the Composer autoloader will also look for classes
|
||||||
|
in the PHP include path.
|
||||||
|
|
||||||
|
## preferred-install
|
||||||
|
|
||||||
|
Defaults to `auto` and can be any of `source`, `dist` or `auto`. This option
|
||||||
|
allows you to set the install method Composer will prefer to use.
|
||||||
|
|
||||||
|
## store-auths
|
||||||
|
|
||||||
|
What to do after prompting for authentication, one of: `true` (always store),
|
||||||
|
`false` (do not store) and `"prompt"` (ask every time), defaults to `"prompt"`.
|
||||||
|
|
||||||
|
## github-protocols
|
||||||
|
|
||||||
|
Defaults to `["git", "https", "ssh"]`. A list of protocols to use when cloning
|
||||||
|
from github.com, in priority order. You can reconfigure it to for example
|
||||||
|
prioritize the https protocol if you are behind a proxy or have somehow bad
|
||||||
|
performances with the git protocol.
|
||||||
|
|
||||||
|
## github-oauth
|
||||||
|
|
||||||
|
A list of domain names and oauth keys. For example using `{"github.com":
|
||||||
|
"oauthtoken"}` as the value of this option will use `oauthtoken` to access
|
||||||
|
private repositories on github and to circumvent the low IP-based rate limiting
|
||||||
|
of their API. [Read
|
||||||
|
more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) on how to get
|
||||||
|
an OAuth token for GitHub.
|
||||||
|
|
||||||
|
## http-basic
|
||||||
|
|
||||||
|
A list of domain names and username/passwords to authenticate against them. For
|
||||||
|
example using `{"example.org": {"username": "alice", "password": "foo"}` as the
|
||||||
|
value of this option will let Composer authenticate against example.org.
|
||||||
|
|
||||||
|
> **Note:** Authentication-related config options like `http-basic` and
|
||||||
|
> `github-oauth` can also be specified inside a `auth.json` file that goes
|
||||||
|
> besides your `composer.json`. That way you can gitignore it and every
|
||||||
|
> developer can place their own credentials in there.
|
||||||
|
|
||||||
|
## platform
|
||||||
|
|
||||||
|
Lets you fake platform packages (PHP and extensions) so that you can emulate a
|
||||||
|
production env or define your target platform in the config. Example: `{"php":
|
||||||
|
"5.4", "ext-something": "4.0"}`.
|
||||||
|
|
||||||
|
## vendor-dir
|
||||||
|
|
||||||
|
Defaults to `vendor`. You can install dependencies into a different directory if
|
||||||
|
you want to. `$HOME` and `~` will be replaced by your home directory's path in
|
||||||
|
vendor-dir and all `*-dir` options below.
|
||||||
|
|
||||||
|
## bin-dir
|
||||||
|
|
||||||
|
Defaults to `vendor/bin`. If a project includes binaries, they will be symlinked
|
||||||
|
into this directory.
|
||||||
|
|
||||||
|
## cache-dir
|
||||||
|
|
||||||
|
Defaults to `$COMPOSER_HOME/cache` on unix systems and
|
||||||
|
`C:\Users\<user>\AppData\Local\Composer` on Windows. Stores all the caches used
|
||||||
|
by Composer. See also [COMPOSER_HOME](03-cli.md#composer-home).
|
||||||
|
|
||||||
|
## cache-files-dir
|
||||||
|
|
||||||
|
Defaults to `$cache-dir/files`. Stores the zip archives of packages.
|
||||||
|
|
||||||
|
## cache-repo-dir
|
||||||
|
|
||||||
|
Defaults to `$cache-dir/repo`. Stores repository metadata for the `composer`
|
||||||
|
type and the VCS repos of type `svn`, `github` and `bitbucket`.
|
||||||
|
|
||||||
|
## cache-vcs-dir
|
||||||
|
|
||||||
|
Defaults to `$cache-dir/vcs`. Stores VCS clones for loading VCS repository
|
||||||
|
metadata for the `git`/`hg` types and to speed up installs.
|
||||||
|
|
||||||
|
## cache-files-ttl
|
||||||
|
|
||||||
|
Defaults to `15552000` (6 months). Composer caches all dist (zip, tar, ..)
|
||||||
|
packages that it downloads. Those are purged after six months of being unused by
|
||||||
|
default. This option allows you to tweak this duration (in seconds) or disable
|
||||||
|
it completely by setting it to 0.
|
||||||
|
|
||||||
|
## cache-files-maxsize
|
||||||
|
|
||||||
|
Defaults to `300MiB`. Composer caches all dist (zip, tar, ..) packages that it
|
||||||
|
downloads. When the garbage collection is periodically ran, this is the maximum
|
||||||
|
size the cache will be able to use. Older (less used) files will be removed
|
||||||
|
first until the cache fits.
|
||||||
|
|
||||||
|
## bin-compat
|
||||||
|
|
||||||
|
Defaults to `auto`. Determines the compatibility of the binaries to be installed.
|
||||||
|
If it is `auto` then Composer only installs .bat proxy files when on Windows. If
|
||||||
|
set to `full` then both .bat files for Windows and scripts for Unix-based
|
||||||
|
operating systems will be installed for each binary. This is mainly useful if you
|
||||||
|
run Composer inside a linux VM but still want the .bat proxies available for use
|
||||||
|
in the Windows host OS.
|
||||||
|
|
||||||
|
## prepend-autoloader
|
||||||
|
|
||||||
|
Defaults to `true`. If `false`, the Composer autoloader will not be prepended to
|
||||||
|
existing autoloaders. This is sometimes required to fix interoperability issues
|
||||||
|
with other autoloaders.
|
||||||
|
|
||||||
|
## autoloader-suffix
|
||||||
|
|
||||||
|
Defaults to `null`. String to be used as a suffix for the generated Composer
|
||||||
|
autoloader. When null a random one will be generated.
|
||||||
|
|
||||||
|
## optimize-autoloader
|
||||||
|
|
||||||
|
Defaults to `false`. If `true`, always optimize when dumping the autoloader.
|
||||||
|
|
||||||
|
## sort-packages
|
||||||
|
|
||||||
|
Defaults to `false`. If `true`, the `require` command keeps packages sorted
|
||||||
|
by name in `composer.json` when adding a new package.
|
||||||
|
|
||||||
|
## classmap-authoritative
|
||||||
|
|
||||||
|
Defaults to `false`. If `true`, the Composer autoloader will only load classes
|
||||||
|
from the classmap. Implies `optimize-autoloader`.
|
||||||
|
|
||||||
|
## github-domains
|
||||||
|
|
||||||
|
Defaults to `["github.com"]`. A list of domains to use in github mode. This is
|
||||||
|
used for GitHub Enterprise setups.
|
||||||
|
|
||||||
|
## github-expose-hostname
|
||||||
|
|
||||||
|
Defaults to `true`. If `false`, the OAuth tokens created to access the
|
||||||
|
github API will have a date instead of the machine hostname.
|
||||||
|
|
||||||
|
## gitlab-domains
|
||||||
|
|
||||||
|
Defaults to `["gitlab.com"]`. A list of domains of GitLab servers.
|
||||||
|
This is used if you use the `gitlab` repository type.
|
||||||
|
|
||||||
|
## notify-on-install
|
||||||
|
|
||||||
|
Defaults to `true`. Composer allows repositories to define a notification URL,
|
||||||
|
so that they get notified whenever a package from that repository is installed.
|
||||||
|
This option allows you to disable that behaviour.
|
||||||
|
|
||||||
|
## discard-changes
|
||||||
|
|
||||||
|
Defaults to `false` and can be any of `true`, `false` or `"stash"`. This option
|
||||||
|
allows you to set the default style of handling dirty updates when in
|
||||||
|
non-interactive mode. `true` will always discard changes in vendors, while
|
||||||
|
`"stash"` will try to stash and reapply. Use this for CI servers or deploy
|
||||||
|
scripts if you tend to have modified vendors.
|
||||||
|
|
||||||
|
## archive-format
|
||||||
|
|
||||||
|
Defaults to `tar`. Composer allows you to add a default archive format when the
|
||||||
|
workflow needs to create a dedicated archiving format.
|
||||||
|
|
||||||
|
## archive-dir
|
||||||
|
|
||||||
|
Defaults to `.`. Composer allows you to add a default archive directory when the
|
||||||
|
workflow needs to create a dedicated archiving format. Or for easier development
|
||||||
|
between modules.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"config": {
|
||||||
|
"archive-dir": "/home/user/.composer/repo"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
← [Repositories](05-repositories.md) | [Community](07-community.md) →
|
|
@ -1,12 +1,14 @@
|
||||||
# Community
|
# Community
|
||||||
|
|
||||||
There are many people using composer already, and quite a few of them are
|
There are many people using Composer already, and quite a few of them are
|
||||||
contributing.
|
contributing.
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
If you would like to contribute to composer, please read the
|
If you would like to contribute to Composer, please read the
|
||||||
[README](https://github.com/composer/composer).
|
[README](https://github.com/composer/composer) and
|
||||||
|
[CONTRIBUTING](https://github.com//composer/composer/blob/master/CONTRIBUTING.md)
|
||||||
|
documents.
|
||||||
|
|
||||||
The most important guidelines are described as follows:
|
The most important guidelines are described as follows:
|
||||||
|
|
||||||
|
@ -17,18 +19,17 @@ The most important guidelines are described as follows:
|
||||||
> Fork the project, create a feature branch, and send us a pull request.
|
> Fork the project, create a feature branch, and send us a pull request.
|
||||||
>
|
>
|
||||||
> To ensure a consistent code base, you should make sure the code follows
|
> To ensure a consistent code base, you should make sure the code follows
|
||||||
> the [Coding Standards](http://symfony.com/doc/2.0/contributing/code/standards.html)
|
> the [PSR-2 Coding Standards](http://www.php-fig.org/psr/psr-2/).
|
||||||
> which we borrowed from Symfony.
|
|
||||||
|
|
||||||
## IRC / mailing list
|
## IRC / mailing list
|
||||||
|
|
||||||
Mailing lists for [user support](http://groups.google.com/group/composer-users) and
|
Mailing lists for [user support](https://groups.google.com/group/composer-users) and
|
||||||
[development](http://groups.google.com/group/composer-dev).
|
[development](https://groups.google.com/group/composer-dev).
|
||||||
|
|
||||||
IRC channels are on irc.freenode.org: [#composer](irc://irc.freenode.org/composer)
|
IRC channels are on irc.freenode.org: [#composer](irc://irc.freenode.org/composer)
|
||||||
for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development.
|
for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development.
|
||||||
|
|
||||||
Stack Overflow has a growing collection of
|
Stack Overflow has a growing collection of
|
||||||
[Composer related questions](http://stackoverflow.com/questions/tagged/composer-php).
|
[Composer related questions](https://stackoverflow.com/questions/tagged/composer-php).
|
||||||
|
|
||||||
← [Repositories](05-repositories.md)
|
← [Config](06-config.md)
|
Loading…
Reference in New Issue