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

Merge pull request #6 from golaravel/sync

Browse Source 
同步更新官方英文文档；并对中文文档做相应的同步；少量增加了部分翻译。
This commit is contained in:
成武 2014-05-24 09:00:42 +08:00
commit 1e3b5c382b
30 changed files with 2278 additions and 1450 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
cn-introduction/00-intro.md
View File

@ -45,11 +45,13 @@ d) Composer 会找出哪个版本的包需要安装，并安装它们（将它
比方说，你正在创建一个项目，你需要一个库来做日志记录。你决定使用 [monolog](https://github.com/Seldaek/monolog)。为了将它添加到你的项目中，你所需要做的就是创建一个 `composer.json` 文件，其中描述了项目的依赖关系。
{
"require": {
"monolog/monolog": "1.2.*"
}
```json
{
"require": {
"monolog/monolog": "1.2.*"
}
}
```
我们只要指出我们的项目需要一些 `monolog/monolog` 的包，从 `1.2` 开始的任何版本。
@ -73,13 +75,23 @@ Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX
要真正获取 Composer，我们需要做两件事。首先安装 Composer （同样的，这意味着它将下载到你的项目中）：
$ curl -sS https://getcomposer.org/installer | php
```sh
curl -sS https://getcomposer.org/installer | php
```
> **注意：** 如果上述方法由于某些原因失败了，你还可以通过 `php` >下载安装器：
```sh
php -r "readfile('https://getcomposer.org/installer');" | php
```
这将检查一些 PHP 的设置，然后下载 `composer.phar` 到你的工作目录中。这是 Composer 的二进制文件。这是一个 PHAR 包（PHP 的归档），这是 PHP 的归档格式可以帮助用户在命令行中执行一些操作。
你可以通过 `--install-dir` 选项指定 Composer 的安装目录（它可以是一个绝对或相对路径）：
$ curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
```sh
curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
```
<a name="Globally"></a>
#### 全局安装
@ -88,8 +100,10 @@ Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX
你可以执行这些命令让 `composer` 在你的系统中进行全局调用：
$ 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
```
> **注意：** 如果上诉命令因为权限执行失败，
> 请使用 sudo 再次尝试运行 `mv` 那行命令。
@ -101,12 +115,13 @@ Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX
Composer 是 homebrew-php 项目的一部分。
1. 在你的 brew installation 中 Tap homebrew-php 版本库，如果你还没有这样做：`brew tap josegonzalez/homebrew-php` 。
2. 运行 `brew install josegonzalez/php/composer`。
3. 使用 `composer` 命令运行 Composer。
> **注意：** 如果你收到一个错误 PHP53 or higher is missing 请执行下面的命令来安装 php
> `brew install php53-intl`
```sh
brew update
brew tap josegonzalez/homebrew-php
brew tap homebrew/versions
brew install php55-intl
brew install josegonzalez/php/composer
```
<a name="Installation-Windows"></a>
## 安装 - Windows
@ -123,21 +138,25 @@ Composer 是 homebrew-php 项目的一部分。
设置系统的环境变量 `PATH` 并运行安装命令下载 composer.phar 文件：
C:\Users\username>cd C:\bin
C:\bin>php -r "eval('?>'.file_get_contents('https://getcomposer.org/installer'));"
```sh
C:\Users\username>cd C:\bin
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
```
> **注意：** 如果收到 file_get_contents 错误提示，请使用 `http` 链接或者在 php.ini 中开启 php_openssl.dll 。
> **注意：** 如果收到 readfile 错误提示，请使用 `http` 链接或者在 php.ini 中开启 php_openssl.dll 。
在 `composer.phar` 同级目录下新建文件 `composer.bat` ：
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
```sh
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
```
关闭当前的命令行窗口，打开新的命令行窗口进行测试：
C:\Users\username>composer -V
Composer version 27d8904
C:\Users\username>
```sh
C:\Users\username>composer -V
Composer version 27d8904
```
<a name="Using-Composer"></a>
## 使用 Composer
@ -146,11 +165,15 @@ Composer 是 homebrew-php 项目的一部分。
要解决和下载依赖，请执行 `install` 命令：
$ php composer.phar install
```sh
php composer.phar install
```
如果你进行了全局安装，并且没有 phar 文件在当前目录，请使用下面的命令代替：
$ composer install
```sh
composer install
```
继续 [上面的例子](#Declaring-dependencies)，这里将下载 monolog 到 `vendor/monolog/monolog` 目录。
@ -159,7 +182,9 @@ Composer 是 homebrew-php 项目的一部分。
除了库的下载，Composer 还准备了一个自动加载文件，它可以加载 Composer 下载的库中所有的类文件。使用它，你只需要将下面这行代码添加到你项目的引导文件中：
require 'vendor/autoload.php';
```php
require 'vendor/autoload.php';
```
现在我们就可以使用 monolog 了！想要学习更多关于 Composer 的知识，请查看“基本用法”章节。

75
cn-introduction/01-basic-usage.md
View File

@ -23,21 +23,26 @@
安装 Composer，你只需要下载 `composer.phar` 可执行文件。
$ curl -sS https://getcomposer.org/installer | php
```sh
curl -sS https://getcomposer.org/installer | php
```
详细请查看 [简介](00-intro.md) 章节。
要检查 Composer 是否正常工作，只需要通过 `php` 来执行 PHAR：
$ php composer.phar
```sh
php composer.phar
```
这将返回给你一个可执行的命令列表。
> **注意：** 你也可以仅执行 `--check` 选项而无需下载 Composer。
> 要获取更多的信息请使用 `--help`。
>
> $ curl -sS https://getcomposer.org/installer | php -- --check
> $ curl -sS https://getcomposer.org/installer | php -- --help
> ```sh
> curl -sS https://getcomposer.org/installer | php -- --help
> ```
<a name="composer.json-Project-Setup"></a>
## `composer.json`：项目安装
@ -51,11 +56,13 @@
第一件事情（并且往往只需要做这一件事），你需要在 `composer.json` 文件中指定 `require` key 的值。你只需要简单的告诉 Composer 你的项目需要依赖哪些包。
{
"require": {
"monolog/monolog": "1.0.*"
}
```json
{
"require": {
"monolog/monolog": "1.0.*"
}
}
```
你可以看到， `require` 需要一个 **包名称** （例如 `monolog/monolog`） 映射到 **包版本** （例如 `1.0.*`） 的对象。
@ -115,6 +122,10 @@
`~` 最好用例子来解释： `~1.2` 相当于 `>=1.2,<2.0`，而 `~1.2.3` 相当于 `>=1.2.3,<1.3`。正如你所看到的这对于遵循 [语义化版本号](http://semver.org/) 的项目最有用。一个常见的用法是标记你所依赖的最低版本，像 `~1.2` （允许1.2以上的任何版本，但不包括2.0）。由于理论上直到2.0应该都没有向后兼容性问题，所以效果很好。你还会看到它的另一种用法，使用 `~` 指定最低版本，但允许版本号的最后一位数字上升。
> **注意：** 虽然 `2.0-beta.1` 严格地说是早于 `2.0`，但是，根据版本约束条件，
> 例如 `~1.2` 却不会安装这个版本。就像前面所讲的 `~1.2` 只意味着 `.2`
> 部分可以改变，但是 `1.` 部分是固定的。
<a name="Stability"></a>
### 稳定性
@ -125,7 +136,9 @@
获取定义的依赖到你的本地项目，只需要调用 `composer.phar` 运行 `install` 命令。
$ php composer.phar install
```sh
php composer.phar install
```
接着前面的例子，这将会找到 `monolog/monolog` 的最新版本，并将它下载到 `vendor` 目录。
这是一个惯例把第三方的代码到一个指定的目录 `vendor`。如果是 monolog 将会创建 `vendor/monolog/monolog` 目录。
@ -151,11 +164,15 @@
这意味着如果你的依赖更新了新的版本，你将不会获得任何更新。此时要更新你的依赖版本请使用 `update` 命令。这将获取最新匹配的版本（根据你的 `composer.json` 文件）并将新版本更新进锁文件。
$ php composer.phar update
```sh
php composer.phar update
```
如果只想安装或更新一个依赖，你可以白名单它们：
$ php composer.phar update monolog/monolog [...]
```sh
php composer.phar update monolog/monolog [...]
```
> **注意：** 对于库，并不一定建议提交锁文件
> 请参考：[库的锁文件](02-libraries.md#Lock-file).
@ -174,36 +191,44 @@
对于库的自动加载信息，Composer 生成了一个 `vendor/autoload.php` 文件。你可以简单的引入这个文件，你会得到一个免费的自动加载支持。
require 'vendor/autoload.php';
```php
require 'vendor/autoload.php';
```
这使得你可以很容易的使用第三方代码。例如：如果你的项目依赖 monolog，你就可以像这样开始使用这个类库，并且他们将被自动加载。
$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');
```
你可以在 `composer.json` 的 `autoload` 字段中增加自己的 autoloader。
{
"autoload": {
"psr-0": {"Acme\\": "src/"}
}
```json
{
"autoload": {
"psr-4": {"Acme\\": "src/"}
}
}
```
Composer 将注册 [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) autoloader 到 `Acme` 命名空间。
Composer 将注册一个 [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader 到 `Acme` 命名空间。
你可以定义一个从命名空间到目录的映射。此时 `src` 会在你项目的根目录，与 `vendor` 文件夹同级。例如 `src/Acme/Foo.php` 文件应该包含 `Acme\Foo` 类。
你可以定义一个从命名空间到目录的映射。此时 `src` 会在你项目的根目录，与 `vendor` 文件夹同级。例如 `src/Foo.php` 文件应该包含 `Acme\Foo` 类。
添加 `autoload` 字段后，你应该再次运行 `install` 命令来生成 `vendor/autoload.php` 文件。
引用这个文件也将返回 autoloader 的实例，你可以将包含调用的返回值存储在变量中，并添加更多的命名空间。这对于在一个测试套件中自动加载类文件是非常有用的，例如。
$loader = require 'vendor/autoload.php';
$loader->add('Acme\\Test\\', __DIR__);
```php
$loader = require 'vendor/autoload.php';
$loader->add('Acme\\Test\\', __DIR__);
```
除了 PSR-0 自动加载，classmap 也是支持的。这允许类被自动加载，即使不符合 PSR-0 规范。详细请查看 [自动加载-参考](04-schema.md#autoload)。
除了 PSR-4 自动加载，classmap 也是支持的。这允许类被自动加载，即使不符合 PSR-0 规范。详细请查看 [自动加载-参考](04-schema.md#autoload)。
> **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_namespaces.php` 文件，它返回一个关联数组映射了命名空间的目录。
> **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_*.php` 文件，它返回一个关联数组，你可以通过这个关联数组配置自己的 autoloader。
&larr; [简介](00-intro.md) | [库（资源包）](02-libraries.md) &rarr;

77
cn-introduction/02-libraries.md
View File

@ -25,12 +25,14 @@
为了使它成为一个可安装的包，你需要给它一个名称。你可以通过 `composer.json` 中的 `name` 来定义：
{
"name": "acme/hello-world",
"require": {
"monolog/monolog": "1.0.*"
}
```json
{
"name": "acme/hello-world",
"require": {
"monolog/monolog": "1.0.*"
}
}
```
在这种情况下项目的名称为 `acme/hello-world`，其中 `acme` 是供应商的名称。供应商的名称是必须填写的。
@ -45,10 +47,13 @@ Composer 将那些已经安装在系统上，但并不是由 Composer 安装的
* `php` 表示用户的 PHP 版本要求，你可以对其做出限制。例如 `>=5.4.0`。如果需要64位版本的 PHP，你可以使用 `php-64bit` 进行限制。
* `hhvm` 代表的是 HHVM（也就是 HipHop Virtual
Machine） 运行环境的版本，并且允许你设置一个版本限制，例如，'>=2.3.3'。
* `ext-<name>` 可以帮你指定需要的 PHP 扩展（包括核心扩展）。通常 PHP 拓展的版本可以是不一致的，将它们的版本约束为 `*` 是一个不错的主意。一个 PHP 扩展包的例子：包名可以写成 `ext-gd`。
* `lib-<name>` 允许对 PHP 库的版本进行限制。
以下是可供使用的名称：`curl`、`iconv`、`libxml`、`openssl`、`pcre`、`uuid`、`xsl`。
以下是可供使用的名称：`curl`、`iconv`、`icu`、`libxml`、`openssl`、`pcre`、`uuid`、`xsl`。
你可以使用 `composer show --platform` 命令来获取可用的平台软件包的列表。
@ -60,9 +65,11 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并
如果你想要手动创建并且真的要明确指定它，你只需要添加一个 `version` 字段：
{
"version": "1.0.0"
}
```json
{
"version": "1.0.0"
}
```
> **注意：** 你应该尽量避免手动设置版本号，因为标签的值必须与标签名相匹配。
@ -73,12 +80,12 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并
下面是有效的标签名称的几个例子：
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
> **注意：** 即使你的标签带有前缀 `v`，
> 由于在需要 `require` 一个[版本的约束](01-basic-usage.md#Package-Versions)时是不允许这种前缀的，
@ -91,9 +98,9 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并
下面是版本分支名称的一些示例：
1.x
1.0 (等同于 1.0.x)
1.1.x
- 1.x
- 1.0 (equals 1.0.x)
- 1.1.x
> **注意：** 当你安装一个新的版本时，将会自动从它 `source` 中拉取。
> 详细请查看 [`install`](03-cli.md#install) 命令。
@ -119,29 +126,33 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并
现在测试这个 `acme/hello-world` 包，我们在本地创建一个新的项目。我们将它命名为 `acme/blog`。此博客将依赖 `acme/hello-world`，而后者又依赖 `monolog/monolog`。我们可以在某处创建一个新的 `blog` 文件夹来完成它，并且需要包含 `composer.json` 文件：
{
"name": "acme/blog",
"require": {
"acme/hello-world": "dev-master"
}
```json
{
"name": "acme/blog",
"require": {
"acme/hello-world": "dev-master"
}
}
```
在这个例子中 `name` 不是必须的，因为我们并不想将它发布为一个库。在这里为 `composer.json` 文件添加描述。
现在我们需要告诉我们的应用，在哪里可以找到 `hello-world` 的依赖。为此我们需要在 `composer.json` 中添加 `repositories` 来源申明：
{
"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"
}
}
```
更多关于包的来源是如何工作的，以及还有什么其他的类型可供选择，请查看[资源库](05-repositories.md)。

163
cn-introduction/03-cli.md
View File

@ -78,7 +78,9 @@
当您运行该命令，它会以交互方式要求您填写一些信息，同时聪明的使用一些默认值。
$ php composer.phar init
```sh
php composer.phar init
```
<a name="init-Options"></a>
### 初始化-参数
@ -96,7 +98,9 @@
`install` 命令从当前目录读取 `composer.json` 文件，处理了依赖关系，并把其安装到 `vendor` 目录下。
$ php composer.phar install
```sh
php composer.phar install
```
如果当前目录下存在 `composer.lock` 文件，它会从此文件读取依赖版本，而不是根据 `composer.json` 文件去获取依赖。这确保了该库的每个使用者都能得到相同的依赖版本。
@ -114,24 +118,30 @@
* **--no-scripts:** 跳过 `composer.json` 文件中定义的脚本。
* **--no-plugins:** 关闭 plugins。
* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。
* **--optimize-autoloader (-o):** 转换 PSR-0 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。
* **--optimize-autoloader (-o):** 转换 PSR-0/4 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。
<a name="update"></a>
## 更新 `update`
为了获取依赖的最新版本，并且升级 `composer.lock` 文件，你应该使用 `update` 命令。
$ php composer.phar update
```sh
php composer.phar update
```
这将解决项目的所有依赖，并将确切的版本号写入 `composer.lock`。
如果你只是想更新几个包，你可以像这样分别列出它们：
$ php composer.phar update vendor/package vendor/package2
```sh
php composer.phar update vendor/package vendor/package2
```
你还可以使用通配符进行批量更新：
$ php composer.phar update vendor/*
```sh
php composer.phar update vendor/*
```
<a name="update-Options"></a>
### 更新-参数
@ -144,7 +154,7 @@
* **--no-scripts:** 跳过 `composer.json` 文件中定义的脚本。
* **--no-plugins:** 关闭 plugins。
* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。
* **--optimize-autoloader (-o):** 转换 PSR-0 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。
* **--optimize-autoloader (-o):** 转换 PSR-0/4 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。
* **--lock:** 仅更新 lock 文件的 hash，取消有关 lock 文件过时的警告。
* **--with-dependencies** 同时更新白名单内包的依赖关系，这将进行递归更新。
@ -153,13 +163,17 @@
`require` 命令增加新的依赖包到当前目录的 `composer.json` 文件中。
$ php composer.phar require
```sh
php composer.phar require
```
在添加或改变依赖时， 修改后的依赖关系将被安装或者更新。
如果你不希望通过交互来指定依赖包，你可以在这条令中直接指明依赖包。
$ php composer.phar require vendor/package:2.* vendor/package2:dev-master
```sh
php composer.phar require vendor/package:2.* vendor/package2:dev-master
```
<a name="require-Options"></a>
### 申明依赖-参数
@ -169,6 +183,7 @@
* **--dev:** 安装 `require-dev` 字段中列出的包。
* **--no-update:** 禁用依赖关系的自动更新。
* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。
* **--update-with-dependencies** 一并更新新装包的依赖。
<a name="global"></a>
## 全局执行 `global`
@ -177,18 +192,24 @@
并且如果你将 `$COMPOSER_HOME/vendor/bin` 加入到了 `$PATH` 环境变量中，你就可以用它在命令行中安装全局应用，下面是一个例子：
$ php composer.phar global require fabpot/php-cs-fixer:dev-master
```sh
php composer.phar global require fabpot/php-cs-fixer:dev-master
```
现在 `php-cs-fixer` 就可以在全局范围使用了（假设你已经设置了你的 PATH）。如果稍后你想更新它，你只需要运行 `global update`：
$ php composer.phar global update
```sh
php composer.phar global update
```
<a name="search"></a>
## 搜索 `search`
`search` 命令允许你为当前项目搜索依赖包，通常它只搜索 packagist.org 上的包，你可以简单的输入你的搜索条件。
$ php composer.phar search monolog
```sh
php composer.phar search monolog
```
您也可以通过传递多个参数来进行多条件搜索。
@ -202,30 +223,36 @@
列出所有可用的软件包，你可以使用 `show` 命令。
$ php composer.phar show
```sh
php composer.phar show
```
如果你想看到一个包的详细信息，你可以输入一个包名称。
$ 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
```
你甚至可以输入一个软件包的版本号，来显示该版本的详细信息。
$ php composer.phar show monolog/monolog 1.0.2
```sh
php composer.phar show monolog/monolog 1.0.2
```
<a name="show-Options"></a>
### 展示-参数
@ -239,13 +266,15 @@
`depends` 命令可以查出已安装在你项目中的某个包，是否正在被其它的包所依赖，并列出他们。
$ 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
```
<a name="depends-Options"></a>
### 依赖性检测-参数
@ -257,36 +286,53 @@
在提交 `composer.json` 文件，和创建 tag 前，你应该始终运行 `validate` 命令。它将检测你的 `composer.json` 文件是否是有效的
$ php composer.phar validate
```sh
php composer.phar validate
```
### 有效性检测参数
* **--no-check-all:** Composer 是否进行完整的校验。
<a name="status"></a>
## 依赖包状态检测 `status`
如果你经常修改依赖包里的代码，并且它们是从 source（自定义源）进行安装的，那么 `status` 命令允许你进行检查，如果你有任何本地的更改它将会给予提示。
$ php composer.phar status
```sh
php composer.phar status
```
你可以使用 `--verbose` 系列参数（-v|vv|vvv）来获取更详细的详细：
$ 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
```
<a name="self-update"></a>
## 自我更新 `self-update`
将 Composer 自身升级到最新版本，只需要运行 `self-update` 命令。它将替换你的 `composer.phar` 文件到最新版本。
$ php composer.phar self-update
```sh
php composer.phar self-update
```
如果你想要升级到一个特定的版本，可以这样简单的指定它：
$ composer self-update 1.0.0-alpha7
```sh
php composer.phar self-update 1.0.0-alpha7
```
如果你已经为整个系统安装 Composer（参见 [全局安装](00-intro.md#全局安装)），你可能需要在 `root` 权限下运行它：
$ sudo composer self-update
```sh
sudo composer self-update
```
<a name="self-update-Options"></a>
### 自我更新-参数
@ -299,7 +345,9 @@
`config` 命令允许你编辑 Composer 的一些基本设置，无论是本地的 `composer.json` 或者全局的 `config.json` 文件。
$ php composer.phar config --list
```sh
php composer.phar config --list
```
<a name="config-Usage"></a>
### 更改配置-使用方法
@ -324,7 +372,9 @@
除了修改配置选项， `config` 命令还支持通过以下方法修改来源信息：
$ 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
```
<a name="create-project"></a>
## 创建项目 `create-project`
@ -341,7 +391,9 @@
如果该目录目前不存在，则会在安装过程中自动创建。
php composer.phar create-project doctrine/orm path 2.2.*
```sh
php composer.phar create-project doctrine/orm path 2.2.*
```
此外，你也可以无需使用这个命令，而是通过现有的 `composer.json` 文件来启动这个项目。
@ -366,12 +418,13 @@
某些情况下你需要更新 autoloader，例如在你的包中加入了一个新的类。你可以使用 `dump-autoload` 来完成，而不必执行 `install` 或 `update` 命令。
此外，它可以打印一个优化过的，符合 PSR-0 规范的类的索引，这也是出于对性能的可考虑。在大型的应用中会有许多类文件，而 autoloader 会占用每个请求的很大一部分时间，使用 classmaps 或许在开发时不太方便，但它在保证性能的前提下，仍然可以获得 PSR-0 规范带来的便利。
此外，它可以打印一个优化过的，符合 PSR-0/4 规范的类的索引，这也是出于对性能的可考虑。在大型的应用中会有许多类文件，而 autoloader 会占用每个请求的很大一部分时间，使用 classmaps 或许在开发时不太方便，但它在保证性能的前提下，仍然可以获得 PSR-0/4 规范带来的便利。
<a name="dump-autoload-Options"></a>
### 打印自动加载索引-参数
* **--optimize (-o):** 转换 PSR-0 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。
* **--optimize (-o):** 转换 PSR-0/4 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。
* **--no-dev:** 禁用 autoload-dev 规则。
<a name="licenses"></a>
## 查看许可协议 `licenses`
@ -388,14 +441,18 @@
如果你觉得发现了一个 bug 或是程序行为变得怪异，你可能需要运行 `diagnose` 命令，来帮助你检测一些常见的问题。
$ php composer.phar diagnose
```sh
php composer.phar diagnose
```
<a name="archive"></a>
## 归档 `archive`
此命令用来对指定包的指定版本进行 zip/tar 归档。它也可以用来归档你的整个项目，不包括 excluded/ignored（排除/忽略）的文件。
$ php composer.phar archive vendor/package 2.0.21 --format=zip
```sh
php composer.phar archive vendor/package 2.0.21 --format=zip
```
<a name="archive-Options"></a>
### 归档-参数
@ -408,7 +465,9 @@
使用 `help` 可以获取指定命令的帮助信息。
$ php composer.phar help install
```sh
php composer.phar help install
```
<a name="Environment-variables"></a>
## 环境变量
@ -422,7 +481,9 @@
例如：
$ COMPOSER=composer-other.json php composer.phar install
```sh
COMPOSER=composer-other.json php composer.phar install
```
<a name="COMPOSER_ROOT_VERSION"></a>
### COMPOSER_ROOT_VERSION

502
cn-introduction/04-schema.md
View File

@ -93,14 +93,14 @@
例：
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
通常，我们能够从 VCS (git, svn, hg) 的信息推断出包的版本号，在这种情况下，我们建议忽略 `version`。
@ -129,13 +129,13 @@ composer 原生支持以下4种类型：
该包相关的关键词的数组。这些可用于搜索和过滤。
例：
实例：
logging
events
database
redis
templating
- logging
- events
- database
- redis
- templating
可选。
@ -162,19 +162,19 @@ composer 原生支持以下4种类型：
最常见的许可协议的推荐写法（按字母排序）：
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
可选，但强烈建议提供此内容。更多许可协议的标识符请参见 [SPDX Open Source License Registry](http://www.spdx.org/licenses/)。
@ -182,26 +182,32 @@ composer 原生支持以下4种类型：
一个例：
{
"license": "MIT"
}
```json
{
"license": "MIT"
}
```
对于一个包，当允许在多个许可协议间进行选择时（"disjunctive license"），这些协议标识符可以被指定为数组。
多协议的一个例：
{
"license": [
"LGPL-2.1",
"GPL-3.0+"
]
}
```json
{
"license": [
"LGPL-2.1",
"GPL-3.0+"
]
}
```
另外它们也可以由 "or" 分隔，并写在括号中：
{
"license": "(LGPL-2.1 or GPL-3.0+)"
}
```json
{
"license": "(LGPL-2.1 or GPL-3.0+)"
}
```
同样，当有多个许可协议需要结合使用时（"conjunctive license"），它们应该被 "and" 分隔，并写在括号中。
@ -217,24 +223,26 @@ composer 原生支持以下4种类型：
* **homepage:** 作者主页的 URL 地址。
* **role:** 该作者在此项目中担任的角色（例：开发人员 或 翻译）。
一个例：
一个实例：
{
"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"
}
]
}
```
可选，但强烈建议提供此内容。
@ -252,14 +260,16 @@ composer 原生支持以下4种类型：
* **irc:** IRC 聊天频道地址，类似于 irc://server/channel。
* **source:** 网址浏览或下载源。
一个例：
一个实例：
{
"support": {
"email": "support@example.org",
"irc": "irc://irc.freenode.org/composer"
}
```json
{
"support": {
"email": "support@example.org",
"irc": "irc://irc.freenode.org/composer"
}
}
```
可选。
@ -268,48 +278,56 @@ composer 原生支持以下4种类型：
下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#Package-Versions) 的映射对象。
例：
实例：
{
"require": {
"monolog/monolog": "1.0.*"
}
```json
{
"require": {
"monolog/monolog": "1.0.*"
}
}
```
所有的这些都是可选的。
`require` 和 `require-dev` 还支持稳定性标签（@，仅针对“root 包”）。这允许你在 [minimum-stability](#minimum-stability) 设定的范围外做进一步的限制或扩展。例：如果你想允许依赖一个不稳定的包，你可以在一个包的版本约束后使用它，或者是一个空的版本约束内使用它。
例：
实例：
{
"require": {
"monolog/monolog": "1.0.*@beta",
"acme/foo": "@dev"
}
```json
{
"require": {
"monolog/monolog": "1.0.*@beta",
"acme/foo": "@dev"
}
}
```
如果你的依赖之一，有对另一个不稳定包的依赖，你最好在 require 中显示的定义它，并带上足够详细的稳定性标识。
例：
实例：
{
"require": {
"doctrine/doctrine-fixtures-bundle": "dev-master",
"doctrine/data-fixtures": "@dev"
}
```json
{
"require": {
"doctrine/doctrine-fixtures-bundle": "dev-master",
"doctrine/data-fixtures": "@dev"
}
}
```
`require` 和 `require-dev` 还支持对 dev（开发）版本的明确引用（即：版本控制系统中的提交编号 commit），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 `#<ref>` 的标识。
例：
实例：
{
"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"
}
}
```
> **注意：** 虽然这有时很方便，但不应该长期在你的包中使用，因为它有一个技术上的限制。
> composer.json 将仍然在哈希值之前指定的分支名称读取元数据，
@ -356,20 +374,76 @@ List of other packages that are provided by this package. This is mostly useful
格式如下，版本约束变成了描述信息。
例：
实例：
{
"suggest": {
"monolog/monolog": "Allows more advanced logging of the application flow"
}
```json
{
"suggest": {
"monolog/monolog": "Allows more advanced logging of the application flow"
}
}
```
<a name="autoload"></a>
### autoload
PHP autoloader 的自动加载映射。
通常 [`PSR-0`](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) autoloading、`classmap` generation 和 `files` 方式都是支持的。PSR-0 是推荐的方式，因为它提供了更大的灵活性（当你添加新的类文件时，不需要重新生成 autoloader）。
Currently [`PSR-0`](http://www.php-fig.org/psr/psr-0/) autoloading,
[`PSR-4`](http://www.php-fig.org/psr/psr-4/) autoloading, `classmap` generation and
`files` includes are supported. PSR-4 is the recommended way though since it offers
greater ease of use (no need to regenerate the autoloader when you add classes).
#### PSR-4
Under the `psr-4` key you define a mapping from namespaces to paths, relative to the
package root. When autoloading a class like `Foo\\Bar\\Baz` a namespace prefix
`Foo\\` pointing to a directory `src/` means that the autoloader will look for a
file named `src/Bar/Baz.php` and include it if present. Note that as opposed to
the older PSR-0 style, the prefix (`Foo\\`) is **not** present in the file path.
Namespace prefixes must end in `\\` to avoid conflicts between similar prefixes.
For example `Foo` would match classes in the `FooBar` namespace so the trailing
backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct.
The PSR-4 references are all combined, during install/update, into a single
key => value array which may be found in the generated file
`vendor/composer/autoload_psr4.php`.
Example:
```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:
```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:
```json
{
"autoload": {
"psr-4": { "": "src/" }
}
}
```
<a name="PSR-0"></a>
#### PSR-0
@ -380,69 +454,105 @@ PHP autoloader 的自动加载映射。
在 install/update 过程中，PSR-0 引用都将被结合为一个单一的键值对数组，存储至 `vendor/composer/autoload_namespaces.php` 文件中。
例：
实例：
{
"autoload": {
"psr-0": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": "src/",
"Vendor_Namespace_": "src/"
}
```json
{
"autoload": {
"psr-0": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": "src/",
"Vendor_Namespace_": "src/"
}
}
}
```
如果你需要搜索多个目录中一个相同的前缀，你可以将它们指定为一个数组，例：
{
"autoload": {
"psr-0": { "Monolog\\": ["src/", "lib/"] }
}
```json
{
"autoload": {
"psr-0": { "Monolog\\": ["src/", "lib/"] }
}
}
```
PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别的指定。这对于只有一个类在全局命名空间的类库是非常有用的（如果 php 源文件也位于包的根目录）。例如，可以这样申明：
{
"autoload": {
"psr-0": { "UniqueGlobalClass": "" }
}
```json
{
"autoload": {
"psr-0": { "UniqueGlobalClass": "" }
}
}
```
如果你想设置一个目录作为任何命名空间的备用目录，你可以使用空的前缀，像这样：
{
"autoload": {
"psr-0": { "": "src/" }
}
```json
{
"autoload": {
"psr-0": { "": "src/" }
}
}
```
<a name="Classmap"></a>
#### Classmap
`classmap` 引用的所有组合，都会在 install/update 过程中生成，并存储到 `vendor/composer/autoload_classmap.php` 文件中。这个 map 是经过扫描指定目录（同样支持直接精确到文件）中所有的 `.php` 和 `.inc` 文件里内置的类而得到的。
你可以用 classmap 生成支持支持自定义加载的不遵循 PSR-0 规范的类库。要配置它指向需要的目录，以便能够准确搜索到类文件。
你可以用 classmap 生成支持支持自定义加载的不遵循 PSR-0/4 规范的类库。要配置它指向需要的目录，以便能够准确搜索到类文件。
例：
实例：
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
```json
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
}
```
<a name="Files"></a>
#### Files
如果你想要明确的指定，在每次请求时都要载入某些文件，那么你可以使用 'files' autoloading。通常作为函数库的载入方式（而非类库）。
例：
实例：
{
"autoload": {
"files": ["src/MyLibrary/functions.php"]
}
```json
{
"autoload": {
"files": ["src/MyLibrary/functions.php"]
}
}
```
### autoload-dev <span>(root-only)</span>
This section allows to define autoload rules for development purposes.
Classes needed to run the test suite should not be included in the main autoload
rules to avoid polluting the autoloader in production and when other people use
your package as a dependency.
Therefore, it is a good idea to rely on a dedicated path for your unit tests
and to add it within the autoload-dev section.
Example:
```json
{
"autoload": {
"psr-4": { "MyLibrary\\": "src/" }
},
"autoload-dev": {
"psr-4": { "MyLibrary\\Tests\\": "tests/" }
}
}
```
<a name="include-path"></a>
### include-path
@ -452,17 +562,23 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别
一个追加到 PHP `include_path` 中的列表。
例：
实例：
{
"include-path": ["lib/"]
}
```json
{
"include-path": ["lib/"]
}
```
可选。
<a name="target-dir"></a>
### target-dir
> **DEPRECATED**: This is only present to support legacy PSR-0 style autoloading,
> and all new code should preferably use PSR-4 without target-dir and projects
> using PSR-0 with PHP namespaces are encouraged to migrate to PSR-4 instead.
定义当前包安装的目标文件夹。
若某个包的根目录，在它申明的命名空间之下，将不能正确的使用自动加载。而 `target-dir` 解决了这个问题。
@ -471,12 +587,14 @@ Symfony 就是一个例子。它有一些独立的包作为组件。Yaml 组件
要做到这一点 `autoload` 和 `target-dir` 应该定义如下：
{
"autoload": {
"psr-0": { "Symfony\\Component\\Yaml\\": "" }
},
"target-dir": "Symfony/Component/Yaml"
}
```json
{
"autoload": {
"psr-0": { "Symfony\\Component\\Yaml\\": "" }
},
"target-dir": "Symfony/Component/Yaml"
}
```
可选。
@ -514,49 +632,51 @@ Repositories 并不是递归调用的，只能在“Root包”的 `composer.json
更多相关内容，请查看 [资源库](05-repositories.md)。
例：
实例：
{
"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/"
}
}
}
]
}
```
> **注意：** 顺序是非常重要的，当 Composer 查找资源包时，它会按照顺序进行。默认情况下 Packagist 是最后加入的，因此自定义设置将可以覆盖 Packagist 上的包。
@ -570,8 +690,12 @@ Repositories 并不是递归调用的，只能在“Root包”的 `composer.json
* **process-timeout:** 默认为 `300`。处理进程结束时间，例如：git 克隆的时间。Composer 将放弃超时的任务。如果你的网络缓慢或者正在使用一个巨大的包，你可能要将这个值设置的更高一些。
* **use-include-path:** 默认为 `false`。如果为 true，Composer autoloader 还将在 PHP include path 中继续查找类文件。
* **preferred-install:** 默认为 `auto`。它的值可以是 `source`、`dist` 或 `auto`。这个选项允许你设置 Composer 的默认安装方法。
* **github-protocols:** 默认为 `["git", "https"]`。从 github.com 克隆时使用的协议优先级清单，因此默认情况下将优先使用 git 协议进行克隆。
* **github-oauth:** 一个域名和 oauth keys 的列表。例如：使用 `{"github.com": "oauthtoken"}` 作为此选项的值，将使用 `oauthtoken` 来访问 github 上的私人仓库，并绕过 low IP-based rate 的 API 限制。
* **github-protocols:** 默认为 `["git", "https", "ssh"]`。从 github.com 克隆时使用的协议优先级清单，因此默认情况下将优先使用 git 协议进行克隆。你可以重新排列它们的次序，例如，如果你的网络有代理服务器或 git 协议的效率很低，你就可以提升 https 协议的优先级。
* **github-oauth:** 一个域名和 oauth keys 的列表。
例如：使用 `{"github.com": "oauthtoken"}` 作为此选项的值，
将使用 `oauthtoken` 来访问 github 上的私人仓库，并绕过 low IP-based rate 的 API 限制。
[关联知识](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
关于如何获取 GitHub 的 OAuth token。
* **vendor-dir:** 默认为 `vendor`。通过设置你可以安装依赖到不同的目录。
* **bin-dir:** 默认为 `vendor/bin`。如果一个项目包含二进制文件，它们将被连接到这个目录。
* **cache-dir:** unix 下默认为 `$home/cache`，Windows 下默认为 `C:\Users\<user>\AppData\Local\Composer`。用于存储 composer 所有的缓存文件。相关信息请查看 [COMPOSER_HOME](03-cli.md#composer-home)。
@ -582,17 +706,21 @@ Repositories 并不是递归调用的，只能在“Root包”的 `composer.json
* **cache-files-maxsize:** 默认为 `300MiB`。Composer 缓存的最大容量，超出后将优先清除旧的缓存数据，直到缓存量低于这个数值。
* **prepend-autoloader:** 默认为 `true`。如果设置为 false，composer autoloader 将不会附加到现有的自动加载机制中。这有时候用来解决与其它自动加载机制产生的冲突。
* **autoloader-suffix:** 默认为 `null`。Composer autoloader 的后缀，当设置为空时将会产生一个随机的字符串。
* **optimize-autoloader** Defaults to `false`. Always optimize when dumping
the autoloader.
* **github-domains:** 默认为 `["github.com"]`。一个 github mode 下的域名列表。这是用于GitHub的企业设置。
* **notify-on-install:** 默认为 `true`。Composer 允许资源仓库定义一个用于通知的 URL，以便有人从其上安装资源包时能够得到一个反馈通知。此选项允许你禁用该行为。
* **discard-changes:** 默认为 `false`，它的值可以是 `true`、`false` 或 `stash`。这个选项允许你设置在非交互模式下，当处理失败的更新时采用的处理方式。`true` 表示永远放弃更改。`"stash"` 表示继续尝试。Use this for CI servers or deploy scripts if you tend to have modified vendors.
例：
实例：
{
"config": {
"bin-dir": "bin"
}
```json
{
"config": {
"bin-dir": "bin"
}
}
```
<a name="scripts"></a>
### scripts <span>(root-only)</span>
@ -608,7 +736,9 @@ Composer 允许你在安装过程中的各个阶段挂接脚本。
这可以是几乎任何东西。若要从脚本事件访问处理程序，你可以这样做：
$extra = $event->getComposer()->getPackage()->getExtra();
```php
$extra = $event->getComposer()->getPackage()->getExtra();
```
可选。
@ -630,13 +760,15 @@ See [Vendor Binaries](articles/vendor-binaries.md) for more details.
* **exclude:** 允许设置一个需要被排除的路径的列表。使用与 .gitignore 文件相同的语法。一个前导的（!）将会使其变成白名单而无视之前相同目录的排除设定。前导斜杠只会在项目的相对路径的开头匹配。星号为通配符。
例：
实例：
{
"archive": {
"exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
}
```json
{
"archive": {
"exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
}
}
```
在这个例子中我们 include `/dir/foo/bar/file`、`/foo/bar/baz`、`/file.php`、`/foo/my.test` 但排除了 `/foo/bar/any`、`/foo/baz`、`/my.test`。

346
cn-introduction/05-repositories.md
View File

@ -76,16 +76,18 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一
唯一必须的字段是 `packages`。它的 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 }
}
```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 }
}
}
}
```
`@composer.json` 标记将会从此包的指定版本中读取 `composer.json` 的内容，其内至少应包含以下信息：
@ -95,14 +97,16 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一
这是一个最简单的包定义：
{
"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"
}
}
```
它还可以包含任何在 [composer.json 架构](04-schema.md) 中介绍的字段。
@ -113,17 +117,21 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一
例如使用下面的值：
{
"notify-batch": "/downloads/"
}
```json
{
"notify-batch": "/downloads/"
}
```
对于 `example.org/packages.json` 包含的 `monolog/monolog` 包，它将会发送一个 `POST` 请求到 `example.org/downloads/`，使用下面的 JSON request body：
{
"downloads": [
{"name": "monolog/monolog", "version": "1.2.1.0"},
]
}
```json
{
"downloads": [
{"name": "monolog/monolog", "version": "1.2.1.0"},
]
}
```
`version` 字段将包含标准化的版本号。
@ -134,21 +142,23 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一
对于较大的资源库，可以拆分 `packages.json` 为多个文件。`includes` 字段允许你引用这些额外的文件。
例：
实例：
{
"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"
}
}
}
```
文件的 SHA-1 码允许它被缓存，仅在 hash 值改变时重新请求。
@ -161,34 +171,38 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一
`providers-url` 描述了如何在服务器上找到这些 provider 文件。它是以资源库的根目录为起点的绝对路径。
例：
实例：
{
"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"
}
```
这些文件包含资源包的名称以及哈希值，以验证文件的完整性，例如：
{
"providers": {
"acme/foo": {
"sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82"
},
"acme/bar": {
"sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233"
}
```json
{
"providers": {
"acme/foo": {
"sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82"
},
"acme/bar": {
"sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233"
}
}
}
```
上述文件申明了 `acme/foo` 和 `acme/bar` 可以在这个资源库找到，通过加载由 `providers-url` 引用的文件，替换 `%name%` 为包名并且替换 `%hash%` 为 sha256 的值。这些文件本身只包含上文提到的 [packages](#packages) 的定义。
上述文件申明了 `acme/foo` 和 `acme/bar` 可以在这个资源库找到，通过加载由 `providers-url` 引用的文件，替换 `%package%` 为包名并且替换 `%hash%` 为 sha256 的值。这些文件本身只包含上文提到的 [packages](#packages) 的定义。
这些字段是可选的。你也许并不需要它们来自定义存储库。
@ -209,17 +223,19 @@ VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管
例如，假设你 fork 了 monolog，在 `bugfix` 分支修复了一个 bug：
{
"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"
}
}
```
当你运行 `php composer.phar update` 时，你应该得到你修改的版本，而不是 packagist.org 上的 `monolog/monolog`。
@ -232,17 +248,19 @@ VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管
完全相同的解决方案，也可以让你使用你 GitHub 和 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"
}
]
}
```
唯一的要求是为一个 git 客户端安装 SSH 秘钥。
@ -264,22 +282,29 @@ Git 并不是 VCS 资源库唯一支持的版本管理系统。
VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需要明确的指定一个 `git`、`svn` 或 `hg` 作为资源库类型，而不是 `vcs`。
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
attempt to use github's zip files.
<a name="Subversion-Options"></a>
#### Subversion 选项
由于 Subversion 没有原生的分支和标签的概念，Composer 假设在默认情况下该代码位于 `$url/trunk`、`$url/branches` 和 `$url/tags` 内。如果你的存储库使用了不同的布局，你可以更改这些值。例如，如果你使用大写的名称，你可以像这样配置资源库：
{
"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"
}
]
}
```
如果你的存储库目录中没有任何分支或标签文件夹，你可以将 `branches-path` 或 `tags-path` 设置为 `false`。
@ -292,18 +317,20 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需
例如使用 `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": "*"
}
}
```
在这种情况下渠道的简称（别名）是 `pear2`，因此 `PEAR2_HTTP_Request` 包的名称应该写作 `pear-pear2/PEAR2_HTTP_Request`。
@ -335,23 +362,25 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需
为了说明这一点，下面的例子会从你的 PEAR 资源库中得到 `BasePackage`、`TopLevelPackage1` 和 `TopLevelPackage2` 资源包，并从 Github 资源库中获取 `IntermediatePackage` 资源包：
{
"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": "*"
}
}
```
<a name="Package"></a>
### Package
@ -362,32 +391,34 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需
这是一个 smarty 模板引擎的例子：
{
"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.*"
}
}
```
通常你不需要去定义 `source`，因为你并不是真的需要它。
@ -432,25 +463,30 @@ Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻
在某些情况下，或许没有能力拥有之前提到的任何一种线上资源库。Typical example could be cross-organisation library exchange through built artifacts。当然大部分的时间他们都是私有的。为了简化维护，可以简单的使用 `artifact` 资源库类型，来引用一个包含那些私有包的 ZIP 存档的文件夹：
{
"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"
}
}
```
每个 zip artifact 都只是一个 ZIP 存档，放置在 `composer.json` 所在的根目录：
$ unzip -l acme-corp-parser-10.3.5.zip
composer.json
...
```sh
unzip -l acme-corp-parser-10.3.5.zip
composer.json
...
```
如果有两个不同版本的资源包，它们都会被导入。当有一个新版本的存档被添加到 artifact 文件夹，并且你运行了 `update` 命令，该版本就会被导入，并且 Composer 将更新到最新版本。
@ -459,13 +495,15 @@ Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻
你可以在 `composer.json` 中禁用默认的 Packagist 资源库。
{
"repositories": [
{
"packagist": false
}
]
}
```json
{
"repositories": [
{
"packagist": false
}
]
}
```
&larr; [架构](04-schema.md) | [社区](06-community.md) &rarr;

36
cn-introduction/articles/aliases.md
View File

@ -6,7 +6,7 @@
## 为什么使用别名？
当你使用 VCS 资源库，你将只会得到类似于这样的版本号：从分支发布的标签获取，它看起来像 `2.0`。比较特殊的是，对于你的 `master` 分支，你会得到一个最新提交的 `dev-master` 版本。对于你的 `bugfix` 分支，你会得到一个最新提交的 `dev-bugfix` 版本。以此类推，这些特殊的版本标识可以用来获取最新的分支源码。
当你使用 VCS 资源库，你将只会得到类似于这样的版本号：从分支发布的标签获取，它看起来像 `2.0` 或 `2.0.x`。比较特殊的是，对于你的 `master` 分支，你会得到一个最新提交的 `dev-master` 版本。对于你的 `bugfix` 分支，你会得到一个最新提交的 `dev-bugfix` 版本。以此类推，这些特殊的版本标识可以用来获取最新的分支源码。
如果你的 `master` 分支使用标签发布了 `1.0` 系列版本，即 `1.0.1`、`1.0.2`、`1.0.3` 等等，任何依赖它的资源包都可能会使用 `1.0.*` 这个版本约束。
@ -18,13 +18,15 @@
`dev-master` 指向一个在你 VCS 项目上的主分支。有些用户会想要使用最新的开发版本，这是相当常见的情况。因此，Composer 允许你别名你的 `dev-master` 版本为一个 `1.0.x-dev` 的版本号。这是通过在 `composer.json` 文件中的 `extra` 下指定 `branch-alias` 字段来完成的：
{
"extra": {
"branch-alias": {
"dev-master": "1.0.x-dev"
}
```json
{
"extra": {
"branch-alias": {
"dev-master": "1.0.x-dev"
}
}
}
```
此处的分支版本必须以 `dev-` 开头（不可比较的版本名称），对应的别名必须是可比较的开发版本名称（即，以数字开头，并以 `.x-dev` 结束）。`branch-alias` 所引用的分支必须是存在的。对于 `dev-master` 你需要在 `master` 分支上提交它。
@ -44,18 +46,20 @@
只要在你项目根目录的 `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"
}
}
```
它将会在你的 GitHub 上获取 `monolog/monolog` 的 `dev-bugfix` 版本并将其版本别名为 `1.0.x-dev`。

128
cn-introduction/articles/custom-installers.md
View File

@ -25,13 +25,15 @@
在这样一个模板包的例子中 composer.json 将使用以下设置：
{
"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": "*"
}
}
```
> **重要提示：** 为了确保这个模板安装程序在安装模板包之前就已存在，模板包必须写入对此安装程序包的依赖。
@ -52,22 +54,24 @@
1. [type][1] 属性必须是 `composer-plugin`。
2. [extra][2] 属性必须包含 `class` 元素，它定义了插件类的名称（包含命名空间）。如果这个包有多个插件类，可以使用数组的形式进行定义。
例：
实例：
{
"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"
}
}
```
### 插件类
@ -75,22 +79,26 @@
这个类可以被放在任何位置、使用任何名字，只要能够根据 `extra.class` 中的定义被自动加载即可。
例：
实例：
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);
}
}
```
### 自定义安装程序类
@ -107,41 +115,45 @@ InstallerInterface 类定义了以下方法（请查阅源码以获得更详细
* **uninstall()** 这里你可以定义在移除一个包时需要执行的动作。
* **getInstallPath()** 这个方法需要返回一个资源包将要安装的位置。_相对于 composer.json 文件的位置。_
例：
实例：
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;
}
}
```
这个例子演示了，简单的继承 [`Composer\Installer\LibraryInstaller`][5] 类来剥离 `phpdocumentor/template-` 前缀，并用剩余的部分重新组装了一个完全不同的安装路径。
> _并非安装在 `/vendor` 目录，任何使用这个安装程序的资源包，将被放置在 `/data/templates/<stripped name>` 目录中。_

132
cn-introduction/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,7 +190,7 @@ 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`:
```
```json
{
"require-dependencies": true
}

112
cn-introduction/articles/plugins.md
View File

@ -23,36 +23,42 @@
此外，你必须 require 一个特殊的资源包 `composer-plugin-api`，定义与你的插件相兼容的 composer plugin API 版本。目前 composer plugin API 的版本为1.0.0。
例：
实例：
{
"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"
}
}
```
### 插件类
每一个插件都必须提供一个实现了 [`Composer\Plugin\PluginInterface`][3] 接口的类。类中的 `activate()` 方法在插件载入后被调用，并接收两个类的实例：[`Composer\Composer`][4] 和 [`Composer\IO\IOInterface`][5]。使用这两个对象可以读取所有的配置，操作所有的内部对象和状态。
例：
实例：
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);
}
}
```
## 事件处理程序
@ -65,48 +71,52 @@
> 一个插件也可以订阅 [脚本事件][7]。
例：
实例：
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);
}
}
}
```
## 使用插件

78
cn-introduction/articles/scripts.md
View File

@ -33,6 +33,8 @@ Composer 在运行过程中将会触发以下事件：
| **post-autoload-dump** | 在自动加载器被转储后触发，无论是 `install`/`update` 还是 `dump-autoload` 命令都会触发。
| **post-root-package-install** | 在 `create-project` 命令期间，根包安装完成后触发。
| **post-create-project-cmd** | 在 `create-project` 命令执行后触发。
- **pre-archive-cmd**: occurs before the `archive` command is executed.
- **post-archive-cmd**: occurs after the `archive` command is executed.
> **注意：**Composer 不会去执行任何依赖包中定义的 `install` 或 `update` 相关脚本。因此你不应该在依赖包中申明 `pre-update-cmd` 或 `pre-install-cmd`。如果你需要在执行 `install` 或 `update` 命令前使用脚本，请确保它们已被定义在根包中。
@ -48,47 +50,51 @@ Composer 在运行过程中将会触发以下事件：
脚本定义实例：
{
"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/"
]
}
}
```
使用前面定义的例子，这里的 `MyVendor\MyClass` 类，就可以被使用来执行 PHP 的回调：
<?php
namespace MyVendor;
use Composer\Script\Event;
class MyClass
```php
<?php
namespace MyVendor;
use Composer\Script\Event;
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
}
}
```
当一个事件被触发，Composer 的内部事件处理程序将接收一个 `Composer\Script\Event` 对象，这是传递给您的 PHP 回调的第一个参数。这个 `Event` 对象拥有一些 getter 方法来帮助你取得当前事件的上下文：
- `getComposer()`: 返回当前的 `Composer\Composer` 对象实例。
@ -99,6 +105,8 @@ Composer 在运行过程中将会触发以下事件：
如果你想手动运行事件脚本，可以使用下面的语法结构：
$ composer run-script [--dev] [--no-dev] script
```sh
composer run-script [--dev] [--no-dev] script
```
例如 `composer run-script post-install-cmd` 将会运行所有 **post-install-cmd** 事件下定义的脚本。

67
cn-introduction/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)
@ -104,3 +112,42 @@ Or, you can increase the limit with a command-line argument:
2. Search for an ```AutoRun``` key inside ```HKEY_LOCAL_MACHINE\Software\Microsoft\Command Processor```
or ```HKEY_CURRENT_USER\Software\Microsoft\Command Processor```.
3. Check if it contains any path to non-existent file, if it's the case, just remove them.
## API rate limit and OAuth tokens
Because of GitHub's rate limits on their API it can happen that Composer prompts
for authentication asking your username and password so it can go ahead with its work.
If you would prefer not to provide your GitHub credentials to Composer you can
manually create a token using the following procedure:
1. [Create](https://github.com/settings/applications) an OAuth token on GitHub.
[Read more](https://github.com/blog/1509-personal-api-tokens) on this.
2. Add it to the configuration running `composer config -g github-oauth.github.com <oauthtoken>`
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`
This could be happening because the VPS runs out of memory and has no Swap space enabled.
```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:
```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
cn-introduction/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
cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md
View File

@ -4,25 +4,29 @@
如果你是一个 **包作者** 并且希望自己的资源包被安装到自定义的目录中，简单的 require `composer/installers` 依赖，并设置适当的 `type` 属性。这是常见的方式，如果你的资源包专门用于一个框架，如 CakePHP、Drupal 或 WordPress。这是一个 WordPress 主题的 composer.json 文件的例子：
{
"name": "you/themename",
"type": "wordpress-theme",
"require": {
"composer/installers": "~1.0"
}
```json
{
"name": "you/themename",
"type": "wordpress-theme",
"require": {
"composer/installers": "~1.0"
}
}
```
现在当你用 Composer 安装这个主题时，它就会被放置在 `wp-content/themes/themename/` 目录。目前已被支持的 `type` 类型请查看 [current supported types](https://github.com/composer/installers#current-supported-types)。
对于一个 **包使用者** 你可以为一个包设置或覆盖安装路径，requires composer/installers 并在 extra 下设置 `installer-paths` 属性。Drupal 的多站点设置就是一个很好的例子，其中的资源包应该被安装到各自网站的子目录。在这里我们使用 composer/installers 来覆盖安装路径：
{
"extra": {
"installer-paths": {
"sites/example.com/modules/{$name}": ["vendor/package"]
}
```json
{
"extra": {
"installer-paths": {
"sites/example.com/modules/{$name}": ["vendor/package"]
}
}
}
```
现在该资源包将被安装到你指定的目录，并替换 `$name` 变量，而不是默认目录。

21
cn-introduction/faqs/why-are-unbound-version-constraints-a-bad-idea.md Normal file
View File

@ -0,0 +1,21 @@
# Why are unbound version constraints a bad idea?
A version constraint without an upper bound such as `*`, `>=3.4` or
`dev-master` will allow updates to any future version of the dependency.
This includes major versions breaking backward compatibility.
Once a release of your package is tagged, you cannot tweak its dependencies
anymore in case a dependency breaks BC - you have to do a new release but the
previous one stays broken.
The only good alternative is to define an upper bound on your constraints,
which you can increase in a new release after testing that your package is
compatible with the new major version of your dependency.
For example instead of using `>=3.4` you should use `~3.4` which allows all
versions up to `3.999` but does not include `4.0` and above. The `~` operator
works very well with libraries follow [semantic versioning](http://semver.org).
**Note:** As a package maintainer, you can make the life of your users easier
by providing an [alias version](../articles/aliases.md) for your development
branch to allow it to match bound constraints.

77
en-back/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,7 +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:
```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
@ -73,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
@ -83,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.
@ -95,13 +110,13 @@ Then, just run `composer` in order to run Composer instead of `php composer.phar
Composer is part of the homebrew-php project.
1. Tap the homebrew-php repository into your brew installation if you haven't done
so yet: `brew tap josegonzalez/homebrew-php`
2. Run `brew install josegonzalez/php/composer`.
3. Use Composer with the `composer` command.
> **Note:** If you receive an error saying PHP53 or higher is missing use this command to install php
> `brew install php53-intl`
```sh
brew update
brew tap josegonzalez/homebrew-php
brew tap homebrew/versions
brew install php55-intl
brew install josegonzalez/php/composer
```
## Installation - Windows
@ -118,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 "eval('?>'.file_get_contents('https://getcomposer.org/installer'));"
```sh
C:\Users\username>cd C:\bin
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
```
> **Note:** If the above fails due to file_get_contents, 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`:
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
@ -142,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.
@ -159,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.

81
en-back/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.*`).
@ -82,6 +90,10 @@ including, 2.0). Since in theory there should be no backwards compatibility
breaks until 2.0, that works well. Another way of looking at it is that using
`~` specifies a minimum version, but allows the last digit specified to go up.
> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint
> like `~1.2` would not install it. As said above `~1.2` only means the `.2`
> can change but the `1.` part is fixed.
### Stability
By default only stable releases are taken into consideration. If you would like
@ -95,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.
@ -137,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).
@ -167,33 +185,38 @@ 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-0": {"Acme\\": "src/"}
}
```json
{
"autoload": {
"psr-4": {"Acme\\": "src/"}
}
}
```
Composer will register a
[PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
autoloader for the `Acme` namespace.
Composer will register a [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader
for the `Acme` namespace.
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/Acme/Foo.php` containing an `Acme\Foo` class.
filename would be `src/Foo.php` containing an `Acme\Foo` class.
After adding the `autoload` field, you have to re-run `install` to re-generate
the `vendor/autoload.php` file.
@ -202,15 +225,17 @@ 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-0 autoloading, classmap is also supported. This allows
classes to be autoloaded even if they do not conform to PSR-0. See the
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.
> **Note:** Composer provides its own autoloader. If you don't want to use
that one, you can just include `vendor/composer/autoload_namespaces.php`,
which returns an associative array mapping namespaces to directories.
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;

83
en-back/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.
@ -33,8 +35,11 @@ installed on the system but are not actually installable by Composer. This
includes PHP itself, PHP extensions and some system libraries.
* `php` represents the PHP version of the user, allowing you to apply
constraints, e.g. `>=5.4.0`. To require a 64bit version of php, you can
require the `php-64bit` package.
constraints, e.g. `>=5.4.0`. To require a 64bit version of php, you can
require the `php-64bit` package.
* `hhvm` represents the version of the HHVM runtime (aka HipHop Virtual
Machine) and allows you to apply a constraint, e.g., '>=2.3.3'.
* `ext-<name>` allows you to require PHP extensions (includes core
extensions). Versioning can be quite inconsistent here, so it's often
@ -42,8 +47,8 @@ includes PHP itself, PHP extensions and some system libraries.
package name is `ext-gd`.
* `lib-<name>` allows constraints to be made on versions of libraries used by
PHP. The following are available: `curl`, `iconv`, `libxml`, `openssl`,
`pcre`, `uuid`, `xsl`.
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.
@ -59,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.
@ -75,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
@ -98,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
@ -137,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
@ -152,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).

166
en-back/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
@ -85,7 +89,7 @@ resolution.
* **--no-plugins:** Disables plugins.
* **--no-progress:** Removes the progress display that can mess with some
terminals or scripts which don't handle backspace characters.
* **--optimize-autoloader (-o):** Convert PSR-0 autoloading to classmap to get a faster
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
autoloader. This is recommended especially for production, but can take
a bit of time to run so it is currently not done by default.
@ -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
@ -118,7 +128,7 @@ You can also use wildcards to update a bunch of packages at once:
* **--no-plugins:** Disables plugins.
* **--no-progress:** Removes the progress display that can mess with some
terminals or scripts which don't handle backspace characters.
* **--optimize-autoloader (-o):** Convert PSR-0 autoloading to classmap to get a faster
* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
autoloader. This is recommended especially for production, but can take
a bit of time to run so it is currently not done by default.
* **--lock:** Only updates the lock file hash to suppress warning about the
@ -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
@ -149,6 +163,8 @@ to the command.
* **--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
required packages.
## global
@ -160,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
@ -174,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.
@ -186,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
@ -225,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
@ -244,7 +274,13 @@ 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
* **--no-check-all:** Wether or not composer do a complete validation.
## status
@ -252,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
@ -288,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
@ -320,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
@ -341,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.
@ -373,18 +426,19 @@ If you need to update the autoloader because of new classes in a classmap
package for example, you can use "dump-autoload" to do that without having to
go through an install or update.
Additionally, it can dump an optimized autoloader that converts PSR-0 packages
Additionally, it can dump an optimized autoloader that converts PSR-0/4 packages
into classmap ones for performance reasons. In large applications with many
classes, the autoloader can take up a substantial portion of every request's
time. Using classmaps for everything is less convenient in development, but
using this option you can still use PSR-0 for convenience and classmaps for
using this option you can still use PSR-0/4 for convenience and classmaps for
performance.
### Options
* **--optimize (-o):** Convert PSR-0 autoloading to classmap to get a faster
* **--optimize (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
autoloader. This is recommended especially for production, but can take
a bit of time to run so it is currently not done by default.
* **--no-dev:** Disables autoload-dev rules.
## licenses
@ -402,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
@ -410,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
@ -422,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
@ -438,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

476
en-back/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,20 +387,73 @@ 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
Autoload mapping for a PHP autoloader.
Currently [`PSR-0`](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
autoloading, `classmap` generation and `files` are supported. PSR-0 is the recommended way though
since it offers greater flexibility (no need to regenerate the autoloader when you add
classes).
Currently [`PSR-0`](http://www.php-fig.org/psr/psr-0/) autoloading,
[`PSR-4`](http://www.php-fig.org/psr/psr-4/) autoloading, `classmap` generation and
`files` includes are supported. PSR-4 is the recommended way though since it offers
greater ease of use (no need to regenerate the autoloader when you add classes).
#### PSR-4
Under the `psr-4` key you define a mapping from namespaces to paths, relative to the
package root. When autoloading a class like `Foo\\Bar\\Baz` a namespace prefix
`Foo\\` pointing to a directory `src/` means that the autoloader will look for a
file named `src/Bar/Baz.php` and include it if present. Note that as opposed to
the older PSR-0 style, the prefix (`Foo\\`) is **not** present in the file path.
Namespace prefixes must end in `\\` to avoid conflicts between similar prefixes.
For example `Foo` would match classes in the `FooBar` namespace so the trailing
backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct.
The PSR-4 references are all combined, during install/update, into a single
key => value array which may be found in the generated file
`vendor/composer/autoload_psr4.php`.
Example:
```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:
```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:
```json
{
"autoload": {
"psr-4": { "": "src/" }
}
}
```
#### PSR-0
@ -399,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
@ -446,16 +524,18 @@ key => value array which may be found in the generated file
classes in all `.php` and `.inc` files in the given directories/files.
You can use the classmap generation support to define autoloading for all libraries
that do not follow PSR-0. To configure this you specify all directories or files
that do not follow PSR-0/4. To configure this you specify all directories or files
to search for classes.
Example:
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
```json
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
}
```
#### Files
@ -465,11 +545,37 @@ 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>
This section allows to define autoload rules for development purposes.
Classes needed to run the test suite should not be included in the main autoload
rules to avoid polluting the autoloader in production and when other people use
your package as a dependency.
Therefore, it is a good idea to rely on a dedicated path for your unit tests
and to add it within the autoload-dev section.
Example:
```json
{
"autoload": {
"psr-4": { "MyLibrary\\": "src/" }
},
"autoload-dev": {
"psr-4": { "MyLibrary\\Tests\\": "tests/" }
}
}
```
### include-path
@ -481,14 +587,20 @@ A list of paths which should get appended to PHP's `include_path`.
Example:
{
"include-path": ["lib/"]
}
```json
{
"include-path": ["lib/"]
}
```
Optional.
### target-dir
> **DEPRECATED**: This is only present to support legacy PSR-0 style autoloading,
> and all new code should preferably use PSR-4 without target-dir and projects
> using PSR-0 with PHP namespaces are encouraged to migrate to PSR-4 instead.
Defines the installation target.
In case the package root is below the namespace declaration you cannot
@ -503,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.
@ -566,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.
@ -627,14 +743,16 @@ The following options are supported:
* **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"]`. A list of protocols to
* **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
prioritize the https protocol if you are behind a proxy or have somehow bad
performances with the git protocol.
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
@ -661,6 +779,8 @@ The following options are supported:
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
@ -674,11 +794,13 @@ The following options are supported:
Example:
{
"config": {
"bin-dir": "bin"
}
```json
{
"config": {
"bin-dir": "bin"
}
}
```
### scripts <span>(root-only)</span>
@ -694,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.
@ -721,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`.

343
en-back/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,35 +174,39 @@ 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
`%name%` by the package name and `%hash%` by the sha256 field. Those files
`%package%` by the package name and `%hash%` by the sha256 field. Those files
themselves just contain package definitions as described [above](#packages).
This field is optional. You probably don't need it for your own custom
@ -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.
@ -292,6 +310,11 @@ The VCS driver to be used is detected automatically based on the URL. However,
should you need to specify one for whatever reason, you can use `git`, `svn` or
`hg` as the repository type instead of `vcs`.
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
attempt to use github's zip files.
#### Subversion Options
Since Subversion has no native concept of branches and tags, Composer assumes
@ -300,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`.
@ -328,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`.
@ -382,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
@ -413,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.
@ -507,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
@ -537,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;

36
en-back/articles/aliases.md
View File

@ -7,7 +7,7 @@
## Why aliases?
When you are using a VCS repository, you will only get comparable versions for
branches that look like versions, such as `2.0`. For your `master` branch, you
branches that look like versions, such as `2.0` or `2.0.x`. For your `master` branch, you
will get a `dev-master` version. For your `bugfix` branch, you will get a
`dev-bugfix` version.
@ -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
en-back/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

132
en-back/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,7 +190,7 @@ 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`:
```
```json
{
"require-dependencies": true
}

106
en-back/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

72
en-back/articles/scripts.md
View File

@ -40,6 +40,8 @@ Composer fires the following named events during its execution process:
installed, during the `create-project` command.
- **post-create-project-cmd**: occurs after the `create-project` command is
executed.
- **pre-archive-cmd**: occurs before the `archive` command is executed.
- **post-archive-cmd**: occurs after the `archive` command is executed.
**NOTE: Composer makes no assumptions about the state of your dependencies
prior to `install` or `update`. Therefore, you should not specify scripts that
@ -65,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:
@ -120,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.

67
en-back/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)
@ -104,3 +112,42 @@ Or, you can increase the limit with a command-line argument:
2. Search for an ```AutoRun``` key inside ```HKEY_LOCAL_MACHINE\Software\Microsoft\Command Processor```
or ```HKEY_CURRENT_USER\Software\Microsoft\Command Processor```.
3. Check if it contains any path to non-existent file, if it's the case, just remove them.
## API rate limit and OAuth tokens
Because of GitHub's rate limits on their API it can happen that Composer prompts
for authentication asking your username and password so it can go ahead with its work.
If you would prefer not to provide your GitHub credentials to Composer you can
manually create a token using the following procedure:
1. [Create](https://github.com/settings/applications) an OAuth token on GitHub.
[Read more](https://github.com/blog/1509-personal-api-tokens) on this.
2. Add it to the configuration running `composer config -g github-oauth.github.com <oauthtoken>`
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`
This could be happening because the VPS runs out of memory and has no Swap space enabled.
```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:
```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
en-back/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
en-back/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.

21
en-back/faqs/why-are-unbound-version-constraints-a-bad-idea.md Normal file
View File

@ -0,0 +1,21 @@
# Why are unbound version constraints a bad idea?
A version constraint without an upper bound such as `*`, `>=3.4` or
`dev-master` will allow updates to any future version of the dependency.
This includes major versions breaking backward compatibility.
Once a release of your package is tagged, you cannot tweak its dependencies
anymore in case a dependency breaks BC - you have to do a new release but the
previous one stays broken.
The only good alternative is to define an upper bound on your constraints,
which you can increase in a new release after testing that your package is
compatible with the new major version of your dependency.
For example instead of using `>=3.4` you should use `~3.4` which allows all
versions up to `3.999` but does not include `4.0` and above. The `~` operator
works very well with libraries follow [semantic versioning](http://semver.org).
**Note:** As a package maintainer, you can make the life of your users easier
by providing an [alias version](../articles/aliases.md) for your development
branch to allow it to match bound constraints.