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

Add code-fences to examples for syntax highlighting

pull/3010/head
Jordi Boggiano 2014-05-19 12:17:07 +02:00
parent 0c343f925a
commit 0c85ca426d
14 changed files with 976 additions and 719 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
doc/00-intro.md
View File

@ -33,11 +33,13 @@ 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.
{
"require": {
"monolog/monolog": "1.2.*"
}
```json
{
"require": {
"monolog/monolog": "1.2.*"
}
}
```
We are simply stating that our project requires some `monolog/monolog` package,
any version beginning with `1.2`.
@ -63,12 +65,16 @@ Linux and OSX.
To actually get Composer, we need to do two things. The first one is installing
Composer (again, this means downloading it into your project):
$ curl -sS https://getcomposer.org/installer | php
```sh
curl -sS https://getcomposer.org/installer | php
```
> **Note:** If the above fails for some reason, you can download the installer
> with `php` instead:
$ php -r "readfile('https://getcomposer.org/installer');" | php
```sh
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
@ -78,7 +84,9 @@ line, amongst other things.
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):
$ curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
```sh
curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
```
#### Globally
@ -88,8 +96,10 @@ executable and invoke it without `php`.
You can run these commands to easily access `composer` from anywhere on your system:
$ curl -sS https://getcomposer.org/installer | php
$ mv composer.phar /usr/local/bin/composer
```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.
@ -123,21 +133,25 @@ just call `composer` from any directory in your command line.
Change to a directory on your `PATH` and run the install snippet to download
composer.phar:
C:\Users\username>cd C:\bin
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
```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
Create a new `composer.bat` file alongside `composer.phar`:
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
```sh
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
```
Close your current terminal. Test usage with a new terminal:
C:\Users\username>composer -V
Composer version 27d8904
C:\Users\username>
```sh
C:\Users\username>composer -V
Composer version 27d8904
```
## Using Composer
@ -147,12 +161,16 @@ don't have a `composer.json` file in the current directory please skip to the
To resolve and download dependencies, run the `install` command:
$ php composer.phar install
```sh
php composer.phar install
```
If you did a global install and do not have the phar in that directory
run this instead:
$ composer install
```sh
composer install
```
Following the [example above](#declaring-dependencies), this will download
monolog into the `vendor/monolog/monolog` directory.
@ -164,7 +182,9 @@ 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:
require 'vendor/autoload.php';
```php
require 'vendor/autoload.php';
```
Woah! Now start using monolog! To keep learning more about Composer, keep
reading the "Basic Usage" chapter.

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

@ -4,20 +4,26 @@
To install Composer, you just need to download the `composer.phar` executable.
$ curl -sS https://getcomposer.org/installer | php
```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`:
$ php composer.phar
```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`.
>
> $ curl -sS https://getcomposer.org/installer | php -- --help
> ```sh
> curl -sS https://getcomposer.org/installer | php -- --help
> ```
## `composer.json`: Project Setup
@ -34,11 +40,13 @@ 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": {
"monolog/monolog": "1.0.*"
}
```json
{
"require": {
"monolog/monolog": "1.0.*"
}
}
```
As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`)
to **package versions** (e.g. `1.0.*`).
@ -99,7 +107,9 @@ packages instead of doing per dependency you can also use the
To fetch the defined dependencies into your local project, just run the
`install` command of `composer.phar`.
$ php composer.phar install
```sh
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.
@ -141,11 +151,15 @@ automatically. To update to the new version, use `update` command. This will fet
the latest matching versions (according to your `composer.json` file) and also update
the lock file with the new version.
$ php composer.phar update
```sh
php composer.phar update
```
If you only want to install or update one dependency, you can whitelist them:
$ php composer.phar update monolog/monolog [...]
```sh
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).
@ -171,25 +185,31 @@ 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.
require 'vendor/autoload.php';
```php
require '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.
$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
```php
$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->addWarning('Foo');
$log->addWarning('Foo');
```
You can even add your own code to the autoloader by adding an `autoload` field
to `composer.json`.
{
"autoload": {
"psr-4": {"Acme\\": "src/"}
}
```json
{
"autoload": {
"psr-4": {"Acme\\": "src/"}
}
}
```
Composer will register a [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader
for the `Acme` namespace.
@ -205,8 +225,10 @@ 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.
$loader = require 'vendor/autoload.php';
$loader->add('Acme\\Test\\', __DIR__);
```php
$loader = require '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

72
doc/02-libraries.md
View File

@ -12,12 +12,14 @@ 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`:
{
"name": "acme/hello-world",
"require": {
"monolog/monolog": "1.0.*"
}
```json
{
"name": "acme/hello-world",
"require": {
"monolog/monolog": "1.0.*"
}
}
```
In this case the project name is `acme/hello-world`, where `acme` is the
vendor name. Supplying a vendor name is mandatory.
@ -62,9 +64,11 @@ version numbers are extracted from these.
If you are creating packages by hand and really have to specify it explicitly,
you can just add a `version` field:
{
"version": "1.0.0"
}
```json
{
"version": "1.0.0"
}
```
> **Note:** You should avoid specifying the version field explicitly, because
> for tags the value must match the tag name.
@ -78,12 +82,12 @@ a number.
Here are a few examples of valid tag names:
1.0.0
v1.0.0
1.10.5-RC1
v4.4.4beta2
v2.0.0-alpha
v2.0.4-p1
- 1.0.0
- v1.0.0
- 1.10.5-RC1
- v4.4.4beta2
- 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
@ -101,9 +105,9 @@ like a version, it will be `dev-{branchname}`. `master` results in a
Here are some examples of version branch names:
1.x
1.0 (equals 1.0.x)
1.1.x
- 1.x
- 1.0 (equals 1.0.x)
- 1.1.x
> **Note:** When you install a development version, it will be automatically
> pulled from its `source`. See the [`install`](03-cli.md#install) command
@ -140,12 +144,14 @@ project locally. We will call it `acme/blog`. This blog will depend on
accomplish this by creating a new `blog` directory somewhere, containing a
`composer.json`:
{
"name": "acme/blog",
"require": {
"acme/hello-world": "dev-master"
}
```json
{
"name": "acme/blog",
"require": {
"acme/hello-world": "dev-master"
}
}
```
The name is not needed in this case, since we don't want to publish the blog
as a library. It is added here to clarify which `composer.json` is being
@ -155,18 +161,20 @@ Now we need to tell the blog app where to find the `hello-world` dependency.
We do this by adding a package repository specification to the blog's
`composer.json`:
{
"name": "acme/blog",
"repositories": [
{
"type": "vcs",
"url": "https://github.com/username/hello-world"
}
],
"require": {
"acme/hello-world": "dev-master"
```json
{
"name": "acme/blog",
"repositories": [
{
"type": "vcs",
"url": "https://github.com/username/hello-world"
}
],
"require": {
"acme/hello-world": "dev-master"
}
}
```
For more details on how package repositories work and what other types are
available, see [Repositories](05-repositories.md).

149
doc/03-cli.md
View File

@ -36,7 +36,9 @@ it a bit easier to do this.
When you run the command it will interactively ask you to fill in the fields,
while using some smart defaults.
$ php composer.phar init
```sh
php composer.phar init
```
### Options
@ -54,7 +56,9 @@ while using some smart defaults.
The `install` command reads the `composer.json` file from the current
directory, resolves the dependencies, and installs them into `vendor`.
$ php composer.phar install
```sh
php composer.phar install
```
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
@ -94,18 +98,24 @@ resolution.
In order to get the latest versions of the dependencies and to update the
`composer.lock` file, you should use the `update` command.
$ php composer.phar update
```sh
php composer.phar update
```
This will resolve all dependencies of the project and write the exact versions
into `composer.lock`.
If you just want to update a few packages and not all, you can list them as such:
$ php composer.phar update vendor/package vendor/package2
```sh
php composer.phar update vendor/package vendor/package2
```
You can also use wildcards to update a bunch of packages at once:
$ php composer.phar update vendor/*
```sh
php composer.phar update vendor/*
```
### Options
@ -131,7 +141,9 @@ You can also use wildcards to update a bunch of packages at once:
The `require` command adds new packages to the `composer.json` file from
the current directory.
$ php composer.phar require
```sh
php composer.phar require
```
After adding/changing the requirements, the modified requirements will be
installed or updated.
@ -139,7 +151,9 @@ installed or updated.
If you do not want to choose requirements interactively, you can just pass them
to the command.
$ php composer.phar require vendor/package:2.* vendor/package2:dev-master
```sh
php composer.phar require vendor/package:2.* vendor/package2:dev-master
```
### Options
@ -162,13 +176,17 @@ This can be used to install CLI utilities globally and if you add
`$COMPOSER_HOME/vendor/bin` to your `$PATH` environment variable. Here is an
example:
$ php composer.phar global require fabpot/php-cs-fixer:dev-master
```sh
php composer.phar global require fabpot/php-cs-fixer:dev-master
```
Now the `php-cs-fixer` binary is available globally (assuming you adjusted
your PATH). If you wish to update the binary later on you can just run a
global update:
$ php composer.phar global update
```sh
php composer.phar global update
```
## search
@ -176,7 +194,9 @@ The search command allows you to search through the current project's package
repositories. Usually this will be just packagist. You simply pass it the
terms you want to search for.
$ php composer.phar search monolog
```sh
php composer.phar search monolog
```
You can also search for more than one term by passing multiple arguments.
@ -188,32 +208,38 @@ You can also search for more than one term by passing multiple arguments.
To list all of the available packages, you can use the `show` command.
$ php composer.phar show
```sh
php composer.phar show
```
If you want to see the details of a certain package, you can pass the package
name.
$ php composer.phar show monolog/monolog
```sh
php composer.phar show monolog/monolog
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
license : MIT
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
license : MIT
autoload
psr-0
Monolog : src/
autoload
psr-0
Monolog : src/
requires
php >=5.3.0
requires
php >=5.3.0
```
You can even pass the package version, which will tell you the details of that
specific version.
$ php composer.phar show monolog/monolog 1.0.2
```sh
php composer.phar show monolog/monolog 1.0.2
```
### Options
@ -227,13 +253,15 @@ The `depends` command tells you which other packages depend on a certain
package. You can specify which link types (`require`, `require-dev`)
should be included in the listing. By default both are used.
$ php composer.phar depends --link-type=require monolog/monolog
```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
poc/poc
propel/propel
symfony/monolog-bridge
symfony/symfony
```
### Options
@ -246,7 +274,9 @@ You should always run the `validate` command before you commit your
`composer.json` file, and before you tag a release. It will check if your
`composer.json` is valid.
$ php composer.phar validate
```sh
php composer.phar validate
```
### Options
@ -258,31 +288,42 @@ If you often need to modify the code of your dependencies and they are
installed from source, the `status` command allows you to check if you have
local changes in any of them.
$ php composer.phar status
```sh
php composer.phar status
```
With the `--verbose` option you get some more information about what was
changed:
$ php composer.phar status -v
You have changes in the following dependencies:
vendor/seld/jsonlint:
M README.mdown
```sh
php composer.phar status -v
You have changes in the following dependencies:
vendor/seld/jsonlint:
M README.mdown
```
## 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.
$ php composer.phar self-update
```sh
php composer.phar self-update
```
If you would like to instead update to a specific release simply specify it:
$ composer self-update 1.0.0-alpha7
```sh
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)),
you may have to run the command with `root` privileges
$ sudo composer self-update
```sh
sudo composer self-update
```
### Options
@ -294,7 +335,9 @@ you may have to run the command with `root` privileges
The `config` command allows you to edit some basic composer settings in either
the local composer.json file or the global config.json file.
$ php composer.phar config --list
```sh
php composer.phar config --list
```
### Usage
@ -326,7 +369,9 @@ the global config file.
In addition to modifying the config section, the `config` command also supports making
changes to the repositories section by using it the following way:
$ php composer.phar config repositories.foo vcs http://github.com/foo/bar
```sh
php composer.phar config repositories.foo vcs http://github.com/foo/bar
```
## create-project
@ -347,7 +392,9 @@ provide a version as third argument, otherwise the latest version is used.
If the directory does not currently exist, it will be created during installation.
php composer.phar create-project doctrine/orm path 2.2.*
```sh
php composer.phar create-project doctrine/orm path 2.2.*
```
It is also possible to run the command without params in a directory with an
existing `composer.json` file to bootstrap a project.
@ -409,7 +456,9 @@ If you think you found a bug, or something is behaving strangely, you might
want to run the `diagnose` command to perform automated checks for many common
problems.
$ php composer.phar diagnose
```sh
php composer.phar diagnose
```
## archive
@ -417,7 +466,9 @@ This command is used to generate a zip/tar archive for a given package in a
given version. It can also be used to archive your entire project without
excluded/ignored files.
$ php composer.phar archive vendor/package 2.0.21 --format=zip
```sh
php composer.phar archive vendor/package 2.0.21 --format=zip
```
### Options
@ -429,7 +480,9 @@ excluded/ignored files.
To get more information about a certain command, just use `help`.
$ php composer.phar help install
```sh
php composer.phar help install
```
## Environment variables
@ -445,7 +498,9 @@ By setting the `COMPOSER` env variable it is possible to set the filename of
For example:
$ COMPOSER=composer-other.json php composer.phar install
```sh
COMPOSER=composer-other.json php composer.phar install
```
### COMPOSER_ROOT_VERSION

427
doc/04-schema.md
View File

@ -59,14 +59,14 @@ RC suffixes can also be followed by a number.
Examples:
1.0.0
1.0.2
1.1.0
0.2.5
1.0.0-dev
1.0.0-alpha3
1.0.0-beta2
1.0.0-RC5
- 1.0.0
- 1.0.2
- 1.1.0
- 0.2.5
- 1.0.0-dev
- 1.0.0-alpha3
- 1.0.0-beta2
- 1.0.0-RC5
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
@ -113,11 +113,11 @@ searching and filtering.
Examples:
logging
events
database
redis
templating
- logging
- events
- database
- redis
- templating
Optional.
@ -141,19 +141,19 @@ The license of the package. This can be either a string or an array of strings.
The recommended notation for the most common licenses is (alphabetical):
Apache-2.0
BSD-2-Clause
BSD-3-Clause
BSD-4-Clause
GPL-2.0
GPL-2.0+
GPL-3.0
GPL-3.0+
LGPL-2.1
LGPL-2.1+
LGPL-3.0
LGPL-3.0+
MIT
- Apache-2.0
- BSD-2-Clause
- BSD-3-Clause
- BSD-4-Clause
- GPL-2.0
- GPL-2.0+
- GPL-3.0
- GPL-3.0+
- LGPL-2.1
- LGPL-2.1+
- LGPL-3.0
- LGPL-3.0+
- 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/).
@ -162,28 +162,33 @@ For closed-source software, you may use `"proprietary"` as the license identifie
An Example:
{
"license": "MIT"
}
```json
{
"license": "MIT"
}
```
For a package, when there is a choice between licenses ("disjunctive license"),
multiple can be specified as array.
An Example for disjunctive licenses:
{
"license": [
"LGPL-2.1",
"GPL-3.0+"
]
}
```json
{
"license": [
"LGPL-2.1",
"GPL-3.0+"
]
}
```
Alternatively they can be separated with "or" and enclosed in parenthesis;
{
"license": "(LGPL-2.1 or GPL-3.0+)"
}
```json
{
"license": "(LGPL-2.1 or GPL-3.0+)"
}
```
Similarly when multiple licenses need to be applied ("conjunctive license"),
they should be separated with "and" and enclosed in parenthesis.
@ -201,22 +206,24 @@ Each author object can have following properties:
An example:
{
"authors": [
{
"name": "Nils Adermann",
"email": "naderman@naderman.de",
"homepage": "http://www.naderman.de",
"role": "Developer"
},
{
"name": "Jordi Boggiano",
"email": "j.boggiano@seld.be",
"homepage": "http://seld.be",
"role": "Developer"
}
]
}
```json
{
"authors": [
{
"name": "Nils Adermann",
"email": "naderman@naderman.de",
"homepage": "http://www.naderman.de",
"role": "Developer"
},
{
"name": "Jordi Boggiano",
"email": "j.boggiano@seld.be",
"homepage": "http://seld.be",
"role": "Developer"
}
]
}
```
Optional, but highly recommended.
@ -235,12 +242,14 @@ Support information includes the following:
An example:
{
"support": {
"email": "support@example.org",
"irc": "irc://irc.freenode.org/composer"
}
```json
{
"support": {
"email": "support@example.org",
"irc": "irc://irc.freenode.org/composer"
}
}
```
Optional.
@ -251,11 +260,13 @@ All of the following take an object which maps package names to
Example:
{
"require": {
"monolog/monolog": "1.0.*"
}
```json
{
"require": {
"monolog/monolog": "1.0.*"
}
}
```
All links are optional fields.
@ -267,24 +278,28 @@ allow unstable packages of a dependency for example.
Example:
{
"require": {
"monolog/monolog": "1.0.*@beta",
"acme/foo": "@dev"
}
```json
{
"require": {
"monolog/monolog": "1.0.*@beta",
"acme/foo": "@dev"
}
}
```
If one of your dependencies has a dependency on an unstable package you need to
explicitly require it as well, along with its sufficient stability flag.
Example:
{
"require": {
"doctrine/doctrine-fixtures-bundle": "dev-master",
"doctrine/data-fixtures": "@dev"
}
```json
{
"require": {
"doctrine/doctrine-fixtures-bundle": "dev-master",
"doctrine/data-fixtures": "@dev"
}
}
```
`require` and `require-dev` additionally support explicit references (i.e.
commit) for dev versions to make sure they are locked to a given state, even
@ -293,12 +308,14 @@ and append the reference with `#<ref>`.
Example:
{
"require": {
"monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7",
"acme/foo": "1.0.x-dev#abc123"
}
```json
{
"require": {
"monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7",
"acme/foo": "1.0.x-dev#abc123"
}
}
```
> **Note:** While this is convenient at times, it should not be how you use
> packages in the long term because it comes with a technical limitation. The
@ -370,11 +387,13 @@ and not version constraints.
Example:
{
"suggest": {
"monolog/monolog": "Allows more advanced logging of the application flow"
}
```json
{
"suggest": {
"monolog/monolog": "Allows more advanced logging of the application flow"
}
}
```
### autoload
@ -403,32 +422,38 @@ key => value array which may be found in the generated file
Example:
{
"autoload": {
"psr-4": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": ""
}
```json
{
"autoload": {
"psr-4": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": ""
}
}
}
```
If you need to search for a same prefix in multiple directories,
you can specify them as an array as such:
{
"autoload": {
"psr-4": { "Monolog\\": ["src/", "lib/"] }
}
```json
{
"autoload": {
"psr-4": { "Monolog\\": ["src/", "lib/"] }
}
}
```
If you want to have a fallback directory where any namespace will be looked for,
you can use an empty prefix like:
{
"autoload": {
"psr-4": { "": "src/" }
}
```json
{
"autoload": {
"psr-4": { "": "src/" }
}
}
```
#### PSR-0
@ -444,44 +469,52 @@ array which may be found in the generated file `vendor/composer/autoload_namespa
Example:
{
"autoload": {
"psr-0": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": "src/",
"Vendor_Namespace_": "src/"
}
```json
{
"autoload": {
"psr-0": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": "src/",
"Vendor_Namespace_": "src/"
}
}
}
```
If you need to search for a same prefix in multiple directories,
you can specify them as an array as such:
{
"autoload": {
"psr-0": { "Monolog\\": ["src/", "lib/"] }
}
```json
{
"autoload": {
"psr-0": { "Monolog\\": ["src/", "lib/"] }
}
}
```
The PSR-0 style is not limited to namespace declarations only but may be
specified right down to the class level. This can be useful for libraries with
only one class in the global namespace. If the php source file is also located
in the root of the package, for example, it may be declared like this:
{
"autoload": {
"psr-0": { "UniqueGlobalClass": "" }
}
```json
{
"autoload": {
"psr-0": { "UniqueGlobalClass": "" }
}
}
```
If you want to have a fallback directory where any namespace can be, you can
use an empty prefix like:
{
"autoload": {
"psr-0": { "": "src/" }
}
```json
{
"autoload": {
"psr-0": { "": "src/" }
}
}
```
#### Classmap
@ -496,11 +529,13 @@ to search for classes.
Example:
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
```json
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
}
```
#### Files
@ -510,11 +545,13 @@ that cannot be autoloaded by PHP.
Example:
{
"autoload": {
"files": ["src/MyLibrary/functions.php"]
}
```json
{
"autoload": {
"files": ["src/MyLibrary/functions.php"]
}
}
```
### autoload-dev <span>(root-only)</span>
@ -529,14 +566,16 @@ and to add it within the autoload-dev section.
Example:
{
"autoload": {
"psr-4": { "MyLibrary\\": "src/" }
},
"autoload-dev": {
"psr-4": { "MyLibrary\\Tests\\": "tests/" }
}
```json
{
"autoload": {
"psr-4": { "MyLibrary\\": "src/" }
},
"autoload-dev": {
"psr-4": { "MyLibrary\\Tests\\": "tests/" }
}
}
```
### include-path
@ -548,9 +587,11 @@ A list of paths which should get appended to PHP's `include_path`.
Example:
{
"include-path": ["lib/"]
}
```json
{
"include-path": ["lib/"]
}
```
Optional.
@ -574,12 +615,14 @@ it from `vendor/symfony/yaml`.
To do that, `autoload` and `target-dir` are defined as follows:
{
"autoload": {
"psr-0": { "Symfony\\Component\\Yaml\\": "" }
},
"target-dir": "Symfony/Component/Yaml"
}
```json
{
"autoload": {
"psr-0": { "Symfony\\Component\\Yaml\\": "" }
},
"target-dir": "Symfony/Component/Yaml"
}
```
Optional.
@ -637,47 +680,49 @@ For more information on any of these, see [Repositories](05-repositories.md).
Example:
{
"repositories": [
{
"type": "composer",
"url": "http://packages.example.com"
},
{
"type": "composer",
"url": "https://packages.example.com",
"options": {
"ssl": {
"verify_peer": "true"
}
}
},
{
"type": "vcs",
"url": "https://github.com/Seldaek/monolog"
},
{
"type": "pear",
"url": "http://pear2.php.net"
},
{
"type": "package",
"package": {
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
},
"source": {
"url": "http://smarty-php.googlecode.com/svn/",
"type": "svn",
"reference": "tags/Smarty_3_1_7/distribution/"
}
```json
{
"repositories": [
{
"type": "composer",
"url": "http://packages.example.com"
},
{
"type": "composer",
"url": "https://packages.example.com",
"options": {
"ssl": {
"verify_peer": "true"
}
}
]
}
},
{
"type": "vcs",
"url": "https://github.com/Seldaek/monolog"
},
{
"type": "pear",
"url": "http://pear2.php.net"
},
{
"type": "package",
"package": {
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
},
"source": {
"url": "http://smarty-php.googlecode.com/svn/",
"type": "svn",
"reference": "tags/Smarty_3_1_7/distribution/"
}
}
}
]
}
```
> **Note:** Order is significant here. When looking for a package, Composer
will look from the first to the last repository, and pick the first match.
@ -749,11 +794,13 @@ The following options are supported:
Example:
{
"config": {
"bin-dir": "bin"
}
```json
{
"config": {
"bin-dir": "bin"
}
}
```
### scripts <span>(root-only)</span>
@ -769,7 +816,9 @@ Arbitrary extra data for consumption by `scripts`.
This can be virtually anything. To access it from within a script event
handler, you can do:
$extra = $event->getComposer()->getPackage()->getExtra();
```php
$extra = $event->getComposer()->getPackage()->getExtra();
```
Optional.
@ -796,11 +845,13 @@ The following options are supported:
Example:
{
"archive": {
"exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
}
```json
{
"archive": {
"exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
}
}
```
The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`,
`/foo/my.test` but it will exclude `/foo/bar/any`, `/foo/baz`, and `/my.test`.

336
doc/05-repositories.md
View File

@ -66,16 +66,18 @@ repository URL would be `example.org`.
The only required field is `packages`. The JSON structure is as follows:
{
"packages": {
"vendor/package-name": {
"dev-master": { @composer.json },
"1.0.x-dev": { @composer.json },
"0.0.1": { @composer.json },
"1.0.0": { @composer.json }
}
```json
{
"packages": {
"vendor/package-name": {
"dev-master": { @composer.json },
"1.0.x-dev": { @composer.json },
"0.0.1": { @composer.json },
"1.0.0": { @composer.json }
}
}
}
```
The `@composer.json` marker would be the contents of the `composer.json` from
that package version including as a minimum:
@ -86,14 +88,16 @@ that package version including as a minimum:
Here is a minimal package definition:
{
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
}
```json
{
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
}
}
```
It may include any of the other fields specified in the [schema](04-schema.md).
@ -105,19 +109,23 @@ every time a user installs a package. The URL can be either an absolute path
An example value:
{
"notify-batch": "/downloads/"
}
```json
{
"notify-batch": "/downloads/"
}
```
For `example.org/packages.json` containing a `monolog/monolog` package, this
would send a `POST` request to `example.org/downloads/` with following
JSON request body:
{
"downloads": [
{"name": "monolog/monolog", "version": "1.2.1.0"},
]
}
```json
{
"downloads": [
{"name": "monolog/monolog", "version": "1.2.1.0"},
]
}
```
The version field will contain the normalized representation of the version
number.
@ -132,19 +140,21 @@ files.
An example:
{
"includes": {
"packages-2011.json": {
"sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17"
},
"packages-2012-01.json": {
"sha1": "897cde726f8a3918faf27c803b336da223d400dd"
},
"packages-2012-02.json": {
"sha1": "26f911ad717da26bbcac3f8f435280d13917efa5"
}
```json
{
"includes": {
"packages-2011.json": {
"sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17"
},
"packages-2012-01.json": {
"sha1": "897cde726f8a3918faf27c803b336da223d400dd"
},
"packages-2012-02.json": {
"sha1": "26f911ad717da26bbcac3f8f435280d13917efa5"
}
}
}
```
The SHA-1 sum of the file allows it to be cached and only re-requested if the
hash changed.
@ -164,31 +174,35 @@ is an absolute path from the repository root.
An example:
{
"provider-includes": {
"providers-a.json": {
"sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c"
},
"providers-b.json": {
"sha256": "b38372163fac0573053536f5b8ef11b86f804ea8b016d239e706191203f6efac"
}
```json
{
"provider-includes": {
"providers-a.json": {
"sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c"
},
"providers-url": "/p/%package%$%hash%.json"
}
"providers-b.json": {
"sha256": "b38372163fac0573053536f5b8ef11b86f804ea8b016d239e706191203f6efac"
}
},
"providers-url": "/p/%package%$%hash%.json"
}
```
Those files contain lists of package names and hashes to verify the file
integrity, for example:
{
"providers": {
"acme/foo": {
"sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82"
},
"acme/bar": {
"sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233"
}
```json
{
"providers": {
"acme/foo": {
"sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82"
},
"acme/bar": {
"sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233"
}
}
}
```
The file above declares that acme/foo and acme/bar can be found in this
repository, by loading the file referenced by `providers-url`, replacing
@ -225,17 +239,19 @@ point to your custom branch. For version constraint naming conventions see
Example assuming you patched monolog to fix a bug in the `bugfix` branch:
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/igorw/monolog"
}
],
"require": {
"monolog/monolog": "dev-bugfix"
```json
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/igorw/monolog"
}
],
"require": {
"monolog/monolog": "dev-bugfix"
}
}
```
When you run `php composer.phar update`, you should get your modified version
of `monolog/monolog` instead of the one from packagist.
@ -256,17 +272,19 @@ For more information [see the aliases article](articles/aliases.md).
Exactly the same solution allows you to work with your private repositories at
GitHub and BitBucket:
{
"require": {
"vendor/my-private-repo": "dev-master"
},
"repositories": [
{
"type": "vcs",
"url": "git@bitbucket.org:vendor/my-private-repo.git"
}
]
}
```json
{
"require": {
"vendor/my-private-repo": "dev-master"
},
"repositories": [
{
"type": "vcs",
"url": "git@bitbucket.org:vendor/my-private-repo.git"
}
]
}
```
The only requirement is the installation of SSH keys for a git client.
@ -305,17 +323,19 @@ by default that code is located in `$url/trunk`, `$url/branches` and
values. For example if you used capitalized names you could configure the
repository like this:
{
"repositories": [
{
"type": "vcs",
"url": "http://svn.example.org/projectA/",
"trunk-path": "Trunk",
"branches-path": "Branches",
"tags-path": "Tags"
}
]
}
```json
{
"repositories": [
{
"type": "vcs",
"url": "http://svn.example.org/projectA/",
"trunk-path": "Trunk",
"branches-path": "Branches",
"tags-path": "Tags"
}
]
}
```
If you have no branches or tags directory you can disable them entirely by
setting the `branches-path` or `tags-path` to `false`.
@ -333,18 +353,20 @@ avoid conflicts. All packages are also aliased with prefix `pear-{channelAlias}/
Example using `pear2.php.net`:
{
"repositories": [
{
"type": "pear",
"url": "http://pear2.php.net"
}
],
"require": {
"pear-pear2.php.net/PEAR2_Text_Markdown": "*",
"pear-pear2/PEAR2_HTTP_Request": "*"
```json
{
"repositories": [
{
"type": "pear",
"url": "http://pear2.php.net"
}
],
"require": {
"pear-pear2.php.net/PEAR2_Text_Markdown": "*",
"pear-pear2/PEAR2_HTTP_Request": "*"
}
}
```
In this case the short name of the channel is `pear2`, so the
`PEAR2_HTTP_Request` package name becomes `pear-pear2/PEAR2_HTTP_Request`.
@ -387,23 +409,25 @@ To illustrate, the following example would get the `BasePackage`,
`TopLevelPackage1`, and `TopLevelPackage2` packages from your PEAR repository
and `IntermediatePackage` from a Github repository:
{
"repositories": [
{
"type": "git",
"url": "https://github.com/foobar/intermediate.git"
},
{
"type": "pear",
"url": "http://pear.foobar.repo",
"vendor-alias": "foobar"
}
],
"require": {
"foobar/TopLevelPackage1": "*",
"foobar/TopLevelPackage2": "*"
```json
{
"repositories": [
{
"type": "git",
"url": "https://github.com/foobar/intermediate.git"
},
{
"type": "pear",
"url": "http://pear.foobar.repo",
"vendor-alias": "foobar"
}
],
"require": {
"foobar/TopLevelPackage1": "*",
"foobar/TopLevelPackage2": "*"
}
}
```
### Package
@ -418,32 +442,34 @@ minimum required fields are `name`, `version`, and either of `dist` or
Here is an example for the smarty template engine:
{
"repositories": [
{
"type": "package",
"package": {
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
},
"source": {
"url": "http://smarty-php.googlecode.com/svn/",
"type": "svn",
"reference": "tags/Smarty_3_1_7/distribution/"
},
"autoload": {
"classmap": ["libs/"]
}
```json
{
"repositories": [
{
"type": "package",
"package": {
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
},
"source": {
"url": "http://smarty-php.googlecode.com/svn/",
"type": "svn",
"reference": "tags/Smarty_3_1_7/distribution/"
},
"autoload": {
"classmap": ["libs/"]
}
}
],
"require": {
"smarty/smarty": "3.1.*"
}
],
"require": {
"smarty/smarty": "3.1.*"
}
}
```
Typically you would leave the source part off, as you don't really need it.
@ -512,25 +538,30 @@ of the times they are private. To simplify maintenance, one can simply use a
repository of type `artifact` with a folder containing ZIP archives of those
private packages:
{
"repositories": [
{
"type": "artifact",
"url": "path/to/directory/with/zips/"
}
],
"require": {
"private-vendor-one/core": "15.6.2",
"private-vendor-two/connectivity": "*",
"acme-corp/parser": "10.3.5"
```json
{
"repositories": [
{
"type": "artifact",
"url": "path/to/directory/with/zips/"
}
],
"require": {
"private-vendor-one/core": "15.6.2",
"private-vendor-two/connectivity": "*",
"acme-corp/parser": "10.3.5"
}
}
```
Each zip artifact is just a ZIP archive with `composer.json` in root folder:
$ unzip -l acme-corp-parser-10.3.5.zip
composer.json
...
```sh
unzip -l acme-corp-parser-10.3.5.zip
composer.json
...
```
If there are two archives with different versions of a package, they are both
imported. When an archive with a newer version is added in the artifact folder
@ -542,13 +573,14 @@ update to the latest version.
You can disable the default Packagist repository by adding this to your
`composer.json`:
{
"repositories": [
{
"packagist": false
}
]
}
```json
{
"repositories": [
{
"packagist": false
}
]
}
```
&larr; [Schema](04-schema.md) | [Community](06-community.md) &rarr;

34
doc/articles/aliases.md
View File

@ -28,13 +28,15 @@ someone will want the latest master dev version. Thus, Composer allows you to
alias your `dev-master` branch to a `1.0.x-dev` version. It is done by
specifying a `branch-alias` field under `extra` in `composer.json`:
{
"extra": {
"branch-alias": {
"dev-master": "1.0.x-dev"
}
```json
{
"extra": {
"branch-alias": {
"dev-master": "1.0.x-dev"
}
}
}
```
The branch version must begin with `dev-` (non-comparable version), the alias
must be a comparable dev version (i.e. start with numbers, and end with
@ -68,18 +70,20 @@ You are using `symfony/monolog-bundle` which requires `monolog/monolog` version
Just add this to your project's root `composer.json`:
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/you/monolog"
}
],
"require": {
"symfony/monolog-bundle": "2.0",
"monolog/monolog": "dev-bugfix as 1.0.x-dev"
```json
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/you/monolog"
}
],
"require": {
"symfony/monolog-bundle": "2.0",
"monolog/monolog": "dev-bugfix as 1.0.x-dev"
}
}
```
That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub
and alias it to `1.0.x-dev`.

122
doc/articles/custom-installers.md
View File

@ -34,13 +34,15 @@ An example use-case would be:
An example composer.json of such a template package would be:
{
"name": "phpdocumentor/template-responsive",
"type": "phpdocumentor-template",
"require": {
"phpdocumentor/template-installer-plugin": "*"
}
```json
{
"name": "phpdocumentor/template-responsive",
"type": "phpdocumentor-template",
"require": {
"phpdocumentor/template-installer-plugin": "*"
}
}
```
> **IMPORTANT**: to make sure that the template installer is present at the
> time the template package is installed, template packages should require
@ -70,20 +72,22 @@ requirements:
Example:
{
"name": "phpdocumentor/template-installer-plugin",
"type": "composer-plugin",
"license": "MIT",
"autoload": {
"psr-0": {"phpDocumentor\\Composer": "src/"}
},
"extra": {
"class": "phpDocumentor\\Composer\\TemplateInstallerPlugin"
},
"require": {
"composer-plugin-api": "1.0.0"
}
```json
{
"name": "phpdocumentor/template-installer-plugin",
"type": "composer-plugin",
"license": "MIT",
"autoload": {
"psr-0": {"phpDocumentor\\Composer": "src/"}
},
"extra": {
"class": "phpDocumentor\\Composer\\TemplateInstallerPlugin"
},
"require": {
"composer-plugin-api": "1.0.0"
}
}
```
### The Plugin class
@ -96,20 +100,24 @@ autoloadable and matches the `extra.class` element in the package definition.
Example:
namespace phpDocumentor\Composer;
```php
<?php
use Composer\Composer;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
namespace phpDocumentor\Composer;
class TemplateInstallerPlugin implements PluginInterface
use Composer\Composer;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
class TemplateInstallerPlugin implements PluginInterface
{
public function activate(Composer $composer, IOInterface $io)
{
public function activate(Composer $composer, IOInterface $io)
{
$installer = new TemplateInstaller($io, $composer);
$composer->getInstallationManager()->addInstaller($installer);
}
$installer = new TemplateInstaller($io, $composer);
$composer->getInstallationManager()->addInstaller($installer);
}
}
```
### The Custom Installer class
@ -138,39 +146,43 @@ source for the exact signature):
Example:
namespace phpDocumentor\Composer;
```php
<?php
use Composer\Package\PackageInterface;
use Composer\Installer\LibraryInstaller;
namespace phpDocumentor\Composer;
class TemplateInstaller extends LibraryInstaller
use Composer\Package\PackageInterface;
use Composer\Installer\LibraryInstaller;
class TemplateInstaller extends LibraryInstaller
{
/**
* {@inheritDoc}
*/
public function getPackageBasePath(PackageInterface $package)
{
/**
* {@inheritDoc}
*/
public function getPackageBasePath(PackageInterface $package)
{
$prefix = substr($package->getPrettyName(), 0, 23);
if ('phpdocumentor/template-' !== $prefix) {
throw new \InvalidArgumentException(
'Unable to install template, phpdocumentor templates '
.'should always start their package name with '
.'"phpdocumentor/template-"'
);
}
return 'data/templates/'.substr($package->getPrettyName(), 23);
$prefix = substr($package->getPrettyName(), 0, 23);
if ('phpdocumentor/template-' !== $prefix) {
throw new \InvalidArgumentException(
'Unable to install template, phpdocumentor templates '
.'should always start their package name with '
.'"phpdocumentor/template-"'
);
}
/**
* {@inheritDoc}
*/
public function supports($packageType)
{
return 'phpdocumentor-template' === $packageType;
}
return 'data/templates/'.substr($package->getPrettyName(), 23);
}
/**
* {@inheritDoc}
*/
public function supports($packageType)
{
return 'phpdocumentor-template' === $packageType;
}
}
```
The example demonstrates that it is quite simple to extend the
[`Composer\Installer\LibraryInstaller`][5] class to strip a prefix
(`phpdocumentor/template-`) and use the remaining part to assemble a completely

139
doc/articles/handling-private-packages-with-satis.md
View File

@ -25,34 +25,38 @@ repositories you defined.
The default file Satis looks for is `satis.json` in the root of the repository.
{
"name": "My Repository",
"homepage": "http://packages.example.org",
"repositories": [
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
{ "type": "vcs", "url": "http://svn.example.org/private/repo" },
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
],
"require-all": true
}
```json
{
"name": "My Repository",
"homepage": "http://packages.example.org",
"repositories": [
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
{ "type": "vcs", "url": "http://svn.example.org/private/repo" },
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
],
"require-all": true
}
```
If you want to cherry pick which packages you want, you can list all the packages
you want to have in your satis repository inside the classic composer `require` key,
using a `"*"` constraint to make sure all versions are selected, or another
constraint if you want really specific versions.
{
"repositories": [
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
{ "type": "vcs", "url": "http://svn.example.org/private/repo" },
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
],
"require": {
"company/package": "*",
"company/package2": "*",
"company/package3": "2.0.0"
}
```json
{
"repositories": [
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
{ "type": "vcs", "url": "http://svn.example.org/private/repo" },
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
],
"require": {
"company/package": "*",
"company/package2": "*",
"company/package3": "2.0.0"
}
}
```
Once you did this, you just run `php bin/satis build <configuration file> <build dir>`.
For example `php bin/satis build config.json web/` would read the `config.json`
@ -80,14 +84,16 @@ everything should work smoothly. You don't need to copy all your repositories
in every project anymore. Only that one unique repository that will update
itself.
{
"repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ],
"require": {
"company/package": "1.2.0",
"company/package2": "1.5.2",
"company/package3": "dev-master"
}
```json
{
"repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ],
"require": {
"company/package": "1.2.0",
"company/package2": "1.5.2",
"company/package3": "dev-master"
}
}
```
### Security
@ -97,39 +103,43 @@ connection options for the server.
Example using a custom repository using SSH (requires the SSH2 PECL extension):
{
"repositories": [
{
"type": "composer",
"url": "ssh2.sftp://example.org",
"options": {
"ssh2": {
"username": "composer",
"pubkey_file": "/home/composer/.ssh/id_rsa.pub",
"privkey_file": "/home/composer/.ssh/id_rsa"
}
```json
{
"repositories": [
{
"type": "composer",
"url": "ssh2.sftp://example.org",
"options": {
"ssh2": {
"username": "composer",
"pubkey_file": "/home/composer/.ssh/id_rsa.pub",
"privkey_file": "/home/composer/.ssh/id_rsa"
}
}
]
}
}
]
}
```
> **Tip:** See [ssh2 context options](http://www.php.net/manual/en/wrappers.ssh2.php#refsect1-wrappers.ssh2-options) for more information.
Example using HTTP over SSL using a client certificate:
{
"repositories": [
{
"type": "composer",
"url": "https://example.org",
"options": {
"ssl": {
"local_cert": "/home/composer/.ssl/composer.pem"
}
```json
{
"repositories": [
{
"type": "composer",
"url": "https://example.org",
"options": {
"ssl": {
"local_cert": "/home/composer/.ssl/composer.pem"
}
}
]
}
}
]
}
```
> **Tip:** See [ssl context options](http://www.php.net/manual/en/context.ssl.php) for more information.
@ -145,14 +155,16 @@ Subversion) will not have downloads available and thus installations usually tak
To enable your satis installation to create downloads for all (Git, Mercurial and Subversion) your packages, add the
following to your `satis.json`:
{
"archive": {
"directory": "dist",
"format": "tar",
"prefix-url": "https://amazing.cdn.example.org",
"skip-dev": true
}
```json
{
"archive": {
"directory": "dist",
"format": "tar",
"prefix-url": "https://amazing.cdn.example.org",
"skip-dev": true
}
}
```
#### Options explained
@ -178,10 +190,11 @@ It is possible to make satis automatically resolve and add all dependencies for
with the Downloads functionality to have a complete local mirror of packages. Just add the following
to your `satis.json`:
{
"require-dependencies": true
}
```json
{
"require-dependencies": true
}
```
When searching for packages, satis will attempt to resolve all the required packages from the listed repositories.
Therefore, if you are requiring a package from Packagist, you will need to define it in your `satis.json`.

106
doc/articles/plugins.md
View File

@ -35,13 +35,15 @@ current composer plugin API version is 1.0.0.
For example
{
"name": "my/plugin-package",
"type": "composer-plugin",
"require": {
"composer-plugin-api": "1.0.0"
}
```json
{
"name": "my/plugin-package",
"type": "composer-plugin",
"require": {
"composer-plugin-api": "1.0.0"
}
}
```
### Plugin Class
@ -54,20 +56,24 @@ be read and all internal objects and state can be manipulated as desired.
Example:
namespace phpDocumentor\Composer;
```php
<?php
use Composer\Composer;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
namespace phpDocumentor\Composer;
class TemplateInstallerPlugin implements PluginInterface
use Composer\Composer;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
class TemplateInstallerPlugin implements PluginInterface
{
public function activate(Composer $composer, IOInterface $io)
{
public function activate(Composer $composer, IOInterface $io)
{
$installer = new TemplateInstaller($io, $composer);
$composer->getInstallationManager()->addInstaller($installer);
}
$installer = new TemplateInstaller($io, $composer);
$composer->getInstallationManager()->addInstaller($installer);
}
}
```
## Event Handler
@ -88,46 +94,50 @@ The events available for plugins are:
Example:
namespace Naderman\Composer\AWS;
```php
<?php
use Composer\Composer;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
use Composer\Plugin\PluginEvents;
use Composer\Plugin\PreFileDownloadEvent;
namespace Naderman\Composer\AWS;
class AwsPlugin implements PluginInterface, EventSubscriberInterface
use Composer\Composer;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
use Composer\Plugin\PluginEvents;
use Composer\Plugin\PreFileDownloadEvent;
class AwsPlugin implements PluginInterface, EventSubscriberInterface
{
protected $composer;
protected $io;
public function activate(Composer $composer, IOInterface $io)
{
protected $composer;
protected $io;
$this->composer = $composer;
$this->io = $io;
}
public function activate(Composer $composer, IOInterface $io)
{
$this->composer = $composer;
$this->io = $io;
}
public static function getSubscribedEvents()
{
return array(
PluginEvents::PRE_FILE_DOWNLOAD => array(
array('onPreFileDownload', 0)
),
);
}
public static function getSubscribedEvents()
{
return array(
PluginEvents::PRE_FILE_DOWNLOAD => array(
array('onPreFileDownload', 0)
),
);
}
public function onPreFileDownload(PreFileDownloadEvent $event)
{
$protocol = parse_url($event->getProcessedUrl(), PHP_URL_SCHEME);
public function onPreFileDownload(PreFileDownloadEvent $event)
{
$protocol = parse_url($event->getProcessedUrl(), PHP_URL_SCHEME);
if ($protocol === 's3') {
$awsClient = new AwsClient($this->io, $this->composer->getConfig());
$s3RemoteFilesystem = new S3RemoteFilesystem($this->io, $event->getRemoteFilesystem()->getOptions(), $awsClient);
$event->setRemoteFilesystem($s3RemoteFilesystem);
}
if ($protocol === 's3') {
$awsClient = new AwsClient($this->io, $this->composer->getConfig());
$s3RemoteFilesystem = new S3RemoteFilesystem($this->io, $event->getRemoteFilesystem()->getOptions(), $awsClient);
$event->setRemoteFilesystem($s3RemoteFilesystem);
}
}
}
```
## Using Plugins

70
doc/articles/scripts.md
View File

@ -67,48 +67,52 @@ autoload functionality.
Script definition example:
{
"scripts": {
"post-update-cmd": "MyVendor\\MyClass::postUpdate",
"post-package-install": [
"MyVendor\\MyClass::postPackageInstall"
],
"post-install-cmd": [
"MyVendor\\MyClass::warmCache",
"phpunit -c app/"
]
}
```json
{
"scripts": {
"post-update-cmd": "MyVendor\\MyClass::postUpdate",
"post-package-install": [
"MyVendor\\MyClass::postPackageInstall"
],
"post-install-cmd": [
"MyVendor\\MyClass::warmCache",
"phpunit -c app/"
]
}
}
```
Using the previous definition example, here's the class `MyVendor\MyClass`
that might be used to execute the PHP callbacks:
<?php
```php
<?php
namespace MyVendor;
namespace MyVendor;
use Composer\Script\Event;
use Composer\Script\Event;
class MyClass
class MyClass
{
public static function postUpdate(Event $event)
{
public static function postUpdate(Event $event)
{
$composer = $event->getComposer();
// do stuff
}
public static function postPackageInstall(Event $event)
{
$installedPackage = $event->getOperation()->getPackage();
// do stuff
}
public static function warmCache(Event $event)
{
// make cache toasty
}
$composer = $event->getComposer();
// do stuff
}
public static function postPackageInstall(Event $event)
{
$installedPackage = $event->getOperation()->getPackage();
// do stuff
}
public static function warmCache(Event $event)
{
// make cache toasty
}
}
```
When an event is fired, Composer's internal event handler receives a
`Composer\Script\Event` object, which is passed as the first argument to your
PHP callback. This `Event` object has getters for other contextual objects:
@ -122,6 +126,8 @@ PHP callback. This `Event` object has getters for other contextual objects:
If you would like to run the scripts for an event manually, the syntax is:
$ composer run-script [--dev] [--no-dev] script
```sh
composer run-script [--dev] [--no-dev] script
```
For example `composer run-script post-install-cmd` will run any **post-install-cmd** scripts that have been defined.

51
doc/articles/troubleshooting.md
View File

@ -63,12 +63,14 @@ You can fix this by aliasing version 0.11 to 0.1:
composer.json:
{
"require": {
"A": "0.2",
"B": "0.11 as 0.1"
}
```json
{
"require": {
"A": "0.2",
"B": "0.11 as 0.1"
}
}
```
See [aliases](aliases.md) for more information.
@ -76,7 +78,7 @@ See [aliases](aliases.md) for more information.
If composer shows memory errors on some commands:
PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...>
`PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...>`
The PHP `memory_limit` should be increased.
@ -86,17 +88,23 @@ The PHP `memory_limit` should be increased.
To get the current `memory_limit` value, run:
php -r "echo ini_get('memory_limit').PHP_EOL;"
```sh
php -r "echo ini_get('memory_limit').PHP_EOL;"
```
Try increasing the limit in your `php.ini` file (ex. `/etc/php5/cli/php.ini` for
Debian-like systems):
; Use -1 for unlimited or define an explicit value like 512M
memory_limit = -1
```ini
; Use -1 for unlimited or define an explicit value like 512M
memory_limit = -1
```
Or, you can increase the limit with a command-line argument:
php -d memory_limit=-1 composer.phar <...>
```sh
php -d memory_limit=-1 composer.phar <...>
```
## "The system cannot find the path specified" (Windows)
@ -123,18 +131,23 @@ Now Composer should install/update without asking for authentication.
## proc_open(): fork failed errors
If composer shows proc_open() fork failed on some commands:
PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar
`PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar`
This could be happening because the VPS runs out of memory and has no Swap space enabled.
[root@my_tiny_vps htdocs]# free -m
total used free shared buffers cached
Mem: 2048 357 1690 0 0 237
-/+ buffers/cache: 119 1928
Swap: 0 0 0
```sh
free -m
total used free shared buffers cached
Mem: 2048 357 1690 0 0 237
-/+ buffers/cache: 119 1928
Swap: 0 0 0
```
To enable the swap you can use for example:
/bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024
/sbin/mkswap /var/swap.1
/sbin/swapon /var/swap.1
```sh
/bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024
/sbin/mkswap /var/swap.1
/sbin/swapon /var/swap.1
```

41
doc/articles/vendor-binaries.md
View File

@ -20,10 +20,11 @@ It is defined by adding the `bin` key to a project's `composer.json`.
It is specified as an array of files so multiple binaries can be added
for any given project.
{
"bin": ["bin/my-script", "bin/my-other-script"]
}
```json
{
"bin": ["bin/my-script", "bin/my-other-script"]
}
```
## What does defining a vendor binary in composer.json do?
@ -46,22 +47,26 @@ symlink is created from each dependency's binaries to `vendor/bin`.
Say package `my-vendor/project-a` has binaries setup like this:
{
"name": "my-vendor/project-a",
"bin": ["bin/project-a-bin"]
}
```json
{
"name": "my-vendor/project-a",
"bin": ["bin/project-a-bin"]
}
```
Running `composer install` for this `composer.json` will not do
anything with `bin/project-a-bin`.
Say project `my-vendor/project-b` has requirements setup like this:
{
"name": "my-vendor/project-b",
"require": {
"my-vendor/project-a": "*"
}
```json
{
"name": "my-vendor/project-b",
"require": {
"my-vendor/project-a": "*"
}
}
```
Running `composer install` for this `composer.json` will look at
all of project-b's dependencies and install them to `vendor/bin`.
@ -95,11 +100,13 @@ Yes, there are two ways an alternate vendor binary location can be specified:
An example of the former looks like this:
{
"config": {
"bin-dir": "scripts"
}
```json
{
"config": {
"bin-dir": "scripts"
}
}
```
Running `composer install` for this `composer.json` will result in
all of the vendor binaries being installed in `scripts/` instead of

26
doc/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md
View File

@ -11,13 +11,15 @@ This is common if your package is intended for a specific framework such as
CakePHP, Drupal or WordPress. Here is an example composer.json file for a
WordPress theme:
{
"name": "you/themename",
"type": "wordpress-theme",
"require": {
"composer/installers": "~1.0"
}
```json
{
"name": "you/themename",
"type": "wordpress-theme",
"require": {
"composer/installers": "~1.0"
}
}
```
Now when your theme is installed with Composer it will be placed into
`wp-content/themes/themename/` folder. Check the
@ -30,13 +32,15 @@ useful example would be for a Drupal multisite setup where the package should be
installed into your sites subdirectory. Here we are overriding the install path
for a module that uses composer/installers:
{
"extra": {
"installer-paths": {
"sites/example.com/modules/{$name}": ["vendor/package"]
}
```json
{
"extra": {
"installer-paths": {
"sites/example.com/modules/{$name}": ["vendor/package"]
}
}
}
```
Now the package would be installed to your folder location, rather than the default
composer/installers determined location.