iSharkFly-Docs
/
composer-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

sync for new version

This commit is contained in:
dongjiawei 2016-01-06 21:56:03 +08:00
parent f97aae1819
commit e16fcb9e19
8 changed files with 747 additions and 425 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

169
en-back/00-intro.md
View File

@ -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) →

186
en-back/01-basic-usage.md
View File

@ -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.
&larr; [Intro](00-intro.md) | [Libraries](02-libraries.md) &rarr;

86
en-back/02-libraries.md
View File

@ -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!
&larr; [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) &rarr;

198
en-back/03-cli.md
View File

@ -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.
&larr; [Libraries](02-libraries.md) | [Schema](04-schema.md) &rarr;

194
en-back/04-schema.md
View File

@ -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.
&larr; [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) &rarr;

131
en-back/05-repositories.md
View File

@ -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,
@ -494,7 +529,7 @@ there are some use cases for hosting your own repository.
might want to keep them separate to packagist. An example of this would be
wordpress plugins.
For hosting your own packages, a native `composer` type of repository is
For hosting your own packages, a native `composer` type of repository is
recommended, which provides the best performance.
There are a few tools that can help you create a `composer` repository.
@ -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
}
```
&larr; [Schema](04-schema.md) | [Community](06-community.md) &rarr;
&larr; [Schema](04-schema.md) | [Config](06-config.md) &rarr;

189
en-back/06-config.md Normal file
View 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"
}
}
```
&larr; [Repositories](05-repositories.md) | [Community](07-community.md) &rarr;

19
en-back/06-community.md → en-back/07-community.md
View File

@ -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).
&larr; [Repositories](05-repositories.md)
&larr; [Config](06-config.md)