Merge pull request #15 from siroccoicode/master
change PSR-0 with PSR-4
This commit is contained in:
成武
GitHub
commit
1b898c7841
@ -241,7 +241,7 @@ $loader = require 'vendor/autoload.php';
|
||||
$loader->add('Acme\\Test\\', __DIR__);
|
||||
```
|
||||
|
||||
除了 PSR-4 自动加载，classmap 也是支持的。这允许类被自动加载，即使不符合 PSR-0 规范。详细请查看 [自动加载-参考](04-schema.md#autoload)。
|
||||
除了 PSR-4 自动加载，Composer 同时支持PSR-0、classmap 和 files自动加载。详细请查看 [自动加载-参考](04-schema.md#autoload)。
|
||||
|
||||
> **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_*.php` 文件，它返回一个关联数组，你可以通过这个关联数组配置自己的 autoloader。
|
||||
|
||||
|
||||
@ -1,54 +1,41 @@
|
||||
# Introduction
|
||||
|
||||
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
|
||||
project for you.
|
||||
the libraries your project depends on and it will manage (install/update) them
|
||||
for you.
|
||||
|
||||
## Dependency management
|
||||
|
||||
Composer is not a package manager. Yes, it deals with "packages" or libraries, but
|
||||
it manages them on a per-project basis, installing them in a directory (e.g. `vendor`)
|
||||
inside your project. By default it will never install anything globally. Thus,
|
||||
it is a dependency manager.
|
||||
Composer is **not** a package manager in the same sense as Yum or Apt are. Yes,
|
||||
it deals with "packages" or libraries, but it manages them on a per-project
|
||||
basis, installing them in a directory (e.g. `vendor`) inside your project. By
|
||||
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/)
|
||||
and ruby's [bundler](http://gembundler.com/). But there has not been such a tool
|
||||
for PHP.
|
||||
This idea is not new and Composer is strongly inspired by node's
|
||||
[npm](https://npmjs.org/) and ruby's [bundler](http://bundler.io/).
|
||||
|
||||
The problem that Composer solves is this:
|
||||
Suppose:
|
||||
|
||||
a) You have a project that depends on a number of 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).
|
||||
|
||||
## 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`.
|
||||
See the [Basic usage](01-basic-usage.md) chapter for more details on declaring
|
||||
dependencies.
|
||||
|
||||
## System Requirements
|
||||
|
||||
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
|
||||
incompatibilities.
|
||||
flags are also required, but when using the installer you will be warned about
|
||||
any incompatibilities.
|
||||
|
||||
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.
|
||||
@ -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,
|
||||
Linux and OSX.
|
||||
|
||||
## Installation - *nix
|
||||
## Installation - Linux / Unix / OSX
|
||||
|
||||
### 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
|
||||
|
||||
To actually get Composer, we need to do two things. The first one is installing
|
||||
Composer (again, this means downloading it into your project):
|
||||
Installing Composer locally is a matter of just running the installer in your
|
||||
project directory:
|
||||
|
||||
```sh
|
||||
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
|
||||
```
|
||||
|
||||
This will just check a few PHP settings and then download `composer.phar` to
|
||||
your working directory. This file is the Composer binary. It is a PHAR (PHP
|
||||
archive), which is an archive format for PHP which can be run on the command
|
||||
line, amongst other things.
|
||||
The installer will just check a few PHP settings and then download
|
||||
`composer.phar` to your working directory. This file is the Composer binary. It
|
||||
is a PHAR (PHP archive), which is an archive format for PHP which can be run on
|
||||
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`
|
||||
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
|
||||
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
|
||||
|
||||
You can place this file anywhere you wish. If you put it in your `PATH`,
|
||||
you can access it globally. On unixy systems you can even make it
|
||||
executable and invoke it without `php`.
|
||||
You can place the Composer PHAR anywhere you wish. If you put it in a directory
|
||||
that is part of your `PATH`, you can access it globally. On unixy systems you
|
||||
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
|
||||
curl -sS https://getcomposer.org/installer | php
|
||||
mv composer.phar /usr/local/bin/composer
|
||||
```
|
||||
|
||||
> **Note:** If the above fails due to permissions, run the `mv` line
|
||||
> again with sudo.
|
||||
> **Note:** If the above fails due to permissions, run the `mv` line again
|
||||
> with sudo.
|
||||
|
||||
Then, just run `composer` in order to run Composer instead of `php composer.phar`.
|
||||
|
||||
#### Globally (on OSX via homebrew)
|
||||
|
||||
Composer is part of the homebrew-php project.
|
||||
A quick copy-paste version including sudo:
|
||||
|
||||
```sh
|
||||
brew update
|
||||
brew tap josegonzalez/homebrew-php
|
||||
brew tap homebrew/versions
|
||||
brew install php55-intl
|
||||
brew install josegonzalez/php/composer
|
||||
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=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
|
||||
|
||||
### Using the Installer
|
||||
|
||||
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),
|
||||
it will install the latest Composer version and set up your PATH so that you can
|
||||
just call `composer` from any directory in your command line.
|
||||
Download and run
|
||||
[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will
|
||||
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
|
||||
|
||||
Change to a directory on your `PATH` and run the install snippet to download
|
||||
composer.phar:
|
||||
`composer.phar`:
|
||||
|
||||
```sh
|
||||
C:\Users\username>cd C:\bin
|
||||
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`:
|
||||
|
||||
@ -146,6 +154,8 @@ Create a new `composer.bat` file alongside `composer.phar`:
|
||||
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:
|
||||
|
||||
```sh
|
||||
@ -155,38 +165,7 @@ Composer version 27d8904
|
||||
|
||||
## Using Composer
|
||||
|
||||
We will now use Composer to install the dependencies of the project. If you
|
||||
don't have a `composer.json` file in the current directory please skip to the
|
||||
[Basic Usage](01-basic-usage.md) chapter.
|
||||
Now that you've installed Composer, you are ready to use it! Head on over to the
|
||||
next chapter for a short and simple demonstration.
|
||||
|
||||
To resolve and download dependencies, run the `install` command:
|
||||
|
||||
```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) →
|
||||
[Basic usage](01-basic-usage.md) →
|
||||
|
||||
@ -1,29 +1,13 @@
|
||||
# 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
|
||||
curl -sS https://getcomposer.org/installer | php
|
||||
```
|
||||
|
||||
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
|
||||
> ```
|
||||
> **Note:** for the sake of simplicity, this introduction will assume you
|
||||
> have performed a [local](00-intro.md#locally) install of Composer.
|
||||
|
||||
## `composer.json`: Project Setup
|
||||
|
||||
@ -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
|
||||
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 first (and often only) thing you specify in `composer.json` is the
|
||||
`require` key. You're simply telling Composer which packages your project
|
||||
depends on.
|
||||
[`require`](04-schema.md#require) key. You're simply telling Composer which
|
||||
packages your project depends on.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -48,15 +29,16 @@ depends on.
|
||||
}
|
||||
```
|
||||
|
||||
As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`)
|
||||
to **package versions** (e.g. `1.0.*`).
|
||||
As you can see, [`require`](04-schema.md#require) takes an object that maps
|
||||
**package names** (e.g. `monolog/monolog`) to **version constraints** (e.g.
|
||||
`1.0.*`).
|
||||
|
||||
### Package Names
|
||||
|
||||
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
|
||||
two different people to create a library named `json`, which would then just be
|
||||
named `igorw/json` and `seldaek/json`.
|
||||
will be identical - the vendor name just exists to prevent naming clashes. It
|
||||
allows two different people to create a library named `json`, which would then
|
||||
just be named `igorw/json` and `seldaek/json`.
|
||||
|
||||
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
|
||||
@ -66,46 +48,26 @@ smaller decoupled parts.
|
||||
|
||||
### Package Versions
|
||||
|
||||
In the previous example we were requiring version `1.0.*` of monolog. This
|
||||
means any version in the `1.0` development branch. It would match `1.0.0`,
|
||||
`1.0.2` or `1.0.20`.
|
||||
In the previous example we were requiring version
|
||||
[`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of
|
||||
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.
|
||||
|
||||
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.
|
||||
Version constraints can be specified in several ways, read
|
||||
[versions](articles/versions.md) for more in-depth information on this topic.
|
||||
|
||||
### Stability
|
||||
|
||||
By default only stable releases are taken into consideration. If you would like
|
||||
to also get RC, beta, alpha or dev versions of your dependencies you can do
|
||||
so using [stability flags](04-schema.md#package-links). To change that for all
|
||||
packages instead of doing per dependency you can also use the
|
||||
By default only stable releases are taken into consideration. If you would
|
||||
like to also get RC, beta, alpha or dev versions of your dependencies you can
|
||||
do so using [stability flags](04-schema.md#package-links). To change that for
|
||||
all packages instead of doing per dependency you can also use the
|
||||
[minimum-stability](04-schema.md#minimum-stability) setting.
|
||||
|
||||
## Installing Dependencies
|
||||
|
||||
To fetch the defined dependencies into your local project, just run the
|
||||
`install` command of `composer.phar`.
|
||||
To install the defined dependencies for your project, just run the
|
||||
[`install`](03-cli.md#install) command.
|
||||
|
||||
```sh
|
||||
php composer.phar install
|
||||
@ -114,14 +76,14 @@ php composer.phar install
|
||||
This will find the latest version of `monolog/monolog` that matches the
|
||||
supplied version constraint and download it into the `vendor` directory.
|
||||
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
|
||||
> `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.
|
||||
|
||||
Another thing that the `install` command does is it adds a `composer.lock`
|
||||
file into your project root.
|
||||
You will notice the [`install`](03-cli.md#install) command also created a
|
||||
`composer.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
|
||||
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,
|
||||
and if it is, it downloads the versions specified there (regardless of what `composer.json`
|
||||
says).
|
||||
This is important because the [`install`](03-cli.md#install) command checks
|
||||
if a lock file is present, and if it is, it downloads the versions specified
|
||||
there (regardless of what `composer.json` says).
|
||||
|
||||
This means that anyone who sets up the project will download the exact
|
||||
same version of the dependencies. Your CI server, production machines, other
|
||||
developers in your team, everything and everyone runs on the same dependencies, which
|
||||
mitigates the potential for bugs affecting only some parts of the deployments. Even if you
|
||||
develop alone, in six months when reinstalling the project you can feel confident the
|
||||
dependencies installed are still working even if your dependencies released
|
||||
many new versions since then.
|
||||
This means that anyone who sets up the project will download the exact same
|
||||
version of the dependencies. Your CI server, production machines, other
|
||||
developers in your team, everything and everyone runs on the same dependencies,
|
||||
which mitigates the potential for bugs affecting only some parts of the
|
||||
deployments. Even if you develop alone, in six months when reinstalling the
|
||||
project you can feel confident the dependencies installed are still working even
|
||||
if your dependencies released many new versions since then.
|
||||
|
||||
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
|
||||
automatically. To update to the new version, use `update` command. This will fetch
|
||||
the latest matching versions (according to your `composer.json` file) and also update
|
||||
the lock file with the new version.
|
||||
This means that if any of the dependencies get a new version, you won't get the
|
||||
updates automatically. To update to the new version, use the
|
||||
[`update`](03-cli.md#update) command. This will fetch the latest matching
|
||||
versions (according to your `composer.json` file) and also update the lock file
|
||||
with the new version.
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
@ -161,47 +128,45 @@ If you only want to install or update one dependency, you can whitelist them:
|
||||
php composer.phar update monolog/monolog [...]
|
||||
```
|
||||
|
||||
> **Note:** For libraries it is not necessarily recommended to commit the lock file,
|
||||
> see also: [Libraries - Lock file](02-libraries.md#lock-file).
|
||||
> **Note:** For libraries it is not necessary to commit the lock
|
||||
> file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
|
||||
|
||||
## Packagist
|
||||
|
||||
[Packagist](https://packagist.org/) is the main Composer repository. A Composer
|
||||
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
|
||||
means that you can automatically `require` any package that is available
|
||||
there.
|
||||
means that you can automatically `require` any package that is available 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.
|
||||
|
||||
Any open source project using Composer should publish their packages on
|
||||
packagist. A library doesn't need to be on packagist to be used by Composer,
|
||||
but it makes life quite a bit simpler.
|
||||
Any open source project using Composer is recommended to publish their packages
|
||||
on Packagist. A library doesn't need to be on Packagist to be used by Composer,
|
||||
but it enables discovery and adoption by other developers more quickly.
|
||||
|
||||
## Autoloading
|
||||
|
||||
For libraries that specify autoload information, Composer generates a
|
||||
`vendor/autoload.php` file. You can simply include this file and you
|
||||
will get autoloading for free.
|
||||
`vendor/autoload.php` file. You can simply include this file and you will get
|
||||
autoloading for free.
|
||||
|
||||
```php
|
||||
require 'vendor/autoload.php';
|
||||
require __DIR__ . '/vendor/autoload.php';
|
||||
```
|
||||
|
||||
This makes it really easy to use third party code. For example: If your
|
||||
project depends on monolog, you can just start using classes from it, and they
|
||||
will be autoloaded.
|
||||
This makes it really easy to use third party code. For example: If your project
|
||||
depends on Monolog, you can just start using classes from it, and they will be
|
||||
autoloaded.
|
||||
|
||||
```php
|
||||
$log = new Monolog\Logger('name');
|
||||
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
|
||||
|
||||
$log->addWarning('Foo');
|
||||
```
|
||||
|
||||
You can even add your own code to the autoloader by adding an `autoload` field
|
||||
to `composer.json`.
|
||||
You can even add your own code to the autoloader by adding an
|
||||
[`autoload`](04-schema.md#autoload) field to `composer.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
|
||||
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
|
||||
the `vendor/autoload.php` file.
|
||||
After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run
|
||||
[`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
|
||||
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.
|
||||
|
||||
```php
|
||||
$loader = require 'vendor/autoload.php';
|
||||
$loader = require __DIR__ . '/vendor/autoload.php';
|
||||
$loader->add('Acme\\Test\\', __DIR__);
|
||||
```
|
||||
|
||||
In addition to PSR-4 autoloading, classmap is also supported. This allows
|
||||
classes to be autoloaded even if they do not conform to PSR-4. See the
|
||||
[autoload reference](04-schema.md#autoload) for more details.
|
||||
In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and
|
||||
files autoloading. See the [`autoload`](04-schema.md#autoload) reference for
|
||||
more information.
|
||||
|
||||
> **Note:** Composer provides its own autoloader. If you don't want to use
|
||||
that one, you can just include `vendor/composer/autoload_*.php` files,
|
||||
which return associative arrays allowing you to configure your own autoloader.
|
||||
> **Note:** Composer provides its own autoloader. If you don't want to use that
|
||||
> one, you can just include `vendor/composer/autoload_*.php` files, which return
|
||||
> associative arrays allowing you to configure your own autoloader.
|
||||
|
||||
← [Intro](00-intro.md) | [Libraries](02-libraries.md) →
|
||||
|
||||
@ -1,16 +1,17 @@
|
||||
# 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
|
||||
|
||||
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
|
||||
depends on other packages. The only difference between your project and
|
||||
libraries is that your project is a package without a name.
|
||||
package. When you add a [`require`](04-schema.md#require) to a project, you are
|
||||
making a package that depends on other packages. The only difference between
|
||||
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
|
||||
this by adding a `name` to `composer.json`:
|
||||
this by adding the [`name`](04-schema.md#name) property in `composer.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
|
||||
vendor name. Supplying a vendor name is mandatory.
|
||||
In this case the project name is `acme/hello-world`, where `acme` is the vendor
|
||||
name. Supplying a vendor name is mandatory.
|
||||
|
||||
> **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
|
||||
convention is all lowercase and dashes for word separation.
|
||||
> username is usually a good bet. While package names are case insensitive, the
|
||||
> convention is all lowercase and dashes for word separation.
|
||||
|
||||
## Platform packages
|
||||
|
||||
@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries.
|
||||
PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
|
||||
`openssl`, `pcre`, `uuid`, `xsl`.
|
||||
|
||||
You can use `composer show --platform` to get a list of your locally available
|
||||
platform packages.
|
||||
You can use [`show --platform`](03-cli.md#show) to get a list of your locally
|
||||
available platform packages.
|
||||
|
||||
## Specifying the version
|
||||
|
||||
You need to specify the package's version some way. When you publish your
|
||||
package on Packagist, it is able to infer the version from the VCS (git, svn,
|
||||
hg) information, so in that case you do not have to specify it, and it is
|
||||
recommended not to. See [tags](#tags) and [branches](#branches) to see how
|
||||
When you publish your package on Packagist, it is able to infer the version
|
||||
from the VCS (git, svn, hg) information. This means you don't have to
|
||||
explicitly declare it. Read [tags](#tags) and [branches](#branches) to see how
|
||||
version numbers are extracted from these.
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
of `-patch`, `-alpha`, `-beta` or `-RC`. The suffixes can also be followed by
|
||||
a number.
|
||||
created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix of
|
||||
`-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffix can also
|
||||
be followed by a number.
|
||||
|
||||
Here are a few examples of valid tag names:
|
||||
|
||||
- 1.0.0
|
||||
- v1.0.0
|
||||
- 1.10.5-RC1
|
||||
- v4.4.4beta2
|
||||
- v4.4.4-beta2
|
||||
- v2.0.0-alpha
|
||||
- v2.0.4-p1
|
||||
|
||||
> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions)
|
||||
> in a `require` statement has to be specified without prefix
|
||||
> (e.g. tag `v1.0.0` will result in version `1.0.0`).
|
||||
> **Note:** Even if your tag is prefixed with `v`, a
|
||||
> [version constraint](01-basic-usage.md#package-versions) in a `require`
|
||||
> statement has to be specified without prefix (e.g. tag `v1.0.0` will result
|
||||
> in version `1.0.0`).
|
||||
|
||||
### Branches
|
||||
|
||||
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
|
||||
a branch `2.0` will get a version `2.0.x-dev` (the `.x` is added for technical
|
||||
reasons, to make sure it is recognized as a branch, a `2.0.x` branch would also
|
||||
be valid and be turned into `2.0.x-dev` as well. If the branch does not look
|
||||
like a version, it will be `dev-{branchname}`. `master` results in a
|
||||
`dev-master` version.
|
||||
name looks like a version, the version will be `{branchname}-dev`. For example,
|
||||
the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for
|
||||
technical reasons, to make sure it is recognized as a branch). The `2.0.x`
|
||||
branch would also be valid and be turned into `2.0.x-dev` as well. If the
|
||||
branch does not look like a version, it will be `dev-{branchname}`. `master`
|
||||
results in a `dev-master` version.
|
||||
|
||||
Here are some examples of version branch names:
|
||||
|
||||
@ -116,8 +117,8 @@ Here are some examples of version branch names:
|
||||
### Aliases
|
||||
|
||||
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
|
||||
the packages.
|
||||
`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in
|
||||
all the packages.
|
||||
|
||||
See [Aliases](articles/aliases.md) for more information.
|
||||
|
||||
@ -133,7 +134,7 @@ the `.gitignore`.
|
||||
|
||||
## 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
|
||||
example we will publish the `acme/hello-world` library on GitHub under
|
||||
`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).
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
Composer, and it is enabled by default. Anything that is published on
|
||||
packagist is available automatically through Composer. Since monolog
|
||||
[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend
|
||||
on it without having to specify any additional repositories.
|
||||
Packagist is available automatically through Composer. Since
|
||||
[Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we
|
||||
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
|
||||
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
|
||||
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.
|
||||
You simply visit [Packagist](https://packagist.org) and hit the "Submit". This
|
||||
will prompt you to sign up if you haven't already, and then allows you to
|
||||
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) →
|
||||
|
||||
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
### Options
|
||||
|
||||
* **--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
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
installing a package, you can use `--dry-run`. This will simulate the
|
||||
installation and show you what would happen.
|
||||
* **--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-plugins:** Disables plugins.
|
||||
* **--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
|
||||
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`.
|
||||
|
||||
## update
|
||||
|
||||
@ -121,9 +128,13 @@ php composer.phar update vendor/*
|
||||
|
||||
* **--prefer-source:** Install packages from `source` 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.
|
||||
* **--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-plugins:** Disables plugins.
|
||||
* **--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
|
||||
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`.
|
||||
* **--lock:** Only updates the lock file hash to suppress warning about the
|
||||
lock file being out of date.
|
||||
* **--with-dependencies** Add also all dependencies of whitelisted packages to the whitelist.
|
||||
So all packages with their dependencies are updated recursively.
|
||||
* **--with-dependencies:** Add also all dependencies of whitelisted packages to the whitelist.
|
||||
* **--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
|
||||
|
||||
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
|
||||
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-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`.
|
||||
* **--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-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.
|
||||
* **--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
|
||||
|
||||
@ -222,8 +275,8 @@ name : monolog/monolog
|
||||
versions : master-dev, 1.0.2, 1.0.1, 1.0.0, 1.0.0-RC1
|
||||
type : library
|
||||
names : monolog/monolog
|
||||
source : [git] http://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
||||
dist : [zip] http://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
||||
source : [git] https://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
||||
dist : [zip] https://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
||||
license : MIT
|
||||
|
||||
autoload
|
||||
@ -246,6 +299,28 @@ php composer.phar show monolog/monolog 1.0.2
|
||||
* **--installed (-i):** List the packages that are installed.
|
||||
* **--platform (-p):** List only platform packages (php & extensions).
|
||||
* **--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
|
||||
|
||||
@ -256,11 +331,11 @@ should be included in the listing. By default both are used.
|
||||
```sh
|
||||
php composer.phar depends --link-type=require monolog/monolog
|
||||
|
||||
nrk/monolog-fluent
|
||||
poc/poc
|
||||
propel/propel
|
||||
symfony/monolog-bridge
|
||||
symfony/symfony
|
||||
nrk/monolog-fluent requires monolog/monolog (~1.8)
|
||||
poc/poc requires monolog/monolog (^1.6)
|
||||
propel/propel requires monolog/monolog (1.*)
|
||||
symfony/monolog-bridge requires monolog/monolog (>=1.2)
|
||||
symfony/symfony requires monolog/monolog (~1)
|
||||
```
|
||||
|
||||
### Options
|
||||
@ -280,7 +355,9 @@ php composer.phar validate
|
||||
|
||||
### 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
|
||||
|
||||
@ -305,7 +382,7 @@ vendor/seld/jsonlint:
|
||||
|
||||
## 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.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
```sh
|
||||
@ -328,11 +405,12 @@ sudo composer self-update
|
||||
### Options
|
||||
|
||||
* **--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
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
@ -347,22 +425,23 @@ php composer.phar config --list
|
||||
configuration value. For settings that can take an array of values (like
|
||||
`github-protocols`), more than one setting-value arguments are allowed.
|
||||
|
||||
See the [config schema section](04-schema.md#config) for valid configuration
|
||||
options.
|
||||
See the [Config](06-config.md) chapter for valid configuration options.
|
||||
|
||||
### Options
|
||||
|
||||
* **--global (-g):** Operate on the global config file located at
|
||||
`$COMPOSER_HOME/config.json` by default. Without this option, this command
|
||||
affects the local composer.json file or a file specified by `--file`.
|
||||
`$COMPOSER_HOME/config.json` by default. Without this option, this command
|
||||
affects the local composer.json file or a file specified by `--file`.
|
||||
* **--editor (-e):** Open the local composer.json file using in a text editor as
|
||||
defined by the `EDITOR` env variable. With the `--global` option, this opens
|
||||
the global config file.
|
||||
defined by the `EDITOR` env variable. With the `--global` option, this opens
|
||||
the global config file.
|
||||
* **--unset:** Remove the configuration element named by `setting-key`.
|
||||
* **--list (-l):** Show the list of current config variables. With the `--global`
|
||||
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
|
||||
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
|
||||
|
||||
@ -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:
|
||||
|
||||
```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
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
project. This is mostly useful if you run the command in non-interactive
|
||||
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
|
||||
|
||||
@ -438,17 +520,33 @@ performance.
|
||||
* **--optimize (-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`.
|
||||
* **--no-dev:** Disables autoload-dev rules.
|
||||
|
||||
## clear-cache
|
||||
|
||||
Deletes all content from Composer's cache directories.
|
||||
|
||||
## licenses
|
||||
|
||||
Lists the name, version and license of every package installed. Use
|
||||
`--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
|
||||
|
||||
### Options
|
||||
|
||||
* **--no-dev:** Disable dev mode
|
||||
* **--list:** List user defined scripts
|
||||
|
||||
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
|
||||
|
||||
@ -502,6 +600,8 @@ For example:
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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`.
|
||||
|
||||
### COMPOSER_BIN_DIR
|
||||
@ -519,7 +619,7 @@ directory to something other than `vendor/bin`.
|
||||
|
||||
### 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.
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
### HTTPS_PROXY_REQUEST_FULLURI
|
||||
|
||||
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.
|
||||
|
||||
### 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
|
||||
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`
|
||||
when you run the `install` and `update` commands.
|
||||
|
||||
This file allows you to set [configuration](04-schema.md#config) and
|
||||
[repositories](05-repositories.md) for the user's projects.
|
||||
This file allows you to set [repositories](05-repositories.md) and
|
||||
[configuration](06-config.md) for the user's projects.
|
||||
|
||||
In case global configuration matches _local_ configuration, the _local_
|
||||
configuration in the project's `composer.json` always wins.
|
||||
|
||||
### COMPOSER_CACHE_DIR
|
||||
|
||||
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.
|
||||
The `COMPOSER_CACHE_DIR` var allows you to change the Composer cache directory,
|
||||
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
|
||||
`C:\Users\<user>\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows.
|
||||
|
||||
### 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).
|
||||
|
||||
### 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
|
||||
|
||||
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.
|
||||
|
||||
### 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) →
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# composer.json
|
||||
# The composer.json Schema
|
||||
|
||||
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
|
||||
`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.
|
||||
> 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
|
||||
@ -54,8 +51,8 @@ The version of the package. In most cases this is not required and should
|
||||
be omitted (see below).
|
||||
|
||||
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
|
||||
RC suffixes can also be followed by a number.
|
||||
of `-dev`, `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`.
|
||||
The patch, alpha, beta and RC suffixes can also be followed by a number.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -67,6 +64,7 @@ Examples:
|
||||
- 1.0.0-alpha3
|
||||
- 1.0.0-beta2
|
||||
- 1.0.0-RC5
|
||||
- v2.0.4-p1
|
||||
|
||||
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
|
||||
@ -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
|
||||
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`.
|
||||
- **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
|
||||
|
||||
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.
|
||||
|
||||
@ -234,11 +232,12 @@ Various information to get support about the project.
|
||||
Support information includes the following:
|
||||
|
||||
* **email:** Email address for support.
|
||||
* **issues:** URL to the Issue Tracker.
|
||||
* **forum:** URL to the Forum.
|
||||
* **wiki:** URL to the Wiki.
|
||||
* **issues:** URL to the issue tracker.
|
||||
* **forum:** URL to the forum.
|
||||
* **wiki:** URL to the wiki.
|
||||
* **irc:** IRC channel for support, as irc://server/channel.
|
||||
* **source:** URL to browse or download the sources.
|
||||
* **docs:** URL to the documentation.
|
||||
|
||||
An example:
|
||||
|
||||
@ -270,7 +269,7 @@ Example:
|
||||
|
||||
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
|
||||
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
|
||||
@ -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
|
||||
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
|
||||
|
||||
Lists packages required by this package. The package will not be installed
|
||||
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
|
||||
tests, etc. The dev requirements of the root package are installed by default.
|
||||
@ -345,10 +358,10 @@ dependencies from being installed.
|
||||
Lists packages that conflict with this version of this package. They
|
||||
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
|
||||
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.
|
||||
|
||||
#### replace
|
||||
|
||||
@ -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
|
||||
simply list it in `provide`.
|
||||
|
||||
### suggest
|
||||
#### suggest
|
||||
|
||||
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
|
||||
@ -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.
|
||||
|
||||
@ -626,7 +659,7 @@ To do that, `autoload` and `target-dir` are defined as follows:
|
||||
|
||||
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
|
||||
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`,
|
||||
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
|
||||
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.
|
||||
|
||||
### repositories <span>(root-only)</span>
|
||||
### repositories <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
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 are not resolved recursively. You can only add them to your main
|
||||
@ -663,14 +696,14 @@ ignored.
|
||||
|
||||
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`
|
||||
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
|
||||
using the `options` parameter.
|
||||
* **vcs:** The version control system repository can fetch packages from git,
|
||||
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.
|
||||
* **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`
|
||||
@ -702,7 +735,7 @@ Example:
|
||||
},
|
||||
{
|
||||
"type": "pear",
|
||||
"url": "http://pear2.php.net"
|
||||
"url": "https://pear2.php.net"
|
||||
},
|
||||
{
|
||||
"type": "package",
|
||||
@ -714,7 +747,7 @@ Example:
|
||||
"type": "zip"
|
||||
},
|
||||
"source": {
|
||||
"url": "http://smarty-php.googlecode.com/svn/",
|
||||
"url": "https://smarty-php.googlecode.com/svn/",
|
||||
"type": "svn",
|
||||
"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
|
||||
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:
|
||||
|
||||
* **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>
|
||||
### scripts <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
Composer allows you to hook into various parts of the installation process
|
||||
through the use of scripts.
|
||||
@ -858,4 +823,39 @@ The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`,
|
||||
|
||||
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) →
|
||||
|
||||
@ -6,7 +6,7 @@ of repositories are available, and how they work.
|
||||
## Concepts
|
||||
|
||||
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
|
||||
|
||||
@ -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
|
||||
to identify the package.
|
||||
|
||||
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
|
||||
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
|
||||
important when you want to change it.
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
(that will use the same domain as the repository) or a fully qualified URL.
|
||||
|
||||
@ -122,7 +122,7 @@ JSON request body:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
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.
|
||||
|
||||
### 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
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
inline-alias it so that it matches a constraint that it otherwise would not.
|
||||
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.
|
||||
The following are supported:
|
||||
|
||||
* **Git:** [git-scm.com](http://git-scm.com)
|
||||
* **Subversion:** [subversion.apache.org](http://subversion.apache.org)
|
||||
* **Git:** [git-scm.com](https://git-scm.com)
|
||||
* **Subversion:** [subversion.apache.org](https://subversion.apache.org)
|
||||
* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com)
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
#### 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`.
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
It is possible to install packages from any PEAR channel by using the `pear`
|
||||
@ -358,7 +393,7 @@ Example using `pear2.php.net`:
|
||||
"repositories": [
|
||||
{
|
||||
"type": "pear",
|
||||
"url": "http://pear2.php.net"
|
||||
"url": "https://pear2.php.net"
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
@ -431,7 +466,7 @@ and `IntermediatePackage` from a Github repository:
|
||||
|
||||
### 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`
|
||||
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,
|
||||
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.
|
||||
|
||||
* **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
|
||||
|
||||
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
|
||||
quite straight-forward to do. However due to its size and complexity, for most
|
||||
small and medium sized companies willing to track a few packages will be better
|
||||
off using Satis.
|
||||
can technically install your own copy of packagist. However it is not a
|
||||
supported use case and changes will happen without caring for third parties
|
||||
using the code.
|
||||
|
||||
Packagist is a Symfony2 application, and it is [available on
|
||||
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
|
||||
of all VCS packages, periodically re-crawls them, and exposes them as a composer
|
||||
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
|
||||
of all VCS packages, periodically re-crawls them, and exposes them as a Composer
|
||||
repository.
|
||||
|
||||
To set your own copy, simply follow the instructions from the [packagist
|
||||
github repository](https://github.com/composer/packagist).
|
||||
### Toran Proxy
|
||||
|
||||
[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
|
||||
|
||||
@ -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
|
||||
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
|
||||
|
||||
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) →
|
||||
|
||||
189
en-back/06-config.md
Normal file
189
en-back/06-config.md
Normal file
@ -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
|
||||
|
||||
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
|
||||
|
||||
If you would like to contribute to composer, please read the
|
||||
[README](https://github.com/composer/composer).
|
||||
If you would like to contribute to Composer, please read the
|
||||
[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:
|
||||
|
||||
@ -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.
|
||||
>
|
||||
> 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)
|
||||
> which we borrowed from Symfony.
|
||||
> the [PSR-2 Coding Standards](http://www.php-fig.org/psr/psr-2/).
|
||||
|
||||
## IRC / mailing list
|
||||
|
||||
Mailing lists for [user support](http://groups.google.com/group/composer-users) and
|
||||
[development](http://groups.google.com/group/composer-dev).
|
||||
Mailing lists for [user support](https://groups.google.com/group/composer-users) and
|
||||
[development](https://groups.google.com/group/composer-dev).
|
||||
|
||||
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.
|
||||
|
||||
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…
x
Reference in New Issue
Block a user