From 03186a658e44f84c8a2a9320206c5c6978a74074 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 1 Jan 2014 06:41:25 -0800 Subject: [PATCH 001/125] Initial commit --- README.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ee67418 --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +composer-doc-cn +=============== + +Composer 中文文档 -- 2.46.2 From 21350be6d0d81cccc71bd20740bc7ebbc102e7bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 1 Jan 2014 22:50:17 +0800 Subject: [PATCH 002/125] added first --- cn-introduction/00-intro.md | 152 ++++ cn-introduction/01-basic-usage.md | 197 +++++ cn-introduction/02-libraries.md | 199 +++++ cn-introduction/03-cli.md | 535 +++++++++++++ cn-introduction/04-schema.md | 735 ++++++++++++++++++ cn-introduction/05-repositories.md | 549 +++++++++++++ cn-introduction/06-community.md | 34 + cn-introduction/articles/aliases.md | 96 +++ cn-introduction/articles/custom-installers.md | 186 +++++ .../handling-private-packages-with-satis.md | 188 +++++ cn-introduction/articles/plugins.md | 150 ++++ cn-introduction/articles/scripts.md | 125 +++ cn-introduction/articles/troubleshooting.md | 106 +++ cn-introduction/articles/vendor-binaries.md | 106 +++ cn-introduction/dev/DefaultPolicy.md | 55 ++ ...ckage-to-a-custom-path-for-my-framework.md | 46 ++ ...the-dependencies-in-my-vendor-directory.md | 31 + ...ng-comparisons-and-wildcards-a-bad-idea.md | 21 + ...-composer-load-repositories-recursively.md | 34 + en-back/00-intro.md | 167 ++++ en-back/01-basic-usage.md | 216 +++++ en-back/02-libraries.md | 199 +++++ en-back/03-cli.md | 535 +++++++++++++ en-back/04-schema.md | 735 ++++++++++++++++++ en-back/05-repositories.md | 549 +++++++++++++ en-back/06-community.md | 34 + en-back/articles/aliases.md | 96 +++ en-back/articles/custom-installers.md | 186 +++++ .../handling-private-packages-with-satis.md | 188 +++++ en-back/articles/plugins.md | 150 ++++ en-back/articles/scripts.md | 125 +++ en-back/articles/troubleshooting.md | 106 +++ en-back/articles/vendor-binaries.md | 106 +++ en-back/dev/DefaultPolicy.md | 55 ++ ...ckage-to-a-custom-path-for-my-framework.md | 46 ++ ...the-dependencies-in-my-vendor-directory.md | 31 + ...ng-comparisons-and-wildcards-a-bad-idea.md | 21 + ...-composer-load-repositories-recursively.md | 34 + 38 files changed, 7124 insertions(+) create mode 100644 cn-introduction/00-intro.md create mode 100644 cn-introduction/01-basic-usage.md create mode 100644 cn-introduction/02-libraries.md create mode 100644 cn-introduction/03-cli.md create mode 100644 cn-introduction/04-schema.md create mode 100644 cn-introduction/05-repositories.md create mode 100644 cn-introduction/06-community.md create mode 100644 cn-introduction/articles/aliases.md create mode 100644 cn-introduction/articles/custom-installers.md create mode 100644 cn-introduction/articles/handling-private-packages-with-satis.md create mode 100644 cn-introduction/articles/plugins.md create mode 100644 cn-introduction/articles/scripts.md create mode 100644 cn-introduction/articles/troubleshooting.md create mode 100644 cn-introduction/articles/vendor-binaries.md create mode 100644 cn-introduction/dev/DefaultPolicy.md create mode 100644 cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md create mode 100644 cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md create mode 100644 cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md create mode 100644 cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md create mode 100644 en-back/00-intro.md create mode 100644 en-back/01-basic-usage.md create mode 100644 en-back/02-libraries.md create mode 100644 en-back/03-cli.md create mode 100644 en-back/04-schema.md create mode 100644 en-back/05-repositories.md create mode 100644 en-back/06-community.md create mode 100644 en-back/articles/aliases.md create mode 100644 en-back/articles/custom-installers.md create mode 100644 en-back/articles/handling-private-packages-with-satis.md create mode 100644 en-back/articles/plugins.md create mode 100644 en-back/articles/scripts.md create mode 100644 en-back/articles/troubleshooting.md create mode 100644 en-back/articles/vendor-binaries.md create mode 100644 en-back/dev/DefaultPolicy.md create mode 100644 en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md create mode 100644 en-back/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md create mode 100644 en-back/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md create mode 100644 en-back/faqs/why-can't-composer-load-repositories-recursively.md diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md new file mode 100644 index 0000000..ee958d3 --- /dev/null +++ b/cn-introduction/00-intro.md @@ -0,0 +1,152 @@ +# 简介 + +Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖的代码库，它会在你的项目中为你安装他们。 + +--- + +- [简介](#简介) + - [依赖管理](#依赖管理) + - [声明依赖关系](#声明依赖关系) + - [系统要求](#系统要求) + - [安装 - *nix](#安装---nix) + - [下载 Composer 的可执行文件](#下载-composer-的可执行文件) + - [局部安装](#局部安装) + - [全局安装](#全局安装) + - [全局安装 (on OSX via homebrew)](#全局安装-on-osx-via-homebrew) + - [安装 - Windows](#安装---windows) + - [使用安装程序](#使用安装程序) + - [手动安装](#手动安装) + - [使用 Composer](#使用-composer) + - [自动加载](#自动加载) + +--- + +## 依赖管理 + +Composer 不是一个包管理器。是的，它涉及 "packages" 和 "libraries"，但它在每个项目的基础上进行管理，在你项目的某个目录中（例如 `vendor`）进行安装。默认情况下它不会在全局安装任何东西。因此，这仅仅是一个依赖管理。 + +这种想法并不新鲜，Composer 受到了 node's [npm](http://npmjs.org/) +和 ruby's [bundler](http://gembundler.com/) 的强烈启发。而当时 PHP 下并没有类似的工具。 + +Composer 将这样为你解决问题： + +a) 你有一个项目依赖于若干个库。 + +b) 其中一些库依赖于其他库。 + +c) 你声明你所依赖的东西。 + +d) Composer 会找出哪个版本的包需要安装，并安装它们（将它们下载到你的项目中）。 + +## 声明依赖关系 + +比方说，你正在创建一个项目，你需要一个库来做日志记录。你决定使用 [monolog](https://github.com/Seldaek/monolog)。为了将它添加到你的项目中，你所需要做的就是创建一个 `composer.json` 文件，其中描述了项目的依赖关系。 + + { + "require": { + "monolog/monolog": "1.2.*" + } + } + +我们只要指出我们的项目需要一些 `monolog/monolog` 的包，从 `1.2` 开始的任何版本。 + +## 系统要求 + +运行 Composer 需要 PHP 5.3.2+ 以上版本。一些敏感的 PHP 设置和编译标志也是必须的，但对于任何不兼容项安装程序都会抛出警告。 + +我们将从包的来源直接安装，而不是简单的下载 zip 文件，你需要 git 、 svn 或者 hg ，这取决于你载入的包所使用的版本管理系统。 + +Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX 平台上运行的同样出色。 + +## 安装 - *nix + +### 下载 Composer 的可执行文件 + +#### 局部安装 + +要真正获取 Composer，我们需要做两件事。首先安装 Composer （同样的，这意味着它将下载到你的项目中）： + + $ curl -sS 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 + +#### 全局安装 + +你可以将此文件放在任何地方。如果你把它放在系统的 `PATH` 目录中，你就能在全局访问它。 在类Unix系统中，你甚至可以在使用时不加 `php` 前缀。 + +你可以执行这些命令让 `composer` 在你的系统中进行全局调用： + + $ curl -sS https://getcomposer.org/installer | php + $ mv composer.phar /usr/local/bin/composer + +> **注意：** 如果上诉命令因为权限执行失败， +> 请使用 sudo 再次尝试运行 `mv` 那行命令。 + +现在只需要运行 `composer` 命令就可以使用 Composer 而不需要输入 `php composer.phar`。 + +#### 全局安装 (on OSX via homebrew) + +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` + +## 安装 - Windows + +### 使用安装程序 + +这是将 Composer 安装在你机器上的最简单的方法。 + +下载并且运行 [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe)，它将安装最新版本的 Composer ，并设置好系统的环境变量，因此你可以在任何目录下直接使用 `composer` 命令。 + +### 手动安装 + +设置系统的环境变量 `PATH` 并运行安装命令下载 composer.phar 文件： + + C:\Users\username>cd C:\bin + C:\bin>php -r "eval('?>'.file_get_contents('https://getcomposer.org/installer'));" + +> **注意：** 如果收到 file_get_contents 错误提示，请使用 `http` 链接或者在 php.ini 中开启 php_openssl.dll 。 + +在 `composer.phar` 同级目录下新建文件 `composer.bat` ： + + C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat + +关闭当前的命令行窗口，打开新的命令行窗口进行测试： + + C:\Users\username>composer -V + Composer version 27d8904 + + C:\Users\username> + +## 使用 Composer + +现在我们将使用 Composer 来安装项目的依赖。如果在当前目录下没有一个 `composer.json` 文件，请查看[基本用法](01-basic-usage.md)章节。 + +要解决和下载依赖，请执行 `install` 命令： + + $ php composer.phar install + +如果你进行了全局安装，并且没有 phar 文件在当前目录，请使用下面的命令代替： + + $ composer install + +继续 [上面的例子](#声明依赖关系)，这里将下载 monolog 到 `vendor/monolog/monolog` 目录。 + +## 自动加载 + +除了库的下载，Composer 还准备了一个自动加载文件，它可以加载 Composer 下载的库中所有的类文件。使用它，你只需要将下面这行代码添加到你项目的引导文件中： + + require 'vendor/autoload.php'; + +现在我们就可以使用 monolog 了！想要学习更多关于 Composer 的知识，请查看“基本用法”章节。 + +[基本用法](01-basic-usage.md) → diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md new file mode 100644 index 0000000..40a547f --- /dev/null +++ b/cn-introduction/01-basic-usage.md @@ -0,0 +1,197 @@ +# 基本用法 + +--- + +- [基本用法](#基本用法) + - [安装](#安装) + - [`composer.json`：项目安装](#composerjson项目安装) + - [关于 `require` Key](#关于-require-key) + - [包名称](#包名称) + - [包版本](#包版本) + - [下一个重要版本（波浪号运算符）](#下一个重要版本波浪号运算符) + - [稳定性](#稳定性) + - [安装依赖关系](#安装依赖关系) + - [`composer.lock` - 锁文件](#composerlock---锁文件) + - [packagist](#packagist) + - [自动加载](#自动加载) + +--- + +## 安装 + +安装 Composer，你只需要下载 `composer.phar` 可执行文件。 + + $ curl -sS https://getcomposer.org/installer | php + +详细请查看 [简介](00-intro.md) 章节。 + +要检查 Composer 是否正常工作，只需要通过 `php` 来执行 PHAR： + + $ php composer.phar + +这将返回给你一个可执行的命令列表。 + +> **注意：** 你也可以仅执行 `--check` 选项而无需下载 Composer。 +> 要获取更多的信息请使用 `--help`。 +> +> $ curl -sS https://getcomposer.org/installer | php -- --check +> $ curl -sS https://getcomposer.org/installer | php -- --help + +## `composer.json`：项目安装 + +要开始在你的项目中使用 Composer，你只需要一个 `composer.json` 文件。该文件包含了项目的依赖和其它的一些元数据。 + +这个 [JSON format](http://json.org/) 是很容易编写的。它允许你定义嵌套结构。 + +### 关于 `require` Key + +第一件事情（并且往往只需要做这一件事），你需要在 `composer.json` 文件中指定 `require` key 的值。你只需要简单的告诉 Composer 你的项目需要依赖哪些包。 + + { + "require": { + "monolog/monolog": "1.0.*" + } + } + +你可以看到， `require` 需要一个 **包名称** （例如 `monolog/monolog`） 映射到 **包版本** （例如 `1.0.*`） 的对象。 + +### 包名称 + +包名称由供应商名称和其项目名称构成。通常容易产生相同的项目名称，而供应商名称的存在则很好的解决了命名冲突的问题。它允许两个不同的人创建同样名为 `json` 的库，而之后它们将被命名为 `igorw/json` 和 `seldaek/json`。 + +这里我们需要引入 `monolog/monolog`，供应商名称与项目的名称相同，对于一个具有唯一名称的项目，我们推荐这么做。它还允许以后在同一个命名空间添加更多的相关项目。如果你维护着一个库，这将使你可以很容易的把它分离成更小的部分。 + +### 包版本 + +在前面的例子中，我们引入的 monolog 版本指定为 `1.0.*`。这表示任何从 `1.0` 开始的开发分支，它将会匹配 `1.0.0`、`1.0.2` 或者 `1.0.20`。 + +版本约束可以用几个不同的方法来指定。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称实例描述
确切的版本号1.0.2你可以指定包的确切版本。
范围 + >=1.0 + >=1.0,<2.0 + >=1.0,<1.1|>=1.2 + 通过使用比较操作符可以指定有效的版本范围。 +
有效的运算符：>、>=、<、<=、!=。 +
你可以定义多个范围，用逗号隔开，这将被视为一个逻辑AND处理。一个管道符号|将作为逻辑OR处理。 +
AND 的优先级高于 OR。
通配符1.0.*你可以使用通配符*来指定一种模式。1.0.*与>=1.0,<1.1是等效的。
赋值运算符~1.2这对于遵循语义化版本号的项目非常有用。~1.2相当于>=1.2,<2.0。想要了解更多，请阅读下一小节。
+ +### 下一个重要版本（波浪号运算符） + +`~` 最好用例子来解释： `~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应该都没有向后兼容性问题，所以效果很好。你还会看到它的另一种用法，使用 `~` 指定最低版本，但允许版本号的最后一位数字上升。 + +### 稳定性 + +默认情况下只有稳定的发行版才会被考虑在内。如果你也想获得 RC、beta、alpha 或 dev 版本，你可以使用 [稳定标志](04-schema.md#package-links)。你可以对所有的包做 [最小稳定性](04-schema.md#minimum-stability) 设置，而不是每个依赖逐一设置。 + +## 安装依赖关系 + +获取定义的依赖到你的本地项目，只需要调用 `composer.phar` 运行 `install` 命令。 + + $ php composer.phar install + +接着前面的例子，这将会找到 `monolog/monolog` 的最新版本，并将它下载到 `vendor` 目录。 +这是一个惯例把第三方的代码到一个指定的目录 `vendor`。如果是 monolog 将会创建 `vendor/monolog/monolog` 目录。 + +> **小技巧：** 如果你正在使用Git来管理你的项目， +> 你可能要添加 `vendor` 到你的 `.gitignore` 文件中。 +> 你不会希望将所有的代码都添加到你的版本库中。 + +另一件事是 `install` 命令将创建一个 `composer.lock` 文件到你项目的根目录中。 + +## `composer.lock` - 锁文件 + +在安装依赖后，Composer 将把安装时确切的版本号列表写入 `composer.lock` 文件。这将锁定改项目的特定版本。 + +**请提交你应用程序的 `composer.lock` （包括 `composer.json`）到你的版本库中** + +这是非常重要的，因为 `install` 命令将会检查锁文件是否存在，如果存在，它将下载指定的版本（忽略 `composer.json` 文件中的定义）。 + +这意味着，任何人建立项目都将下载与指定版本完全相同的依赖。你的持续集成服务器、生产环境、你团队中的其他开发人员、每件事、每个人都使用相同的依赖，从而减轻潜在的错误对部署的影响。即使你独自开发项目，在六个月内重新安装项目时，你也可以放心的继续工作，即使从那时起你的依赖已经发布了许多新的版本。 + +如果不存在 `composer.lock` 文件，Composer 将读取 `composer.json` 并创建锁文件。 + +这意味着如果你的依赖更新了新的版本，你将不会获得任何更新。此时要更新你的依赖版本请使用 `update` 命令。这将获取最新匹配的版本（根据你的 `composer.json` 文件）并将新版本更新进锁文件。 + + $ php composer.phar update + +如果只想安装或更新一个依赖，你可以白名单它们： + + $ php composer.phar update monolog/monolog [...] + +> **注意：** 对于库，并不一定建议提交锁文件 +> 请参考：[库的锁文件](02-libraries.md#lock-file). + +## packagist + +[packagist](https://packagist.org/) 是 Composer 的主要资源库。 一个 Composer 的库基本上是一个包的源：记录了可以得到包的地方。Packagist 的目标是成为大家使用库资源的中央存储平台。这意味着你可以 `require` 那里的任何包。 + +当你访问 [packagist website](https://packagist.org/) (packagist.org)，你可以浏览和搜索资源包。 + +任何支持 Composer 的开源项目应该发布自己的包在 packagist 上。虽然并不一定要发布在 packagist 上来使用 Composer，但它使我们的编程生活更加轻松。 + +## 自动加载 + +对于库的自动加载信息，Composer 生成了一个 `vendor/autoload.php` 文件。你可以简单的引入这个文件，你会得到一个免费的自动加载支持。 + + require 'vendor/autoload.php'; + +这使得你可以很容易的使用第三方代码。例如：如果你的项目依赖 monolog，你就可以像这样开始使用这个类库，并且他们将被自动加载。 + + $log = new Monolog\Logger('name'); + $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); + + $log->addWarning('Foo'); + +你可以在 `composer.json` 的 `autoload` 字段中增加自己的 autoloader。 + + { + "autoload": { + "psr-0": {"Acme\\": "src/"} + } + } + +Composer 将注册 [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) autoloader 到 `Acme` 命名空间。 + +你可以定义一个从命名空间到目录的映射。此时 `src` 会在你项目的根目录，与 `vendor` 文件夹同级。例如 `src/Acme/Foo.php` 文件应该包含 `Acme\Foo` 类。 + +添加 `autoload` 字段后，你应该再次运行 `install` 命令来生成 `vendor/autoload.php` 文件。 + +引用这个文件也将返回 autoloader 的实例，你可以将包含调用的返回值存储在变量中，并添加更多的命名空间。这对于在一个测试套件中自动加载类文件是非常有用的，例如。 + + $loader = require 'vendor/autoload.php'; + $loader->add('Acme\\Test\\', __DIR__); + +除了 PSR-0 自动加载，classmap 也是支持的。这允许类被自动加载，即使不符合 PSR-0 规范。详细请查看 [自动加载-参考](04-schema.md#autoload)。 + +> **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_namespaces.php` 文件，它返回一个关联数组映射了命名空间的目录。 + +← [简介](00-intro.md) | [库](02-libraries.md) → diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md new file mode 100644 index 0000000..2742806 --- /dev/null +++ b/cn-introduction/02-libraries.md @@ -0,0 +1,199 @@ +# Libraries + +This chapter will tell you how to make your library installable through Composer. + +## Every project is a package + +As soon as you have a `composer.json` in a directory, that directory is a +package. When you add a `require` to a project, you are making a package that +depends on other packages. The only difference between your project and +libraries is that your project is a package without a name. + +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.*" + } + } + +In this case the project name is `acme/hello-world`, where `acme` is the +vendor name. Supplying a vendor name is mandatory. + +> **Note:** If you don't know what to use as a vendor name, your GitHub +username is usually a good bet. While package names are case insensitive, the +convention is all lowercase and dashes for word separation. + +## Platform packages + +Composer has platform packages, which are virtual packages for things that are +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. + +* `ext-` allows you to require PHP extensions (includes core + extensions). Versioning can be quite inconsistent here, so it's often + a good idea to just set the constraint to `*`. An example of an extension + package name is `ext-gd`. + +* `lib-` allows constraints to be made on versions of libraries used by + PHP. The following are available: `curl`, `iconv`, `libxml`, `openssl`, + `pcre`, `uuid`, `xsl`. + +You can use `composer show --platform` to get a list of your locally available +platform packages. + +## Specifying the version + +You need to specify the package's version some way. When you publish your +package on Packagist, it is able to infer the version from the VCS (git, svn, +hg) information, so in that case you do not have to specify it, and it is +recommended not to. See [tags](#tags) and [branches](#branches) to see how +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" + } + +> **Note:** You should avoid specifying the version field explicitly, because +> for tags the value must match the tag name. + +### Tags + +For every tag that looks like a version, a package version of that tag will be +created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix +of `-patch`, `-alpha`, `-beta` or `-RC`. The suffixes can also be followed by +a number. + +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 + +> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions) +> in a `require` statement has to be specified without prefix +> (e.g. tag `v1.0.0` will result in version `1.0.0`). + +### Branches + +For every branch, a package development version will be created. If the branch +name looks like a version, the version will be `{branchname}-dev`. For example +a branch `2.0` will get a version `2.0.x-dev` (the `.x` is added for technical +reasons, to make sure it is recognized as a branch, a `2.0.x` branch would also +be valid and be turned into `2.0.x-dev` as well. If the branch does not look +like a version, it will be `dev-{branchname}`. `master` results in a +`dev-master` version. + +Here are some examples of version branch names: + + 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 +> for more details. + +### Aliases + +It is possible to alias branch names to versions. For example, you could alias +`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all +the packages. + +See [Aliases](articles/aliases.md) for more information. + +## Lock file + +For your library you may commit the `composer.lock` file if you want to. This +can help your team to always test against the same dependency versions. +However, this lock file will not have any effect on other projects that depend +on it. It only has an effect on the main project. + +If you do not want to commit the lock file and you are using git, add it to +the `.gitignore`. + +## Publishing to a VCS + +Once you have a vcs repository (version control system, e.g. git) containing a +`composer.json` file, your library is already composer-installable. In this +example we will publish the `acme/hello-world` library on GitHub under +`github.com/username/hello-world`. + +Now, to test installing the `acme/hello-world` package, we create a new +project locally. We will call it `acme/blog`. This blog will depend on +`acme/hello-world`, which in turn depends on `monolog/monolog`. We can +accomplish this by creating a new `blog` directory somewhere, containing a +`composer.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 +described. + +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" + } + } + +For more details on how package repositories work and what other types are +available, see [Repositories](05-repositories.md). + +That's all. You can now install the dependencies by running Composer's +`install` command! + +**Recap:** Any git/svn/hg repository containing a `composer.json` can be added +to your project by specifying the package repository and declaring the +dependency in the `require` field. + +## Publishing to packagist + +Alright, so now you can publish packages. But specifying the vcs repository +every time is cumbersome. You don't want to force all your users to do that. + +The other thing that you may have noticed is that we did not specify a package +repository for `monolog/monolog`. How did that work? The answer is packagist. + +[Packagist](https://packagist.org/) is the main package repository for +Composer, and it is enabled by default. Anything that is published on +packagist is available automatically through Composer. Since monolog +[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend +on it without having to specify any additional repositories. + +If we wanted to share `hello-world` with the world, we would publish it on +packagist as well. Doing so is really easy. + +You simply hit the big "Submit Package" button and sign up. Then you submit +the URL to your VCS repository, at which point packagist will start crawling +it. Once it is done, your package will be available to anyone. + +← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) → diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md new file mode 100644 index 0000000..84539b4 --- /dev/null +++ b/cn-introduction/03-cli.md @@ -0,0 +1,535 @@ +# Command-line interface + +You've already learned how to use the command-line interface to do some +things. This chapter documents all the available commands. + +To get help from the command-line, simply call `composer` or `composer list` +to see the complete list of commands, then `--help` combined with any of those +can give you more information. + +## Global Options + +The following options are available with every command: + +* **--verbose (-v):** Increase verbosity of messages. +* **--help (-h):** Display help information. +* **--quiet (-q):** Do not output any message. +* **--no-interaction (-n):** Do not ask any interactive question. +* **--working-dir (-d):** If specified, use the given directory as working directory. +* **--profile:** Display timing and memory usage information +* **--ansi:** Force ANSI output. +* **--no-ansi:** Disable ANSI output. +* **--version (-V):** Display this application version. + +## Process Exit Codes + +* **0:** OK +* **1:** Generic/unknown error code +* **2:** Dependency solving error code + +## init + +In the [Libraries](02-libraries.md) chapter we looked at how to create a +`composer.json` by hand. There is also an `init` command available that makes +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 + +### Options + +* **--name:** Name of the package. +* **--description:** Description of the package. +* **--author:** Author name of the package. +* **--homepage:** Homepage of the package. +* **--require:** Package to require with a version constraint. Should be + in format `foo/bar:1.0.0`. +* **--require-dev:** Development requirements, see **--require**. +* **--stability (-s):** Value for the `minimum-stability` field. + +## install + +The `install` command reads the `composer.json` file from the current +directory, resolves the dependencies, and installs them into `vendor`. + + $ 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 +everyone using the library will get the same versions of the dependencies. + +If there is no `composer.lock` file, composer will create one after dependency +resolution. + +### Options + +* **--prefer-source:** There are two ways of downloading a package: `source` + and `dist`. For stable versions composer will use the `dist` by default. + The `source` is a version control repository. If `--prefer-source` is + enabled, composer will install from `source` if there is one. This is + useful if you want to make a bugfix to a project and get a local git + clone of the dependency directly. +* **--prefer-dist:** Reverse of `--prefer-source`, composer will install + from `dist` if possible. This can speed up installs substantially on build + servers and other use cases where you typically do not run updates of the + vendors. It is also a way to circumvent problems with git if you do not + have a proper setup. +* **--dry-run:** If you want to run through an installation without actually + installing a package, you can use `--dry-run`. This will simulate the + installation and show you what would happen. +* **--dev:** Install packages listed in `require-dev` (this is the default behavior). +* **--no-dev:** Skip installing packages listed in `require-dev`. +* **--no-scripts:** Skips execution of scripts defined in `composer.json`. +* **--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 + autoloader. This is recommended especially for production, but can take + a bit of time to run so it is currently not done by default. + +## update + +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 + +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 + +You can also use wildcards to update a bunch of packages at once: + + $ php composer.phar update vendor/* + +### Options + +* **--prefer-source:** Install packages from `source` when available. +* **--prefer-dist:** Install packages from `dist` when available. +* **--dry-run:** Simulate the command without actually doing anything. +* **--dev:** Install packages listed in `require-dev` (this is the default behavior). +* **--no-dev:** Skip installing packages listed in `require-dev`. +* **--no-scripts:** Skips execution of scripts defined in `composer.json`. +* **--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 + 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 + lock file being out of date. +* **--with-dependencies** Add also all dependencies of whitelisted packages to the whitelist. + So all packages with their dependencies are updated recursively. + +## require + +The `require` command adds new packages to the `composer.json` file from +the current directory. + + $ php composer.phar require + +After adding/changing the requirements, the modified requirements will be +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 + +### Options + +* **--prefer-source:** Install packages from `source` when available. +* **--prefer-dist:** Install packages from `dist` when available. +* **--dev:** Add packages to `require-dev`. +* **--no-update:** Disables the automatic update of the dependencies. +* **--no-progress:** Removes the progress display that can mess with some + terminals or scripts which don't handle backspace characters. + +## global + +The global command allows you to run other commands like `install`, `require` +or `update` as if you were running them from the [COMPOSER_HOME](#composer-home) +directory. + +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 + +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 + +## search + +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 + +You can also search for more than one term by passing multiple arguments. + +### Options + +* **--only-name (-N):** Search only in name. + +## show + +To list all of the available packages, you can use the `show` command. + + $ 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 + + 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/ + + 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 + +### Options + +* **--installed (-i):** List the packages that are installed. +* **--platform (-p):** List only platform packages (php & extensions). +* **--self (-s):** List the root package info. + +## depends + +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 + + nrk/monolog-fluent + poc/poc + propel/propel + symfony/monolog-bridge + symfony/symfony + +### Options + +* **--link-type:** The link types to match on, can be specified multiple + times. + +## validate + +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 + +## status + +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 + +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 + +## 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 + +If you would like to instead update to a specific release simply specify it: + + $ composer 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 + +### Options + +* **--rollback (-r):** Rollback to the last version you had installed. +* **--clean-backups:** Delete old backups during an update. This makes the current version of composer the only backup available after the update. + +## config + +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 + +### Usage + +`config [options] [setting-key] [setting-value1] ... [setting-valueN]` + +`setting-key` is a configuration option name and `setting-value1` is a +configuration value. For settings that can take an array of values (like +`github-protocols`), more than one setting-value arguments are allowed. + +See the [config schema section](04-schema.md#config) for valid configuration +options. + +### Options + +* **--global (-g):** Operate on the global config file located at +`$COMPOSER_HOME/config.json` by default. Without this option, this command +affects the local composer.json file or a file specified by `--file`. +* **--editor (-e):** Open the local composer.json file using in a text editor as +defined by the `EDITOR` env variable. With the `--global` option, this opens +the global config file. +* **--unset:** Remove the configuration element named by `setting-key`. +* **--list (-l):** Show the list of current config variables. With the `--global` + option this lists the global configuration only. +* **--file="..." (-f):** Operate on a specific file instead of composer.json. Note + that this cannot be used in conjunction with the `--global` option. + +### Modifying Repositories + +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 + +## create-project + +You can use Composer to create new projects from an existing package. This is +the equivalent of doing a git clone/svn checkout followed by a composer install +of the vendors. + +There are several applications for this: + +1. You can deploy application packages. +2. You can check out any package and start developing on patches for example. +3. Projects with multiple developers can use this feature to bootstrap the + initial application for development. + +To create a new project using composer you can use the "create-project" command. +Pass it a package name, and the directory to create the project in. You can also +provide a version as third argument, otherwise the latest version is used. + +If the directory does not currently exist, it will be created during installation. + + 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. + +By default the command checks for the packages on packagist.org. + +### Options + +* **--repository-url:** Provide a custom repository to search for the package, + which will be used instead of packagist. Can be either an HTTP URL pointing + to a `composer` repository, or a path to a local `packages.json` file. +* **--stability (-s):** Minimum stability of package. Defaults to `stable`. +* **--prefer-source:** Install packages from `source` when available. +* **--prefer-dist:** Install packages from `dist` when available. +* **--dev:** Install packages listed in `require-dev`. +* **--no-install:** Disables installation of the vendors. +* **--no-plugins:** Disables plugins. +* **--no-scripts:** Disables the execution of the scripts defined in the root + package. +* **--no-progress:** Removes the progress display that can mess with some + terminals or scripts which don't handle backspace characters. +* **--keep-vcs:** Skip the deletion of the VCS metadata for the created + project. This is mostly useful if you run the command in non-interactive + mode. + +## dump-autoload + +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 +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 +performance. + +### Options + +* **--optimize (-o):** Convert PSR-0 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. + +## licenses + +Lists the name, version and license of every package installed. Use +`--format=json` to get machine readable output. + +## run-script + +To run [scripts](articles/scripts.md) manually you can use this command, +just give it the script name and optionally --no-dev to disable the dev mode. + +## diagnose + +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 + +## archive + +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 + +### Options + +* **--format (-f):** Format of the resulting archive: tar or zip (default: + "tar") +* **--dir:** Write the archive to this directory (default: ".") + +## help + +To get more information about a certain command, just use `help`. + + $ php composer.phar help install + +## Environment variables + +You can set a number of environment variables that override certain settings. +Whenever possible it is recommended to specify these settings in the `config` +section of `composer.json` instead. It is worth noting that the env vars will +always take precedence over the values specified in `composer.json`. + +### COMPOSER + +By setting the `COMPOSER` env variable it is possible to set the filename of +`composer.json` to something else. + +For example: + + $ COMPOSER=composer-other.json php composer.phar install + +### COMPOSER_ROOT_VERSION + +By setting this var you can specify the version of the root package, if it can +not be guessed from VCS info and is not present in `composer.json`. + +### COMPOSER_VENDOR_DIR + +By setting this var you can make composer install the dependencies into a +directory other than `vendor`. + +### COMPOSER_BIN_DIR + +By setting this option you can change the `bin` ([Vendor Binaries](articles/vendor-binaries.md)) +directory to something other than `vendor/bin`. + +### http_proxy or HTTP_PROXY + +If you are using composer from behind an HTTP proxy, you can use the standard +`http_proxy` or `HTTP_PROXY` env vars. Simply set it to the URL of your proxy. +Many operating systems already set this variable for you. + +Using `http_proxy` (lowercased) or even defining both might be preferable since +some tools like git or curl will only use the lower-cased `http_proxy` version. +Alternatively you can also define the git proxy using +`git config --global http.proxy `. + +### no_proxy + +If you are behind a proxy and would like to disable it for certain domains, you +can use the `no_proxy` env var. Simply set it to a comma separated list of +domains the proxy should *not* be used for. + +The env var accepts domains, IP addresses, and IP address blocks in CIDR +notation. You can restrict the filter to a particular port (e.g. `:80`). You +can also set it to `*` to ignore the proxy for all HTTP requests. + +### HTTP_PROXY_REQUEST_FULLURI + +If you use a proxy but it does not support the request_fulluri flag, then you +should set this env var to `false` or `0` to prevent composer from setting the +request_fulluri option. + +### HTTPS_PROXY_REQUEST_FULLURI + +If you use a proxy but it does not support the request_fulluri flag for HTTPS +requests, then you should set this env var to `false` or `0` to prevent composer +from setting the request_fulluri option. + +### COMPOSER_HOME + +The `COMPOSER_HOME` var allows you to change the composer home directory. This +is a hidden, global (per-user on the machine) directory that is shared between +all projects. + +By default it points to `/home//.composer` on \*nix, +`/Users//.composer` on OSX and +`C:\Users\\AppData\Roaming\Composer` on Windows. + +#### COMPOSER_HOME/config.json + +You may put a `config.json` file into the location which `COMPOSER_HOME` points +to. Composer will merge this configuration with your project's `composer.json` +when you run the `install` and `update` commands. + +This file allows you to set [configuration](04-schema.md#config) and +[repositories](05-repositories.md) for the user's projects. + +In case global configuration matches _local_ configuration, the _local_ +configuration in the project's `composer.json` always wins. + +### COMPOSER_CACHE_DIR + +The `COMPOSER_CACHE_DIR` var allows you to change the composer cache directory, +which is also configurable via the [`cache-dir`](04-schema.md#config) option. + +By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and +`C:\Users\\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows. + +### COMPOSER_PROCESS_TIMEOUT + +This env var controls the time composer waits for commands (such as git +commands) to finish executing. The default value is 300 seconds (5 minutes). + +### COMPOSER_DISCARD_CHANGES + +This env var controls the discard-changes [config option](04-schema.md#config). + +### COMPOSER_NO_INTERACTION + +If set to 1, this env var will make composer behave as if you passed the +`--no-interaction` flag to every command. This can be set on build boxes/CI. + +← [Libraries](02-libraries.md) | [Schema](04-schema.md) → diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md new file mode 100644 index 0000000..56e7871 --- /dev/null +++ b/cn-introduction/04-schema.md @@ -0,0 +1,735 @@ +# composer.json + +This chapter will explain all of the fields available in `composer.json`. + +## JSON schema + +We have a [JSON schema](http://json-schema.org) that documents the format and +can also be used to validate your `composer.json`. In fact, it is used by the +`validate` command. You can find it at: +[`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). + +## Root Package + +The root package is the package defined by the `composer.json` at the root of +your project. It is the main `composer.json` that defines your project +requirements. + +Certain fields only apply when in the root package context. One example of +this is the `config` field. Only the root package can define configuration. +The config of dependencies is ignored. This makes the `config` field +`root-only`. + +If you clone one of those dependencies to work on it, then that package is the +root package. The `composer.json` is identical, but the context is different. + +> **Note:** A package can be the root package or not, depending on the context. +> For example, if your project depends on the `monolog` library, your project +> is the root package. However, if you clone `monolog` from GitHub in order to +> fix a bug in it, then `monolog` is the root package. + +## Properties + +### name + +The name of the package. It consists of vendor name and project name, +separated by `/`. + +Examples: + +* monolog/monolog +* igorw/event-source + +Required for published packages (libraries). + +### description + +A short description of the package. Usually this is just one line long. + +Required for published packages (libraries). + +### version + +The version of the package. In most cases this is not required and should +be omitted (see below). + +This must follow the format of `X.Y.Z` or `vX.Y.Z` with an optional suffix +of `-dev`, `-patch`, `-alpha`, `-beta` or `-RC`. The patch, alpha, beta and +RC suffixes can also be followed by a number. + +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 + +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 +to omit it. + +> **Note:** Packagist uses VCS repositories, so the statement above is very +> much true for Packagist as well. Specifying the version yourself will +> most likely end up creating problems at some point due to human error. + +### type + +The type of the package. It defaults to `library`. + +Package types are used for custom installation logic. If you have a package +that needs some special logic, you can define a custom type. This could be a +`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will +all be specific to certain projects, and they will need to provide an +installer capable of installing packages of that type. + +Out of the box, composer supports four types: + +- **library:** This is the default. It will simply copy the files to `vendor`. +- **project:** This denotes a project rather than a library. For example + application shells like the [Symfony standard edition](https://github.com/symfony/symfony-standard), + CMSs like the [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) + or full fledged applications distributed as packages. This can for example + be used by IDEs to provide listings of projects to initialize when creating + a new workspace. +- **metapackage:** An empty package that contains requirements and will trigger + their installation, but contains no files and will not write anything to the + filesystem. As such, it does not require a dist or source key to be + installable. +- **composer-plugin:** A package of type `composer-plugin` may provide an + installer for other packages that have a custom type. Read more in the + [dedicated article](articles/custom-installers.md). + +Only use a custom type if you need custom logic during installation. It is +recommended to omit this field and have it just default to `library`. + +### keywords + +An array of keywords that the package is related to. These can be used for +searching and filtering. + +Examples: + + logging + events + database + redis + templating + +Optional. + +### homepage + +An URL to the website of the project. + +Optional. + +### time + +Release date of the version. + +Must be in `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` format. + +Optional. + +### license + +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 + +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/). + +For closed-source software, you may use `"proprietary"` as the license identifier. + +An Example: + + { + "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+" + ] + } + +Alternatively they can be separated with "or" and enclosed in parenthesis; + + { + "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. + +### authors + +The authors of the package. This is an array of objects. + +Each author object can have following properties: + +* **name:** The author's name. Usually his real name. +* **email:** The author's email address. +* **homepage:** An URL to the author's website. +* **role:** The authors' role in the project (e.g. developer or translator) + +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" + } + ] + } + +Optional, but highly recommended. + +### support + +Various information to get support about the project. + +Support information includes the following: + +* **email:** Email address for support. +* **issues:** URL to the Issue Tracker. +* **forum:** URL to the Forum. +* **wiki:** URL to the Wiki. +* **irc:** IRC channel for support, as irc://server/channel. +* **source:** URL to browse or download the sources. + +An example: + + { + "support": { + "email": "support@example.org", + "irc": "irc://irc.freenode.org/composer" + } + } + +Optional. + +### Package links + +All of the following take an object which maps package names to +[version constraints](01-basic-usage.md#package-versions). + +Example: + + { + "require": { + "monolog/monolog": "1.0.*" + } + } + +All links are optional fields. + +`require` and `require-dev` additionally support stability flags (root-only). +These allow you to further restrict or expand the stability of a package beyond +the scope of the [minimum-stability](#minimum-stability) setting. You can apply +them to a constraint, or just apply them to an empty constraint if you want to +allow unstable packages of a dependency for example. + +Example: + + { + "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" + } + } + +`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 +when you run update. These only work if you explicitly require a dev version +and append the reference with `#`. + +Example: + + { + "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 +> composer.json metadata will still be read from the branch name you specify +> before the hash. Because of that in some cases it will not be a practical +> workaround, and you should always try to switch to tagged releases as soon +> as you can. + +It is also possible to inline-alias a package constraint so that it matches +a constraint that it otherwise would not. For more information [see the +aliases article](articles/aliases.md). + +#### require + +Lists packages required by this package. The package will not be installed +unless those requirements can be met. + +#### require-dev (root-only) + +Lists packages required for developing this package, or running +tests, etc. The dev requirements of the root package are installed by default. +Both `install` or `update` support the `--no-dev` option that prevents dev +dependencies from being installed. + +#### conflict + +Lists packages that conflict with this version of this package. They +will not be allowed to be installed together with your package. + +Note that when specifying ranges like `<1.0, >= 1.1` in a `conflict` link, +this will state a conflict with all versions that are less than 1.0 *and* equal +or newer than 1.1 at the same time, which is probably not what you want. You +probably want to go for `<1.0 | >= 1.1` in this case. + +#### replace + +Lists packages that are replaced by this package. This allows you to fork a +package, publish it under a different name with its own version numbers, while +packages requiring the original package continue to work with your fork because +it replaces the original package. + +This is also useful for packages that contain sub-packages, for example the main +symfony/symfony package contains all the Symfony Components which are also +available as individual packages. If you require the main package it will +automatically fulfill any requirement of one of the individual components, +since it replaces them. + +Caution is advised when using replace for the sub-package purpose explained +above. You should then typically only replace using `self.version` as a version +constraint, to make sure the main package only replaces the sub-packages of +that exact version, and not any other version, which would be incorrect. + +#### provide + +List of other packages that are provided by this package. This is mostly +useful for common interfaces. A package could depend on some virtual +`logger` package, any library that implements this logger interface would +simply list it in `provide`. + +### suggest + +Suggested packages that can enhance or work well with this package. These are +just informational and are displayed after the package is installed, to give +your users a hint that they could add more packages, even though they are not +strictly required. + +The format is like package links above, except that the values are free text +and not version constraints. + +Example: + + { + "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). + +#### PSR-0 + +Under the `psr-0` key you define a mapping from namespaces to paths, relative to the +package root. Note that this also supports the PEAR-style non-namespaced convention. + +Please note namespace declarations should end in `\\` to make sure the autoloader +responds exactly. For example `Foo` would match in `FooBar` so the trailing +backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct. + +The PSR-0 references are all combined, during install/update, into a single key => value +array which may be found in the generated file `vendor/composer/autoload_namespaces.php`. + +Example: + + { + "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/"] } + } + } + +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": "" } + } + } + +If you want to have a fallback directory where any namespace can be, you can +use an empty prefix like: + + { + "autoload": { + "psr-0": { "": "src/" } + } + } + +#### Classmap + +The `classmap` references are all combined, during install/update, into a single +key => value array which may be found in the generated file +`vendor/composer/autoload_classmap.php`. This map is built by scanning for +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 +to search for classes. + +Example: + + { + "autoload": { + "classmap": ["src/", "lib/", "Something.php"] + } + } + +#### Files + +If you want to require certain files explicitly on every request then you can use +the 'files' autoloading mechanism. This is useful if your package includes PHP functions +that cannot be autoloaded by PHP. + +Example: + + { + "autoload": { + "files": ["src/MyLibrary/functions.php"] + } + } + +### include-path + +> **DEPRECATED**: This is only present to support legacy projects, and all new code +> should preferably use autoloading. As such it is a deprecated practice, but the +> feature itself will not likely disappear from Composer. + +A list of paths which should get appended to PHP's `include_path`. + +Example: + + { + "include-path": ["lib/"] + } + +Optional. + +### target-dir + +Defines the installation target. + +In case the package root is below the namespace declaration you cannot +autoload properly. `target-dir` solves this problem. + +An example is Symfony. There are individual packages for the components. The +Yaml component is under `Symfony\Component\Yaml`. The package root is that +`Yaml` directory. To make autoloading possible, we need to make sure that it +is not installed into `vendor/symfony/yaml`, but instead into +`vendor/symfony/yaml/Symfony/Component/Yaml`, so that the autoloader can load +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" + } + +Optional. + +### minimum-stability (root-only) + +This defines the default behavior for filtering packages by stability. This +defaults to `stable`, so if you rely on a `dev` package, you should specify +it in your file to avoid surprises. + +All versions of each package are checked for stability, and those that are less +stable than the `minimum-stability` setting will be ignored when resolving +your project dependencies. Specific changes to the stability requirements of +a given package can be done in `require` or `require-dev` (see +[package links](#package-links)). + +Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`, +and `stable`. + +### prefer-stable (root-only) + +When this is enabled, Composer will prefer more stable packages over unstable +ones when finding compatible stable packages is possible. If you require a +dev version or only alphas are available for a package, those will still be +selected granted that the minimum-stability allows for it. + +Use `"prefer-stable": true` to enable. + +### repositories (root-only) + +Custom package repositories to use. + +By default composer just uses the packagist repository. By specifying +repositories you can get packages from elsewhere. + +Repositories are not resolved recursively. You can only add them to your main +`composer.json`. Repository declarations of dependencies' `composer.json`s are +ignored. + +The following repository types are supported: + +* **composer:** A composer repository is simply a `packages.json` file served + via the network (HTTP, FTP, SSH), that contains a list of `composer.json` + objects with additional `dist` and/or `source` information. The `packages.json` + file is loaded using a PHP stream. You can set extra options on that stream + using the `options` parameter. +* **vcs:** The version control system repository can fetch packages from git, + svn and hg repositories. +* **pear:** With this you can import any pear repository into your composer + project. +* **package:** If you depend on a project that does not have any support for + composer whatsoever you can define the package inline using a `package` + repository. You basically just inline the `composer.json` object. + +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/" + } + } + } + ] + } + +> **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. +By default Packagist is added last which means that custom repositories can +override packages from it. + +### config (root-only) + +A set of configuration options. It is only used for projects. + +The following options are supported: + +* **process-timeout:** Defaults to `300`. The duration processes like git clones + can run before Composer assumes they died out. You may need to make this + higher if you have a slow connection or huge vendors. +* **use-include-path:** Defaults to `false`. If true, the Composer autoloader + will also look for classes in the PHP include path. +* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or + `auto`. This option allows you to set the install method Composer will prefer to + use. +* **github-protocols:** Defaults to `["git", "https"]`. 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. +* **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. +* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a + different directory if you want to. +* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they + will be symlinked into this directory. +* **cache-dir:** Defaults to `$home/cache` on unix systems and + `C:\Users\\AppData\Local\Composer` on Windows. Stores all the caches + used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home). +* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives + of packages. +* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata + for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`. +* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for + loading VCS repository metadata for the `git`/`hg` types and to speed up installs. +* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all + dist (zip, tar, ..) packages that it downloads. Those are purged after six + months of being unused by default. This option allows you to tweak this + duration (in seconds) or disable it completely by setting it to 0. +* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all + dist (zip, tar, ..) packages that it downloads. When the garbage collection + is periodically ran, this is the maximum size the cache will be able to use. + Older (less used) files will be removed first until the cache fits. +* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader + will not be prepended to existing autoloaders. This is sometimes required to fix + interoperability issues with other autoloaders. +* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for + the generated Composer autoloader. When null a random one will be generated. +* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in + github mode. This is used for GitHub Enterprise setups. +* **notify-on-install:** Defaults to `true`. Composer allows repositories to + define a notification URL, so that they get notified whenever a package from + that repository is installed. This option allows you to disable that behaviour. +* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or + `"stash"`. This option allows you to set the default style of handling dirty + updates when in non-interactive mode. `true` will always discard changes in + vendors, while `"stash"` will try to stash and reapply. Use this for CI + servers or deploy scripts if you tend to have modified vendors. + +Example: + + { + "config": { + "bin-dir": "bin" + } + } + +### scripts (root-only) + +Composer allows you to hook into various parts of the installation process +through the use of scripts. + +See [Scripts](articles/scripts.md) for events details and examples. + +### extra + +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(); + +Optional. + +### bin + +A set of files that should be treated as binaries and symlinked into the `bin-dir` +(from config). + +See [Vendor Binaries](articles/vendor-binaries.md) for more details. + +Optional. + +### archive + +A set of options for creating package archives. + +The following options are supported: + +* **exclude:** Allows configuring a list of patterns for excluded paths. The + pattern syntax matches .gitignore files. A leading exclamation mark (!) will + result in any matching files to be included even if a previous pattern + excluded them. A leading slash will only match at the beginning of the project + relative path. An asterisk will not expand to a directory separator. + +Example: + + { + "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`. + +Optional. + +← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) → diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md new file mode 100644 index 0000000..ae947ea --- /dev/null +++ b/cn-introduction/05-repositories.md @@ -0,0 +1,549 @@ +# Repositories + +This chapter will explain the concept of packages and repositories, what kinds +of repositories are available, and how they work. + +## Concepts + +Before we look at the different types of repositories that exist, we need to +understand some of the basic concepts that composer is built on. + +### Package + +Composer is a dependency manager. It installs packages locally. A package is +essentially just a directory containing something. In this case it is PHP +code, but in theory it could be anything. And it contains a package +description which has a name and a version. The name and the version are used +to identify the package. + +In fact, internally composer sees every version as a separate package. While +this distinction does not matter when you are using composer, it's quite +important when you want to change it. + +In addition to the name and the version, there is useful metadata. The information +most relevant for installation is the source definition, which describes where +to get the package contents. The package data points to the contents of the +package. And there are two options here: dist and source. + +**Dist:** The dist is a packaged version of the package data. Usually a +released version, usually a stable release. + +**Source:** The source is used for development. This will usually originate +from a source code repository, such as git. You can fetch this when you want +to modify the downloaded package. + +Packages can supply either of these, or even both. Depending on certain +factors, such as user-supplied options and stability of the package, one will +be preferred. + +### Repository + +A repository is a package source. It's a list of packages/versions. Composer +will look in all your repositories to find the packages your project requires. + +By default only the Packagist repository is registered in Composer. You can +add more repositories to your project by declaring them in `composer.json`. + +Repositories are only available to the root package and the repositories +defined in your dependencies will not be loaded. Read the +[FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md) if you +want to learn why. + +## Types + +### Composer + +The main repository type is the `composer` repository. It uses a single +`packages.json` file that contains all of the package metadata. + +This is also the repository type that packagist uses. To reference a +`composer` repository, just supply the path before the `packages.json` file. +In case of packagist, that file is located at `/packages.json`, so the URL of +the repository would be `packagist.org`. For `example.org/packages.json` the +repository URL would be `example.org`. + +#### packages + +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 } + } + } + } + +The `@composer.json` marker would be the contents of the `composer.json` from +that package version including as a minimum: + +* name +* version +* dist or source + +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" + } + } + +It may include any of the other fields specified in the [schema](04-schema.md). + +#### notify-batch + +The `notify-batch` field allows you to specify an URL that will be called +every time a user installs a package. The URL can be either an absolute path +(that will use the same domain as the repository) or a fully qualified URL. + +An example value: + + { + "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"}, + ] + } + +The version field will contain the normalized representation of the version +number. + +This field is optional. + +#### includes + +For larger repositories it is possible to split the `packages.json` into +multiple files. The `includes` field allows you to reference these additional +files. + +An example: + + { + "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. + +This field is optional. You probably don't need it for your own custom +repository. + +#### provider-includes and providers-url + +For very large repositories like packagist.org using the so-called provider +files is the preferred method. The `provider-includes` field allows you to +list a set of files that list package names provided by this repository. The +hash should be a sha256 of the files in this case. + +The `providers-url` describes how provider files are found on the server. It +is an absolute path from the repository root. + +An example: + + { + "provider-includes": { + "providers-a.json": { + "sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c" + }, + "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" + } + } + } + +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 +themselves just contain package definitions as described [above](#packages). + +This field is optional. You probably don't need it for your own custom +repository. + +#### stream options + +The `packages.json` file is loaded using a PHP stream. You can set extra options +on that stream using the `options` parameter. You can set any valid PHP stream +context option. See [Context options and parameters](http://php.net/manual/en/context.php) +for more information. + +### VCS + +VCS stands for version control system. This includes versioning systems like +git, svn or hg. Composer has a repository type for installing packages from +these systems. + +#### Loading a package from a VCS repository + +There are a few use cases for this. The most common one is maintaining your +own fork of a third party library. If you are using a certain library for your +project and you decide to change something in the library, you will want your +project to use the patched version. If the library is on GitHub (this is the +case most of the time), you can simply fork it there and push your changes to +your fork. After that you update the project's `composer.json`. All you have +to do is add your fork as a repository and update the version constraint to +point to your custom branch. For version constraint naming conventions see +[Libraries](02-libraries.md) for more information. + +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" + } + } + +When you run `php composer.phar update`, you should get your modified version +of `monolog/monolog` instead of the one from packagist. + +Note that you should not rename the package unless you really intend to fork +it in the long term, and completely move away from the original package. +Composer will correctly pick your package over the original one since the +custom repository has priority over packagist. If you want to rename the +package, you should do so in the default (often master) branch and not in a +feature branch, since the package name is taken from the default branch. + +If other dependencies rely on the package you forked, it is possible to +inline-alias it so that it matches a constraint that it otherwise would not. +For more information [see the aliases article](articles/aliases.md). + +#### Using private repositories + +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" + } + ] + } + +The only requirement is the installation of SSH keys for a git client. + +#### Git alternatives + +Git is not the only version control system supported by the VCS repository. +The following are supported: + +* **Git:** [git-scm.com](http://git-scm.com) +* **Subversion:** [subversion.apache.org](http://subversion.apache.org) +* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com) + +To get packages from these systems you need to have their respective clients +installed. That can be inconvenient. And for this reason there is special +support for GitHub and BitBucket that use the APIs provided by these sites, to +fetch the packages without having to install the version control system. The +VCS repository provides `dist`s for them that fetch the packages as zips. + +* **GitHub:** [github.com](https://github.com) (Git) +* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial) + +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`. + +#### Subversion Options + +Since Subversion has no native concept of branches and tags, Composer assumes +by default that code is located in `$url/trunk`, `$url/branches` and +`$url/tags`. If your repository has a different layout you can change those +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" + } + ] + } + +If you have no branches or tags directory you can disable them entirely by +setting the `branches-path` or `tags-path` to `false`. + +If the package is in a sub-directory, e.g. `/trunk/foo/bar/composer.json` and +`/tags/1.0/foo/bar/composer.json`, then you can make composer access it by +setting the `"package-path"` option to the sub-directory, in this example it +would be `"package-path": "foo/bar/"`. + +### PEAR + +It is possible to install packages from any PEAR channel by using the `pear` +repository. Composer will prefix all package names with `pear-{channelName}/` to +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": "*" + } + } + +In this case the short name of the channel is `pear2`, so the +`PEAR2_HTTP_Request` package name becomes `pear-pear2/PEAR2_HTTP_Request`. + +> **Note:** The `pear` repository requires doing quite a few requests per +> package, so this may considerably slow down the installation process. + +#### Custom vendor alias + +It is possible to alias PEAR channel packages with a custom vendor name. + +Example: + +Suppose you have a private PEAR repository and wish to use Composer to +incorporate dependencies from a VCS. Your PEAR repository contains the +following packages: + + * `BasePackage` + * `IntermediatePackage`, which depends on `BasePackage` + * `TopLevelPackage1` and `TopLevelPackage2` which both depend on `IntermediatePackage` + +Without a vendor alias, Composer will use the PEAR channel name as the +vendor portion of the package name: + + * `pear-pear.foobar.repo/BasePackage` + * `pear-pear.foobar.repo/IntermediatePackage` + * `pear-pear.foobar.repo/TopLevelPackage1` + * `pear-pear.foobar.repo/TopLevelPackage2` + +Suppose at a later time you wish to migrate your PEAR packages to a +Composer repository and naming scheme, and adopt the vendor name of `foobar`. +Projects using your PEAR packages would not see the updated packages, since +they have a different vendor name (`foobar/IntermediatePackage` vs +`pear-pear.foobar.repo/IntermediatePackage`). + +By specifying `vendor-alias` for the PEAR repository from the start, you can +avoid this scenario and future-proof your package names. + +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": "*" + } + } + +### Package + +If you want to use a project that does not support composer through any of the +means above, you still can define the package yourself by using a `package` +repository. + +Basically, you define the same information that is included in the `composer` +repository's `packages.json`, but only for a single package. Again, the +minimum required fields are `name`, `version`, and either of `dist` or +`source`. + +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/"] + } + } + } + ], + "require": { + "smarty/smarty": "3.1.*" + } + } + +Typically you would leave the source part off, as you don't really need it. + +> **Note**: This repository type has a few limitations and should be avoided +> whenever possible: +> +> - Composer will not update the package unless you change the `version` field. +> - Composer will not update the commit references, so if you use `master` as +> reference you will have to delete the package to force an update, and will +> have to deal with an unstable lock file. + +## Hosting your own + +While you will probably want to put your packages on packagist most of the time, +there are some use cases for hosting your own repository. + +* **Private company packages:** If you are part of a company that uses composer + for their packages internally, you might want to keep those packages private. + +* **Separate ecosystem:** If you have a project which has its own ecosystem, + and the packages aren't really reusable by the greater PHP community, you + might want to keep them separate to packagist. An example of this would be + wordpress plugins. + +For hosting your own packages, a native `composer` type of repository is +recommended, which provides the best performance. + +There are a few tools that can help you create a `composer` repository. + +### Packagist + +The underlying application used by packagist is open source. This means that you +can just install your own copy of packagist, re-brand, and use it. It's really +quite straight-forward to do. However due to its size and complexity, for most +small and medium sized companies willing to track a few packages will be better +off using Satis. + +Packagist is a Symfony2 application, and it is [available on +GitHub](https://github.com/composer/packagist). It uses composer internally and +acts as a proxy between VCS repositories and the composer users. It holds a list +of all VCS packages, periodically re-crawls them, and exposes them as a composer +repository. + +To set your own copy, simply follow the instructions from the [packagist +github repository](https://github.com/composer/packagist). + +### Satis + +Satis is a static `composer` repository generator. It is a bit like an ultra- +lightweight, static file-based version of packagist. + +You give it a `composer.json` containing repositories, typically VCS and +package repository definitions. It will fetch all the packages that are +`require`d and dump a `packages.json` that is your `composer` repository. + +Check [the satis GitHub repository](https://github.com/composer/satis) and +the [Satis article](articles/handling-private-packages-with-satis.md) for more +information. + +### Artifact + +There are some cases, when there is no ability to have one of the previously +mentioned repository types online, even the VCS one. Typical example could be +cross-organisation library exchange through built artifacts. Of course, most +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" + } + } + +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 + ... + +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 +and you run `update`, that version will be imported as well and Composer will +update to the latest version. + +## Disabling Packagist + +You can disable the default Packagist repository by adding this to your +`composer.json`: + + { + "repositories": [ + { + "packagist": false + } + ] + } + + +← [Schema](04-schema.md) | [Community](06-community.md) → diff --git a/cn-introduction/06-community.md b/cn-introduction/06-community.md new file mode 100644 index 0000000..10ef31b --- /dev/null +++ b/cn-introduction/06-community.md @@ -0,0 +1,34 @@ +# Community + +There are many people using composer already, and quite a few of them are +contributing. + +## Contributing + +If you would like to contribute to composer, please read the +[README](https://github.com/composer/composer). + +The most important guidelines are described as follows: + +> All code contributions - including those of people having commit access - must +> go through a pull request and approved by a core developer before being +> merged. This is to ensure proper review of all the code. +> +> Fork the project, create a feature branch, and send us a pull request. +> +> To ensure a consistent code base, you should make sure the code follows +> the [Coding Standards](http://symfony.com/doc/2.0/contributing/code/standards.html) +> which we borrowed from Symfony. + +## IRC / mailing list + +Mailing lists for [user support](http://groups.google.com/group/composer-users) and +[development](http://groups.google.com/group/composer-dev). + +IRC channels are on irc.freenode.org: [#composer](irc://irc.freenode.org/composer) +for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development. + +Stack Overflow has a growing collection of +[Composer related questions](http://stackoverflow.com/questions/tagged/composer-php). + +← [Repositories](05-repositories.md) diff --git a/cn-introduction/articles/aliases.md b/cn-introduction/articles/aliases.md new file mode 100644 index 0000000..26a9c46 --- /dev/null +++ b/cn-introduction/articles/aliases.md @@ -0,0 +1,96 @@ + + +# Aliases + +## 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 +will get a `dev-master` version. For your `bugfix` branch, you will get a +`dev-bugfix` version. + +If your `master` branch is used to tag releases of the `1.0` development line, +i.e. `1.0.1`, `1.0.2`, `1.0.3`, etc., any package depending on it will +probably require version `1.0.*`. + +If anyone wants to require the latest `dev-master`, they have a problem: Other +packages may require `1.0.*`, so requiring that dev version will lead to +conflicts, since `dev-master` does not match the `1.0.*` constraint. + +Enter aliases. + +## Branch alias + +The `dev-master` branch is one in your main VCS repo. It is rather common that +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" + } + } + } + +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 +`.x-dev`). The `branch-alias` must be present on the branch that it references. +For `dev-master`, you need to commit it on the `master` branch. + +As a result, anyone can now require `1.0.*` and it will happily install +`dev-master`. + +In order to use branch aliasing, you must own the repository of the package +being aliased. If you want to alias a third party package without maintaining +a fork of it, use inline aliases as described below. + +## Require inline alias + +Branch aliases are great for aliasing main development lines. But in order to +use them you need to have control over the source repository, and you need to +commit changes to version control. + +This is not really fun when you just want to try a bugfix of some library that +is a dependency of your local project. + +For this reason, you can alias packages in your `require` and `require-dev` +fields. Let's say you found a bug in the `monolog/monolog` package. You cloned +[Monolog](https://github.com/Seldaek/monolog) on GitHub and fixed the issue in +a branch named `bugfix`. Now you want to install that version of monolog in your +local project. + +You are using `symfony/monolog-bundle` which requires `monolog/monolog` version +`1.*`. So you need your `dev-bugfix` to match that constraint. + +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" + } + } + +That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub +and alias it to `1.0.x-dev`. + +> **Note:** If a package with inline aliases is required, the alias (right of +> the `as`) is used as the version constraint. The part left of the `as` is +> discarded. As a consequence, if A requires B and B requires `monolog/monolog` +> version `dev-bugfix as 1.0.x-dev`, installing A will make B require +> `1.0.x-dev`, which may exist as a branch alias or an actual `1.0` branch. If +> it does not, it must be re-inline-aliased in A's `composer.json`. + +> **Note:** Inline aliasing should be avoided, especially for published +> packages. If you found a bug, try and get your fix merged upstream. This +> helps to avoid issues for users of your package. diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md new file mode 100644 index 0000000..feeebe5 --- /dev/null +++ b/cn-introduction/articles/custom-installers.md @@ -0,0 +1,186 @@ + + +# Setting up and using custom installers + +## Synopsis + +At times it may be necessary for a package to require additional actions during +installation, such as installing packages outside of the default `vendor` +library. + +In these cases you could consider creating a Custom Installer to handle your +specific logic. + +## Calling a Custom Installer + +Suppose that your project already has a Custom Installer for specific modules +then invoking that installer is a matter of defining the correct [type][1] in +your package file. + +> _See the next chapter for an instruction how to create Custom Installers._ + +Every Custom Installer defines which [type][1] string it will recognize. Once +recognized it will completely override the default installer and only apply its +own logic. + +An example use-case would be: + +> phpDocumentor features Templates that need to be installed outside of the +> default /vendor folder structure. As such they have chosen to adopt the +> `phpdocumentor-template` [type][1] and create a plugin providing the Custom +> Installer to send these templates to the correct folder. + +An example composer.json of such a template package would be: + + { + "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 +> the plugin package. + +## Creating an Installer + +A Custom Installer is defined as a class that implements the +[`Composer\Installer\InstallerInterface`][3] and is usually distributed in a +Composer Plugin. + +A basic Installer Plugin would thus compose of three files: + +1. the package file: composer.json +2. The Plugin class, e.g.: `My\Project\Composer\Plugin.php`, containing a class that implements `Composer\Plugin\PluginInterface`. +3. The Installer class, e.g.: `My\Project\Composer\Installer.php`, containing a class that implements `Composer\Installer\InstallerInterface`. + +### composer.json + +The package file is the same as any other package file but with the following +requirements: + +1. the [type][1] attribute must be `composer-plugin`. +2. the [extra][2] attribute must contain an element `class` defining the + class name of the plugin (including namespace). If a package contains + multiple plugins this can be array of class names. + +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" + } + } + +### The Plugin class + +The class defining the Composer plugin must implement the +[`Composer\Plugin\PluginInterface`][3]. It can then register the Custom +Installer in its `activate()` method. + +The class may be placed in any location and have any name, as long as it is +autoloadable and matches the `extra.class` element in the package definition. + +Example: + + namespace phpDocumentor\Composer; + + use Composer\Composer; + use Composer\IO\IOInterface; + use Composer\Plugin\PluginInterface; + + class TemplateInstallerPlugin implements PluginInterface + { + public function activate(Composer $composer, IOInterface $io) + { + $installer = new TemplateInstaller($io, $composer); + $composer->getInstallationManager()->addInstaller($installer); + } + } + +### The Custom Installer class + +The class that executes the custom installation should implement the +[`Composer\Installer\InstallerInterface`][4] (or extend another installer that +implements that interface). It defines the [type][1] string as it will be +recognized by packages that will use this installer in the `supports()` method. + +> **NOTE**: _choose your [type][1] name carefully, it is recommended to follow +> the format: `vendor-type`_. For example: `phpdocumentor-template`. + +The InstallerInterface class defines the following methods (please see the +source for the exact signature): + +* **supports()**, here you test whether the passed [type][1] matches the name + that you declared for this installer (see the example). +* **isInstalled()**, determines whether a supported package is installed or not. +* **install()**, here you can determine the actions that need to be executed + upon installation. +* **update()**, here you define the behavior that is required when Composer is + invoked with the update argument. +* **uninstall()**, here you can determine the actions that need to be executed + when the package needs to be removed. +* **getInstallPath()**, this method should return the location where the + package is to be installed, _relative from the location of composer.json._ + +Example: + + namespace phpDocumentor\Composer; + + use Composer\Package\PackageInterface; + use Composer\Installer\LibraryInstaller; + + class TemplateInstaller extends LibraryInstaller + { + /** + * {@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); + } + + /** + * {@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 +different installation path. + +> _Instead of being installed in `/vendor` any package installed using this +> Installer will be put in the `/data/templates/` folder._ + +[1]: ../04-schema.md#type +[2]: ../04-schema.md#extra +[3]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/PluginInterface.php +[4]: https://github.com/composer/composer/blob/master/src/Composer/Installer/InstallerInterface.php +[5]: https://github.com/composer/composer/blob/master/src/Composer/Installer/LibraryInstaller.php diff --git a/cn-introduction/articles/handling-private-packages-with-satis.md b/cn-introduction/articles/handling-private-packages-with-satis.md new file mode 100644 index 0000000..0219f81 --- /dev/null +++ b/cn-introduction/articles/handling-private-packages-with-satis.md @@ -0,0 +1,188 @@ + + +# Handling private packages with Satis + +Satis is a static `composer` repository generator. It is a bit like an ultra- +lightweight, static file-based version of packagist and can be used to host the +metadata of your company's private packages, or your own. It basically acts as +a micro-packagist. You can get it from +[GitHub](http://github.com/composer/satis) or install via CLI: +`composer.phar create-project composer/satis --stability=dev`. + +## Setup + +For example let's assume you have a few packages you want to reuse across your +company but don't really want to open-source. You would first define a Satis +configuration: a json file with an arbitrary name that lists your curated +[repositories](../05-repositories.md). + +Here is an example configuration, you see that it holds a few VCS repositories, +but those could be any types of [repositories](../05-repositories.md). Then it +uses `"require-all": true` which selects all versions of all packages in the +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 + } + +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" + } + } + +Once you did this, you just run `php bin/satis build `. +For example `php bin/satis build config.json web/` would read the `config.json` +file and build a static repository inside the `web/` directory. + +When you ironed out that process, what you would typically do is run this +command as a cron job on a server. It would then update all your package info +much like Packagist does. + +Note that if your private packages are hosted on GitHub, your server should have +an ssh key that gives it access to those packages, and then you should add +the `--no-interaction` (or `-n`) flag to the command to make sure it falls back +to ssh key authentication instead of prompting for a password. This is also a +good trick for continuous integration servers. + +Set up a virtual-host that points to that `web/` directory, let's say it is +`packages.example.org`. Alternatively, with PHP >= 5.4.0, you can use the built-in +CLI server `php -S localhost:port -t satis-output-dir/` for a temporary solution. + +## Usage + +In your projects all you need to add now is your own composer repository using +the `packages.example.org` as URL, then you can require your private packages and +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" + } + } + +### Security + +To secure your private repository you can host it over SSH or SSL using a client +certificate. In your project you can use the `options` parameter to specify the +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" + } + } + } + ] + } + +> **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" + } + } + } + ] + } + +> **Tip:** See [ssl context options](http://www.php.net/manual/en/context.ssl.php) for more information. + +### Downloads + +When GitHub or BitBucket repositories are mirrored on your local satis, the build process will include +the location of the downloads these platforms make available. This means that the repository and your setup depend +on the availability of these services. + +At the same time, this implies that all code which is hosted somewhere else (on another service or for example in +Subversion) will not have downloads available and thus installations usually take a lot longer. + +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 + } + } + +#### Options explained + + * `directory`: the location of the dist files (inside the `output-dir`) + * `format`: optional, `zip` (default) or `tar` + * `prefix-url`: optional, location of the downloads, homepage (from `satis.json`) followed by `directory` by default + * `skip-dev`: optional, `false` by default, when enabled (`true`) satis will not create downloads for branches + +Once enabled, all downloads (include those from GitHub and BitBucket) will be replaced with a _local_ version. + +#### prefix-url + +Prefixing the URL with another host is especially helpful if the downloads end up in a private Amazon S3 +bucket or on a CDN host. A CDN would drastically improve download times and therefore package installation. + +Example: A `prefix-url` of `http://my-bucket.s3.amazonaws.com` (and `directory` set to `dist`) creates download URLs +which look like the following: `http://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip`. + + +### Resolving dependencies + +It is possible to make satis automatically resolve and add all dependencies for your projects. This can be used +with the Downloads functionality to have a complete local mirror of packages. Just add the following +to your `satis.json`: + +``` +{ + "require-dependencies": true +} +``` + +When searching for packages, satis will attempt to resolve all the required packages from the listed repositories. +Therefore, if you are requiring a package from Packagist, you will need to define it in your `satis.json`. diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md new file mode 100644 index 0000000..75706f7 --- /dev/null +++ b/cn-introduction/articles/plugins.md @@ -0,0 +1,150 @@ + + +# Setting up and using plugins + +## Synopsis + +You may wish to alter or expand Composer's functionality with your own. For +example if your environment poses special requirements on the behaviour of +Composer which do not apply to the majority of its users or if you wish to +accomplish something with composer in a way that is not desired by most users. + +In these cases you could consider creating a plugin to handle your +specific logic. + +## Creating a Plugin + +A plugin is a regular composer package which ships its code as part of the +package and may also depend on further packages. + +### Plugin Package + +The package file is the same as any other package file but with the following +requirements: + +1. the [type][1] attribute must be `composer-plugin`. +2. the [extra][2] attribute must contain an element `class` defining the + class name of the plugin (including namespace). If a package contains + multiple plugins this can be array of class names. + +Additionally you must require the special package called `composer-plugin-api` +to define which composer API versions your plugin is compatible with. The +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" + } + } + +### Plugin Class + +Every plugin has to supply a class which implements the +[`Composer\Plugin\PluginInterface`][3]. The `activate()` method of the plugin +is called after the plugin is loaded and receives an instance of +[`Composer\Composer`][4] as well as an instance of +[`Composer\IO\IOInterface`][5]. Using these two objects all configuration can +be read and all internal objects and state can be manipulated as desired. + +Example: + + namespace phpDocumentor\Composer; + + use Composer\Composer; + use Composer\IO\IOInterface; + use Composer\Plugin\PluginInterface; + + class TemplateInstallerPlugin implements PluginInterface + { + public function activate(Composer $composer, IOInterface $io) + { + $installer = new TemplateInstaller($io, $composer); + $composer->getInstallationManager()->addInstaller($installer); + } + } + +## Event Handler + +Furthermore plugins may implement the +[`Composer\EventDispatcher\EventSubscriberInterface`][6] in order to have its +event handlers automatically registered with the `EventDispatcher` when the +plugin is loaded. + +The events available for plugins are: + +* **COMMAND**, is called at the beginning of all commands that load plugins. + It provides you with access to the input and output objects of the program. +* **PRE_FILE_DOWNLOAD**, is triggered before files are downloaded and allows + you to manipulate the `RemoteFilesystem` object prior to downloading files + based on the URL to be downloaded. + +> A plugin can also subscribe to [script events][7]. + +Example: + + namespace Naderman\Composer\AWS; + + 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) + { + $this->composer = $composer; + $this->io = $io; + } + + 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); + + 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 + +Plugin packages are automatically loaded as soon as they are installed and will +be loaded when composer starts up if they are found in the current project's +list of installed packages. Additionally all plugin packages installed in the +`COMPOSER_HOME` directory using the composer global command are loaded before +local project plugins are loaded. + +> You may pass the `--no-plugins` option to composer commands to disable all +> installed commands. This may be particularly helpful if any of the plugins +> causes errors and you wish to update or uninstall it. + +[1]: ../04-schema.md#type +[2]: ../04-schema.md#extra +[3]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/PluginInterface.php +[4]: https://github.com/composer/composer/blob/master/src/Composer/Composer.php +[5]: https://github.com/composer/composer/blob/master/src/Composer/IO/IOInterface.php +[6]: https://github.com/composer/composer/blob/master/src/Composer/EventDispatcher/EventSubscriberInterface.php +[7]: ./scripts.md#event-names diff --git a/cn-introduction/articles/scripts.md b/cn-introduction/articles/scripts.md new file mode 100644 index 0000000..06e7c78 --- /dev/null +++ b/cn-introduction/articles/scripts.md @@ -0,0 +1,125 @@ + + +# Scripts + +## What is a script? + +A script, in Composer's terms, can either be a PHP callback (defined as a +static method) or any command-line executable command. Scripts are useful +for executing a package's custom code or package-specific commands during +the Composer execution process. + +**NOTE: Only scripts defined in the root package's `composer.json` are +executed. If a dependency of the root package specifies its own scripts, +Composer does not execute those additional scripts.** + + +## Event names + +Composer fires the following named events during its execution process: + +- **pre-install-cmd**: occurs before the `install` command is executed. +- **post-install-cmd**: occurs after the `install` command is executed. +- **pre-update-cmd**: occurs before the `update` command is executed. +- **post-update-cmd**: occurs after the `update` command is executed. +- **pre-status-cmd**: occurs before the `status` command is executed. +- **post-status-cmd**: occurs after the `status` command is executed. +- **pre-package-install**: occurs before a package is installed. +- **post-package-install**: occurs after a package is installed. +- **pre-package-update**: occurs before a package is updated. +- **post-package-update**: occurs after a package is updated. +- **pre-package-uninstall**: occurs before a package has been uninstalled. +- **post-package-uninstall**: occurs after a package has been uninstalled. +- **pre-autoload-dump**: occurs before the autoloader is dumped, either + during `install`/`update`, or via the `dump-autoload` command. +- **post-autoload-dump**: occurs after the autoloader is dumped, either + during `install`/`update`, or via the `dump-autoload` command. +- **post-root-package-install**: occurs after the root package has been + installed, during the `create-project` command. +- **post-create-project-cmd**: occurs after the `create-project` 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 +require Composer-managed dependencies in the `pre-update-cmd` or +`pre-install-cmd` event hooks. If you need to execute scripts prior to +`install` or `update` please make sure they are self-contained within your +root package.** + +## Defining scripts + +The root JSON object in `composer.json` should have a property called +`"scripts"`, which contains pairs of named events and each event's +corresponding scripts. An event's scripts can be defined as either as a string +(only for a single script) or an array (for single or multiple scripts.) + +For any given event: + +- Scripts execute in the order defined when their corresponding event is fired. +- An array of scripts wired to a single event can contain both PHP callbacks +and command-line executables commands. +- PHP classes containing defined callbacks must be autoloadable via Composer's +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/" + ] + } + } + +Using the previous definition example, here's the class `MyVendor\MyClass` +that might be used to execute the PHP callbacks: + + 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: + +- `getComposer()`: returns the current instance of `Composer\Composer` +- `getName()`: returns the name of the event being fired as a string +- `getIO()`: returns the current input/output stream which implements +`Composer\IO\IOInterface` for writing to the console + +## Running scripts manually + +If you would like to run the scripts for an event manually, the syntax is: + + $ 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. diff --git a/cn-introduction/articles/troubleshooting.md b/cn-introduction/articles/troubleshooting.md new file mode 100644 index 0000000..3483b1c --- /dev/null +++ b/cn-introduction/articles/troubleshooting.md @@ -0,0 +1,106 @@ + +# Troubleshooting + +This is a list of common pitfalls on using Composer, and how to avoid them. + +## General + +1. Before asking anyone, run [`composer diagnose`](../03-cli.md#diagnose) to check + for common problems. If it all checks out, proceed to the next steps. + +2. When facing any kind of problems using Composer, be sure to **work with the + latest version**. See [self-update](../03-cli.md#self-update) for details. + +3. Make sure you have no problems with your setup by running the installer's + checks via `curl -sS https://getcomposer.org/installer | php -- --check`. + +4. Ensure you're **installing vendors straight from your `composer.json`** via + `rm -rf vendor && composer update -v` when troubleshooting, excluding any + possible interferences with existing vendor installations or `composer.lock` + entries. + +## Package not found + +1. Double-check you **don't have typos** in your `composer.json` or repository + branches and tag names. + +2. Be sure to **set the right + [minimum-stability](../04-schema.md#minimum-stability)**. To get started or be + sure this is no issue, set `minimum-stability` to "dev". + +3. Packages **not coming from [Packagist](https://packagist.org/)** should + always be **defined in the root package** (the package depending on all + vendors). + +4. Use the **same vendor and package name** throughout all branches and tags of + your repository, especially when maintaining a third party fork and using + `replace`. + +## Package not found on travis-ci.org + +1. Check the ["Package not found"](#package-not-found) item above. + +2. If the package tested is a dependency of one of its dependencies (cyclic + dependency), the problem might be that composer is not able to detect the version + of the package properly. If it is a git clone it is generally alright and Composer + will detect the version of the current branch, but travis does shallow clones so + that process can fail when testing pull requests and feature branches in general. + The best solution is to define the version you are on via an environment variable + called COMPOSER_ROOT_VERSION. You set it to `dev-master` for example to define + the root package's version as `dev-master`. + Use: `before_script: COMPOSER_ROOT_VERSION=dev-master composer install` to export + the variable for the call to composer. + +## Need to override a package version + +Let say your project depends on package A which in turn depends on a specific +version of package B (say 0.1) and you need a different version of that +package - version 0.11. + +You can fix this by aliasing version 0.11 to 0.1: + +composer.json: + + { + "require": { + "A": "0.2", + "B": "0.11 as 0.1" + } + } + +See [aliases](aliases.md) for more information. + +## Memory limit errors + +If composer shows memory errors on some commands: + + PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...> + +The PHP `memory_limit` should be increased. + +> **Note:** Composer internally increases the `memory_limit` to `512M`. +> If you have memory issues when using composer, please consider [creating +> an issue ticket](https://github.com/composer/composer/issues) so we can look into it. + +To get the current `memory_limit` value, run: + + 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 + +Or, you can increase the limit with a command-line argument: + + php -d memory_limit=-1 composer.phar <...> + +## "The system cannot find the path specified" (Windows) + +1. Open regedit. +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. diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md new file mode 100644 index 0000000..b258dcc --- /dev/null +++ b/cn-introduction/articles/vendor-binaries.md @@ -0,0 +1,106 @@ + + +# Vendor binaries and the `vendor/bin` directory + +## What is a vendor binary? + +Any command line script that a Composer package would like to pass along +to a user who installs the package should be listed as a vendor binary. + +If a package contains other scripts that are not needed by the package +users (like build or compile scripts) that code should not be listed +as a vendor binary. + + +## How is it defined? + +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"] + } + + +## What does defining a vendor binary in composer.json do? + +It instructs Composer to install the package's binaries to `vendor/bin` +for any project that **depends** on that project. + +This is a convenient way to expose useful scripts that would +otherwise be hidden deep in the `vendor/` directory. + + +## What happens when Composer is run on a composer.json that defines vendor binaries? + +For the binaries that a package defines directly, nothing happens. + + +## What happens when Composer is run on a composer.json that has dependencies with vendor binaries listed? + +Composer looks for the binaries defined in all of the dependencies. A +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"] + } + +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": "*" + } + } + +Running `composer install` for this `composer.json` will look at +all of project-b's dependencies and install them to `vendor/bin`. + +In this case, Composer will make `vendor/my-vendor/project-a/bin/project-a-bin` +available as `vendor/bin/project-a-bin`. On a Unix-like platform +this is accomplished by creating a symlink. + + +## What about Windows and .bat files? + +Packages managed entirely by Composer do not *need* to contain any +`.bat` files for Windows compatibility. Composer handles installation +of binaries in a special way when run in a Windows environment: + + * A `.bat` file is generated automatically to reference the binary + * A Unix-style proxy file with the same name as the binary is generated + automatically (useful for Cygwin or Git Bash) + +Packages that need to support workflows that may not include Composer +are welcome to maintain custom `.bat` files. In this case, the package +should **not** list the `.bat` file as a binary as it is not needed. + + +## Can vendor binaries be installed somewhere other than vendor/bin? + +Yes, there are two ways an alternate vendor binary location can be specified: + + 1. Setting the `bin-dir` configuration setting in `composer.json` + 1. Setting the environment variable `COMPOSER_BIN_DIR` + +An example of the former looks like this: + + { + "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 +`vendor/bin/`. diff --git a/cn-introduction/dev/DefaultPolicy.md b/cn-introduction/dev/DefaultPolicy.md new file mode 100644 index 0000000..61db2bf --- /dev/null +++ b/cn-introduction/dev/DefaultPolicy.md @@ -0,0 +1,55 @@ +# Default Solver Policy + +A solver policy defines behaviour variables of the dependency solver. It decides +which versions are considered newer than others, which packages should be +preferred over others and whether operations like downgrades or uninstall are +allowed. + +## Selection of preferred Packages + +The following describe package pool situations with user requests and the +resulting order in which the solver will try to install them. + +The rules are to be applied in the order of these descriptions. + +### Package versions + +Packages: Av1, Av2, Av3 + +* Installed: Av2 + +Request: install A + +* (Av3) + +### Repository priorities + +Packages Repo1.Av1, Repo2.Av1 + +* priority(Repo1) >= priority(Repo2) => (Repo1.Av1, Repo2.Av1) +* priority(Repo1) < priority(Repo2) => (Repo2.Av1, Repo1.Av1) + +### Virtual Packages (provides) + +Packages Av1, Bv1 + +* Av1 provides Xv1 +* Bv1 provides Xv1 + +Request: install X + +* priority(Av1.repo) >= priority(Bv1.repo) => (Av1, Bv1) +* priority(Av1.repo) < priority(Bv1.repo) => (Bv1, Av1) + +### Package replacements + +Packages: Av1, Bv2 + +* Bv2 replaces Av1 + +Request: install A + +* priority(Av1.repo) >= priority(Bv2.repo) => (Av1, Bv2) +* priority(Av1.repo) < priority(Bv2.repo) => (Bv2, Av1) + +Bv2 version is ignored, only the replacement version for A matters. diff --git a/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md b/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md new file mode 100644 index 0000000..b5956ca --- /dev/null +++ b/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md @@ -0,0 +1,46 @@ +# How do I install a package to a custom path for my framework? + +Each framework may have one or many different required package installation +paths. Composer can be configured to install packages to a folder other than +the default `vendor` folder by using +[composer/installers](https://github.com/composer/installers). + +If you are a **package author** and want your package installed to a custom +directory, simply require `composer/installers` and set the appropriate `type`. +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" + } + } + +Now when your theme is installed with Composer it will be placed into +`wp-content/themes/themename/` folder. Check the +[current supported types](https://github.com/composer/installers#current-supported-types) +for your package. + +As a **package consumer** you can set or override the install path for a package +that requires composer/installers by configuring the `installer-paths` extra. A +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"] + } + } + } + +Now the package would be installed to your folder location, rather than the default +composer/installers determined location. + +> **Note:** You cannot use this to change the path of any package. This is only +> applicable to packages that require `composer/installers` and use a custom type +> that it handles. diff --git a/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md new file mode 100644 index 0000000..8e50f72 --- /dev/null +++ b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md @@ -0,0 +1,31 @@ +# Should I commit the dependencies in my vendor directory? + +The general recommendation is **no**. The vendor directory (or wherever your +dependencies are installed) should be added to `.gitignore`/`svn:ignore`/etc. + +The best practice is to then have all the developers use Composer to install +the dependencies. Similarly, the build server, CI, deployment tools etc should +be adapted to run Composer as part of their project bootstrapping. + +While it can be tempting to commit it in some environment, it leads to a few +problems: + +- Large VCS repository size and diffs when you update code. +- Duplication of the history of all your dependencies in your own VCS. +- Adding dependencies installed via git to a git repo will show them as + submodules. This is problematic because they are not real submodules, and you + will run into issues. + +If you really feel like you must do this, you have a few options: + +1. Limit yourself to installing tagged releases (no dev versions), so that you + only get zipped installs, and avoid problems with the git "submodules". +2. Use --prefer-dist or set `preferred-install` to `dist` in your + [config](../04-schema.md#config). +3. Remove the `.git` directory of every dependency after the installation, then + you can add them to your git repo. You can do that with `rm -rf vendor/**/.git` + but this means you will have to delete those dependencies from disk before + running composer update. +4. Add a .gitignore rule (`vendor/.git`) to ignore all the vendor `.git` folders. + This approach does not require that you delete dependencies from disk prior to + running a composer update. diff --git a/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md b/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md new file mode 100644 index 0000000..bac633a --- /dev/null +++ b/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md @@ -0,0 +1,21 @@ +# Why are version constraints combining comparisons and wildcards a bad idea? + +This is a fairly common mistake people make, defining version constraints in +their package requires like `>=2.*` or `>=1.1.*`. + +If you think about it and what it really means though, you will quickly +realize that it does not make much sense. If we decompose `>=2.*`, you +have two parts: + +- `>=2` which says the package should be in version 2.0.0 or above. +- `2.*` which says the package should be between version 2.0.0 (inclusive) + and 3.0.0 (exclusive). + +As you see, both rules agree on the fact that the package must be >=2.0.0, +but it is not possible to determine if when you wrote that you were thinking +of a package in version 3.0.0 or not. Should it match because you asked for +`>=2` or should it not match because you asked for a `2.*`? + +For this reason, Composer just throws an error and says that this is invalid. +The easy way to fix it is to think about what you really mean, and use only +one of those rules. \ No newline at end of file diff --git a/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md b/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md new file mode 100644 index 0000000..d81a0f0 --- /dev/null +++ b/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md @@ -0,0 +1,34 @@ +# Why can't Composer load repositories recursively? + +You may run into problems when using custom repositories because Composer does +not load the repositories of your requirements, so you have to redefine those +repositories in all your `composer.json` files. + +Before going into details as to why this is like that, you have to understand +that the main use of custom VCS & package repositories is to temporarily try +some things, or use a fork of a project until your pull request is merged, etc. +You should not use them to keep track of private packages. For that you should +look into [setting up Satis](../articles/handling-private-packages-with-satis.md) +for your company or even for yourself. + +There are three ways the dependency solver could work with custom repositories: + +- Fetch the repositories of root package, get all the packages from the defined +repositories, resolve requirements. This is the current state and it works well +except for the limitation of not loading repositories recursively. + +- Fetch the repositories of root package, while initializing packages from the +defined repos, initialize recursively all repos found in those packages, and +their package's packages, etc, then resolve requirements. It could work, but it +slows down the initialization a lot since VCS repos can each take a few seconds, +and it could end up in a completely broken state since many versions of a package +could define the same packages inside a package repository, but with different +dist/source. There are many many ways this could go wrong. + +- Fetch the repositories of root package, then fetch the repositories of the +first level dependencies, then fetch the repositories of their dependencies, etc, +then resolve requirements. This sounds more efficient, but it suffers from the +same problems than the second solution, because loading the repositories of the +dependencies is not as easy as it sounds. You need to load all the repos of all +the potential matches for a requirement, which again might have conflicting +package definitions. diff --git a/en-back/00-intro.md b/en-back/00-intro.md new file mode 100644 index 0000000..7b62fee --- /dev/null +++ b/en-back/00-intro.md @@ -0,0 +1,167 @@ +# Introduction + +Composer is a tool for dependency management in PHP. It allows you to declare +the dependent libraries your project needs and it will install them in your +project for you. + +## Dependency management + +Composer is not a package manager. Yes, it deals with "packages" or libraries, but +it manages them on a per-project basis, installing them in a directory (e.g. `vendor`) +inside your project. By default it will never install anything globally. Thus, +it is a dependency manager. + +This idea is not new and Composer is strongly inspired by node's [npm](http://npmjs.org/) +and ruby's [bundler](http://gembundler.com/). But there has not been such a tool +for PHP. + +The problem that Composer solves is this: + +a) You have a project that depends on a number of libraries. + +b) Some of those libraries depend on other libraries. + +c) You declare the things you depend on. + +d) Composer finds out which versions of which packages need to be installed, and + installs them (meaning it downloads them into your project). + +## Declaring dependencies + +Let's say you are creating a project, and you need a library that does logging. +You decide to use [monolog](https://github.com/Seldaek/monolog). In order to +add it to your project, all you need to do is create a `composer.json` file +which describes the project's dependencies. + + { + "require": { + "monolog/monolog": "1.2.*" + } + } + +We are simply stating that our project requires some `monolog/monolog` package, +any version beginning with `1.2`. + +## System Requirements + +Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile +flags are also required, but the installer will warn you about any +incompatibilities. + +To install packages from sources instead of simple zip archives, you will need +git, svn or hg depending on how the package is version-controlled. + +Composer is multi-platform and we strive to make it run equally well on Windows, +Linux and OSX. + +## Installation - *nix + +### Downloading the Composer Executable + +#### Locally + +To actually get Composer, we need to do two things. The first one is installing +Composer (again, this means downloading it into your project): + + $ curl -sS https://getcomposer.org/installer | php + +This will just check a few PHP settings and then download `composer.phar` to +your working directory. This file is the Composer binary. It is a PHAR (PHP +archive), which is an archive format for PHP which can be run on the command +line, amongst other things. + +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 + +#### Globally + +You can place this file anywhere you wish. If you put it in your `PATH`, +you can access it globally. On unixy systems you can even make it +executable and invoke it without `php`. + +You can 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 + +> **Note:** If the above fails due to permissions, run the `mv` line +> again with sudo. + +Then, just run `composer` in order to run Composer instead of `php composer.phar`. + +#### Globally (on OSX via homebrew) + +Composer is part of the homebrew-php project. + +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` + +## Installation - Windows + +### Using the Installer + +This is the easiest way to get Composer set up on your machine. + +Download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe), +it will install the latest Composer version and set up your PATH so that you can +just call `composer` from any directory in your command line. + +### Manual Installation + +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'));" + +> **Note:** If the above fails due to file_get_contents, 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 + +Close your current terminal. Test usage with a new terminal: + + C:\Users\username>composer -V + Composer version 27d8904 + + C:\Users\username> + +## Using Composer + +We will now use Composer to install the dependencies of the project. If you +don't have a `composer.json` file in the current directory please skip to the +[Basic Usage](01-basic-usage.md) chapter. + +To resolve and download dependencies, run the `install` command: + + $ php composer.phar install + +If you did a global install and do not have the phar in that directory +run this instead: + + $ composer install + +Following the [example above](#declaring-dependencies), this will download +monolog into the `vendor/monolog/monolog` directory. + +## Autoloading + +Besides downloading the library, Composer also prepares an autoload file that's +capable of autoloading all of the classes in any of the libraries that it +downloads. To use it, just add the following line to your code's bootstrap +process: + + require 'vendor/autoload.php'; + +Woah! Now start using monolog! To keep learning more about Composer, keep +reading the "Basic Usage" chapter. + +[Basic Usage](01-basic-usage.md) → diff --git a/en-back/01-basic-usage.md b/en-back/01-basic-usage.md new file mode 100644 index 0000000..c353b8b --- /dev/null +++ b/en-back/01-basic-usage.md @@ -0,0 +1,216 @@ +# Basic usage + +## Installation + +To install Composer, you just need to download the `composer.phar` executable. + + $ 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 + +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 + +## `composer.json`: Project Setup + +To start using Composer in your project, all you need is a `composer.json` +file. This file describes the dependencies of your project and may contain +other metadata as well. + +The [JSON format](http://json.org/) is quite easy to write. It allows you to +define nested structures. + +### The `require` Key + +The first (and often only) thing you specify in `composer.json` is the +`require` key. You're simply telling Composer which packages your project +depends on. + + { + "require": { + "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.*`). + +### Package Names + +The package name consists of a vendor name and the project's name. Often these +will be identical - the vendor name just exists to prevent naming clashes. It allows +two different people to create a library named `json`, which would then just be +named `igorw/json` and `seldaek/json`. + +Here we are requiring `monolog/monolog`, so the vendor name is the same as the +project's name. For projects with a unique name this is recommended. It also +allows adding more related projects under the same namespace later on. If you +are maintaining a library, this would make it really easy to split it up into +smaller decoupled parts. + +### Package Versions + +In the previous example we were requiring version `1.0.*` of monolog. This +means any version in the `1.0` development branch. It would match `1.0.0`, +`1.0.2` or `1.0.20`. + +Version constraints can be specified in a few different ways. + +Name | Example | Description +-------------- | --------------------- | ----------- +Exact version | `1.0.2` | You can specify the exact version of a package. +Range | `>=1.0` `>=1.0,<2.0` `>=1.0,<1.1 | >=1.2` | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`.
You can define multiple ranges, separated by a comma, which will be treated as a **logical AND**. A pipe symbol `|` will be treated as a **logical OR**.
AND has higher precedence than OR. +Wildcard | `1.0.*` | You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0,<1.1`. +Tilde Operator | `~1.2` | Very useful for projects that follow semantic versioning. `~1.2` is equivalent to `>=1.2,<2.0`. For more details, read the next section below. + +### Next Significant Release (Tilde Operator) + +The `~` operator is best explained by example: `~1.2` is equivalent to +`>=1.2,<2.0`, while `~1.2.3` is equivalent to `>=1.2.3,<1.3`. As you can see +it is mostly useful for projects respecting [semantic +versioning](http://semver.org/). A common usage would be to mark the minimum +minor version you depend on, like `~1.2` (which allows anything up to, but not +including, 2.0). Since in theory there should be no backwards compatibility +breaks until 2.0, that works well. Another way of looking at it is that using +`~` specifies a minimum version, but allows the last digit specified to go up. + +### Stability + +By default only stable releases are taken into consideration. If you would like +to also get RC, beta, alpha or dev versions of your dependencies you can do +so using [stability flags](04-schema.md#package-links). To change that for all +packages instead of doing per dependency you can also use the +[minimum-stability](04-schema.md#minimum-stability) setting. + +## Installing Dependencies + +To fetch the defined dependencies into your local project, just run the +`install` command of `composer.phar`. + + $ php composer.phar install + +This will find the latest version of `monolog/monolog` that matches the +supplied version constraint and download it into the `vendor` directory. +It's a convention to put third party code into a directory named `vendor`. +In case of monolog it will put it into `vendor/monolog/monolog`. + +> **Tip:** If you are using git for your project, you probably want to add +> `vendor` into your `.gitignore`. You really don't want to add all of that +> code to your repository. + +Another thing that the `install` command does is it adds a `composer.lock` +file into your project root. + +## `composer.lock` - The Lock File + +After installing the dependencies, Composer writes the list of the exact +versions it installed into a `composer.lock` file. This locks the project +to those specific versions. + +**Commit your application's `composer.lock` (along with `composer.json`) into version control.** + +This is important because the `install` command checks if a lock file is present, +and if it is, it downloads the versions specified there (regardless of what `composer.json` +says). + +This means that anyone who sets up the project will download the exact +same version of the dependencies. Your CI server, production machines, other +developers in your team, everything and everyone runs on the same dependencies, which +mitigates the potential for bugs affecting only some parts of the deployments. Even if you +develop alone, in six months when reinstalling the project you can feel confident the +dependencies installed are still working even if your dependencies released +many new versions since then. + +If no `composer.lock` file exists, Composer will read the dependencies and +versions from `composer.json` and create the lock file. + +This means that if any of the dependencies get a new version, you won't get the updates +automatically. To update to the new version, use `update` command. This will fetch +the latest matching versions (according to your `composer.json` file) and also update +the lock file with the new version. + + $ php composer.phar update + +If you only want to install or update one dependency, you can whitelist them: + + $ php composer.phar update monolog/monolog [...] + +> **Note:** For libraries it is not necessarily recommended to commit the lock file, +> see also: [Libraries - Lock file](02-libraries.md#lock-file). + +## Packagist + +[Packagist](https://packagist.org/) is the main Composer repository. A Composer +repository is basically a package source: a place where you can get packages +from. Packagist aims to be the central repository that everybody uses. This +means that you can automatically `require` any package that is available +there. + +If you go to the [packagist website](https://packagist.org/) (packagist.org), +you can browse and search for packages. + +Any open source project using Composer should publish their packages on +packagist. A library doesn't need to be on packagist to be used by Composer, +but it makes life quite a bit simpler. + +## Autoloading + +For libraries that specify autoload information, Composer generates a +`vendor/autoload.php` file. You can simply include this file and you +will get autoloading for free. + + 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)); + + $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/"} + } + } + +Composer will register a +[PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) +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. + +After adding the `autoload` field, you have to re-run `install` to re-generate +the `vendor/autoload.php` file. + +Including that file will also return the autoloader instance, so you can store +the return value of the include call in a variable and add more namespaces. +This can be useful for autoloading classes in a test suite, for example. + + $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 +[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. + +← [Intro](00-intro.md) | [Libraries](02-libraries.md) → diff --git a/en-back/02-libraries.md b/en-back/02-libraries.md new file mode 100644 index 0000000..2742806 --- /dev/null +++ b/en-back/02-libraries.md @@ -0,0 +1,199 @@ +# Libraries + +This chapter will tell you how to make your library installable through Composer. + +## Every project is a package + +As soon as you have a `composer.json` in a directory, that directory is a +package. When you add a `require` to a project, you are making a package that +depends on other packages. The only difference between your project and +libraries is that your project is a package without a name. + +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.*" + } + } + +In this case the project name is `acme/hello-world`, where `acme` is the +vendor name. Supplying a vendor name is mandatory. + +> **Note:** If you don't know what to use as a vendor name, your GitHub +username is usually a good bet. While package names are case insensitive, the +convention is all lowercase and dashes for word separation. + +## Platform packages + +Composer has platform packages, which are virtual packages for things that are +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. + +* `ext-` allows you to require PHP extensions (includes core + extensions). Versioning can be quite inconsistent here, so it's often + a good idea to just set the constraint to `*`. An example of an extension + package name is `ext-gd`. + +* `lib-` allows constraints to be made on versions of libraries used by + PHP. The following are available: `curl`, `iconv`, `libxml`, `openssl`, + `pcre`, `uuid`, `xsl`. + +You can use `composer show --platform` to get a list of your locally available +platform packages. + +## Specifying the version + +You need to specify the package's version some way. When you publish your +package on Packagist, it is able to infer the version from the VCS (git, svn, +hg) information, so in that case you do not have to specify it, and it is +recommended not to. See [tags](#tags) and [branches](#branches) to see how +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" + } + +> **Note:** You should avoid specifying the version field explicitly, because +> for tags the value must match the tag name. + +### Tags + +For every tag that looks like a version, a package version of that tag will be +created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix +of `-patch`, `-alpha`, `-beta` or `-RC`. The suffixes can also be followed by +a number. + +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 + +> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions) +> in a `require` statement has to be specified without prefix +> (e.g. tag `v1.0.0` will result in version `1.0.0`). + +### Branches + +For every branch, a package development version will be created. If the branch +name looks like a version, the version will be `{branchname}-dev`. For example +a branch `2.0` will get a version `2.0.x-dev` (the `.x` is added for technical +reasons, to make sure it is recognized as a branch, a `2.0.x` branch would also +be valid and be turned into `2.0.x-dev` as well. If the branch does not look +like a version, it will be `dev-{branchname}`. `master` results in a +`dev-master` version. + +Here are some examples of version branch names: + + 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 +> for more details. + +### Aliases + +It is possible to alias branch names to versions. For example, you could alias +`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all +the packages. + +See [Aliases](articles/aliases.md) for more information. + +## Lock file + +For your library you may commit the `composer.lock` file if you want to. This +can help your team to always test against the same dependency versions. +However, this lock file will not have any effect on other projects that depend +on it. It only has an effect on the main project. + +If you do not want to commit the lock file and you are using git, add it to +the `.gitignore`. + +## Publishing to a VCS + +Once you have a vcs repository (version control system, e.g. git) containing a +`composer.json` file, your library is already composer-installable. In this +example we will publish the `acme/hello-world` library on GitHub under +`github.com/username/hello-world`. + +Now, to test installing the `acme/hello-world` package, we create a new +project locally. We will call it `acme/blog`. This blog will depend on +`acme/hello-world`, which in turn depends on `monolog/monolog`. We can +accomplish this by creating a new `blog` directory somewhere, containing a +`composer.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 +described. + +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" + } + } + +For more details on how package repositories work and what other types are +available, see [Repositories](05-repositories.md). + +That's all. You can now install the dependencies by running Composer's +`install` command! + +**Recap:** Any git/svn/hg repository containing a `composer.json` can be added +to your project by specifying the package repository and declaring the +dependency in the `require` field. + +## Publishing to packagist + +Alright, so now you can publish packages. But specifying the vcs repository +every time is cumbersome. You don't want to force all your users to do that. + +The other thing that you may have noticed is that we did not specify a package +repository for `monolog/monolog`. How did that work? The answer is packagist. + +[Packagist](https://packagist.org/) is the main package repository for +Composer, and it is enabled by default. Anything that is published on +packagist is available automatically through Composer. Since monolog +[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend +on it without having to specify any additional repositories. + +If we wanted to share `hello-world` with the world, we would publish it on +packagist as well. Doing so is really easy. + +You simply hit the big "Submit Package" button and sign up. Then you submit +the URL to your VCS repository, at which point packagist will start crawling +it. Once it is done, your package will be available to anyone. + +← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) → diff --git a/en-back/03-cli.md b/en-back/03-cli.md new file mode 100644 index 0000000..84539b4 --- /dev/null +++ b/en-back/03-cli.md @@ -0,0 +1,535 @@ +# Command-line interface + +You've already learned how to use the command-line interface to do some +things. This chapter documents all the available commands. + +To get help from the command-line, simply call `composer` or `composer list` +to see the complete list of commands, then `--help` combined with any of those +can give you more information. + +## Global Options + +The following options are available with every command: + +* **--verbose (-v):** Increase verbosity of messages. +* **--help (-h):** Display help information. +* **--quiet (-q):** Do not output any message. +* **--no-interaction (-n):** Do not ask any interactive question. +* **--working-dir (-d):** If specified, use the given directory as working directory. +* **--profile:** Display timing and memory usage information +* **--ansi:** Force ANSI output. +* **--no-ansi:** Disable ANSI output. +* **--version (-V):** Display this application version. + +## Process Exit Codes + +* **0:** OK +* **1:** Generic/unknown error code +* **2:** Dependency solving error code + +## init + +In the [Libraries](02-libraries.md) chapter we looked at how to create a +`composer.json` by hand. There is also an `init` command available that makes +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 + +### Options + +* **--name:** Name of the package. +* **--description:** Description of the package. +* **--author:** Author name of the package. +* **--homepage:** Homepage of the package. +* **--require:** Package to require with a version constraint. Should be + in format `foo/bar:1.0.0`. +* **--require-dev:** Development requirements, see **--require**. +* **--stability (-s):** Value for the `minimum-stability` field. + +## install + +The `install` command reads the `composer.json` file from the current +directory, resolves the dependencies, and installs them into `vendor`. + + $ 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 +everyone using the library will get the same versions of the dependencies. + +If there is no `composer.lock` file, composer will create one after dependency +resolution. + +### Options + +* **--prefer-source:** There are two ways of downloading a package: `source` + and `dist`. For stable versions composer will use the `dist` by default. + The `source` is a version control repository. If `--prefer-source` is + enabled, composer will install from `source` if there is one. This is + useful if you want to make a bugfix to a project and get a local git + clone of the dependency directly. +* **--prefer-dist:** Reverse of `--prefer-source`, composer will install + from `dist` if possible. This can speed up installs substantially on build + servers and other use cases where you typically do not run updates of the + vendors. It is also a way to circumvent problems with git if you do not + have a proper setup. +* **--dry-run:** If you want to run through an installation without actually + installing a package, you can use `--dry-run`. This will simulate the + installation and show you what would happen. +* **--dev:** Install packages listed in `require-dev` (this is the default behavior). +* **--no-dev:** Skip installing packages listed in `require-dev`. +* **--no-scripts:** Skips execution of scripts defined in `composer.json`. +* **--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 + autoloader. This is recommended especially for production, but can take + a bit of time to run so it is currently not done by default. + +## update + +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 + +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 + +You can also use wildcards to update a bunch of packages at once: + + $ php composer.phar update vendor/* + +### Options + +* **--prefer-source:** Install packages from `source` when available. +* **--prefer-dist:** Install packages from `dist` when available. +* **--dry-run:** Simulate the command without actually doing anything. +* **--dev:** Install packages listed in `require-dev` (this is the default behavior). +* **--no-dev:** Skip installing packages listed in `require-dev`. +* **--no-scripts:** Skips execution of scripts defined in `composer.json`. +* **--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 + 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 + lock file being out of date. +* **--with-dependencies** Add also all dependencies of whitelisted packages to the whitelist. + So all packages with their dependencies are updated recursively. + +## require + +The `require` command adds new packages to the `composer.json` file from +the current directory. + + $ php composer.phar require + +After adding/changing the requirements, the modified requirements will be +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 + +### Options + +* **--prefer-source:** Install packages from `source` when available. +* **--prefer-dist:** Install packages from `dist` when available. +* **--dev:** Add packages to `require-dev`. +* **--no-update:** Disables the automatic update of the dependencies. +* **--no-progress:** Removes the progress display that can mess with some + terminals or scripts which don't handle backspace characters. + +## global + +The global command allows you to run other commands like `install`, `require` +or `update` as if you were running them from the [COMPOSER_HOME](#composer-home) +directory. + +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 + +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 + +## search + +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 + +You can also search for more than one term by passing multiple arguments. + +### Options + +* **--only-name (-N):** Search only in name. + +## show + +To list all of the available packages, you can use the `show` command. + + $ 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 + + 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/ + + 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 + +### Options + +* **--installed (-i):** List the packages that are installed. +* **--platform (-p):** List only platform packages (php & extensions). +* **--self (-s):** List the root package info. + +## depends + +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 + + nrk/monolog-fluent + poc/poc + propel/propel + symfony/monolog-bridge + symfony/symfony + +### Options + +* **--link-type:** The link types to match on, can be specified multiple + times. + +## validate + +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 + +## status + +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 + +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 + +## 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 + +If you would like to instead update to a specific release simply specify it: + + $ composer 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 + +### Options + +* **--rollback (-r):** Rollback to the last version you had installed. +* **--clean-backups:** Delete old backups during an update. This makes the current version of composer the only backup available after the update. + +## config + +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 + +### Usage + +`config [options] [setting-key] [setting-value1] ... [setting-valueN]` + +`setting-key` is a configuration option name and `setting-value1` is a +configuration value. For settings that can take an array of values (like +`github-protocols`), more than one setting-value arguments are allowed. + +See the [config schema section](04-schema.md#config) for valid configuration +options. + +### Options + +* **--global (-g):** Operate on the global config file located at +`$COMPOSER_HOME/config.json` by default. Without this option, this command +affects the local composer.json file or a file specified by `--file`. +* **--editor (-e):** Open the local composer.json file using in a text editor as +defined by the `EDITOR` env variable. With the `--global` option, this opens +the global config file. +* **--unset:** Remove the configuration element named by `setting-key`. +* **--list (-l):** Show the list of current config variables. With the `--global` + option this lists the global configuration only. +* **--file="..." (-f):** Operate on a specific file instead of composer.json. Note + that this cannot be used in conjunction with the `--global` option. + +### Modifying Repositories + +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 + +## create-project + +You can use Composer to create new projects from an existing package. This is +the equivalent of doing a git clone/svn checkout followed by a composer install +of the vendors. + +There are several applications for this: + +1. You can deploy application packages. +2. You can check out any package and start developing on patches for example. +3. Projects with multiple developers can use this feature to bootstrap the + initial application for development. + +To create a new project using composer you can use the "create-project" command. +Pass it a package name, and the directory to create the project in. You can also +provide a version as third argument, otherwise the latest version is used. + +If the directory does not currently exist, it will be created during installation. + + 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. + +By default the command checks for the packages on packagist.org. + +### Options + +* **--repository-url:** Provide a custom repository to search for the package, + which will be used instead of packagist. Can be either an HTTP URL pointing + to a `composer` repository, or a path to a local `packages.json` file. +* **--stability (-s):** Minimum stability of package. Defaults to `stable`. +* **--prefer-source:** Install packages from `source` when available. +* **--prefer-dist:** Install packages from `dist` when available. +* **--dev:** Install packages listed in `require-dev`. +* **--no-install:** Disables installation of the vendors. +* **--no-plugins:** Disables plugins. +* **--no-scripts:** Disables the execution of the scripts defined in the root + package. +* **--no-progress:** Removes the progress display that can mess with some + terminals or scripts which don't handle backspace characters. +* **--keep-vcs:** Skip the deletion of the VCS metadata for the created + project. This is mostly useful if you run the command in non-interactive + mode. + +## dump-autoload + +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 +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 +performance. + +### Options + +* **--optimize (-o):** Convert PSR-0 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. + +## licenses + +Lists the name, version and license of every package installed. Use +`--format=json` to get machine readable output. + +## run-script + +To run [scripts](articles/scripts.md) manually you can use this command, +just give it the script name and optionally --no-dev to disable the dev mode. + +## diagnose + +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 + +## archive + +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 + +### Options + +* **--format (-f):** Format of the resulting archive: tar or zip (default: + "tar") +* **--dir:** Write the archive to this directory (default: ".") + +## help + +To get more information about a certain command, just use `help`. + + $ php composer.phar help install + +## Environment variables + +You can set a number of environment variables that override certain settings. +Whenever possible it is recommended to specify these settings in the `config` +section of `composer.json` instead. It is worth noting that the env vars will +always take precedence over the values specified in `composer.json`. + +### COMPOSER + +By setting the `COMPOSER` env variable it is possible to set the filename of +`composer.json` to something else. + +For example: + + $ COMPOSER=composer-other.json php composer.phar install + +### COMPOSER_ROOT_VERSION + +By setting this var you can specify the version of the root package, if it can +not be guessed from VCS info and is not present in `composer.json`. + +### COMPOSER_VENDOR_DIR + +By setting this var you can make composer install the dependencies into a +directory other than `vendor`. + +### COMPOSER_BIN_DIR + +By setting this option you can change the `bin` ([Vendor Binaries](articles/vendor-binaries.md)) +directory to something other than `vendor/bin`. + +### http_proxy or HTTP_PROXY + +If you are using composer from behind an HTTP proxy, you can use the standard +`http_proxy` or `HTTP_PROXY` env vars. Simply set it to the URL of your proxy. +Many operating systems already set this variable for you. + +Using `http_proxy` (lowercased) or even defining both might be preferable since +some tools like git or curl will only use the lower-cased `http_proxy` version. +Alternatively you can also define the git proxy using +`git config --global http.proxy `. + +### no_proxy + +If you are behind a proxy and would like to disable it for certain domains, you +can use the `no_proxy` env var. Simply set it to a comma separated list of +domains the proxy should *not* be used for. + +The env var accepts domains, IP addresses, and IP address blocks in CIDR +notation. You can restrict the filter to a particular port (e.g. `:80`). You +can also set it to `*` to ignore the proxy for all HTTP requests. + +### HTTP_PROXY_REQUEST_FULLURI + +If you use a proxy but it does not support the request_fulluri flag, then you +should set this env var to `false` or `0` to prevent composer from setting the +request_fulluri option. + +### HTTPS_PROXY_REQUEST_FULLURI + +If you use a proxy but it does not support the request_fulluri flag for HTTPS +requests, then you should set this env var to `false` or `0` to prevent composer +from setting the request_fulluri option. + +### COMPOSER_HOME + +The `COMPOSER_HOME` var allows you to change the composer home directory. This +is a hidden, global (per-user on the machine) directory that is shared between +all projects. + +By default it points to `/home//.composer` on \*nix, +`/Users//.composer` on OSX and +`C:\Users\\AppData\Roaming\Composer` on Windows. + +#### COMPOSER_HOME/config.json + +You may put a `config.json` file into the location which `COMPOSER_HOME` points +to. Composer will merge this configuration with your project's `composer.json` +when you run the `install` and `update` commands. + +This file allows you to set [configuration](04-schema.md#config) and +[repositories](05-repositories.md) for the user's projects. + +In case global configuration matches _local_ configuration, the _local_ +configuration in the project's `composer.json` always wins. + +### COMPOSER_CACHE_DIR + +The `COMPOSER_CACHE_DIR` var allows you to change the composer cache directory, +which is also configurable via the [`cache-dir`](04-schema.md#config) option. + +By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and +`C:\Users\\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows. + +### COMPOSER_PROCESS_TIMEOUT + +This env var controls the time composer waits for commands (such as git +commands) to finish executing. The default value is 300 seconds (5 minutes). + +### COMPOSER_DISCARD_CHANGES + +This env var controls the discard-changes [config option](04-schema.md#config). + +### COMPOSER_NO_INTERACTION + +If set to 1, this env var will make composer behave as if you passed the +`--no-interaction` flag to every command. This can be set on build boxes/CI. + +← [Libraries](02-libraries.md) | [Schema](04-schema.md) → diff --git a/en-back/04-schema.md b/en-back/04-schema.md new file mode 100644 index 0000000..56e7871 --- /dev/null +++ b/en-back/04-schema.md @@ -0,0 +1,735 @@ +# composer.json + +This chapter will explain all of the fields available in `composer.json`. + +## JSON schema + +We have a [JSON schema](http://json-schema.org) that documents the format and +can also be used to validate your `composer.json`. In fact, it is used by the +`validate` command. You can find it at: +[`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). + +## Root Package + +The root package is the package defined by the `composer.json` at the root of +your project. It is the main `composer.json` that defines your project +requirements. + +Certain fields only apply when in the root package context. One example of +this is the `config` field. Only the root package can define configuration. +The config of dependencies is ignored. This makes the `config` field +`root-only`. + +If you clone one of those dependencies to work on it, then that package is the +root package. The `composer.json` is identical, but the context is different. + +> **Note:** A package can be the root package or not, depending on the context. +> For example, if your project depends on the `monolog` library, your project +> is the root package. However, if you clone `monolog` from GitHub in order to +> fix a bug in it, then `monolog` is the root package. + +## Properties + +### name + +The name of the package. It consists of vendor name and project name, +separated by `/`. + +Examples: + +* monolog/monolog +* igorw/event-source + +Required for published packages (libraries). + +### description + +A short description of the package. Usually this is just one line long. + +Required for published packages (libraries). + +### version + +The version of the package. In most cases this is not required and should +be omitted (see below). + +This must follow the format of `X.Y.Z` or `vX.Y.Z` with an optional suffix +of `-dev`, `-patch`, `-alpha`, `-beta` or `-RC`. The patch, alpha, beta and +RC suffixes can also be followed by a number. + +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 + +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 +to omit it. + +> **Note:** Packagist uses VCS repositories, so the statement above is very +> much true for Packagist as well. Specifying the version yourself will +> most likely end up creating problems at some point due to human error. + +### type + +The type of the package. It defaults to `library`. + +Package types are used for custom installation logic. If you have a package +that needs some special logic, you can define a custom type. This could be a +`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will +all be specific to certain projects, and they will need to provide an +installer capable of installing packages of that type. + +Out of the box, composer supports four types: + +- **library:** This is the default. It will simply copy the files to `vendor`. +- **project:** This denotes a project rather than a library. For example + application shells like the [Symfony standard edition](https://github.com/symfony/symfony-standard), + CMSs like the [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) + or full fledged applications distributed as packages. This can for example + be used by IDEs to provide listings of projects to initialize when creating + a new workspace. +- **metapackage:** An empty package that contains requirements and will trigger + their installation, but contains no files and will not write anything to the + filesystem. As such, it does not require a dist or source key to be + installable. +- **composer-plugin:** A package of type `composer-plugin` may provide an + installer for other packages that have a custom type. Read more in the + [dedicated article](articles/custom-installers.md). + +Only use a custom type if you need custom logic during installation. It is +recommended to omit this field and have it just default to `library`. + +### keywords + +An array of keywords that the package is related to. These can be used for +searching and filtering. + +Examples: + + logging + events + database + redis + templating + +Optional. + +### homepage + +An URL to the website of the project. + +Optional. + +### time + +Release date of the version. + +Must be in `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` format. + +Optional. + +### license + +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 + +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/). + +For closed-source software, you may use `"proprietary"` as the license identifier. + +An Example: + + { + "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+" + ] + } + +Alternatively they can be separated with "or" and enclosed in parenthesis; + + { + "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. + +### authors + +The authors of the package. This is an array of objects. + +Each author object can have following properties: + +* **name:** The author's name. Usually his real name. +* **email:** The author's email address. +* **homepage:** An URL to the author's website. +* **role:** The authors' role in the project (e.g. developer or translator) + +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" + } + ] + } + +Optional, but highly recommended. + +### support + +Various information to get support about the project. + +Support information includes the following: + +* **email:** Email address for support. +* **issues:** URL to the Issue Tracker. +* **forum:** URL to the Forum. +* **wiki:** URL to the Wiki. +* **irc:** IRC channel for support, as irc://server/channel. +* **source:** URL to browse or download the sources. + +An example: + + { + "support": { + "email": "support@example.org", + "irc": "irc://irc.freenode.org/composer" + } + } + +Optional. + +### Package links + +All of the following take an object which maps package names to +[version constraints](01-basic-usage.md#package-versions). + +Example: + + { + "require": { + "monolog/monolog": "1.0.*" + } + } + +All links are optional fields. + +`require` and `require-dev` additionally support stability flags (root-only). +These allow you to further restrict or expand the stability of a package beyond +the scope of the [minimum-stability](#minimum-stability) setting. You can apply +them to a constraint, or just apply them to an empty constraint if you want to +allow unstable packages of a dependency for example. + +Example: + + { + "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" + } + } + +`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 +when you run update. These only work if you explicitly require a dev version +and append the reference with `#`. + +Example: + + { + "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 +> composer.json metadata will still be read from the branch name you specify +> before the hash. Because of that in some cases it will not be a practical +> workaround, and you should always try to switch to tagged releases as soon +> as you can. + +It is also possible to inline-alias a package constraint so that it matches +a constraint that it otherwise would not. For more information [see the +aliases article](articles/aliases.md). + +#### require + +Lists packages required by this package. The package will not be installed +unless those requirements can be met. + +#### require-dev (root-only) + +Lists packages required for developing this package, or running +tests, etc. The dev requirements of the root package are installed by default. +Both `install` or `update` support the `--no-dev` option that prevents dev +dependencies from being installed. + +#### conflict + +Lists packages that conflict with this version of this package. They +will not be allowed to be installed together with your package. + +Note that when specifying ranges like `<1.0, >= 1.1` in a `conflict` link, +this will state a conflict with all versions that are less than 1.0 *and* equal +or newer than 1.1 at the same time, which is probably not what you want. You +probably want to go for `<1.0 | >= 1.1` in this case. + +#### replace + +Lists packages that are replaced by this package. This allows you to fork a +package, publish it under a different name with its own version numbers, while +packages requiring the original package continue to work with your fork because +it replaces the original package. + +This is also useful for packages that contain sub-packages, for example the main +symfony/symfony package contains all the Symfony Components which are also +available as individual packages. If you require the main package it will +automatically fulfill any requirement of one of the individual components, +since it replaces them. + +Caution is advised when using replace for the sub-package purpose explained +above. You should then typically only replace using `self.version` as a version +constraint, to make sure the main package only replaces the sub-packages of +that exact version, and not any other version, which would be incorrect. + +#### provide + +List of other packages that are provided by this package. This is mostly +useful for common interfaces. A package could depend on some virtual +`logger` package, any library that implements this logger interface would +simply list it in `provide`. + +### suggest + +Suggested packages that can enhance or work well with this package. These are +just informational and are displayed after the package is installed, to give +your users a hint that they could add more packages, even though they are not +strictly required. + +The format is like package links above, except that the values are free text +and not version constraints. + +Example: + + { + "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). + +#### PSR-0 + +Under the `psr-0` key you define a mapping from namespaces to paths, relative to the +package root. Note that this also supports the PEAR-style non-namespaced convention. + +Please note namespace declarations should end in `\\` to make sure the autoloader +responds exactly. For example `Foo` would match in `FooBar` so the trailing +backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct. + +The PSR-0 references are all combined, during install/update, into a single key => value +array which may be found in the generated file `vendor/composer/autoload_namespaces.php`. + +Example: + + { + "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/"] } + } + } + +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": "" } + } + } + +If you want to have a fallback directory where any namespace can be, you can +use an empty prefix like: + + { + "autoload": { + "psr-0": { "": "src/" } + } + } + +#### Classmap + +The `classmap` references are all combined, during install/update, into a single +key => value array which may be found in the generated file +`vendor/composer/autoload_classmap.php`. This map is built by scanning for +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 +to search for classes. + +Example: + + { + "autoload": { + "classmap": ["src/", "lib/", "Something.php"] + } + } + +#### Files + +If you want to require certain files explicitly on every request then you can use +the 'files' autoloading mechanism. This is useful if your package includes PHP functions +that cannot be autoloaded by PHP. + +Example: + + { + "autoload": { + "files": ["src/MyLibrary/functions.php"] + } + } + +### include-path + +> **DEPRECATED**: This is only present to support legacy projects, and all new code +> should preferably use autoloading. As such it is a deprecated practice, but the +> feature itself will not likely disappear from Composer. + +A list of paths which should get appended to PHP's `include_path`. + +Example: + + { + "include-path": ["lib/"] + } + +Optional. + +### target-dir + +Defines the installation target. + +In case the package root is below the namespace declaration you cannot +autoload properly. `target-dir` solves this problem. + +An example is Symfony. There are individual packages for the components. The +Yaml component is under `Symfony\Component\Yaml`. The package root is that +`Yaml` directory. To make autoloading possible, we need to make sure that it +is not installed into `vendor/symfony/yaml`, but instead into +`vendor/symfony/yaml/Symfony/Component/Yaml`, so that the autoloader can load +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" + } + +Optional. + +### minimum-stability (root-only) + +This defines the default behavior for filtering packages by stability. This +defaults to `stable`, so if you rely on a `dev` package, you should specify +it in your file to avoid surprises. + +All versions of each package are checked for stability, and those that are less +stable than the `minimum-stability` setting will be ignored when resolving +your project dependencies. Specific changes to the stability requirements of +a given package can be done in `require` or `require-dev` (see +[package links](#package-links)). + +Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`, +and `stable`. + +### prefer-stable (root-only) + +When this is enabled, Composer will prefer more stable packages over unstable +ones when finding compatible stable packages is possible. If you require a +dev version or only alphas are available for a package, those will still be +selected granted that the minimum-stability allows for it. + +Use `"prefer-stable": true` to enable. + +### repositories (root-only) + +Custom package repositories to use. + +By default composer just uses the packagist repository. By specifying +repositories you can get packages from elsewhere. + +Repositories are not resolved recursively. You can only add them to your main +`composer.json`. Repository declarations of dependencies' `composer.json`s are +ignored. + +The following repository types are supported: + +* **composer:** A composer repository is simply a `packages.json` file served + via the network (HTTP, FTP, SSH), that contains a list of `composer.json` + objects with additional `dist` and/or `source` information. The `packages.json` + file is loaded using a PHP stream. You can set extra options on that stream + using the `options` parameter. +* **vcs:** The version control system repository can fetch packages from git, + svn and hg repositories. +* **pear:** With this you can import any pear repository into your composer + project. +* **package:** If you depend on a project that does not have any support for + composer whatsoever you can define the package inline using a `package` + repository. You basically just inline the `composer.json` object. + +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/" + } + } + } + ] + } + +> **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. +By default Packagist is added last which means that custom repositories can +override packages from it. + +### config (root-only) + +A set of configuration options. It is only used for projects. + +The following options are supported: + +* **process-timeout:** Defaults to `300`. The duration processes like git clones + can run before Composer assumes they died out. You may need to make this + higher if you have a slow connection or huge vendors. +* **use-include-path:** Defaults to `false`. If true, the Composer autoloader + will also look for classes in the PHP include path. +* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or + `auto`. This option allows you to set the install method Composer will prefer to + use. +* **github-protocols:** Defaults to `["git", "https"]`. 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. +* **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. +* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a + different directory if you want to. +* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they + will be symlinked into this directory. +* **cache-dir:** Defaults to `$home/cache` on unix systems and + `C:\Users\\AppData\Local\Composer` on Windows. Stores all the caches + used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home). +* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives + of packages. +* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata + for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`. +* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for + loading VCS repository metadata for the `git`/`hg` types and to speed up installs. +* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all + dist (zip, tar, ..) packages that it downloads. Those are purged after six + months of being unused by default. This option allows you to tweak this + duration (in seconds) or disable it completely by setting it to 0. +* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all + dist (zip, tar, ..) packages that it downloads. When the garbage collection + is periodically ran, this is the maximum size the cache will be able to use. + Older (less used) files will be removed first until the cache fits. +* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader + will not be prepended to existing autoloaders. This is sometimes required to fix + interoperability issues with other autoloaders. +* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for + the generated Composer autoloader. When null a random one will be generated. +* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in + github mode. This is used for GitHub Enterprise setups. +* **notify-on-install:** Defaults to `true`. Composer allows repositories to + define a notification URL, so that they get notified whenever a package from + that repository is installed. This option allows you to disable that behaviour. +* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or + `"stash"`. This option allows you to set the default style of handling dirty + updates when in non-interactive mode. `true` will always discard changes in + vendors, while `"stash"` will try to stash and reapply. Use this for CI + servers or deploy scripts if you tend to have modified vendors. + +Example: + + { + "config": { + "bin-dir": "bin" + } + } + +### scripts (root-only) + +Composer allows you to hook into various parts of the installation process +through the use of scripts. + +See [Scripts](articles/scripts.md) for events details and examples. + +### extra + +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(); + +Optional. + +### bin + +A set of files that should be treated as binaries and symlinked into the `bin-dir` +(from config). + +See [Vendor Binaries](articles/vendor-binaries.md) for more details. + +Optional. + +### archive + +A set of options for creating package archives. + +The following options are supported: + +* **exclude:** Allows configuring a list of patterns for excluded paths. The + pattern syntax matches .gitignore files. A leading exclamation mark (!) will + result in any matching files to be included even if a previous pattern + excluded them. A leading slash will only match at the beginning of the project + relative path. An asterisk will not expand to a directory separator. + +Example: + + { + "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`. + +Optional. + +← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) → diff --git a/en-back/05-repositories.md b/en-back/05-repositories.md new file mode 100644 index 0000000..ae947ea --- /dev/null +++ b/en-back/05-repositories.md @@ -0,0 +1,549 @@ +# Repositories + +This chapter will explain the concept of packages and repositories, what kinds +of repositories are available, and how they work. + +## Concepts + +Before we look at the different types of repositories that exist, we need to +understand some of the basic concepts that composer is built on. + +### Package + +Composer is a dependency manager. It installs packages locally. A package is +essentially just a directory containing something. In this case it is PHP +code, but in theory it could be anything. And it contains a package +description which has a name and a version. The name and the version are used +to identify the package. + +In fact, internally composer sees every version as a separate package. While +this distinction does not matter when you are using composer, it's quite +important when you want to change it. + +In addition to the name and the version, there is useful metadata. The information +most relevant for installation is the source definition, which describes where +to get the package contents. The package data points to the contents of the +package. And there are two options here: dist and source. + +**Dist:** The dist is a packaged version of the package data. Usually a +released version, usually a stable release. + +**Source:** The source is used for development. This will usually originate +from a source code repository, such as git. You can fetch this when you want +to modify the downloaded package. + +Packages can supply either of these, or even both. Depending on certain +factors, such as user-supplied options and stability of the package, one will +be preferred. + +### Repository + +A repository is a package source. It's a list of packages/versions. Composer +will look in all your repositories to find the packages your project requires. + +By default only the Packagist repository is registered in Composer. You can +add more repositories to your project by declaring them in `composer.json`. + +Repositories are only available to the root package and the repositories +defined in your dependencies will not be loaded. Read the +[FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md) if you +want to learn why. + +## Types + +### Composer + +The main repository type is the `composer` repository. It uses a single +`packages.json` file that contains all of the package metadata. + +This is also the repository type that packagist uses. To reference a +`composer` repository, just supply the path before the `packages.json` file. +In case of packagist, that file is located at `/packages.json`, so the URL of +the repository would be `packagist.org`. For `example.org/packages.json` the +repository URL would be `example.org`. + +#### packages + +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 } + } + } + } + +The `@composer.json` marker would be the contents of the `composer.json` from +that package version including as a minimum: + +* name +* version +* dist or source + +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" + } + } + +It may include any of the other fields specified in the [schema](04-schema.md). + +#### notify-batch + +The `notify-batch` field allows you to specify an URL that will be called +every time a user installs a package. The URL can be either an absolute path +(that will use the same domain as the repository) or a fully qualified URL. + +An example value: + + { + "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"}, + ] + } + +The version field will contain the normalized representation of the version +number. + +This field is optional. + +#### includes + +For larger repositories it is possible to split the `packages.json` into +multiple files. The `includes` field allows you to reference these additional +files. + +An example: + + { + "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. + +This field is optional. You probably don't need it for your own custom +repository. + +#### provider-includes and providers-url + +For very large repositories like packagist.org using the so-called provider +files is the preferred method. The `provider-includes` field allows you to +list a set of files that list package names provided by this repository. The +hash should be a sha256 of the files in this case. + +The `providers-url` describes how provider files are found on the server. It +is an absolute path from the repository root. + +An example: + + { + "provider-includes": { + "providers-a.json": { + "sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c" + }, + "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" + } + } + } + +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 +themselves just contain package definitions as described [above](#packages). + +This field is optional. You probably don't need it for your own custom +repository. + +#### stream options + +The `packages.json` file is loaded using a PHP stream. You can set extra options +on that stream using the `options` parameter. You can set any valid PHP stream +context option. See [Context options and parameters](http://php.net/manual/en/context.php) +for more information. + +### VCS + +VCS stands for version control system. This includes versioning systems like +git, svn or hg. Composer has a repository type for installing packages from +these systems. + +#### Loading a package from a VCS repository + +There are a few use cases for this. The most common one is maintaining your +own fork of a third party library. If you are using a certain library for your +project and you decide to change something in the library, you will want your +project to use the patched version. If the library is on GitHub (this is the +case most of the time), you can simply fork it there and push your changes to +your fork. After that you update the project's `composer.json`. All you have +to do is add your fork as a repository and update the version constraint to +point to your custom branch. For version constraint naming conventions see +[Libraries](02-libraries.md) for more information. + +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" + } + } + +When you run `php composer.phar update`, you should get your modified version +of `monolog/monolog` instead of the one from packagist. + +Note that you should not rename the package unless you really intend to fork +it in the long term, and completely move away from the original package. +Composer will correctly pick your package over the original one since the +custom repository has priority over packagist. If you want to rename the +package, you should do so in the default (often master) branch and not in a +feature branch, since the package name is taken from the default branch. + +If other dependencies rely on the package you forked, it is possible to +inline-alias it so that it matches a constraint that it otherwise would not. +For more information [see the aliases article](articles/aliases.md). + +#### Using private repositories + +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" + } + ] + } + +The only requirement is the installation of SSH keys for a git client. + +#### Git alternatives + +Git is not the only version control system supported by the VCS repository. +The following are supported: + +* **Git:** [git-scm.com](http://git-scm.com) +* **Subversion:** [subversion.apache.org](http://subversion.apache.org) +* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com) + +To get packages from these systems you need to have their respective clients +installed. That can be inconvenient. And for this reason there is special +support for GitHub and BitBucket that use the APIs provided by these sites, to +fetch the packages without having to install the version control system. The +VCS repository provides `dist`s for them that fetch the packages as zips. + +* **GitHub:** [github.com](https://github.com) (Git) +* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial) + +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`. + +#### Subversion Options + +Since Subversion has no native concept of branches and tags, Composer assumes +by default that code is located in `$url/trunk`, `$url/branches` and +`$url/tags`. If your repository has a different layout you can change those +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" + } + ] + } + +If you have no branches or tags directory you can disable them entirely by +setting the `branches-path` or `tags-path` to `false`. + +If the package is in a sub-directory, e.g. `/trunk/foo/bar/composer.json` and +`/tags/1.0/foo/bar/composer.json`, then you can make composer access it by +setting the `"package-path"` option to the sub-directory, in this example it +would be `"package-path": "foo/bar/"`. + +### PEAR + +It is possible to install packages from any PEAR channel by using the `pear` +repository. Composer will prefix all package names with `pear-{channelName}/` to +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": "*" + } + } + +In this case the short name of the channel is `pear2`, so the +`PEAR2_HTTP_Request` package name becomes `pear-pear2/PEAR2_HTTP_Request`. + +> **Note:** The `pear` repository requires doing quite a few requests per +> package, so this may considerably slow down the installation process. + +#### Custom vendor alias + +It is possible to alias PEAR channel packages with a custom vendor name. + +Example: + +Suppose you have a private PEAR repository and wish to use Composer to +incorporate dependencies from a VCS. Your PEAR repository contains the +following packages: + + * `BasePackage` + * `IntermediatePackage`, which depends on `BasePackage` + * `TopLevelPackage1` and `TopLevelPackage2` which both depend on `IntermediatePackage` + +Without a vendor alias, Composer will use the PEAR channel name as the +vendor portion of the package name: + + * `pear-pear.foobar.repo/BasePackage` + * `pear-pear.foobar.repo/IntermediatePackage` + * `pear-pear.foobar.repo/TopLevelPackage1` + * `pear-pear.foobar.repo/TopLevelPackage2` + +Suppose at a later time you wish to migrate your PEAR packages to a +Composer repository and naming scheme, and adopt the vendor name of `foobar`. +Projects using your PEAR packages would not see the updated packages, since +they have a different vendor name (`foobar/IntermediatePackage` vs +`pear-pear.foobar.repo/IntermediatePackage`). + +By specifying `vendor-alias` for the PEAR repository from the start, you can +avoid this scenario and future-proof your package names. + +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": "*" + } + } + +### Package + +If you want to use a project that does not support composer through any of the +means above, you still can define the package yourself by using a `package` +repository. + +Basically, you define the same information that is included in the `composer` +repository's `packages.json`, but only for a single package. Again, the +minimum required fields are `name`, `version`, and either of `dist` or +`source`. + +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/"] + } + } + } + ], + "require": { + "smarty/smarty": "3.1.*" + } + } + +Typically you would leave the source part off, as you don't really need it. + +> **Note**: This repository type has a few limitations and should be avoided +> whenever possible: +> +> - Composer will not update the package unless you change the `version` field. +> - Composer will not update the commit references, so if you use `master` as +> reference you will have to delete the package to force an update, and will +> have to deal with an unstable lock file. + +## Hosting your own + +While you will probably want to put your packages on packagist most of the time, +there are some use cases for hosting your own repository. + +* **Private company packages:** If you are part of a company that uses composer + for their packages internally, you might want to keep those packages private. + +* **Separate ecosystem:** If you have a project which has its own ecosystem, + and the packages aren't really reusable by the greater PHP community, you + might want to keep them separate to packagist. An example of this would be + wordpress plugins. + +For hosting your own packages, a native `composer` type of repository is +recommended, which provides the best performance. + +There are a few tools that can help you create a `composer` repository. + +### Packagist + +The underlying application used by packagist is open source. This means that you +can just install your own copy of packagist, re-brand, and use it. It's really +quite straight-forward to do. However due to its size and complexity, for most +small and medium sized companies willing to track a few packages will be better +off using Satis. + +Packagist is a Symfony2 application, and it is [available on +GitHub](https://github.com/composer/packagist). It uses composer internally and +acts as a proxy between VCS repositories and the composer users. It holds a list +of all VCS packages, periodically re-crawls them, and exposes them as a composer +repository. + +To set your own copy, simply follow the instructions from the [packagist +github repository](https://github.com/composer/packagist). + +### Satis + +Satis is a static `composer` repository generator. It is a bit like an ultra- +lightweight, static file-based version of packagist. + +You give it a `composer.json` containing repositories, typically VCS and +package repository definitions. It will fetch all the packages that are +`require`d and dump a `packages.json` that is your `composer` repository. + +Check [the satis GitHub repository](https://github.com/composer/satis) and +the [Satis article](articles/handling-private-packages-with-satis.md) for more +information. + +### Artifact + +There are some cases, when there is no ability to have one of the previously +mentioned repository types online, even the VCS one. Typical example could be +cross-organisation library exchange through built artifacts. Of course, most +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" + } + } + +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 + ... + +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 +and you run `update`, that version will be imported as well and Composer will +update to the latest version. + +## Disabling Packagist + +You can disable the default Packagist repository by adding this to your +`composer.json`: + + { + "repositories": [ + { + "packagist": false + } + ] + } + + +← [Schema](04-schema.md) | [Community](06-community.md) → diff --git a/en-back/06-community.md b/en-back/06-community.md new file mode 100644 index 0000000..10ef31b --- /dev/null +++ b/en-back/06-community.md @@ -0,0 +1,34 @@ +# Community + +There are many people using composer already, and quite a few of them are +contributing. + +## Contributing + +If you would like to contribute to composer, please read the +[README](https://github.com/composer/composer). + +The most important guidelines are described as follows: + +> All code contributions - including those of people having commit access - must +> go through a pull request and approved by a core developer before being +> merged. This is to ensure proper review of all the code. +> +> Fork the project, create a feature branch, and send us a pull request. +> +> To ensure a consistent code base, you should make sure the code follows +> the [Coding Standards](http://symfony.com/doc/2.0/contributing/code/standards.html) +> which we borrowed from Symfony. + +## IRC / mailing list + +Mailing lists for [user support](http://groups.google.com/group/composer-users) and +[development](http://groups.google.com/group/composer-dev). + +IRC channels are on irc.freenode.org: [#composer](irc://irc.freenode.org/composer) +for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development. + +Stack Overflow has a growing collection of +[Composer related questions](http://stackoverflow.com/questions/tagged/composer-php). + +← [Repositories](05-repositories.md) diff --git a/en-back/articles/aliases.md b/en-back/articles/aliases.md new file mode 100644 index 0000000..26a9c46 --- /dev/null +++ b/en-back/articles/aliases.md @@ -0,0 +1,96 @@ + + +# Aliases + +## 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 +will get a `dev-master` version. For your `bugfix` branch, you will get a +`dev-bugfix` version. + +If your `master` branch is used to tag releases of the `1.0` development line, +i.e. `1.0.1`, `1.0.2`, `1.0.3`, etc., any package depending on it will +probably require version `1.0.*`. + +If anyone wants to require the latest `dev-master`, they have a problem: Other +packages may require `1.0.*`, so requiring that dev version will lead to +conflicts, since `dev-master` does not match the `1.0.*` constraint. + +Enter aliases. + +## Branch alias + +The `dev-master` branch is one in your main VCS repo. It is rather common that +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" + } + } + } + +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 +`.x-dev`). The `branch-alias` must be present on the branch that it references. +For `dev-master`, you need to commit it on the `master` branch. + +As a result, anyone can now require `1.0.*` and it will happily install +`dev-master`. + +In order to use branch aliasing, you must own the repository of the package +being aliased. If you want to alias a third party package without maintaining +a fork of it, use inline aliases as described below. + +## Require inline alias + +Branch aliases are great for aliasing main development lines. But in order to +use them you need to have control over the source repository, and you need to +commit changes to version control. + +This is not really fun when you just want to try a bugfix of some library that +is a dependency of your local project. + +For this reason, you can alias packages in your `require` and `require-dev` +fields. Let's say you found a bug in the `monolog/monolog` package. You cloned +[Monolog](https://github.com/Seldaek/monolog) on GitHub and fixed the issue in +a branch named `bugfix`. Now you want to install that version of monolog in your +local project. + +You are using `symfony/monolog-bundle` which requires `monolog/monolog` version +`1.*`. So you need your `dev-bugfix` to match that constraint. + +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" + } + } + +That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub +and alias it to `1.0.x-dev`. + +> **Note:** If a package with inline aliases is required, the alias (right of +> the `as`) is used as the version constraint. The part left of the `as` is +> discarded. As a consequence, if A requires B and B requires `monolog/monolog` +> version `dev-bugfix as 1.0.x-dev`, installing A will make B require +> `1.0.x-dev`, which may exist as a branch alias or an actual `1.0` branch. If +> it does not, it must be re-inline-aliased in A's `composer.json`. + +> **Note:** Inline aliasing should be avoided, especially for published +> packages. If you found a bug, try and get your fix merged upstream. This +> helps to avoid issues for users of your package. diff --git a/en-back/articles/custom-installers.md b/en-back/articles/custom-installers.md new file mode 100644 index 0000000..feeebe5 --- /dev/null +++ b/en-back/articles/custom-installers.md @@ -0,0 +1,186 @@ + + +# Setting up and using custom installers + +## Synopsis + +At times it may be necessary for a package to require additional actions during +installation, such as installing packages outside of the default `vendor` +library. + +In these cases you could consider creating a Custom Installer to handle your +specific logic. + +## Calling a Custom Installer + +Suppose that your project already has a Custom Installer for specific modules +then invoking that installer is a matter of defining the correct [type][1] in +your package file. + +> _See the next chapter for an instruction how to create Custom Installers._ + +Every Custom Installer defines which [type][1] string it will recognize. Once +recognized it will completely override the default installer and only apply its +own logic. + +An example use-case would be: + +> phpDocumentor features Templates that need to be installed outside of the +> default /vendor folder structure. As such they have chosen to adopt the +> `phpdocumentor-template` [type][1] and create a plugin providing the Custom +> Installer to send these templates to the correct folder. + +An example composer.json of such a template package would be: + + { + "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 +> the plugin package. + +## Creating an Installer + +A Custom Installer is defined as a class that implements the +[`Composer\Installer\InstallerInterface`][3] and is usually distributed in a +Composer Plugin. + +A basic Installer Plugin would thus compose of three files: + +1. the package file: composer.json +2. The Plugin class, e.g.: `My\Project\Composer\Plugin.php`, containing a class that implements `Composer\Plugin\PluginInterface`. +3. The Installer class, e.g.: `My\Project\Composer\Installer.php`, containing a class that implements `Composer\Installer\InstallerInterface`. + +### composer.json + +The package file is the same as any other package file but with the following +requirements: + +1. the [type][1] attribute must be `composer-plugin`. +2. the [extra][2] attribute must contain an element `class` defining the + class name of the plugin (including namespace). If a package contains + multiple plugins this can be array of class names. + +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" + } + } + +### The Plugin class + +The class defining the Composer plugin must implement the +[`Composer\Plugin\PluginInterface`][3]. It can then register the Custom +Installer in its `activate()` method. + +The class may be placed in any location and have any name, as long as it is +autoloadable and matches the `extra.class` element in the package definition. + +Example: + + namespace phpDocumentor\Composer; + + use Composer\Composer; + use Composer\IO\IOInterface; + use Composer\Plugin\PluginInterface; + + class TemplateInstallerPlugin implements PluginInterface + { + public function activate(Composer $composer, IOInterface $io) + { + $installer = new TemplateInstaller($io, $composer); + $composer->getInstallationManager()->addInstaller($installer); + } + } + +### The Custom Installer class + +The class that executes the custom installation should implement the +[`Composer\Installer\InstallerInterface`][4] (or extend another installer that +implements that interface). It defines the [type][1] string as it will be +recognized by packages that will use this installer in the `supports()` method. + +> **NOTE**: _choose your [type][1] name carefully, it is recommended to follow +> the format: `vendor-type`_. For example: `phpdocumentor-template`. + +The InstallerInterface class defines the following methods (please see the +source for the exact signature): + +* **supports()**, here you test whether the passed [type][1] matches the name + that you declared for this installer (see the example). +* **isInstalled()**, determines whether a supported package is installed or not. +* **install()**, here you can determine the actions that need to be executed + upon installation. +* **update()**, here you define the behavior that is required when Composer is + invoked with the update argument. +* **uninstall()**, here you can determine the actions that need to be executed + when the package needs to be removed. +* **getInstallPath()**, this method should return the location where the + package is to be installed, _relative from the location of composer.json._ + +Example: + + namespace phpDocumentor\Composer; + + use Composer\Package\PackageInterface; + use Composer\Installer\LibraryInstaller; + + class TemplateInstaller extends LibraryInstaller + { + /** + * {@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); + } + + /** + * {@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 +different installation path. + +> _Instead of being installed in `/vendor` any package installed using this +> Installer will be put in the `/data/templates/` folder._ + +[1]: ../04-schema.md#type +[2]: ../04-schema.md#extra +[3]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/PluginInterface.php +[4]: https://github.com/composer/composer/blob/master/src/Composer/Installer/InstallerInterface.php +[5]: https://github.com/composer/composer/blob/master/src/Composer/Installer/LibraryInstaller.php diff --git a/en-back/articles/handling-private-packages-with-satis.md b/en-back/articles/handling-private-packages-with-satis.md new file mode 100644 index 0000000..0219f81 --- /dev/null +++ b/en-back/articles/handling-private-packages-with-satis.md @@ -0,0 +1,188 @@ + + +# Handling private packages with Satis + +Satis is a static `composer` repository generator. It is a bit like an ultra- +lightweight, static file-based version of packagist and can be used to host the +metadata of your company's private packages, or your own. It basically acts as +a micro-packagist. You can get it from +[GitHub](http://github.com/composer/satis) or install via CLI: +`composer.phar create-project composer/satis --stability=dev`. + +## Setup + +For example let's assume you have a few packages you want to reuse across your +company but don't really want to open-source. You would first define a Satis +configuration: a json file with an arbitrary name that lists your curated +[repositories](../05-repositories.md). + +Here is an example configuration, you see that it holds a few VCS repositories, +but those could be any types of [repositories](../05-repositories.md). Then it +uses `"require-all": true` which selects all versions of all packages in the +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 + } + +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" + } + } + +Once you did this, you just run `php bin/satis build `. +For example `php bin/satis build config.json web/` would read the `config.json` +file and build a static repository inside the `web/` directory. + +When you ironed out that process, what you would typically do is run this +command as a cron job on a server. It would then update all your package info +much like Packagist does. + +Note that if your private packages are hosted on GitHub, your server should have +an ssh key that gives it access to those packages, and then you should add +the `--no-interaction` (or `-n`) flag to the command to make sure it falls back +to ssh key authentication instead of prompting for a password. This is also a +good trick for continuous integration servers. + +Set up a virtual-host that points to that `web/` directory, let's say it is +`packages.example.org`. Alternatively, with PHP >= 5.4.0, you can use the built-in +CLI server `php -S localhost:port -t satis-output-dir/` for a temporary solution. + +## Usage + +In your projects all you need to add now is your own composer repository using +the `packages.example.org` as URL, then you can require your private packages and +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" + } + } + +### Security + +To secure your private repository you can host it over SSH or SSL using a client +certificate. In your project you can use the `options` parameter to specify the +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" + } + } + } + ] + } + +> **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" + } + } + } + ] + } + +> **Tip:** See [ssl context options](http://www.php.net/manual/en/context.ssl.php) for more information. + +### Downloads + +When GitHub or BitBucket repositories are mirrored on your local satis, the build process will include +the location of the downloads these platforms make available. This means that the repository and your setup depend +on the availability of these services. + +At the same time, this implies that all code which is hosted somewhere else (on another service or for example in +Subversion) will not have downloads available and thus installations usually take a lot longer. + +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 + } + } + +#### Options explained + + * `directory`: the location of the dist files (inside the `output-dir`) + * `format`: optional, `zip` (default) or `tar` + * `prefix-url`: optional, location of the downloads, homepage (from `satis.json`) followed by `directory` by default + * `skip-dev`: optional, `false` by default, when enabled (`true`) satis will not create downloads for branches + +Once enabled, all downloads (include those from GitHub and BitBucket) will be replaced with a _local_ version. + +#### prefix-url + +Prefixing the URL with another host is especially helpful if the downloads end up in a private Amazon S3 +bucket or on a CDN host. A CDN would drastically improve download times and therefore package installation. + +Example: A `prefix-url` of `http://my-bucket.s3.amazonaws.com` (and `directory` set to `dist`) creates download URLs +which look like the following: `http://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip`. + + +### Resolving dependencies + +It is possible to make satis automatically resolve and add all dependencies for your projects. This can be used +with the Downloads functionality to have a complete local mirror of packages. Just add the following +to your `satis.json`: + +``` +{ + "require-dependencies": true +} +``` + +When searching for packages, satis will attempt to resolve all the required packages from the listed repositories. +Therefore, if you are requiring a package from Packagist, you will need to define it in your `satis.json`. diff --git a/en-back/articles/plugins.md b/en-back/articles/plugins.md new file mode 100644 index 0000000..75706f7 --- /dev/null +++ b/en-back/articles/plugins.md @@ -0,0 +1,150 @@ + + +# Setting up and using plugins + +## Synopsis + +You may wish to alter or expand Composer's functionality with your own. For +example if your environment poses special requirements on the behaviour of +Composer which do not apply to the majority of its users or if you wish to +accomplish something with composer in a way that is not desired by most users. + +In these cases you could consider creating a plugin to handle your +specific logic. + +## Creating a Plugin + +A plugin is a regular composer package which ships its code as part of the +package and may also depend on further packages. + +### Plugin Package + +The package file is the same as any other package file but with the following +requirements: + +1. the [type][1] attribute must be `composer-plugin`. +2. the [extra][2] attribute must contain an element `class` defining the + class name of the plugin (including namespace). If a package contains + multiple plugins this can be array of class names. + +Additionally you must require the special package called `composer-plugin-api` +to define which composer API versions your plugin is compatible with. The +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" + } + } + +### Plugin Class + +Every plugin has to supply a class which implements the +[`Composer\Plugin\PluginInterface`][3]. The `activate()` method of the plugin +is called after the plugin is loaded and receives an instance of +[`Composer\Composer`][4] as well as an instance of +[`Composer\IO\IOInterface`][5]. Using these two objects all configuration can +be read and all internal objects and state can be manipulated as desired. + +Example: + + namespace phpDocumentor\Composer; + + use Composer\Composer; + use Composer\IO\IOInterface; + use Composer\Plugin\PluginInterface; + + class TemplateInstallerPlugin implements PluginInterface + { + public function activate(Composer $composer, IOInterface $io) + { + $installer = new TemplateInstaller($io, $composer); + $composer->getInstallationManager()->addInstaller($installer); + } + } + +## Event Handler + +Furthermore plugins may implement the +[`Composer\EventDispatcher\EventSubscriberInterface`][6] in order to have its +event handlers automatically registered with the `EventDispatcher` when the +plugin is loaded. + +The events available for plugins are: + +* **COMMAND**, is called at the beginning of all commands that load plugins. + It provides you with access to the input and output objects of the program. +* **PRE_FILE_DOWNLOAD**, is triggered before files are downloaded and allows + you to manipulate the `RemoteFilesystem` object prior to downloading files + based on the URL to be downloaded. + +> A plugin can also subscribe to [script events][7]. + +Example: + + namespace Naderman\Composer\AWS; + + 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) + { + $this->composer = $composer; + $this->io = $io; + } + + 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); + + 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 + +Plugin packages are automatically loaded as soon as they are installed and will +be loaded when composer starts up if they are found in the current project's +list of installed packages. Additionally all plugin packages installed in the +`COMPOSER_HOME` directory using the composer global command are loaded before +local project plugins are loaded. + +> You may pass the `--no-plugins` option to composer commands to disable all +> installed commands. This may be particularly helpful if any of the plugins +> causes errors and you wish to update or uninstall it. + +[1]: ../04-schema.md#type +[2]: ../04-schema.md#extra +[3]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/PluginInterface.php +[4]: https://github.com/composer/composer/blob/master/src/Composer/Composer.php +[5]: https://github.com/composer/composer/blob/master/src/Composer/IO/IOInterface.php +[6]: https://github.com/composer/composer/blob/master/src/Composer/EventDispatcher/EventSubscriberInterface.php +[7]: ./scripts.md#event-names diff --git a/en-back/articles/scripts.md b/en-back/articles/scripts.md new file mode 100644 index 0000000..06e7c78 --- /dev/null +++ b/en-back/articles/scripts.md @@ -0,0 +1,125 @@ + + +# Scripts + +## What is a script? + +A script, in Composer's terms, can either be a PHP callback (defined as a +static method) or any command-line executable command. Scripts are useful +for executing a package's custom code or package-specific commands during +the Composer execution process. + +**NOTE: Only scripts defined in the root package's `composer.json` are +executed. If a dependency of the root package specifies its own scripts, +Composer does not execute those additional scripts.** + + +## Event names + +Composer fires the following named events during its execution process: + +- **pre-install-cmd**: occurs before the `install` command is executed. +- **post-install-cmd**: occurs after the `install` command is executed. +- **pre-update-cmd**: occurs before the `update` command is executed. +- **post-update-cmd**: occurs after the `update` command is executed. +- **pre-status-cmd**: occurs before the `status` command is executed. +- **post-status-cmd**: occurs after the `status` command is executed. +- **pre-package-install**: occurs before a package is installed. +- **post-package-install**: occurs after a package is installed. +- **pre-package-update**: occurs before a package is updated. +- **post-package-update**: occurs after a package is updated. +- **pre-package-uninstall**: occurs before a package has been uninstalled. +- **post-package-uninstall**: occurs after a package has been uninstalled. +- **pre-autoload-dump**: occurs before the autoloader is dumped, either + during `install`/`update`, or via the `dump-autoload` command. +- **post-autoload-dump**: occurs after the autoloader is dumped, either + during `install`/`update`, or via the `dump-autoload` command. +- **post-root-package-install**: occurs after the root package has been + installed, during the `create-project` command. +- **post-create-project-cmd**: occurs after the `create-project` 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 +require Composer-managed dependencies in the `pre-update-cmd` or +`pre-install-cmd` event hooks. If you need to execute scripts prior to +`install` or `update` please make sure they are self-contained within your +root package.** + +## Defining scripts + +The root JSON object in `composer.json` should have a property called +`"scripts"`, which contains pairs of named events and each event's +corresponding scripts. An event's scripts can be defined as either as a string +(only for a single script) or an array (for single or multiple scripts.) + +For any given event: + +- Scripts execute in the order defined when their corresponding event is fired. +- An array of scripts wired to a single event can contain both PHP callbacks +and command-line executables commands. +- PHP classes containing defined callbacks must be autoloadable via Composer's +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/" + ] + } + } + +Using the previous definition example, here's the class `MyVendor\MyClass` +that might be used to execute the PHP callbacks: + + 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: + +- `getComposer()`: returns the current instance of `Composer\Composer` +- `getName()`: returns the name of the event being fired as a string +- `getIO()`: returns the current input/output stream which implements +`Composer\IO\IOInterface` for writing to the console + +## Running scripts manually + +If you would like to run the scripts for an event manually, the syntax is: + + $ 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. diff --git a/en-back/articles/troubleshooting.md b/en-back/articles/troubleshooting.md new file mode 100644 index 0000000..3483b1c --- /dev/null +++ b/en-back/articles/troubleshooting.md @@ -0,0 +1,106 @@ + +# Troubleshooting + +This is a list of common pitfalls on using Composer, and how to avoid them. + +## General + +1. Before asking anyone, run [`composer diagnose`](../03-cli.md#diagnose) to check + for common problems. If it all checks out, proceed to the next steps. + +2. When facing any kind of problems using Composer, be sure to **work with the + latest version**. See [self-update](../03-cli.md#self-update) for details. + +3. Make sure you have no problems with your setup by running the installer's + checks via `curl -sS https://getcomposer.org/installer | php -- --check`. + +4. Ensure you're **installing vendors straight from your `composer.json`** via + `rm -rf vendor && composer update -v` when troubleshooting, excluding any + possible interferences with existing vendor installations or `composer.lock` + entries. + +## Package not found + +1. Double-check you **don't have typos** in your `composer.json` or repository + branches and tag names. + +2. Be sure to **set the right + [minimum-stability](../04-schema.md#minimum-stability)**. To get started or be + sure this is no issue, set `minimum-stability` to "dev". + +3. Packages **not coming from [Packagist](https://packagist.org/)** should + always be **defined in the root package** (the package depending on all + vendors). + +4. Use the **same vendor and package name** throughout all branches and tags of + your repository, especially when maintaining a third party fork and using + `replace`. + +## Package not found on travis-ci.org + +1. Check the ["Package not found"](#package-not-found) item above. + +2. If the package tested is a dependency of one of its dependencies (cyclic + dependency), the problem might be that composer is not able to detect the version + of the package properly. If it is a git clone it is generally alright and Composer + will detect the version of the current branch, but travis does shallow clones so + that process can fail when testing pull requests and feature branches in general. + The best solution is to define the version you are on via an environment variable + called COMPOSER_ROOT_VERSION. You set it to `dev-master` for example to define + the root package's version as `dev-master`. + Use: `before_script: COMPOSER_ROOT_VERSION=dev-master composer install` to export + the variable for the call to composer. + +## Need to override a package version + +Let say your project depends on package A which in turn depends on a specific +version of package B (say 0.1) and you need a different version of that +package - version 0.11. + +You can fix this by aliasing version 0.11 to 0.1: + +composer.json: + + { + "require": { + "A": "0.2", + "B": "0.11 as 0.1" + } + } + +See [aliases](aliases.md) for more information. + +## Memory limit errors + +If composer shows memory errors on some commands: + + PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...> + +The PHP `memory_limit` should be increased. + +> **Note:** Composer internally increases the `memory_limit` to `512M`. +> If you have memory issues when using composer, please consider [creating +> an issue ticket](https://github.com/composer/composer/issues) so we can look into it. + +To get the current `memory_limit` value, run: + + 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 + +Or, you can increase the limit with a command-line argument: + + php -d memory_limit=-1 composer.phar <...> + +## "The system cannot find the path specified" (Windows) + +1. Open regedit. +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. diff --git a/en-back/articles/vendor-binaries.md b/en-back/articles/vendor-binaries.md new file mode 100644 index 0000000..b258dcc --- /dev/null +++ b/en-back/articles/vendor-binaries.md @@ -0,0 +1,106 @@ + + +# Vendor binaries and the `vendor/bin` directory + +## What is a vendor binary? + +Any command line script that a Composer package would like to pass along +to a user who installs the package should be listed as a vendor binary. + +If a package contains other scripts that are not needed by the package +users (like build or compile scripts) that code should not be listed +as a vendor binary. + + +## How is it defined? + +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"] + } + + +## What does defining a vendor binary in composer.json do? + +It instructs Composer to install the package's binaries to `vendor/bin` +for any project that **depends** on that project. + +This is a convenient way to expose useful scripts that would +otherwise be hidden deep in the `vendor/` directory. + + +## What happens when Composer is run on a composer.json that defines vendor binaries? + +For the binaries that a package defines directly, nothing happens. + + +## What happens when Composer is run on a composer.json that has dependencies with vendor binaries listed? + +Composer looks for the binaries defined in all of the dependencies. A +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"] + } + +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": "*" + } + } + +Running `composer install` for this `composer.json` will look at +all of project-b's dependencies and install them to `vendor/bin`. + +In this case, Composer will make `vendor/my-vendor/project-a/bin/project-a-bin` +available as `vendor/bin/project-a-bin`. On a Unix-like platform +this is accomplished by creating a symlink. + + +## What about Windows and .bat files? + +Packages managed entirely by Composer do not *need* to contain any +`.bat` files for Windows compatibility. Composer handles installation +of binaries in a special way when run in a Windows environment: + + * A `.bat` file is generated automatically to reference the binary + * A Unix-style proxy file with the same name as the binary is generated + automatically (useful for Cygwin or Git Bash) + +Packages that need to support workflows that may not include Composer +are welcome to maintain custom `.bat` files. In this case, the package +should **not** list the `.bat` file as a binary as it is not needed. + + +## Can vendor binaries be installed somewhere other than vendor/bin? + +Yes, there are two ways an alternate vendor binary location can be specified: + + 1. Setting the `bin-dir` configuration setting in `composer.json` + 1. Setting the environment variable `COMPOSER_BIN_DIR` + +An example of the former looks like this: + + { + "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 +`vendor/bin/`. diff --git a/en-back/dev/DefaultPolicy.md b/en-back/dev/DefaultPolicy.md new file mode 100644 index 0000000..61db2bf --- /dev/null +++ b/en-back/dev/DefaultPolicy.md @@ -0,0 +1,55 @@ +# Default Solver Policy + +A solver policy defines behaviour variables of the dependency solver. It decides +which versions are considered newer than others, which packages should be +preferred over others and whether operations like downgrades or uninstall are +allowed. + +## Selection of preferred Packages + +The following describe package pool situations with user requests and the +resulting order in which the solver will try to install them. + +The rules are to be applied in the order of these descriptions. + +### Package versions + +Packages: Av1, Av2, Av3 + +* Installed: Av2 + +Request: install A + +* (Av3) + +### Repository priorities + +Packages Repo1.Av1, Repo2.Av1 + +* priority(Repo1) >= priority(Repo2) => (Repo1.Av1, Repo2.Av1) +* priority(Repo1) < priority(Repo2) => (Repo2.Av1, Repo1.Av1) + +### Virtual Packages (provides) + +Packages Av1, Bv1 + +* Av1 provides Xv1 +* Bv1 provides Xv1 + +Request: install X + +* priority(Av1.repo) >= priority(Bv1.repo) => (Av1, Bv1) +* priority(Av1.repo) < priority(Bv1.repo) => (Bv1, Av1) + +### Package replacements + +Packages: Av1, Bv2 + +* Bv2 replaces Av1 + +Request: install A + +* priority(Av1.repo) >= priority(Bv2.repo) => (Av1, Bv2) +* priority(Av1.repo) < priority(Bv2.repo) => (Bv2, Av1) + +Bv2 version is ignored, only the replacement version for A matters. diff --git a/en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md b/en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md new file mode 100644 index 0000000..b5956ca --- /dev/null +++ b/en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md @@ -0,0 +1,46 @@ +# How do I install a package to a custom path for my framework? + +Each framework may have one or many different required package installation +paths. Composer can be configured to install packages to a folder other than +the default `vendor` folder by using +[composer/installers](https://github.com/composer/installers). + +If you are a **package author** and want your package installed to a custom +directory, simply require `composer/installers` and set the appropriate `type`. +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" + } + } + +Now when your theme is installed with Composer it will be placed into +`wp-content/themes/themename/` folder. Check the +[current supported types](https://github.com/composer/installers#current-supported-types) +for your package. + +As a **package consumer** you can set or override the install path for a package +that requires composer/installers by configuring the `installer-paths` extra. A +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"] + } + } + } + +Now the package would be installed to your folder location, rather than the default +composer/installers determined location. + +> **Note:** You cannot use this to change the path of any package. This is only +> applicable to packages that require `composer/installers` and use a custom type +> that it handles. diff --git a/en-back/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md b/en-back/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md new file mode 100644 index 0000000..8e50f72 --- /dev/null +++ b/en-back/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md @@ -0,0 +1,31 @@ +# Should I commit the dependencies in my vendor directory? + +The general recommendation is **no**. The vendor directory (or wherever your +dependencies are installed) should be added to `.gitignore`/`svn:ignore`/etc. + +The best practice is to then have all the developers use Composer to install +the dependencies. Similarly, the build server, CI, deployment tools etc should +be adapted to run Composer as part of their project bootstrapping. + +While it can be tempting to commit it in some environment, it leads to a few +problems: + +- Large VCS repository size and diffs when you update code. +- Duplication of the history of all your dependencies in your own VCS. +- Adding dependencies installed via git to a git repo will show them as + submodules. This is problematic because they are not real submodules, and you + will run into issues. + +If you really feel like you must do this, you have a few options: + +1. Limit yourself to installing tagged releases (no dev versions), so that you + only get zipped installs, and avoid problems with the git "submodules". +2. Use --prefer-dist or set `preferred-install` to `dist` in your + [config](../04-schema.md#config). +3. Remove the `.git` directory of every dependency after the installation, then + you can add them to your git repo. You can do that with `rm -rf vendor/**/.git` + but this means you will have to delete those dependencies from disk before + running composer update. +4. Add a .gitignore rule (`vendor/.git`) to ignore all the vendor `.git` folders. + This approach does not require that you delete dependencies from disk prior to + running a composer update. diff --git a/en-back/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md b/en-back/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md new file mode 100644 index 0000000..bac633a --- /dev/null +++ b/en-back/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md @@ -0,0 +1,21 @@ +# Why are version constraints combining comparisons and wildcards a bad idea? + +This is a fairly common mistake people make, defining version constraints in +their package requires like `>=2.*` or `>=1.1.*`. + +If you think about it and what it really means though, you will quickly +realize that it does not make much sense. If we decompose `>=2.*`, you +have two parts: + +- `>=2` which says the package should be in version 2.0.0 or above. +- `2.*` which says the package should be between version 2.0.0 (inclusive) + and 3.0.0 (exclusive). + +As you see, both rules agree on the fact that the package must be >=2.0.0, +but it is not possible to determine if when you wrote that you were thinking +of a package in version 3.0.0 or not. Should it match because you asked for +`>=2` or should it not match because you asked for a `2.*`? + +For this reason, Composer just throws an error and says that this is invalid. +The easy way to fix it is to think about what you really mean, and use only +one of those rules. \ No newline at end of file diff --git a/en-back/faqs/why-can't-composer-load-repositories-recursively.md b/en-back/faqs/why-can't-composer-load-repositories-recursively.md new file mode 100644 index 0000000..d81a0f0 --- /dev/null +++ b/en-back/faqs/why-can't-composer-load-repositories-recursively.md @@ -0,0 +1,34 @@ +# Why can't Composer load repositories recursively? + +You may run into problems when using custom repositories because Composer does +not load the repositories of your requirements, so you have to redefine those +repositories in all your `composer.json` files. + +Before going into details as to why this is like that, you have to understand +that the main use of custom VCS & package repositories is to temporarily try +some things, or use a fork of a project until your pull request is merged, etc. +You should not use them to keep track of private packages. For that you should +look into [setting up Satis](../articles/handling-private-packages-with-satis.md) +for your company or even for yourself. + +There are three ways the dependency solver could work with custom repositories: + +- Fetch the repositories of root package, get all the packages from the defined +repositories, resolve requirements. This is the current state and it works well +except for the limitation of not loading repositories recursively. + +- Fetch the repositories of root package, while initializing packages from the +defined repos, initialize recursively all repos found in those packages, and +their package's packages, etc, then resolve requirements. It could work, but it +slows down the initialization a lot since VCS repos can each take a few seconds, +and it could end up in a completely broken state since many versions of a package +could define the same packages inside a package repository, but with different +dist/source. There are many many ways this could go wrong. + +- Fetch the repositories of root package, then fetch the repositories of the +first level dependencies, then fetch the repositories of their dependencies, etc, +then resolve requirements. This sounds more efficient, but it suffers from the +same problems than the second solution, because loading the repositories of the +dependencies is not as easy as it sounds. You need to load all the repos of all +the potential matches for a requirement, which again might have conflicting +package definitions. -- 2.46.2 From 5bf2a68332cccb8f61e2f847790534fb22c249bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 1 Jan 2014 23:27:19 +0800 Subject: [PATCH 003/125] update README.md --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index ee67418..121c87e 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,13 @@ composer-doc-cn =============== Composer 中文文档 + +--- + +- Book + - [简介](#/cn-introduction/00-intro.md) + - [基本用法](#/cn-introduction/01-basic-usage.md) + - [库](#/cn-introduction/02-libraries.md) + - [命令行](#/cn-introduction/03-cli.md) + +--- \ No newline at end of file -- 2.46.2 From 2cc794b628fc8467bd7bf9d78b8d9316ddc1ecd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 1 Jan 2014 23:39:05 +0800 Subject: [PATCH 004/125] update README.md --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 121c87e..42c67d6 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,46 @@ Composer 中文文档 --- -- Book - - [简介](#/cn-introduction/00-intro.md) - - [基本用法](#/cn-introduction/01-basic-usage.md) - - [库](#/cn-introduction/02-libraries.md) - - [命令行](#/cn-introduction/03-cli.md) +## Book +- [简介](#/cn-introduction/00-intro.md) +- [基本用法](#/cn-introduction/01-basic-usage.md) +- [库](#/cn-introduction/02-libraries.md) +- [命令行](#/cn-introduction/03-cli.md) +- [Schema](#/cn-introduction/04-schema.md) +- [Repositories](#/cn-introduction/05-repositories.md) +- [Community](#/cn-introduction/06-community.md) ---- \ No newline at end of file +--- + +## Articles +- Aliases +Alias branch names to versions +- Custom Installers +Modify the way certain types of packages are installed +- Handling Private Packages With Satis +Host your own composer repository +- Plugins +Modify and extend Composer's functionality +- Scripts +Script are callbacks that are called before/after installing packages +- Troubleshooting +Solving problems +- Vendor Binaries +Expose command-line scripts from packages + +--- + +## FAQs + +- [How Do I Install A Package To A Custom Path For My Framework](/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md) +- [Should I Commit The Dependencies In My Vendor Directory](/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md) +- [Why Are Version Constraints Combining Comparisons And Wildcards A Bad Idea](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) +- [Why Can't Composer Load Repositories Recursively](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) + +## PDF Docs + +The whole documentation is also available as a [PDF download](http://getcomposer.org/book.pdf). + +## API Docs + +If you need to work with composer as a library you may also want to check out the [API Docs](http://getcomposer.org/apidoc/master/index.html) \ No newline at end of file -- 2.46.2 From 0a6355695d41424ede30b1a259a598eacbf687f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 1 Jan 2014 23:40:35 +0800 Subject: [PATCH 005/125] update README.md --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index 42c67d6..bc63fb7 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,6 @@ composer-doc-cn Composer 中文文档 ---- - ## Book - [简介](#/cn-introduction/00-intro.md) - [基本用法](#/cn-introduction/01-basic-usage.md) @@ -14,8 +12,6 @@ Composer 中文文档 - [Repositories](#/cn-introduction/05-repositories.md) - [Community](#/cn-introduction/06-community.md) ---- - ## Articles - Aliases Alias branch names to versions @@ -32,8 +28,6 @@ Solving problems - Vendor Binaries Expose command-line scripts from packages ---- - ## FAQs - [How Do I Install A Package To A Custom Path For My Framework](/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md) -- 2.46.2 From 50166e827a4b64a4a73d45a7ad47e5382fae9612 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 1 Jan 2014 23:43:48 +0800 Subject: [PATCH 006/125] update README.md --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index bc63fb7..c0bae4c 100644 --- a/README.md +++ b/README.md @@ -13,19 +13,19 @@ Composer 中文文档 - [Community](#/cn-introduction/06-community.md) ## Articles -- Aliases +- [Aliases](/cn-introduction/articles/aliases.md) Alias branch names to versions -- Custom Installers +- [Custom Installers](/cn-introduction/articles/custom-installers.md) Modify the way certain types of packages are installed -- Handling Private Packages With Satis +- [Handling Private Packages With Satis](/cn-introduction/articles/handling-private-packages-with-satis.md) Host your own composer repository -- Plugins +- [Plugins](/cn-introduction/articles/plugins.md) Modify and extend Composer's functionality -- Scripts +- [Scripts](/cn-introduction/articles/scripts.md) Script are callbacks that are called before/after installing packages -- Troubleshooting +- [Troubleshooting](/cn-introduction/articles/troubleshooting.md) Solving problems -- Vendor Binaries +- [Vendor Binaries](/cn-introduction/articles/vendor-binaries.md) Expose command-line scripts from packages ## FAQs -- 2.46.2 From a3690933bc7dfe038e1720310979e458ef619642 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 1 Jan 2014 23:50:23 +0800 Subject: [PATCH 007/125] update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c0bae4c..4a5eb92 100644 --- a/README.md +++ b/README.md @@ -35,10 +35,10 @@ Expose command-line scripts from packages - [Why Are Version Constraints Combining Comparisons And Wildcards A Bad Idea](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) - [Why Can't Composer Load Repositories Recursively](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) -## PDF Docs +## PDF 文档 -The whole documentation is also available as a [PDF download](http://getcomposer.org/book.pdf). +整个文档也可以作为 [PDF 下载](http://getcomposer.org/book.pdf)。 -## API Docs +## API 文档 -If you need to work with composer as a library you may also want to check out the [API Docs](http://getcomposer.org/apidoc/master/index.html) \ No newline at end of file +如果你需要在工作中使用 composer 作为库的管理，你或许也想看看 [API 文档](http://getcomposer.org/apidoc/master/index.html)。 \ No newline at end of file -- 2.46.2 From 70039ecb0731e7725542c25d6356914ef2a91fd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 07:29:18 +0800 Subject: [PATCH 008/125] updata README.md --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4a5eb92..730e607 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ composer-doc-cn Composer 中文文档 ## Book -- [简介](#/cn-introduction/00-intro.md) -- [基本用法](#/cn-introduction/01-basic-usage.md) -- [库](#/cn-introduction/02-libraries.md) -- [命令行](#/cn-introduction/03-cli.md) -- [Schema](#/cn-introduction/04-schema.md) -- [Repositories](#/cn-introduction/05-repositories.md) -- [Community](#/cn-introduction/06-community.md) +- [简介](/cn-introduction/00-intro.md) +- [基本用法](/cn-introduction/01-basic-usage.md) +- [库](/cn-introduction/02-libraries.md) +- [命令行](/cn-introduction/03-cli.md) +- [Schema](/cn-introduction/04-schema.md) +- [Repositories](/cn-introduction/05-repositories.md) +- [Community](/cn-introduction/06-community.md) ## Articles - [Aliases](/cn-introduction/articles/aliases.md) -- 2.46.2 From b0dd26e6e04e48a3e18020408812f37f2659ca74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 08:31:48 +0800 Subject: [PATCH 009/125] update cn-introduction/02-libraries.md --- cn-introduction/02-libraries.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index 2742806..3da359d 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -1,16 +1,12 @@ -# Libraries +# 库 -This chapter will tell you how to make your library installable through Composer. +本章将告诉你如何通过 Composer 来安装你的库。 -## Every project is a package +## 每一个项目都是一个包 -As soon as you have a `composer.json` in a directory, that directory is a -package. When you add a `require` to a project, you are making a package that -depends on other packages. The only difference between your project and -libraries is that your project is a package without a name. +只要你有一个 `composer.json` 文件在目录中，那么整个目录就是一个包。当你添加一个 `require` 到项目中，你就是在创建一个依赖于其它库的包。你的项目和库之间唯一的区别是，你的项目是一个没有名字的包。 -In order to make that package installable you need to give it a name. You do -this by adding a `name` to `composer.json`: +为了使它成为一个可安装的包，你需要给它一个名称。你可以通过 `composer.json` 中的 `name` 来定义： { "name": "acme/hello-world", @@ -19,18 +15,15 @@ this by adding a `name` to `composer.json`: } } -In this case the project name is `acme/hello-world`, where `acme` is the -vendor name. Supplying a vendor name is mandatory. +在这种情况下项目的名称为 `acme/hello-world`，其中 `acme` 是供应商的名称。供应商的名称是必须填写的。 -> **Note:** If you don't know what to use as a vendor name, your GitHub -username is usually a good bet. While package names are case insensitive, the -convention is all lowercase and dashes for word separation. +> **注意：** 如果你不知道拿什么作为供应商的名称， +> 那么使用你 github 上的用户名通常是不错的选择。 +> 虽然包名不区分大小写，但惯例是使用小写字母，并用连字符作为单词的分隔。 ## Platform packages -Composer has platform packages, which are virtual packages for things that are -installed on the system but are not actually installable by Composer. This -includes PHP itself, PHP extensions and some system libraries. +Composer has platform packages, which are virtual packages for things that are installed on the system but are not actually installable by Composer. 这包括PHP本身，PHP扩展和一些系统库。 * `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 -- 2.46.2 From e8f486619c0ce20a485b2400e1b502bf83caec82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 09:05:45 +0800 Subject: [PATCH 010/125] update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 730e607..37e4144 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ composer-doc-cn Composer 中文文档 +--- + ## Book - [简介](/cn-introduction/00-intro.md) - [基本用法](/cn-introduction/01-basic-usage.md) -- 2.46.2 From 0d8d6c8161414ee96b72519204708683470fc691 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 16:03:44 +0800 Subject: [PATCH 011/125] update cn-introduction/02-libraries.md --- cn-introduction/02-libraries.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index 3da359d..400e1a0 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -21,25 +21,17 @@ > 那么使用你 github 上的用户名通常是不错的选择。 > 虽然包名不区分大小写，但惯例是使用小写字母，并用连字符作为单词的分隔。 -## Platform packages +## 平台软件包 -Composer has platform packages, which are virtual packages for things that are installed on the system but are not actually installable by Composer. 这包括PHP本身，PHP扩展和一些系统库。 +Composer 将那些已经安装在系统上，但并不是由 Composer 安装的包视为一个虚拟的平台软件包。这包括PHP本身，PHP扩展和一些系统库。 -* `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. +* `php` 表示用户的 PHP 版本要求，你可以对其做出限制。例如 `>=5.4.0`。如果需要64位版本的 PHP，你可以使用 `php-64bit` 进行限制。 -* `ext-` allows you to require PHP extensions (includes core - extensions). Versioning can be quite inconsistent here, so it's often - a good idea to just set the constraint to `*`. An example of an extension - package name is `ext-gd`. +* `ext-` 可以帮你指定需要的 PHP 扩展（包括核心扩展）。通常 PHP 拓展的版本可以是不一致的，将它们的版本约束为 `*` 是一个不错的主意。一个 PHP 扩展包的例子：包名可以写成 `ext-gd`。 -* `lib-` allows constraints to be made on versions of libraries used by - PHP. The following are available: `curl`, `iconv`, `libxml`, `openssl`, - `pcre`, `uuid`, `xsl`. +* `lib-` 允许对 PHP 库的版本进行限制。以下是可供使用的名称：`curl`、`iconv`、`libxml`、`openssl`、`pcre`、`uuid`、`xsl`。 -You can use `composer show --platform` to get a list of your locally available -platform packages. +你可以使用 `composer show --platform` 命令来获取可用的平台软件包的列表。 ## Specifying the version -- 2.46.2 From d14cc2527a88d292766cb9a7d4b714eeea362002 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 16:49:57 +0800 Subject: [PATCH 012/125] update cn-introduction/02-libraries.md --- cn-introduction/02-libraries.md | 32 ++++++++++++-------------------- 1 file changed, 12 insertions(+), 20 deletions(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index 400e1a0..7654655 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -33,32 +33,24 @@ Composer 将那些已经安装在系统上，但并不是由 Composer 安装的 你可以使用 `composer show --platform` 命令来获取可用的平台软件包的列表。 -## Specifying the version +## 指明版本 -You need to specify the package's version some way. When you publish your -package on Packagist, it is able to infer the version from the VCS (git, svn, -hg) information, so in that case you do not have to specify it, and it is -recommended not to. See [tags](#tags) and [branches](#branches) to see how -version numbers are extracted from these. +你需要一些方法来指明自己开发的包的版本，当你在 Packagist 上发布自己的包，它能够从 VCS (git, svn, +hg) 的信息推断出包的版本，因此你不必手动指明版本号，并且也不建议这样做。请查看 [标签](#标签) 和 [分支](#分支) 来了解版本号是如何被提取的。 -If you are creating packages by hand and really have to specify it explicitly, -you can just add a `version` field: +如果你想要手动创建并且真的要明确指定它，你只需要添加一个 `version` 字段： { "version": "1.0.0" } -> **Note:** You should avoid specifying the version field explicitly, because -> for tags the value must match the tag name. +> **注意：** 你应该尽量避免手动设置版本号，因为标签的值必须与标签名相匹配。 -### Tags +### 标签 -For every tag that looks like a version, a package version of that tag will be -created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix -of `-patch`, `-alpha`, `-beta` or `-RC`. The suffixes can also be followed by -a number. +对于每一个看起来像版本号的标签，都会相应的创建一个包的版本。它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式，`-patch`、`-alpha`、`-beta` 或 `-RC` 这些后缀是可选的。在后缀之后也可以再跟上一个数字。 -Here are a few examples of valid tag names: +下面是有效的标签名称的几个例子： 1.0.0 v1.0.0 @@ -67,11 +59,11 @@ Here are a few examples of valid tag names: v2.0.0-alpha v2.0.4-p1 -> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions) -> in a `require` statement has to be specified without prefix -> (e.g. tag `v1.0.0` will result in version `1.0.0`). +> **注意：** 即使你的标签带有前缀 `v`， +> 由于在需要 `require` 一个[版本的约束](01-basic-usage.md#包版本)时是不允许这种前缀的， +> 因此 `v` 将被省略（例如标签 `V1.0.0` 将创建 `1.0.0` 版本）。 -### Branches +### 分支 For every branch, a package development version will be created. If the branch name looks like a version, the version will be `{branchname}-dev`. For example -- 2.46.2 From e176b613257666a98ed2c64a098294a584544ff1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 17:19:47 +0800 Subject: [PATCH 013/125] update cn-introduction/02-libraries.md --- cn-introduction/02-libraries.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index 7654655..e64c8a2 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -65,23 +65,16 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 ### 分支 -For every branch, a package development version will be created. If the branch -name looks like a version, the version will be `{branchname}-dev`. For example -a branch `2.0` will get a version `2.0.x-dev` (the `.x` is added for technical -reasons, to make sure it is recognized as a branch, a `2.0.x` branch would also -be valid and be turned into `2.0.x-dev` as well. If the branch does not look -like a version, it will be `dev-{branchname}`. `master` results in a -`dev-master` version. +对于每一个分支，都会相应的创建一个包的开发版本。如果分支名看起来像一个版本号，那么将创建一个如同 `{分支名}-dev` 的包版本号。例如一个分支 `2.0` 将产生一个 `2.0.x-dev` 包版本（加入了 `.x` 是出于技术的原因，以确保它被识别为一个分支，而 `2.0.x` 的分支名称也是允许的，它同样会被转换为 `2.0.x-dev`）。如果分支名看起来不像一个版本号，它将会创建 `dev-{分支名}` 形式的版本号。例如 `master` 将产生一个 `dev-master` 的版本号。 -Here are some examples of version branch names: +下面是版本分支名称的一些示例： 1.x - 1.0 (equals 1.0.x) + 1.0 (等同于 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 -> for more details. +> **注意：** 当你安装一个新的版本时，将会自动从它 `source` 中拉取。 +> 详细请查看 [`install`](03-cli.md#install) 命令。 ### Aliases -- 2.46.2 From c8b823ab1031feb6b20b149b85456d8bf87bc4e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 19:21:18 +0800 Subject: [PATCH 014/125] update cn-introduction/02-libraries.md --- cn-introduction/02-libraries.md | 45 ++++++++++----------------------- 1 file changed, 13 insertions(+), 32 deletions(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index e64c8a2..d3a7b10 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -76,36 +76,23 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 > **注意：** 当你安装一个新的版本时，将会自动从它 `source` 中拉取。 > 详细请查看 [`install`](03-cli.md#install) 命令。 -### Aliases +### 别名 -It is possible to alias branch names to versions. For example, you could alias -`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all -the packages. +它表示一个包版本的别名。例如，你可以为 `dev-master` 设置别名 `1.0.x-dev`，这样就可以通过 require `1.0.x-dev` 来得到 `dev-master` 版本的包。 -See [Aliases](articles/aliases.md) for more information. +详细请查看[“别名”](articles/aliases.md)。 -## Lock file +## 锁文件 -For your library you may commit the `composer.lock` file if you want to. This -can help your team to always test against the same dependency versions. -However, this lock file will not have any effect on other projects that depend -on it. It only has an effect on the main project. +如果你愿意，可以在你的项目中提交 `composer.lock` 文件。他将帮助你的团队始终针对同一个依赖版本进行测试。任何时候，这个锁文件都只对于你的项目产生影响。 -If you do not want to commit the lock file and you are using git, add it to -the `.gitignore`. +如果你不想提交锁文件，并且你正在使用 Git，那么请将它添加到 `.gitignore` 文件中。 -## Publishing to a VCS +## 发布到 VCS（线上版本控制系统） -Once you have a vcs repository (version control system, e.g. git) containing a -`composer.json` file, your library is already composer-installable. In this -example we will publish the `acme/hello-world` library on GitHub under -`github.com/username/hello-world`. +一旦你有一个包含 `composer.json` 文件的库存储在线上版本控制系统（例如：Git），你的库就可以被 Composer 所安装。在这个例子中，我们将 `acme/hello-world` 库发布在 GitHub 上的 `github.com/username/hello-world` 中。 -Now, to test installing the `acme/hello-world` package, we create a new -project locally. We will call it `acme/blog`. This blog will depend on -`acme/hello-world`, which in turn depends on `monolog/monolog`. We can -accomplish this by creating a new `blog` directory somewhere, containing a -`composer.json`: +现在测试这个 `acme/hello-world` 包，我们在本地创建一个新的项目。我们将它命名为 `acme/blog`。此博客将依赖 `acme/hello-world`，而后者又依赖 `monolog/monolog`。我们可以在某处创建一个新的 `blog` 文件夹来完成它，并且需要包含 `composer.json` 文件： { "name": "acme/blog", @@ -114,13 +101,9 @@ accomplish this by creating a new `blog` directory somewhere, containing a } } -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 -described. +在这个例子中 `name` 不是必须的，因为我们并不想将它发布为一个库。在这里为 `composer.json` 文件添加描述。 -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`: +现在我们需要告诉我们的应用，在哪里可以找到 `hello-world` 的依赖。为此我们需要在 `composer.json` 中添加 `repositories` 来源申明： { "name": "acme/blog", @@ -135,11 +118,9 @@ We do this by adding a package repository specification to the blog's } } -For more details on how package repositories work and what other types are -available, see [Repositories](05-repositories.md). +更多关于包的来源是如何工作的，以及还有什么其他的类型可供选择，请查看[来源](05-repositories.md)。 -That's all. You can now install the dependencies by running Composer's -`install` command! +这就是全部了。你现在可以使用 Composer 的 `install` 命令来安装你的依赖关系了！ **Recap:** Any git/svn/hg repository containing a `composer.json` can be added to your project by specifying the package repository and declaring the -- 2.46.2 From 78395fb0f1013a4635e29e35fdd44d4beaf09ee5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 20:00:31 +0800 Subject: [PATCH 015/125] update cn-introduction/02-libraries.md --- cn-introduction/02-libraries.md | 43 ++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index d3a7b10..86c13d8 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -2,6 +2,21 @@ 本章将告诉你如何通过 Composer 来安装你的库。 +--- + +- [库](#库) + - [每一个项目都是一个包](#每一个项目都是一个包) + - [平台软件包](#平台软件包) + - [指明版本](#指明版本) + - [标签](#标签) + - [分支](#分支) + - [别名](#别名) + - [锁文件](#锁文件) + - [发布到 VCS（线上版本控制系统）](#发布到-VCS-线上版本控制系统) + - [发布到 packagist](#发布到-packagist) + +--- + ## 每一个项目都是一个包 只要你有一个 `composer.json` 文件在目录中，那么整个目录就是一个包。当你添加一个 `require` 到项目中，你就是在创建一个依赖于其它库的包。你的项目和库之间唯一的区别是，你的项目是一个没有名字的包。 @@ -122,29 +137,19 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 这就是全部了。你现在可以使用 Composer 的 `install` 命令来安装你的依赖关系了！ -**Recap:** Any git/svn/hg repository containing a `composer.json` can be added -to your project by specifying the package repository and declaring the -dependency in the `require` field. +**小结：** 任何含有 `composer.json` 的 `GIT`、`SVN`、`HG` 存储库，都可以通过 `require` 字段指定“包来源”和“声明依赖”来添加到你的项目中。 -## Publishing to packagist +## 发布到 packagist -Alright, so now you can publish packages. But specifying the vcs repository -every time is cumbersome. You don't want to force all your users to do that. +好的，你现在可以发布你的包了，但你不会希望你的用户每次都这样繁琐的指定包的来源。 -The other thing that you may have noticed is that we did not specify a package -repository for `monolog/monolog`. How did that work? The answer is packagist. +你可能注意到了另一件事，我们并没有指定 `monolog/monolog` 的来源。它是怎么工作的？答案是 packagist。 -[Packagist](https://packagist.org/) is the main package repository for -Composer, and it is enabled by default. Anything that is published on -packagist is available automatically through Composer. Since monolog -[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend -on it without having to specify any additional repositories. +[Packagist](https://packagist.org/) 是 Composer 主要的一个包信息存储库，它默认是启用的。任何在 packagist 上发布的包都可以直接被 Composer 使用。就像 monolog +它被 [发布在 packagist 上](https://packagist.org/packages/monolog/monolog)，我们可以直接使用它，而不必指定任何额外的来源信息。 -If we wanted to share `hello-world` with the world, we would publish it on -packagist as well. Doing so is really easy. +如果我们想与世界分享我们的 `hello-world`，我们最好将它发布到 packagist 上。这样做是很容易的。 -You simply hit the big "Submit Package" button and sign up. Then you submit -the URL to your VCS repository, at which point packagist will start crawling -it. Once it is done, your package will be available to anyone. +你只需要点击那个大大的 "Submit Package" 按钮并注册。接着提交你库的来源地址，此时 packagist 就开始了抓取。一旦完成，你的包将可以提供给任何人使用。 -← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) → +← [基本用法](01-basic-usage.md) | [命令行](03-cli.md) → -- 2.46.2 From ed9252d8e83ed2b4e74d52a67bef72fb64016b09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 20:07:06 +0800 Subject: [PATCH 016/125] update cn-introduction/02-libraries.md --- cn-introduction/02-libraries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index 86c13d8..bd100d3 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -12,7 +12,7 @@ - [分支](#分支) - [别名](#别名) - [锁文件](#锁文件) - - [发布到 VCS（线上版本控制系统）](#发布到-VCS-线上版本控制系统) + - [发布到 VCS（线上版本控制系统）](#发布到-VCS线上版本控制系统) - [发布到 packagist](#发布到-packagist) --- -- 2.46.2 From d0d1e52089d7a877bfc5538d25cb8afe9c2f0352 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 20:11:08 +0800 Subject: [PATCH 017/125] Update 02-libraries.md --- cn-introduction/02-libraries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index bd100d3..7e9ece2 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -12,7 +12,7 @@ - [分支](#分支) - [别名](#别名) - [锁文件](#锁文件) - - [发布到 VCS（线上版本控制系统）](#发布到-VCS线上版本控制系统) + - [发布到 VCS（线上版本控制系统）](#发布到-vcs线上版本控制系统) - [发布到 packagist](#发布到-packagist) --- -- 2.46.2 From 2d79cbfec40d57a746ad7d17de32408994e73a27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 20:50:56 +0800 Subject: [PATCH 018/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 84539b4..28e9944 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -1,17 +1,17 @@ -# Command-line interface +# 命令行 -You've already learned how to use the command-line interface to do some -things. This chapter documents all the available commands. +你已经学会了如何使用命令行界面做一些事情。本章将向你介绍所有可用的命令。 -To get help from the command-line, simply call `composer` or `composer list` -to see the complete list of commands, then `--help` combined with any of those -can give you more information. +为了从命令行获得帮助信息，请运行 `composer` 或者 `composer list` 命令，然后结合 `--help` 命令来获得更多的帮助信息。 -## Global Options +## 全局选项 -The following options are available with every command: +下列选项可与每一个命令结合使用： -* **--verbose (-v):** Increase verbosity of messages. +* **--verbose (-v):** 增加反馈信息的详细度， + * -v 表示正常输出 + * -vv 表示更详细的输出 + * -vvv 则是为了 debug * **--help (-h):** Display help information. * **--quiet (-q):** Do not output any message. * **--no-interaction (-n):** Do not ask any interactive question. -- 2.46.2 From 72853b4ee4769fbb0e324d5bf0f69e1b1c05ae07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 2 Jan 2014 21:28:48 +0800 Subject: [PATCH 019/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 70 ++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 37 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 28e9944..18e77b0 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -8,48 +8,44 @@ 下列选项可与每一个命令结合使用： -* **--verbose (-v):** 增加反馈信息的详细度， - * -v 表示正常输出 - * -vv 表示更详细的输出 - * -vvv 则是为了 debug -* **--help (-h):** Display help information. -* **--quiet (-q):** Do not output any message. -* **--no-interaction (-n):** Do not ask any interactive question. -* **--working-dir (-d):** If specified, use the given directory as working directory. -* **--profile:** Display timing and memory usage information -* **--ansi:** Force ANSI output. -* **--no-ansi:** Disable ANSI output. -* **--version (-V):** Display this application version. +* **--verbose (-v):** 增加反馈信息的详细度。 + * -v 表示正常输出。 + * -vv 表示更详细的输出。 + * -vvv 则是为了 debug。 +* **--help (-h):** 显示帮助信息。 +* **--quiet (-q):** 禁止输出任何信息。 +* **--no-interaction (-n):** 不要询问任何交互问题。 +* **--working-dir (-d):** 如果指定的话，使用给定的目录作为工作目录。 +* **--profile:** 显示时间和内存使用信息。 +* **--ansi:** 强制 ANSI 输出。 +* **--no-ansi:** 关闭 ANSI 输出。 +* **--version (-V):** 显示当前应用程序的版本信息。 -## Process Exit Codes +## 进程退出代码 -* **0:** OK -* **1:** Generic/unknown error code -* **2:** Dependency solving error code +* **0:** 正常 +* **1:** 通用/未知错误 +* **2:** 依赖关系处理错误 -## init +## 初始化 `init` -In the [Libraries](02-libraries.md) chapter we looked at how to create a -`composer.json` by hand. There is also an `init` command available that makes -it a bit easier to do this. +在 [“库”](02-libraries.md) 那一章我们看到了如何手动创建 `composer.json` 文件。实际上还有一个 `init` 命令可以更容易的做到这一点。 -When you run the command it will interactively ask you to fill in the fields, -while using some smart defaults. +当您运行该命令，它会以交互方式要求您填写一些信息，同时聪明的使用一些默认值。 $ php composer.phar init -### Options +### 初始化选项 -* **--name:** Name of the package. -* **--description:** Description of the package. -* **--author:** Author name of the package. -* **--homepage:** Homepage of the package. -* **--require:** Package to require with a version constraint. Should be - in format `foo/bar:1.0.0`. -* **--require-dev:** Development requirements, see **--require**. -* **--stability (-s):** Value for the `minimum-stability` field. +* **--name:** 包的名称。 +* **--description:** 包的描述。 +* **--author:** 包的作者。 +* **--homepage:** 包的主页。 +* **--require:** 需要依赖的其它包，必须要有一个版本约束。并且应该遵循 `foo/bar:1.0.0` 这样的格式。 +* **--require-dev:** 开发版的依赖包，内容格式与 **--require** 相同。 +* **--stability (-s):** `minimum-stability` 字段的值。 -## install +## 安装 `install` The `install` command reads the `composer.json` file from the current directory, resolves the dependencies, and installs them into `vendor`. @@ -63,7 +59,7 @@ everyone using the library will get the same versions of the dependencies. If there is no `composer.lock` file, composer will create one after dependency resolution. -### Options +### 安装选项 * **--prefer-source:** There are two ways of downloading a package: `source` and `dist`. For stable versions composer will use the `dist` by default. @@ -89,7 +85,7 @@ resolution. autoloader. This is recommended especially for production, but can take a bit of time to run so it is currently not done by default. -## update +## 更新 `update` In order to get the latest versions of the dependencies and to update the `composer.lock` file, you should use the `update` command. @@ -107,7 +103,7 @@ You can also use wildcards to update a bunch of packages at once: $ php composer.phar update vendor/* -### Options +### 更新选项 * **--prefer-source:** Install packages from `source` when available. * **--prefer-dist:** Install packages from `dist` when available. @@ -126,7 +122,7 @@ You can also use wildcards to update a bunch of packages at once: * **--with-dependencies** Add also all dependencies of whitelisted packages to the whitelist. So all packages with their dependencies are updated recursively. -## require +## 申明依赖 `require` The `require` command adds new packages to the `composer.json` file from the current directory. @@ -141,7 +137,7 @@ to the command. $ php composer.phar require vendor/package:2.* vendor/package2:dev-master -### Options +### 申明依赖的选项 * **--prefer-source:** Install packages from `source` when available. * **--prefer-dist:** Install packages from `dist` when available. -- 2.46.2 From 77a54e40b01d6f776f5244e07ff4adf088c9d41c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 3 Jan 2014 08:57:46 +0800 Subject: [PATCH 020/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 18e77b0..d14aef7 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -47,31 +47,19 @@ ## 安装 `install` -The `install` command reads the `composer.json` file from the current -directory, resolves the dependencies, and installs them into `vendor`. +`install` 命令从当前目录读取 `composer.json` 文件，处理了依赖关系，并把其安装到 `vendor` 目录下。 $ 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 -everyone using the library will get the same versions of the dependencies. +如果当前目录下存在 `composer.lock` 文件，它会从此文件读取依赖版本，而不是根据 `composer.json` 文件去获取依赖。这确保了该库的每个使用者都能得到相同的依赖版本。 -If there is no `composer.lock` file, composer will create one after dependency -resolution. +如果没有 `composer.lock` 文件，composer 将在处理完依赖关系后创建它。 ### 安装选项 -* **--prefer-source:** There are two ways of downloading a package: `source` - and `dist`. For stable versions composer will use the `dist` by default. - The `source` is a version control repository. If `--prefer-source` is - enabled, composer will install from `source` if there is one. This is - useful if you want to make a bugfix to a project and get a local git - clone of the dependency directly. -* **--prefer-dist:** Reverse of `--prefer-source`, composer will install - from `dist` if possible. This can speed up installs substantially on build - servers and other use cases where you typically do not run updates of the - vendors. It is also a way to circumvent problems with git if you do not - have a proper setup. +* **--prefer-source:** 下载包的方式有两种： `source` + 和 `dist`。对于稳定版本 composer 将默认使用 `dist` 方式。而 `source` 表示版本控制源 。如果 `--prefer-source` 是被启用的，composer 将从 `source` 安装（如果有的话）。如果想要使用一个 bugfix 到你的项目，这是非常有用的。并且可以直接从本地的版本库直接获取依赖关系。 +* **--prefer-dist:** 与 `--prefer-source` 相反，composer 将尽可能的从 `dist` 获取，这将大幅度的加快在 build servers 上的安装。这也是一个回避 git 问题的途径，如果你清楚任何正确的设置。 * **--dry-run:** If you want to run through an installation without actually installing a package, you can use `--dry-run`. This will simulate the installation and show you what would happen. -- 2.46.2 From 14f4edf8af80959d1dd9ade25692a8e88b83a7e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 3 Jan 2014 15:23:59 +0800 Subject: [PATCH 021/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 78 ++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 47 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index d14aef7..feb0085 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -59,80 +59,64 @@ * **--prefer-source:** 下载包的方式有两种： `source` 和 `dist`。对于稳定版本 composer 将默认使用 `dist` 方式。而 `source` 表示版本控制源 。如果 `--prefer-source` 是被启用的，composer 将从 `source` 安装（如果有的话）。如果想要使用一个 bugfix 到你的项目，这是非常有用的。并且可以直接从本地的版本库直接获取依赖关系。 -* **--prefer-dist:** 与 `--prefer-source` 相反，composer 将尽可能的从 `dist` 获取，这将大幅度的加快在 build servers 上的安装。这也是一个回避 git 问题的途径，如果你清楚任何正确的设置。 -* **--dry-run:** If you want to run through an installation without actually - installing a package, you can use `--dry-run`. This will simulate the - installation and show you what would happen. -* **--dev:** Install packages listed in `require-dev` (this is the default behavior). -* **--no-dev:** Skip installing packages listed in `require-dev`. -* **--no-scripts:** Skips execution of scripts defined in `composer.json`. -* **--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 - autoloader. This is recommended especially for production, but can take - a bit of time to run so it is currently not done by default. +* **--prefer-dist:** 与 `--prefer-source` 相反，composer 将尽可能的从 `dist` 获取，这将大幅度的加快在 build servers 上的安装。这也是一个回避 git 问题的途径，如果你不清楚如何正确的设置。 +* **--dry-run:** 如果你只是想演示而并非实际安装一个包，你可以运行 `--dry-run` 命令，它将模拟安装并显示将会发生什么。 +* **--dev:** 安装 `require-dev` 字段中列出的包（这是一个默认值）。 +* **--no-dev:** 跳过 `require-dev` 字段中列出的包。 +* **--no-scripts:** 跳过 `composer.json` 文件中定义的脚本。 +* **--no-plugins:** 关闭 plugins。 +* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 +* **--optimize-autoloader (-o):** 转换 PSR-0 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。 ## 更新 `update` -In order to get the latest versions of the dependencies and to update the -`composer.lock` file, you should use the `update` command. +为了获取依赖的最新版本，并且升级 `composer.lock` 文件，你应该使用 `update` 命令。 $ php composer.phar update -This will resolve all dependencies of the project and write the exact versions -into `composer.lock`. +这将解决项目的所有依赖，并将确切的版本号写入 `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 -You can also use wildcards to update a bunch of packages at once: +你还可以使用通配符进行批量更新： $ php composer.phar update vendor/* ### 更新选项 -* **--prefer-source:** Install packages from `source` when available. -* **--prefer-dist:** Install packages from `dist` when available. -* **--dry-run:** Simulate the command without actually doing anything. -* **--dev:** Install packages listed in `require-dev` (this is the default behavior). -* **--no-dev:** Skip installing packages listed in `require-dev`. -* **--no-scripts:** Skips execution of scripts defined in `composer.json`. -* **--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 - 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 - lock file being out of date. -* **--with-dependencies** Add also all dependencies of whitelisted packages to the whitelist. - So all packages with their dependencies are updated recursively. +* **--prefer-source:** 当有可用的包时，从 `source` 安装。 +* **--prefer-dist:** 当有可用的包时，从 `dist` 安装。 +* **--dry-run:** 模拟命令，并没有做实际的操作。 +* **--dev:** 安装 `require-dev` 字段中列出的包（这是一个默认值）。 +* **--no-dev:** 跳过 `require-dev` 字段中列出的包。 +* **--no-scripts:** 跳过 `composer.json` 文件中定义的脚本。 +* **--no-plugins:** 关闭 plugins。 +* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 +* **--optimize-autoloader (-o):** 转换 PSR-0 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。 +* **--lock:** 仅更新 lock 文件的 hash，取消有关 lock 文件过时的警告。 +* **--with-dependencies** 同时更新白名单内包的依赖关系，这将进行递归更新。 ## 申明依赖 `require` -The `require` command adds new packages to the `composer.json` file from -the current directory. +`require` 命令增加新的依赖包到当前目录的 `composer.json` 文件中。 $ php composer.phar require -After adding/changing the requirements, the modified requirements will be -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 ### 申明依赖的选项 -* **--prefer-source:** Install packages from `source` when available. -* **--prefer-dist:** Install packages from `dist` when available. -* **--dev:** Add packages to `require-dev`. -* **--no-update:** Disables the automatic update of the dependencies. -* **--no-progress:** Removes the progress display that can mess with some - terminals or scripts which don't handle backspace characters. +* **--prefer-source:** 当有可用的包时，从 `source` 安装。 +* **--prefer-dist:** 当有可用的包时，从 `dist` 安装。 +* **--dev:** 安装 `require-dev` 字段中列出的包。 +* **--no-update:** 禁用依赖关系的自动更新。 +* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 ## global -- 2.46.2 From 9486f4984d3627b36f4553c8ead7cbeac367317f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 3 Jan 2014 17:47:30 +0800 Subject: [PATCH 022/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 73 ++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 44 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index feb0085..2ac2c8b 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -4,9 +4,9 @@ 为了从命令行获得帮助信息，请运行 `composer` 或者 `composer list` 命令，然后结合 `--help` 命令来获得更多的帮助信息。 -## 全局选项 +## 全局参数 -下列选项可与每一个命令结合使用： +下列参数可与每一个命令结合使用： * **--verbose (-v):** 增加反馈信息的详细度。 * -v 表示正常输出。 @@ -35,7 +35,7 @@ $ php composer.phar init -### 初始化选项 +### 初始化参数 * **--name:** 包的名称。 * **--description:** 包的描述。 @@ -55,7 +55,7 @@ 如果没有 `composer.lock` 文件，composer 将在处理完依赖关系后创建它。 -### 安装选项 +### 安装参数 * **--prefer-source:** 下载包的方式有两种： `source` 和 `dist`。对于稳定版本 composer 将默认使用 `dist` 方式。而 `source` 表示版本控制源 。如果 `--prefer-source` 是被启用的，composer 将从 `source` 安装（如果有的话）。如果想要使用一个 bugfix 到你的项目，这是非常有用的。并且可以直接从本地的版本库直接获取依赖关系。 @@ -84,7 +84,7 @@ $ php composer.phar update vendor/* -### 更新选项 +### 更新参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 * **--prefer-dist:** 当有可用的包时，从 `dist` 安装。 @@ -110,7 +110,7 @@ $ php composer.phar require vendor/package:2.* vendor/package2:dev-master -### 申明依赖的选项 +### 申明依赖的参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 * **--prefer-dist:** 当有可用的包时，从 `dist` 安装。 @@ -118,46 +118,37 @@ * **--no-update:** 禁用依赖关系的自动更新。 * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 -## global +## 全局执行 `global` -The global command allows you to run other commands like `install`, `require` -or `update` as if you were running them from the [COMPOSER_HOME](#composer-home) -directory. +`global` 命令允许你在 [COMPOSER_HOME](#composer-home) 目录下执行其它命令，像 `install`、`require` 或 `update`。 -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: +并且如果你将 `$COMPOSER_HOME/vendor/bin` 加入到了 `$PATH` 环境变量中，你就可以用它在命令行中安装全局应用，下面是一个例子： $ 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-cs-fixer` 就可以在全局范围使用了（假设你已经设置了你的 PATH）。如果稍后你想更新它，你只需要运行 `global update`： $ php composer.phar global update -## search +## 搜索 `search` -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. +`search` 命令允许你为当前项目搜索依赖包，通常它只搜索 packagist.org 上的包，你可以简单的输入你的搜索条件。 $ php composer.phar search monolog -You can also search for more than one term by passing multiple arguments. +您也可以通过传递多个参数来进行多条件搜索。 -### Options +### 搜索参数 -* **--only-name (-N):** Search only in name. +* **--only-name (-N):** 仅针对指定的名称搜索（完全匹配）。 -## show +## 展示 `show` -To list all of the available packages, you can use the `show` command. +列出所有可用的软件包，你可以使用 `show` 命令。 $ 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 @@ -176,22 +167,19 @@ name. 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 -### Options +### 展示的参数 -* **--installed (-i):** List the packages that are installed. -* **--platform (-p):** List only platform packages (php & extensions). -* **--self (-s):** List the root package info. +* **--installed (-i):** 列出已安装的依赖包。 +* **--platform (-p):** 仅列出平台软件包（PHP 与它的扩展）。 +* **--self (-s):** 仅列出当前项目信息。 -## depends +## 依赖性检测 `depends` -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. +`depends` 命令可以查出已安装在你项目中的某个包，是否正在被其它的包所依赖，并列出他们。 $ php composer.phar depends --link-type=require monolog/monolog @@ -201,16 +189,13 @@ should be included in the listing. By default both are used. symfony/monolog-bridge symfony/symfony -### Options +### 依赖性检测的参数 -* **--link-type:** The link types to match on, can be specified multiple - times. +* **--link-type:** 检测的类型，默认为 `require` 也可以是 `require-dev`。 -## validate +## 有效性检测 `validate` -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. +在提交 `composer.json` 文件，和创建 tag 前，你应该始终运行 `validate` 命令。它将检测你的 `composer.json` 文件是否是有效的 $ php composer.phar validate -- 2.46.2 From b48c620b9662d60d0e2d4c73395dc3a7da161a3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 3 Jan 2014 23:12:55 +0800 Subject: [PATCH 023/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 2ac2c8b..f24c619 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -199,16 +199,13 @@ $ php composer.phar validate -## status +## 依赖包状态检测 `status` -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. +如果你经常修改依赖包里的代码，并且它们是从 source（自定义源）进行安装的，那么 `status` 命令允许你进行检查，如果你有任何本地的更改它将会给予提示。 $ php composer.phar status -With the `--verbose` option you get some more information about what was -changed: +你可以使用 `--verbose` 系列参数（-v|vv|vvv）来获取更详细的详细： $ php composer.phar status -v You have changes in the following dependencies: -- 2.46.2 From 9c0f0e1ce585af59571c73a1d5dbc07c33d1decc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sat, 4 Jan 2014 08:32:06 +0800 Subject: [PATCH 024/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 95 ++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 57 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index f24c619..f14bb48 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -35,7 +35,7 @@ $ php composer.phar init -### 初始化参数 +### 初始化-参数 * **--name:** 包的名称。 * **--description:** 包的描述。 @@ -55,7 +55,7 @@ 如果没有 `composer.lock` 文件，composer 将在处理完依赖关系后创建它。 -### 安装参数 +### 安装-参数 * **--prefer-source:** 下载包的方式有两种： `source` 和 `dist`。对于稳定版本 composer 将默认使用 `dist` 方式。而 `source` 表示版本控制源 。如果 `--prefer-source` 是被启用的，composer 将从 `source` 安装（如果有的话）。如果想要使用一个 bugfix 到你的项目，这是非常有用的。并且可以直接从本地的版本库直接获取依赖关系。 @@ -84,7 +84,7 @@ $ php composer.phar update vendor/* -### 更新参数 +### 更新-参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 * **--prefer-dist:** 当有可用的包时，从 `dist` 安装。 @@ -110,7 +110,7 @@ $ php composer.phar require vendor/package:2.* vendor/package2:dev-master -### 申明依赖的参数 +### 申明依赖-参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 * **--prefer-dist:** 当有可用的包时，从 `dist` 安装。 @@ -138,7 +138,7 @@ 您也可以通过传递多个参数来进行多条件搜索。 -### 搜索参数 +### 搜索-参数 * **--only-name (-N):** 仅针对指定的名称搜索（完全匹配）。 @@ -171,7 +171,7 @@ $ php composer.phar show monolog/monolog 1.0.2 -### 展示的参数 +### 展示-参数 * **--installed (-i):** 列出已安装的依赖包。 * **--platform (-p):** 仅列出平台软件包（PHP 与它的扩展）。 @@ -189,7 +189,7 @@ symfony/monolog-bridge symfony/symfony -### 依赖性检测的参数 +### 依赖性检测-参数 * **--link-type:** 检测的类型，默认为 `require` 也可以是 `require-dev`。 @@ -212,93 +212,74 @@ vendor/seld/jsonlint: M README.mdown -## self-update +## 自我更新 `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. +将 Composer 自身升级到最新版本，只需要运行 `self-update` 命令。它将替换你的 `composer.phar` 文件到最新版本。 $ 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 -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 +如果你已经为整个系统安装 Composer（参见 [全局安装](00-intro.md#全局安装)），你可能需要在 `root` 权限下运行它： $ sudo composer self-update -### Options +### 自我更新-参数 -* **--rollback (-r):** Rollback to the last version you had installed. -* **--clean-backups:** Delete old backups during an update. This makes the current version of composer the only backup available after the update. +* **--rollback (-r):** 回滚到你已经安装的最后一个版本。 +* **--clean-backups:** 在更新过程中删除旧的备份，这使得更新过后的当前版本是唯一可用的备份。 -## config +## 更改配置 `config` -The `config` command allows you to edit some basic composer settings in either -the local composer.json file or the global config.json file. +`config` 命令允许你编辑 Composer 的一些基本设置，无论是本地的 `composer.json` 或者全局的 `config.json` 文件。 $ php composer.phar config --list -### Usage +### 更改配置-使用方法 `config [options] [setting-key] [setting-value1] ... [setting-valueN]` -`setting-key` is a configuration option name and `setting-value1` is a -configuration value. For settings that can take an array of values (like -`github-protocols`), more than one setting-value arguments are allowed. +`setting-key` 是一个配置选项的名称，`setting-value1` 是一个配置的值。可以使用数组作为配置的值（像 `github-protocols`），多个 `setting-value` 是允许的。 -See the [config schema section](04-schema.md#config) for valid configuration -options. +有效的配置选项，请查看“架构”章节的 [config](04-schema.md#config) 。 -### Options +### 更改配置-参数 -* **--global (-g):** Operate on the global config file located at -`$COMPOSER_HOME/config.json` by default. Without this option, this command -affects the local composer.json file or a file specified by `--file`. -* **--editor (-e):** Open the local composer.json file using in a text editor as -defined by the `EDITOR` env variable. With the `--global` option, this opens -the global config file. -* **--unset:** Remove the configuration element named by `setting-key`. -* **--list (-l):** Show the list of current config variables. With the `--global` - option this lists the global configuration only. -* **--file="..." (-f):** Operate on a specific file instead of composer.json. Note - that this cannot be used in conjunction with the `--global` option. +* **--global (-g):** 操作位于 `$COMPOSER_HOME/config.json` 的全局配置文件。如果不指定该参数，此命令将影响当前项目的 composer.json 文件，或 `--file` 参数所指向的文件。 +* **--editor (-e):** 使用文本编辑器打开 composer.json 文件。默认情况下始终是打开当前项目的文件。当存在 `--global` 参数时，将会打开全局 composer.json 文件。 +* **--unset:** 移除由 `setting-key` 指定名称的配置选项。 +* **--list (-l):** 显示当前配置选项的列表。当存在 `--global` 参数时，将会显示全局配置选项的列表。 +* **--file="..." (-f):** 在一个指定的文件上操作，而不是 composer.json。注意：不能与 `--global` 参数一起使用。 -### Modifying Repositories +### 修改包来源 -In addition to modifying the config section, the `config` command also supports making -changes to the repositories section by using it the following way: +除了修改配置选项， `config` 命令还支持通过以下方法修改来源信息： $ php composer.phar config repositories.foo vcs http://github.com/foo/bar -## create-project +## 创建项目 `create-project` -You can use Composer to create new projects from an existing package. This is -the equivalent of doing a git clone/svn checkout followed by a composer install -of the vendors. +你可以使用 Composer 从现有的包中创建一个新的项目。这相当于执行了一个 `git clone` 或 `svn checkout` 命令后将这个包的依赖安装到它自己的 vendor 目录。 -There are several applications for this: +此命令有几个常见的用途： -1. You can deploy application packages. -2. You can check out any package and start developing on patches for example. -3. Projects with multiple developers can use this feature to bootstrap the - initial application for development. +1. 你可以快速的部署你的应用。 +2. 你可以检出任何资源包，并开发它的补丁、用例。 +3. 多人开发项目，可以用它来加快应用的初始化。 -To create a new project using composer you can use the "create-project" command. -Pass it a package name, and the directory to create the project in. You can also -provide a version as third argument, otherwise the latest version is used. +要创建基于 Composer 的新项目，你可以使用 "create-project" 命令。传递一个包名，它会为你创建项目的目录。你也可以在第三个参数中指定版本号，否则将获取最新的版本。 -If the directory does not currently exist, it will be created during installation. +如果该目录目前不存在，则会在安装过程中自动创建。 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. +此外，你也可以无需使用这个命令，而是通过现有的 `composer.json` 文件来启动这个项目。 -By default the command checks for the packages on packagist.org. +默认情况下，这个命令会在 packagist.org 上查找你指定的包。 -### Options +### 创建项目-参数 * **--repository-url:** Provide a custom repository to search for the package, which will be used instead of packagist. Can be either an HTTP URL pointing -- 2.46.2 From 50795c53757e4678a37fda76d9116b556d7dc45f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sat, 4 Jan 2014 10:28:52 +0800 Subject: [PATCH 025/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 43 ++++++++++++++------------------------- 1 file changed, 15 insertions(+), 28 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index f14bb48..0770726 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -266,7 +266,7 @@ 此命令有几个常见的用途： 1. 你可以快速的部署你的应用。 -2. 你可以检出任何资源包，并开发它的补丁、用例。 +2. 你可以检出任何资源包，并开发它的补丁。 3. 多人开发项目，可以用它来加快应用的初始化。 要创建基于 Composer 的新项目，你可以使用 "create-project" 命令。传递一个包名，它会为你创建项目的目录。你也可以在第三个参数中指定版本号，否则将获取最新的版本。 @@ -281,37 +281,24 @@ ### 创建项目-参数 -* **--repository-url:** Provide a custom repository to search for the package, - which will be used instead of packagist. Can be either an HTTP URL pointing - to a `composer` repository, or a path to a local `packages.json` file. -* **--stability (-s):** Minimum stability of package. Defaults to `stable`. -* **--prefer-source:** Install packages from `source` when available. -* **--prefer-dist:** Install packages from `dist` when available. -* **--dev:** Install packages listed in `require-dev`. -* **--no-install:** Disables installation of the vendors. -* **--no-plugins:** Disables plugins. -* **--no-scripts:** Disables the execution of the scripts defined in the root - package. -* **--no-progress:** Removes the progress display that can mess with some - terminals or scripts which don't handle backspace characters. -* **--keep-vcs:** Skip the deletion of the VCS metadata for the created - project. This is mostly useful if you run the command in non-interactive - mode. +* **--repository-url:** 提供一个自定义的储存库来搜索包，这将被用来代替 packagist.org。可以是一个指向 `composer` 资源库的 HTTP URL，或者是指向某个 `packages.json` 文件的本地路径。 +* **--stability (-s):** 资源包的最低稳定版本，默认为 `stable`。 +* **--prefer-source:** 当有可用的包时，从 `source` 安装。 +* **--prefer-dist:** 当有可用的包时，从 `dist` 安装。 +* **--dev:** 安装 `require-dev` 字段中列出的包。 +* **--no-install:** 禁止安装包的依赖。 +* **--no-plugins:** 禁用 plugins。 +* **--no-scripts:** 禁止在根资源包中定义的脚本执行。 +* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 +* **--keep-vcs:** 创建时跳过缺失的 VCS 。如果你在非交互模式下运行创建命令，这将是非常有用的。 -## dump-autoload +## 打印自动加载索引 `dump-autoload` -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. +某些情况下你需要更新 autoloader，例如在你的包中加入了一个新的类。你可以使用 `dump-autoload` 来完成，而不必执行 `install` 或 `update` 命令。 -Additionally, it can dump an optimized autoloader that converts PSR-0 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 -performance. +此外，它可以打印一个优化过的，符合 PSR-0 规范的类的索引，这也是出于对性能的可考虑。在大型的应用中会有许多类文件，而 autoloader 会占用每个请求的很大一部分时间，使用 classmaps 或许在开发时不太方便，但它在保证性能的前提下，仍然可以获得 PSR-0 规范带来的便利。 -### Options +### 打印自动加载索引-参数 * **--optimize (-o):** Convert PSR-0 autoloading to classmap to get a faster autoloader. This is recommended especially for production, but can take -- 2.46.2 From d347a060a694e21aa301c168daaf45438a0e27b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sat, 4 Jan 2014 14:54:47 +0800 Subject: [PATCH 026/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 65 +++++++++++++-------------------------- 1 file changed, 22 insertions(+), 43 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 0770726..460d9b2 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -300,89 +300,68 @@ ### 打印自动加载索引-参数 -* **--optimize (-o):** Convert PSR-0 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. +* **--optimize (-o):** 转换 PSR-0 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。 -## licenses +## 查看许可协议 `licenses` -Lists the name, version and license of every package installed. Use -`--format=json` to get machine readable output. +列出已安装的每个包的名称、版本、许可协议。可以使用 `--format=json` 参数来获取 JSON 格式的输出。 -## run-script +## 执行脚本 `run-script` -To run [scripts](articles/scripts.md) manually you can use this command, -just give it the script name and optionally --no-dev to disable the dev mode. +你可以运行此命令来手动执行 [脚本](articles/scripts.md)，只需要指定脚本的名称，可选的 `--no-dev` 参数允许你禁用开发者模式。 ## diagnose -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. +如果你觉得发现了一个 bug 或是程序行为变得怪异，你可能需要运行 `diagnose` 命令，来帮助你检测一些常见的问题。 $ php composer.phar diagnose -## archive +## 归档 `archive` -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. +此命令用来对指定包的指定版本进行 zip/tar 归档。它也可以用来归档你的整个项目，不包括 excluded/ignored（排除/忽略）的文件。 $ php composer.phar archive vendor/package 2.0.21 --format=zip -### Options +### 归档-参数 -* **--format (-f):** Format of the resulting archive: tar or zip (default: - "tar") -* **--dir:** Write the archive to this directory (default: ".") +* **--format (-f):** 指定归档格式：tar 或 zip（默认为 tar）。 +* **--dir:** 指定归档存放的目录（默认为当前目录）。 -## help +## 获取帮助信息 `help` -To get more information about a certain command, just use `help`. +使用 `help` 可以获取指定命令的帮助信息。 $ php composer.phar help install -## Environment variables +## 环境变量 -You can set a number of environment variables that override certain settings. -Whenever possible it is recommended to specify these settings in the `config` -section of `composer.json` instead. It is worth noting that the env vars will -always take precedence over the values specified in `composer.json`. +你可以设置一些环境变量来覆盖默认的配置。建议尽可能的在 `composer.json` 的 `config` 字段中设置这些值，而不是通过命令行设置环境变量。值得注意的是环境变量中的值，将始终优先于 `composer.json` 中所指定的值。 ### COMPOSER -By setting the `COMPOSER` env variable it is possible to set the filename of -`composer.json` to something else. +环境变量 `COMPOSER` 可以为 `composer.json` 文件指定其它的文件名。 -For example: +例如： $ COMPOSER=composer-other.json php composer.phar install ### COMPOSER_ROOT_VERSION -By setting this var you can specify the version of the root package, if it can -not be guessed from VCS info and is not present in `composer.json`. +通过设置这个环境变量，你可以指定 root 包的版本，如果程序不能从 VCS 上猜测出版本号，并且未在 `composer.json` 文件中申明。 ### COMPOSER_VENDOR_DIR -By setting this var you can make composer install the dependencies into a -directory other than `vendor`. +通过设置这个环境变量，你可以指定 composer 将依赖安装在 `vendor` 以外的其它目录中。 ### COMPOSER_BIN_DIR -By setting this option you can change the `bin` ([Vendor Binaries](articles/vendor-binaries.md)) -directory to something other than `vendor/bin`. +通过设置这个环境变量，你可以指定 `bin`（[Vendor Binaries](articles/vendor-binaries.md)）目录到 `vendor/bin` 以外的其它目录。 ### http_proxy or HTTP_PROXY -If you are using composer from behind an HTTP proxy, you can use the standard -`http_proxy` or `HTTP_PROXY` env vars. Simply set it to the URL of your proxy. -Many operating systems already set this variable for you. +如果你是通过 HTTP 代理来使用 Composer，你可以使用 `http_proxy` 或 `HTTP_PROXY` 环境变量。只要简单的将它设置为代理服务器的 URL。许多操作系统已经为你的服务设置了此变量。 -Using `http_proxy` (lowercased) or even defining both might be preferable since -some tools like git or curl will only use the lower-cased `http_proxy` version. -Alternatively you can also define the git proxy using -`git config --global http.proxy `. +建议使用 `http_proxy`（小写）或者两者都进行定义。因为某些工具，像 git 或 curl 将使用 `http_proxy` 小写的版本。另外，你还可以使用 `git config --global http.proxy ` 来单独设置 git 的代理。 ### no_proxy -- 2.46.2 From 36f735621845b5caa76748d369741110c215d2b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sat, 4 Jan 2014 17:02:11 +0800 Subject: [PATCH 027/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 55 ++++++++++++++------------------------- 1 file changed, 20 insertions(+), 35 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 460d9b2..136d2bf 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -365,68 +365,53 @@ ### no_proxy -If you are behind a proxy and would like to disable it for certain domains, you -can use the `no_proxy` env var. Simply set it to a comma separated list of -domains the proxy should *not* be used for. +如果你是使用代理服务器，并且想要对某些域名禁用代理，就可以使用 `no_proxy` 环境变量。只需要输入一个逗号相隔的域名 *排除* 列表。 -The env var accepts domains, IP addresses, and IP address blocks in CIDR -notation. You can restrict the filter to a particular port (e.g. `:80`). You -can also set it to `*` to ignore the proxy for all HTTP requests. +此环境变量接受域名、IP 以及 CIDR地址块。你可以将它限制到一个端口（例如：`:80`）。你还可以把它设置为 `*` 来忽略所有的 HTTP 代理请求。 ### HTTP_PROXY_REQUEST_FULLURI -If you use a proxy but it does not support the request_fulluri flag, then you -should set this env var to `false` or `0` to prevent composer from setting the -request_fulluri option. +如果你使用了 HTTP 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。 ### HTTPS_PROXY_REQUEST_FULLURI -If you use a proxy but it does not support the request_fulluri flag for HTTPS -requests, then you should set this env var to `false` or `0` to prevent composer -from setting the request_fulluri option. +如果你使用了 HTTPS 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。 ### COMPOSER_HOME -The `COMPOSER_HOME` var allows you to change the composer home directory. This -is a hidden, global (per-user on the machine) directory that is shared between -all projects. +`COMPOSER_HOME` 环境变量允许你改变 Composer 的主目录。这是一个隐藏的、所有项目共享的全局目录（对本机的所有用户都可用）。 -By default it points to `/home//.composer` on \*nix, -`/Users//.composer` on OSX and -`C:\Users\\AppData\Roaming\Composer` on Windows. +它在各个系统上的默认值分别为： +- \*nix `/home//.composer`。 +- OSX `/Users//.composer`。 +- Windows `C:\Users\\AppData\Roaming\Composer`。 #### COMPOSER_HOME/config.json -You may put a `config.json` file into the location which `COMPOSER_HOME` points -to. Composer will merge this configuration with your project's `composer.json` -when you run the `install` and `update` commands. +你可以在 `COMPOSER_HOME` 目录中放置一个 `config.json` 文件。在你执行 `install` 和 `update` 命令时，Composer 会将它与你项目中的 `composer.json` 文件进行合并。 -This file allows you to set [configuration](04-schema.md#config) and -[repositories](05-repositories.md) for the user's projects. +该文件允许你为用户的项目设置 [配置信息](04-schema.md#config) 和 [资源地址](05-repositories.md)。 -In case global configuration matches _local_ configuration, the _local_ -configuration in the project's `composer.json` always wins. +若 _全局_ 和 _项目_ 存在相同配置项，那么项目中的 `composer.json` 文件拥有更高的优先级。 ### COMPOSER_CACHE_DIR -The `COMPOSER_CACHE_DIR` var allows you to change the composer cache directory, -which is also configurable via the [`cache-dir`](04-schema.md#config) option. +`COMPOSER_CACHE_DIR` 环境变量允许你设置 Composer 的缓存目录，这也可以通过 [`cache-dir`](04-schema.md#config) 进行配置。 -By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and -`C:\Users\\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows. +它在各个系统上的默认值分别为： +- \*nix and OSX `$COMPOSER_HOME/cache`。 +- Windows `C:\Users\\AppData\Local\Composer` 或 `%LOCALAPPDATA%/Composer`。 ### COMPOSER_PROCESS_TIMEOUT -This env var controls the time composer waits for commands (such as git -commands) to finish executing. The default value is 300 seconds (5 minutes). +这个环境变量控制着 Composer 执行命令的等待时间（例如：git 命令）。默认值为300秒（5分钟）。 ### COMPOSER_DISCARD_CHANGES -This env var controls the discard-changes [config option](04-schema.md#config). +这个环境变量控制着 discard-changes [config option](04-schema.md#config)。 ### COMPOSER_NO_INTERACTION -If set to 1, this env var will make composer behave as if you passed the -`--no-interaction` flag to every command. This can be set on build boxes/CI. +如果设置为1，这个环境变量将使 Composer 在执行每一个命令时都放弃交互，相当于对每一命令都使用了 `--no-interaction` 标签。This can be set on build boxes/CI. -← [Libraries](02-libraries.md) | [Schema](04-schema.md) → +← [库](02-libraries.md) | [架构](04-schema.md) → -- 2.46.2 From f9edbc67f0181799fd347393ae6a04e93208608d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sat, 4 Jan 2014 21:35:57 +0800 Subject: [PATCH 028/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 55 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 136d2bf..6327fc4 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -4,6 +4,59 @@ 为了从命令行获得帮助信息，请运行 `composer` 或者 `composer list` 命令，然后结合 `--help` 命令来获得更多的帮助信息。 +--- + +- [命令行](#命令行) +- [全局参数](#全局参数) + - [进程退出代码](#进程退出代码) + - [初始化 `init`](#初始化-init) - [参数](#初始化-参数) + - [安装 `install`](#安装-install) - [参数](#安装-参数) + - [更新 `update`](#更新-update) - [参数](#更新-参数) + - 申明依赖 `require` + - 申明依赖-参数 + - 全局执行 `global` + - 搜索 `search` + - 搜索-参数 + - 展示 `show` + - 展示-参数 + - 依赖性检测 `depends` + - 依赖性检测-参数 + - 有效性检测 `validate` + - 依赖包状态检测 `status` + - 自我更新 `self-update` + - 自我更新-参数 + - 更改配置 `config` + - 更改配置-使用方法 + - 更改配置-参数 + - 修改包来源 + - 创建项目 `create-project` + - 创建项目-参数 + - 打印自动加载索引 `dump-autoload` + - 打印自动加载索引-参数 + - 查看许可协议 `licenses` + - 执行脚本 `run-script` + - diagnose + - 归档 `archive` + - 归档-参数 + - 获取帮助信息 `help` + - 环境变量 + - COMPOSER + - COMPOSER_ROOT_VERSION + - COMPOSER_VENDOR_DIR + - COMPOSER_BIN_DIR + - http_proxy or HTTP_PROXY + - no_proxy + - HTTP_PROXY_REQUEST_FULLURI + - HTTPS_PROXY_REQUEST_FULLURI + - COMPOSER_HOME + - COMPOSER_HOME/config.json + - COMPOSER_CACHE_DIR + - COMPOSER_PROCESS_TIMEOUT + - COMPOSER_DISCARD_CHANGES + - COMPOSER_NO_INTERACTION + +--- + ## 全局参数 下列参数可与每一个命令结合使用： @@ -412,6 +465,6 @@ ### COMPOSER_NO_INTERACTION -如果设置为1，这个环境变量将使 Composer 在执行每一个命令时都放弃交互，相当于对每一命令都使用了 `--no-interaction` 标签。This can be set on build boxes/CI. +如果设置为1，这个环境变量将使 Composer 在执行每一个命令时都放弃交互，相当于对所有命令都使用了 `--no-interaction`。可以在搭建 *虚拟机/持续集成服务器* 时这样设置。 ← [库](02-libraries.md) | [架构](04-schema.md) → -- 2.46.2 From 26d8e3a81a15daf6b8667adbf8a4aa155669dfc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sat, 4 Jan 2014 22:17:51 +0800 Subject: [PATCH 029/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 42 +++++++++++++++------------------------ 1 file changed, 16 insertions(+), 26 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 6327fc4..893c810 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -9,32 +9,22 @@ - [命令行](#命令行) - [全局参数](#全局参数) - [进程退出代码](#进程退出代码) - - [初始化 `init`](#初始化-init) - [参数](#初始化-参数) - - [安装 `install`](#安装-install) - [参数](#安装-参数) - - [更新 `update`](#更新-update) - [参数](#更新-参数) - - 申明依赖 `require` - - 申明依赖-参数 - - 全局执行 `global` - - 搜索 `search` - - 搜索-参数 - - 展示 `show` - - 展示-参数 - - 依赖性检测 `depends` - - 依赖性检测-参数 - - 有效性检测 `validate` - - 依赖包状态检测 `status` - - 自我更新 `self-update` - - 自我更新-参数 - - 更改配置 `config` - - 更改配置-使用方法 - - 更改配置-参数 - - 修改包来源 - - 创建项目 `create-project` - - 创建项目-参数 - - 打印自动加载索引 `dump-autoload` - - 打印自动加载索引-参数 - - 查看许可协议 `licenses` - - 执行脚本 `run-script` + - [初始化 `init`](#初始化-init) - - [参数](#初始化-参数) + - [安装 `install`](#安装-install) - - [参数](#安装-参数) + - [更新 `update`](#更新-update) - - [参数](#更新-参数) + - [申明依赖 `require`](#申明依赖-require) - - [参数](#申明依赖-参数) + - [全局执行 `global`](#全局执行-global) + - [搜索 `search`](#搜索-search) - - [参数](#搜索-参数) + - [展示 `show`](#展示-show) - - [参数](#展示-参数) + - [依赖性检测 `depends`](#依赖性检测-depends) - - [参数](#依赖性检测-参数) + - [有效性检测 `validate`](#有效性检测-validate) + - [依赖包状态检测 `status`](#依赖包状态检测-status) + - [自我更新 `self-update`](#自我更新-self-update) - - [参数](#自我更新-参数) + - [更改配置 `config`](#更改配置-config) - - [使用方法](#更改配置-使用方法) - - [参数](#更改配置-参数) - - [修改包来源](#修改包来源) + - [创建项目 `create-project`](#创建项目-create-project) - - [参数](#创建项目-参数) + - [打印自动加载索引 `dump-autoload`](#打印自动加载索引-dump-autoload) - - [参数](#打印自动加载索引-参数) + - [查看许可协议 `licenses`](#查看许可协议-licenses) + - [执行脚本 `run-script`](#执行脚本-run-script) - diagnose - 归档 `archive` - 归档-参数 -- 2.46.2 From 5c01620abfb7c29fd1bbec951c02e1f0c15385e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sat, 4 Jan 2014 22:31:33 +0800 Subject: [PATCH 030/125] update cn-introduction/03-cli.md --- cn-introduction/03-cli.md | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 893c810..b8bb04f 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -25,25 +25,24 @@ - [打印自动加载索引 `dump-autoload`](#打印自动加载索引-dump-autoload) - - [参数](#打印自动加载索引-参数) - [查看许可协议 `licenses`](#查看许可协议-licenses) - [执行脚本 `run-script`](#执行脚本-run-script) - - diagnose - - 归档 `archive` - - 归档-参数 - - 获取帮助信息 `help` - - 环境变量 - - COMPOSER - - COMPOSER_ROOT_VERSION - - COMPOSER_VENDOR_DIR - - COMPOSER_BIN_DIR - - http_proxy or HTTP_PROXY - - no_proxy - - HTTP_PROXY_REQUEST_FULLURI - - HTTPS_PROXY_REQUEST_FULLURI - - COMPOSER_HOME - - COMPOSER_HOME/config.json - - COMPOSER_CACHE_DIR - - COMPOSER_PROCESS_TIMEOUT - - COMPOSER_DISCARD_CHANGES - - COMPOSER_NO_INTERACTION + - [诊断 `diagnose`](#诊断-diagnose) + - [归档 `archive`](#归档-archive) - - [参数](#归档-参数) + - [获取帮助信息 `help`](#获取帮助信息-help) + - [环境变量](#环境变量) + - [COMPOSER](#composer) + - [COMPOSER_ROOT_VERSION](#composer_root_version) + - [COMPOSER_VENDOR_DIR](#composer_vendor_dir) + - [COMPOSER_BIN_DIR](#composer_bin_dir) + - [http_proxy or HTTP_PROXY](#http_proxy-or-http_proxy) + - [no_proxy](#no_proxy) + - [HTTP_PROXY_REQUEST_FULLURI](#http_proxy_request_fulluri) + - [HTTPS_PROXY_REQUEST_FULLURI](#https_proxy_request_fulluri) + - [COMPOSER_HOME](#composer_home) + - [COMPOSER_HOME/config.json](#composer_homeconfigjson) + - [COMPOSER_CACHE_DIR](#composer_cache_dir) + - [COMPOSER_PROCESS_TIMEOUT](#composer_process_timeout) + - [COMPOSER_DISCARD_CHANGES](#composer_discard_changes) + - [COMPOSER_NO_INTERACTION](#composer_no_interaction) --- @@ -353,7 +352,7 @@ 你可以运行此命令来手动执行 [脚本](articles/scripts.md)，只需要指定脚本的名称，可选的 `--no-dev` 参数允许你禁用开发者模式。 -## diagnose +## 诊断 `diagnose` 如果你觉得发现了一个 bug 或是程序行为变得怪异，你可能需要运行 `diagnose` 命令，来帮助你检测一些常见的问题。 -- 2.46.2 From e115826e99e4b642869f885e94392016f5c108b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sun, 5 Jan 2014 18:31:45 +0800 Subject: [PATCH 031/125] update README.md cn-introduction/04-schema.md cn-introduction/articles/custom-installers.md --- README.md | 4 +- cn-introduction/04-schema.md | 97 +++++++------------ cn-introduction/articles/custom-installers.md | 13 +-- 3 files changed, 41 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 37e4144..c8bb7d9 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,8 @@ Composer 中文文档 ## Articles - [Aliases](/cn-introduction/articles/aliases.md) Alias branch names to versions -- [Custom Installers](/cn-introduction/articles/custom-installers.md) -Modify the way certain types of packages are installed +- [自定义安装程序](/cn-introduction/articles/custom-installers.md) +修改某些特殊类型包的安装方式。 - [Handling Private Packages With Satis](/cn-introduction/articles/handling-private-packages-with-satis.md) Host your own composer repository - [Plugins](/cn-introduction/articles/plugins.md) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 56e7871..f6624e5 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -1,63 +1,50 @@ # composer.json -This chapter will explain all of the fields available in `composer.json`. +本章将解释所有在 `composer.json` 中可用的字段。 ## JSON schema -We have a [JSON schema](http://json-schema.org) that documents the format and -can also be used to validate your `composer.json`. In fact, it is used by the -`validate` command. You can find it at: -[`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). +我们有一个 [JSON schema](http://json-schema.org) 格式化文档，它也可以被用来验证你的 `composer.json` 文件。事实上，它已经被 `validate` 命令所使用。 你可以在这里找到它： [`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). ## Root Package -The root package is the package defined by the `composer.json` at the root of -your project. It is the main `composer.json` that defines your project -requirements. +root package 是指由 `composer.json` 定义的在你项目根目录的包。这是 `composer.json` 定义你项目所需的主要条件。（简单的说，你自己的项目就是一个 root package） -Certain fields only apply when in the root package context. One example of -this is the `config` field. Only the root package can define configuration. -The config of dependencies is ignored. This makes the `config` field -`root-only`. +某些字段仅适用于 root package 上下文。 `config` 字段就是其中一个例子。只有 root package 可以定义 configuration。在依赖包中定义的 `config` 字段将被忽略，这使得 `config` 字段只有 root package 可用（`root-only`）。 -If you clone one of those dependencies to work on it, then that package is the -root package. The `composer.json` is identical, but the context is different. +如果你克隆了其中的一个依赖包，直接在其上开始工作，那么它就变成了 root package。与作为他人的依赖包时使用相同的 `composer.json` 文件，但上下文发生了变化。 -> **Note:** A package can be the root package or not, depending on the context. -> For example, if your project depends on the `monolog` library, your project -> is the root package. However, if you clone `monolog` from GitHub in order to -> fix a bug in it, then `monolog` is the root package. +> **注意：** 一个资源包是不是 root package，取决于它的上下文。 +> 例如：如果你的项目依赖 `monolog` 库，那么你的项目就是 root package。 +> 但是，如果你从 GitHub 上克隆了 `monolog` 为它修复 bug， +> 那么此时 `monolog` 就是 root package。 -## Properties +## 属性 -### name +### 包名 `name` -The name of the package. It consists of vendor name and project name, -separated by `/`. +包的名称，它包括供应商名称和项目名称，使用 `/` 分隔。 -Examples: +例如： * monolog/monolog * igorw/event-source -Required for published packages (libraries). +对于需要发布的包（库），这是必须填写的。 -### description +### 描述 `description` -A short description of the package. Usually this is just one line long. +一个包的简短描述。通常这个最长只有一行。 -Required for published packages (libraries). +对于需要发布的包（库），这是必须填写的。 -### version +### 版本 `version` -The version of the package. In most cases this is not required and should -be omitted (see below). +`version` 不是必须的，并且建议忽略（见下文）。 -This must follow the format of `X.Y.Z` or `vX.Y.Z` with an optional suffix -of `-dev`, `-patch`, `-alpha`, `-beta` or `-RC`. The patch, alpha, beta and -RC suffixes can also be followed by a number. +它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式， `-dev`、`-patch`、`-alpha`、`-beta` 或 `-RC` 这些后缀是可选的。在后缀之后也可以再跟上一个数字。 -Examples: +例如： 1.0.0 1.0.2 @@ -68,43 +55,27 @@ Examples: 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 -to omit it. +通常，我们能够从 VCS (git, svn, hg) 的信息推断出包的版本号，在这种情况下，我们建议忽略 `version`。 -> **Note:** Packagist uses VCS repositories, so the statement above is very -> much true for Packagist as well. Specifying the version yourself will -> most likely end up creating problems at some point due to human error. +> **注意：** Packagist 使用 VCS 仓库， +> 因此 `version` 定义的版本号必须是真实准确的。 +> 自己手动指定的 `version`，最终有可能在某个时候因为人为错误造成问题。 -### type +### 安装类型 `type` -The type of the package. It defaults to `library`. +包的安装类型，默认为 `library`。 -Package types are used for custom installation logic. If you have a package -that needs some special logic, you can define a custom type. This could be a -`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will -all be specific to certain projects, and they will need to provide an -installer capable of installing packages of that type. +包的安装类型，用来定义安装逻辑。如果你有一个包需要一个特殊的逻辑，你可以设定一个自定义的类型。这可以是一个 `symfony-bundle`，一个 `wordpress-plugin` 或者一个 `typo3-module`。这些类型都将是具体到某一个项目，而对应的项目将要提供一种能够安装该类型包的安装程序。 -Out of the box, composer supports four types: +composer 原生支持以下4种类型： -- **library:** This is the default. It will simply copy the files to `vendor`. -- **project:** This denotes a project rather than a library. For example - application shells like the [Symfony standard edition](https://github.com/symfony/symfony-standard), - CMSs like the [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) - or full fledged applications distributed as packages. This can for example - be used by IDEs to provide listings of projects to initialize when creating - a new workspace. -- **metapackage:** An empty package that contains requirements and will trigger - their installation, but contains no files and will not write anything to the - filesystem. As such, it does not require a dist or source key to be - installable. +- **library:** 这是默认类型，它会简单的将文件复制到 `vendor` 目录。 +- **project:** 这表示当前包是一个项目，而不是一个库。例如：框架应用程序 [Symfony standard edition](https://github.com/symfony/symfony-standard)，内容管理系统 [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) 或者完全成熟的分布式应用程序。使用 IDE 创建一个新的工作区时，这可以为其提供项目列表的初始化。 +- **metapackage:** 当一个空的包，包含依赖并且需要触发依赖的安装，这将不会对系统写入额外的文件。因此这种安装类型并不需要一个 dist 或 source。 - **composer-plugin:** A package of type `composer-plugin` may provide an - installer for other packages that have a custom type. Read more in the - [dedicated article](articles/custom-installers.md). + installer for other packages that have a custom type.详细请查看 [自定义安装类型](articles/custom-installers.md)。 -Only use a custom type if you need custom logic during installation. It is -recommended to omit this field and have it just default to `library`. +仅在你需要一个自定义的安装逻辑时才使用它。建议忽略这个属性，采用默认的 `library`。 ### keywords diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index feeebe5..a3e7166 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -2,18 +2,15 @@ tagline: Modify the way certain types of packages are installed --> -# Setting up and using custom installers +# 设置和使用自定义安装类型 -## Synopsis +## 概要 -At times it may be necessary for a package to require additional actions during -installation, such as installing packages outside of the default `vendor` -library. +有时需要在包的安装过程中执行其它的动作，例如：将它安装在默认的 `vendor` 以外的其它目录。 -In these cases you could consider creating a Custom Installer to handle your -specific logic. +在这些情况下，你可以考虑创建一个自定义安装程序来处理特定的逻辑。 -## Calling a Custom Installer +## 调用自定义安装程序 Suppose that your project already has a Custom Installer for specific modules then invoking that installer is a matter of defining the correct [type][1] in -- 2.46.2 From 66dddc4d59dd4cf65954ac96c76fd51ccaf417b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sun, 5 Jan 2014 20:30:01 +0800 Subject: [PATCH 032/125] update --- cn-introduction/04-schema.md | 90 +++++++++---------- cn-introduction/articles/custom-installers.md | 8 +- 2 files changed, 45 insertions(+), 53 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index f6624e5..ffc3334 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -72,17 +72,15 @@ composer 原生支持以下4种类型： - **library:** 这是默认类型，它会简单的将文件复制到 `vendor` 目录。 - **project:** 这表示当前包是一个项目，而不是一个库。例如：框架应用程序 [Symfony standard edition](https://github.com/symfony/symfony-standard)，内容管理系统 [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) 或者完全成熟的分布式应用程序。使用 IDE 创建一个新的工作区时，这可以为其提供项目列表的初始化。 - **metapackage:** 当一个空的包，包含依赖并且需要触发依赖的安装，这将不会对系统写入额外的文件。因此这种安装类型并不需要一个 dist 或 source。 -- **composer-plugin:** A package of type `composer-plugin` may provide an - installer for other packages that have a custom type.详细请查看 [自定义安装类型](articles/custom-installers.md)。 +- **composer-plugin:** 一个安装类型为 `composer-plugin` 的包，它有一个自定义安装类型，可以为其它包提供一个 installler。详细请查看 [自定义安装类型](articles/custom-installers.md)。 仅在你需要一个自定义的安装逻辑时才使用它。建议忽略这个属性，采用默认的 `library`。 -### keywords +### 关键字 `keywords` -An array of keywords that the package is related to. These can be used for -searching and filtering. +该包相关的关键词的数组。这些可用于搜索和过滤。 -Examples: +例如： logging events @@ -90,27 +88,27 @@ Examples: redis templating -Optional. +可选。 -### homepage +### 项目主页 `homepage` -An URL to the website of the project. +该项目网站的 URL 地址。 -Optional. +可选。 -### time +### 版本发布时间 `time` -Release date of the version. +版本发布时间。 -Must be in `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` format. +必须符合 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM:SS` 格式。 -Optional. +可选。 -### license +### 许可协议 `license` -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 @@ -126,22 +124,19 @@ The recommended notation for the most common licenses is (alphabetical): 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/). +可选，但强烈建议提供此内容。更多许可协议的标识符请参见 [SPDX Open Source License Registry](http://www.spdx.org/licenses/)。 -For closed-source software, you may use `"proprietary"` as the license identifier. +对于闭源软件，你必须使用 `"proprietary"` 协议标识符。 -An Example: +一个例子： { "license": "MIT" } +对于一个包，当允许在多个许可协议间进行选择时（"disjunctive license"），这些协议标识符可以被指定为数组。 -For a package, when there is a choice between licenses ("disjunctive license"), -multiple can be specified as array. - -An Example for disjunctive licenses: +多协议的一个例子： { "license": [ @@ -150,27 +145,26 @@ An Example for disjunctive licenses: ] } -Alternatively they can be separated with "or" and enclosed in parenthesis; +另外它们也可以由 "or" 分隔，并写在括号中： { "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. +同样，当有多个许可协议需要结合使用时（"conjunctive license"），它们应该被 "and" 分隔，并写在括号中。 -### authors +### 作者 `authors` -The authors of the package. This is an array of objects. +包的作者。这是一个对象数组。 -Each author object can have following properties: +这个对象必须包含以下属性： -* **name:** The author's name. Usually his real name. -* **email:** The author's email address. -* **homepage:** An URL to the author's website. -* **role:** The authors' role in the project (e.g. developer or translator) +* **name:** 作者的姓名，通常使用真名。 +* **email:** 作者的 email 地址。 +* **homepage:** 作者主页的 URL 地址。 +* **role:** 该作者在此项目中担任的角色（例如：开发人员 或 翻译）。 -An example: +一个例子： { "authors": [ @@ -189,22 +183,22 @@ An example: ] } -Optional, but highly recommended. +可选，但强烈建议提供此内容。 -### support +### 支持 `support` -Various information to get support about the project. +获取项目支持的向相关信息对象。 -Support information includes the following: +这个对象必须包含以下属性： -* **email:** Email address for support. -* **issues:** URL to the Issue Tracker. -* **forum:** URL to the Forum. -* **wiki:** URL to the Wiki. -* **irc:** IRC channel for support, as irc://server/channel. -* **source:** URL to browse or download the sources. +* **email:** 项目支持 email 地址。 +* **issues:** 跟踪问题的 URL 地址。 +* **forum:** 论坛地址。 +* **wiki:** Wiki 地址。 +* **irc:** IRC 聊天频道地址，类似于 irc://server/channel。 +* **source:** 网址浏览或下载源。 -An example: +一个例子： { "support": { @@ -213,7 +207,7 @@ An example: } } -Optional. +可选。 ### Package links diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index a3e7166..794d0c4 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -12,11 +12,9 @@ ## 调用自定义安装程序 -Suppose that your project already has a Custom Installer for specific modules -then invoking that installer is a matter of defining the correct [type][1] in -your package file. +假设你的项目已经有了一个自定义的安装模块，那么如何根据 [type][1] 正确调用你包文件中的安装程序就成为了一个问题。 -> _See the next chapter for an instruction how to create Custom Installers._ +> _参见见下一章，如何通过指令创建自定义安装程序。_ Every Custom Installer defines which [type][1] string it will recognize. Once recognized it will completely override the default installer and only apply its @@ -176,7 +174,7 @@ different installation path. > _Instead of being installed in `/vendor` any package installed using this > Installer will be put in the `/data/templates/` folder._ -[1]: ../04-schema.md#type +[1]: ../04-schema.md#安装类型-type [2]: ../04-schema.md#extra [3]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/PluginInterface.php [4]: https://github.com/composer/composer/blob/master/src/Composer/Installer/InstallerInterface.php -- 2.46.2 From 322381a166941dc696971aa5ccd25ea9a22f388a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sun, 5 Jan 2014 23:52:50 +0800 Subject: [PATCH 033/125] update 04-schema.md --- cn-introduction/04-schema.md | 39 ++++++++++++++---------------------- 1 file changed, 15 insertions(+), 24 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index ffc3334..8344e1b 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -6,18 +6,18 @@ 我们有一个 [JSON schema](http://json-schema.org) 格式化文档，它也可以被用来验证你的 `composer.json` 文件。事实上，它已经被 `validate` 命令所使用。 你可以在这里找到它： [`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). -## Root Package +## Root 包 -root package 是指由 `composer.json` 定义的在你项目根目录的包。这是 `composer.json` 定义你项目所需的主要条件。（简单的说，你自己的项目就是一个 root package） +“root 包”是指由 `composer.json` 定义的在你项目根目录的包。这是 `composer.json` 定义你项目所需的主要条件。（简单的说，你自己的项目就是一个 root 包） -某些字段仅适用于 root package 上下文。 `config` 字段就是其中一个例子。只有 root package 可以定义 configuration。在依赖包中定义的 `config` 字段将被忽略，这使得 `config` 字段只有 root package 可用（`root-only`）。 +某些字段仅适用于“root 包”上下文。 `config` 字段就是其中一个例子。只有“root 包”可以定义。在依赖包中定义的 `config` 字段将被忽略，这使得 `config` 字段只有“root 包”可用（`root-only`）。 -如果你克隆了其中的一个依赖包，直接在其上开始工作，那么它就变成了 root package。与作为他人的依赖包时使用相同的 `composer.json` 文件，但上下文发生了变化。 +如果你克隆了其中的一个依赖包，直接在其上开始工作，那么它就变成了“root 包”。与作为他人的依赖包时使用相同的 `composer.json` 文件，但上下文发生了变化。 -> **注意：** 一个资源包是不是 root package，取决于它的上下文。 -> 例如：如果你的项目依赖 `monolog` 库，那么你的项目就是 root package。 +> **注意：** 一个资源包是不是“root 包”，取决于它的上下文。 +> 例如：如果你的项目依赖 `monolog` 库，那么你的项目就是“root 包”。 > 但是，如果你从 GitHub 上克隆了 `monolog` 为它修复 bug， -> 那么此时 `monolog` 就是 root package。 +> 那么此时 `monolog` 就是“root 包”。 ## 属性 @@ -211,10 +211,9 @@ composer 原生支持以下4种类型： ### Package links -All of the following take an object which maps package names to -[version constraints](01-basic-usage.md#package-versions). +下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#包版本) 的映射对象。 -Example: +例如： { "require": { @@ -222,15 +221,11 @@ Example: } } -All links are optional fields. +所有的这些都是可选的。 -`require` and `require-dev` additionally support stability flags (root-only). -These allow you to further restrict or expand the stability of a package beyond -the scope of the [minimum-stability](#minimum-stability) setting. You can apply -them to a constraint, or just apply them to an empty constraint if you want to -allow unstable packages of a dependency for example. +`require` 和 `require-dev` 还支持稳定性标签（@，仅针对“root 包”）。这允许你在 [minimum-stability](#minimum-stability) 设定的范围外做进一步的限制或扩展。例如：如果你想允许依赖一个不稳定的包，你可以在一个包的版本约束后使用它，或者是一个空的版本约束内使用它。 -Example: +例子： { "require": { @@ -239,10 +234,9 @@ Example: } } -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. +如果你的依赖之一，有对另一个不稳定包的依赖，你最好在 require 中显示的定义它，并带上足够详细的稳定性标识。 -Example: +例子： { "require": { @@ -251,10 +245,7 @@ Example: } } -`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 -when you run update. These only work if you explicitly require a dev version -and append the reference with `#`. +`require` 和 `require-dev` 还支持对 dev（开发）版本的明确引用（即：版本控制系统中的提交编号 commit），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 `#` 的标识。 Example: -- 2.46.2 From d4441457bce85e63d34874cfdd2789016bb7facc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 6 Jan 2014 00:16:05 +0800 Subject: [PATCH 034/125] update 04-schema.md aliases.md --- cn-introduction/04-schema.md | 10 ++++------ cn-introduction/articles/aliases.md | 4 ++-- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 8344e1b..9f7f3db 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -256,12 +256,10 @@ Example: } } -> **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 -> composer.json metadata will still be read from the branch name you specify -> before the hash. Because of that in some cases it will not be a practical -> workaround, and you should always try to switch to tagged releases as soon -> as you can. +> **注意：** 虽然这有时很方便，但不应该长期在你的包中使用，因为它有一个技术上的限制。 +> composer.json 将仍然在哈希值之前指定的分支名称读取元数据， +> 正因为如此，在某些情况下，它不会是一个实用的解决方法， +> 如果可能，你应该总是尝试切换到拥有标签的版本。 It is also possible to inline-alias a package constraint so that it matches a constraint that it otherwise would not. For more information [see the diff --git a/cn-introduction/articles/aliases.md b/cn-introduction/articles/aliases.md index 26a9c46..f8eab03 100644 --- a/cn-introduction/articles/aliases.md +++ b/cn-introduction/articles/aliases.md @@ -2,9 +2,9 @@ tagline: Alias branch names to versions --> -# Aliases +# 别名 -## 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 -- 2.46.2 From 30e5df40b263957a672ac543378a9dba8f1a6db5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 6 Jan 2014 00:25:32 +0800 Subject: [PATCH 035/125] update 04-schema.md --- cn-introduction/04-schema.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 9f7f3db..c589d16 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -261,9 +261,7 @@ Example: > 正因为如此，在某些情况下，它不会是一个实用的解决方法， > 如果可能，你应该总是尝试切换到拥有标签的版本。 -It is also possible to inline-alias a package constraint so that it matches -a constraint that it otherwise would not. For more information [see the -aliases article](articles/aliases.md). +它也可以应用于行内别名，这样它将匹配一个约束，否则不会。更多信息请参考 [别名](articles/aliases.md). #### require -- 2.46.2 From 7e9e05606a8ef60ac8f6e5d302c41eb9168f20cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 6 Jan 2014 12:09:42 +0800 Subject: [PATCH 036/125] update 04-schema.md --- cn-introduction/04-schema.md | 36 +++++++++--------------------------- 1 file changed, 9 insertions(+), 27 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index c589d16..c7fd809 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -247,7 +247,7 @@ composer 原生支持以下4种类型： `require` 和 `require-dev` 还支持对 dev（开发）版本的明确引用（即：版本控制系统中的提交编号 commit），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 `#` 的标识。 -Example: +例子： { "require": { @@ -261,47 +261,29 @@ Example: > 正因为如此，在某些情况下，它不会是一个实用的解决方法， > 如果可能，你应该总是尝试切换到拥有标签的版本。 -它也可以应用于行内别名，这样它将匹配一个约束，否则不会。更多信息请参考 [别名](articles/aliases.md). +它也可以应用于行内别名，这样它将匹配一个约束，否则不会。更多信息请参考 [别名](articles/aliases.md)。 #### require -Lists packages required by this package. The package will not be installed -unless those requirements can be met. +必须的软件包列表，除非这些依赖被满足，否则不会完成安装。 #### require-dev (root-only) -Lists packages required for developing this package, or running -tests, etc. The dev requirements of the root package are installed by default. -Both `install` or `update` support the `--no-dev` option that prevents dev -dependencies from being installed. +这个列表是为开发或测试等目的，额外列出的依赖。“root 包”的 require-dev 默认是会被安装的。然而 `install` 或 `update` 支持使用 `--no-dev` 参数来跳过 `require-dev` 字段中列出的包。 #### conflict -Lists packages that conflict with this version of this package. They -will not be allowed to be installed together with your package. +此列表中的包与当前包的这个版本冲突。它们将不允许同时被安装。 -Note that when specifying ranges like `<1.0, >= 1.1` in a `conflict` link, -this will state a conflict with all versions that are less than 1.0 *and* equal -or newer than 1.1 at the same time, which is probably not what you want. You -probably want to go for `<1.0 | >= 1.1` in this case. +请注意，在 `conflict` 中指定类似于 `<1.0, >= 1.1` 的版本范围时，这表示它与小于1.0 *并且* 同时大等于1.1的版本冲突，这很可能不是你想要的。在这种情况下你可能想要表达的是 `<1.0 | >= 1.1` 。 #### replace -Lists packages that are replaced by this package. This allows you to fork a -package, publish it under a different name with its own version numbers, while -packages requiring the original package continue to work with your fork because -it replaces the original package. +这个列表中的包将被当前包取代。这使你可以 fork 一个包，以不同的名称和版本号发布，同时要求依赖于原包的其它包，在这之后依赖于你 fork 的这个包，因为它取代了原来的包。 -This is also useful for packages that contain sub-packages, for example the main -symfony/symfony package contains all the Symfony Components which are also -available as individual packages. If you require the main package it will -automatically fulfill any requirement of one of the individual components, -since it replaces them. +这对于创建一个内部包含子包的主包也非常的有用。例如 symfony/symfony 这个主包，包含了所有 Symfony 的组件，而这些组件又可以作为单独的包进行发布。如果你 require 了主包，那么它就会自动完成其下各个组件的任务，因为主包取代了子包。 -Caution is advised when using replace for the sub-package purpose explained -above. You should then typically only replace using `self.version` as a version -constraint, to make sure the main package only replaces the sub-packages of -that exact version, and not any other version, which would be incorrect. +注意，在使用上述方法取代子包时，通常你应该只对子包使用 `self.version` 这一个版本约束，以确保主包仅替换掉子包的准确版本，而不是任何其他版本。 #### provide -- 2.46.2 From ecfa7eaa523e86969f9d0e6a300e014b91c0e396 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 6 Jan 2014 17:20:03 +0800 Subject: [PATCH 037/125] update 04-schema.md --- cn-introduction/04-schema.md | 71 ++++++++++++------------------------ 1 file changed, 24 insertions(+), 47 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index c7fd809..fd9a972 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -128,7 +128,7 @@ composer 原生支持以下4种类型： 对于闭源软件，你必须使用 `"proprietary"` 协议标识符。 -一个例子： +一个例如： { "license": "MIT" @@ -136,7 +136,7 @@ composer 原生支持以下4种类型： 对于一个包，当允许在多个许可协议间进行选择时（"disjunctive license"），这些协议标识符可以被指定为数组。 -多协议的一个例子： +多协议的一个例如： { "license": [ @@ -164,7 +164,7 @@ composer 原生支持以下4种类型： * **homepage:** 作者主页的 URL 地址。 * **role:** 该作者在此项目中担任的角色（例如：开发人员 或 翻译）。 -一个例子： +一个例如： { "authors": [ @@ -198,7 +198,7 @@ composer 原生支持以下4种类型： * **irc:** IRC 聊天频道地址，类似于 irc://server/channel。 * **source:** 网址浏览或下载源。 -一个例子： +一个例如： { "support": { @@ -225,7 +225,7 @@ composer 原生支持以下4种类型： `require` 和 `require-dev` 还支持稳定性标签（@，仅针对“root 包”）。这允许你在 [minimum-stability](#minimum-stability) 设定的范围外做进一步的限制或扩展。例如：如果你想允许依赖一个不稳定的包，你可以在一个包的版本约束后使用它，或者是一个空的版本约束内使用它。 -例子： +例如： { "require": { @@ -236,7 +236,7 @@ composer 原生支持以下4种类型： 如果你的依赖之一，有对另一个不稳定包的依赖，你最好在 require 中显示的定义它，并带上足够详细的稳定性标识。 -例子： +例如： { "require": { @@ -247,7 +247,7 @@ composer 原生支持以下4种类型： `require` 和 `require-dev` 还支持对 dev（开发）版本的明确引用（即：版本控制系统中的提交编号 commit），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 `#` 的标识。 -例子： +例如： { "require": { @@ -294,15 +294,11 @@ simply list it in `provide`. ### suggest -Suggested packages that can enhance or work well with this package. These are -just informational and are displayed after the package is installed, to give -your users a hint that they could add more packages, even though they are not -strictly required. +建议安装的包，它们增强或能够与当前包良好的工作。这些只是信息，并显示在依赖包安装完成之后，给你的用户一个建议，他们可以添加更多的包。 -The format is like package links above, except that the values are free text -and not version constraints. +格式如下，版本约束变成了描述信息。 -Example: +例如： { "suggest": { @@ -312,26 +308,19 @@ Example: ### autoload -Autoload mapping for a PHP autoloader. +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). +通常 [`PSR-0`](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) autoloading、`classmap` generation 和 `files` 方式都是支持的。PSR-0 是推荐的方式，因为它提供了更大的灵活性（当你添加新的类文件时，不需要重新生成 autoloader）。 #### PSR-0 -Under the `psr-0` key you define a mapping from namespaces to paths, relative to the -package root. Note that this also supports the PEAR-style non-namespaced convention. +在 `psr-0` key 下你定义了一个命名空间到实际路径的映射（相对于包的根目录）。注意，这里同样支持 PEAR-style 方式的约定（与命名空间不同，PEAR 类库在类名上采用了下划线分隔）。 -Please note namespace declarations should end in `\\` to make sure the autoloader -responds exactly. For example `Foo` would match in `FooBar` so the trailing -backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct. +请注意，命名空间的申明应该以 `\\` 结束，以确保 autoloader 能够准确响应。例如： `Foo` 将会与 `FooBar` 匹配，然而以反斜杠结束就可以解决这样的问题， `Foo\\` 和 `FooBar\\` 将会被区分开来。 -The PSR-0 references are all combined, during install/update, into a single key => value -array which may be found in the generated file `vendor/composer/autoload_namespaces.php`. +在 install/update 过程中，PSR-0 引用都将被结合为一个单一的键值对数组，存储至 `vendor/composer/autoload_namespaces.php` 文件中。 -Example: +例如： { "autoload": { @@ -343,8 +332,7 @@ Example: } } -If you need to search for a same prefix in multiple directories, -you can specify them as an array as such: +如果你需要搜索多个目录中一个相同的前缀，你可以将它们指定为一个数组，例如： { "autoload": { @@ -352,10 +340,7 @@ you can specify them as an array as such: } } -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: +PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别的指定。这对于只有一个类在全局命名空间的类库是非常有用的（如果 php 源文件也位于包的根目录）。例如，可以这样申明： { "autoload": { @@ -363,8 +348,7 @@ in the root of the package, for example, it may be declared like this: } } -If you want to have a fallback directory where any namespace can be, you can -use an empty prefix like: +如果你想设置一个目录作为任何命名空间的备用目录，你可以使用空的前缀，像这样： { "autoload": { @@ -374,16 +358,11 @@ use an empty prefix like: #### Classmap -The `classmap` references are all combined, during install/update, into a single -key => value array which may be found in the generated file -`vendor/composer/autoload_classmap.php`. This map is built by scanning for -classes in all `.php` and `.inc` files in the given directories/files. +`classmap` 引用的所有组合，都会在 install/update 过程中生成，并存储到 `vendor/composer/autoload_classmap.php` 文件中。这个 map 是经过扫描指定目录（同样支持直接精确到文件）中所有的 `.php` 和 `.inc` 文件里内置的类而得到的。 -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 -to search for classes. +你可以用 classmap 生成支持支持自定义加载的不遵循 PSR-0 规范的类库。要配置它指向需要的目录，以便能够准确搜索到类文件。 -Example: +例如： { "autoload": { @@ -393,11 +372,9 @@ Example: #### Files -If you want to require certain files explicitly on every request then you can use -the 'files' autoloading mechanism. This is useful if your package includes PHP functions -that cannot be autoloaded by PHP. +如果你想要明确的指定，在每次请求时都要载入某些文件，那么你可以使用 'files' autoloading。通常作为函数库的载入方式（而非类库）。 -Example: +例如： { "autoload": { -- 2.46.2 From e028a895009a625cb1b47faa8b63097618ffc04d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 6 Jan 2014 18:34:55 +0800 Subject: [PATCH 038/125] update 04-schema.md --- cn-introduction/04-schema.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index fd9a972..b62f039 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -384,35 +384,28 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 ### include-path -> **DEPRECATED**: This is only present to support legacy projects, and all new code -> should preferably use autoloading. As such it is a deprecated practice, but the -> feature itself will not likely disappear from Composer. +> **不建议**：这是目前唯一支持传统项目的做法，所有新的代码都建议使用自动加载。 +> 这是一个过时的做法，但 Composer 将仍然保留这个功能。 -A list of paths which should get appended to PHP's `include_path`. +一个追加到 PHP `include_path` 中的列表。 -Example: +例如： { "include-path": ["lib/"] } -Optional. +可选。 ### target-dir -Defines the installation target. +定义当前包安装的目标文件夹。 -In case the package root is below the namespace declaration you cannot -autoload properly. `target-dir` solves this problem. +若某个包的根目录，在它申明的命名空间之下，将不能正确的使用自动加载。而 `target-dir` 解决了这个问题。 -An example is Symfony. There are individual packages for the components. The -Yaml component is under `Symfony\Component\Yaml`. The package root is that -`Yaml` directory. To make autoloading possible, we need to make sure that it -is not installed into `vendor/symfony/yaml`, but instead into -`vendor/symfony/yaml/Symfony/Component/Yaml`, so that the autoloader can load -it from `vendor/symfony/yaml`. +Symfony 就是一个例子。它有一些独立的包作为组件。Yaml 组件就放在 `Symfony\Component\Yaml` 目录下，然而这个包的根目录实际上是 `Yaml`。为了使自动加载成为可能，我们需要确保它不会被安装到 `vendor/symfony/yaml`，而是安装到 `vendor/symfony/yaml/Symfony/Component/Yaml`，从而使 Symfony 定义的 autoloader 可以从 `vendor/symfony/yaml` 加载它。 -To do that, `autoload` and `target-dir` are defined as follows: +要做到这一点 `autoload` 和 `target-dir` 应该定义如下： { "autoload": { @@ -421,7 +414,7 @@ To do that, `autoload` and `target-dir` are defined as follows: "target-dir": "Symfony/Component/Yaml" } -Optional. +可选。 ### minimum-stability (root-only) -- 2.46.2 From 8f2e2ad2eaedb00125c5d2dff3ac8207839c3ccb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 6 Jan 2014 19:17:55 +0800 Subject: [PATCH 039/125] update 04-schema.md --- cn-introduction/04-schema.md | 79 +++++++++++++++--------------------- 1 file changed, 33 insertions(+), 46 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index b62f039..16f7a6f 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -15,7 +15,7 @@ 如果你克隆了其中的一个依赖包，直接在其上开始工作，那么它就变成了“root 包”。与作为他人的依赖包时使用相同的 `composer.json` 文件，但上下文发生了变化。 > **注意：** 一个资源包是不是“root 包”，取决于它的上下文。 -> 例如：如果你的项目依赖 `monolog` 库，那么你的项目就是“root 包”。 +> 例：如果你的项目依赖 `monolog` 库，那么你的项目就是“root 包”。 > 但是，如果你从 GitHub 上克隆了 `monolog` 为它修复 bug， > 那么此时 `monolog` 就是“root 包”。 @@ -25,7 +25,7 @@ 包的名称，它包括供应商名称和项目名称，使用 `/` 分隔。 -例如： +例： * monolog/monolog * igorw/event-source @@ -44,7 +44,7 @@ 它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式， `-dev`、`-patch`、`-alpha`、`-beta` 或 `-RC` 这些后缀是可选的。在后缀之后也可以再跟上一个数字。 -例如： +例： 1.0.0 1.0.2 @@ -70,7 +70,7 @@ composer 原生支持以下4种类型： - **library:** 这是默认类型，它会简单的将文件复制到 `vendor` 目录。 -- **project:** 这表示当前包是一个项目，而不是一个库。例如：框架应用程序 [Symfony standard edition](https://github.com/symfony/symfony-standard)，内容管理系统 [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) 或者完全成熟的分布式应用程序。使用 IDE 创建一个新的工作区时，这可以为其提供项目列表的初始化。 +- **project:** 这表示当前包是一个项目，而不是一个库。例：框架应用程序 [Symfony standard edition](https://github.com/symfony/symfony-standard)，内容管理系统 [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) 或者完全成熟的分布式应用程序。使用 IDE 创建一个新的工作区时，这可以为其提供项目列表的初始化。 - **metapackage:** 当一个空的包，包含依赖并且需要触发依赖的安装，这将不会对系统写入额外的文件。因此这种安装类型并不需要一个 dist 或 source。 - **composer-plugin:** 一个安装类型为 `composer-plugin` 的包，它有一个自定义安装类型，可以为其它包提供一个 installler。详细请查看 [自定义安装类型](articles/custom-installers.md)。 @@ -80,7 +80,7 @@ composer 原生支持以下4种类型： 该包相关的关键词的数组。这些可用于搜索和过滤。 -例如： +例： logging events @@ -128,7 +128,7 @@ composer 原生支持以下4种类型： 对于闭源软件，你必须使用 `"proprietary"` 协议标识符。 -一个例如： +一个例： { "license": "MIT" @@ -136,7 +136,7 @@ composer 原生支持以下4种类型： 对于一个包，当允许在多个许可协议间进行选择时（"disjunctive license"），这些协议标识符可以被指定为数组。 -多协议的一个例如： +多协议的一个例： { "license": [ @@ -162,9 +162,9 @@ composer 原生支持以下4种类型： * **name:** 作者的姓名，通常使用真名。 * **email:** 作者的 email 地址。 * **homepage:** 作者主页的 URL 地址。 -* **role:** 该作者在此项目中担任的角色（例如：开发人员 或 翻译）。 +* **role:** 该作者在此项目中担任的角色（例：开发人员 或 翻译）。 -一个例如： +一个例： { "authors": [ @@ -198,7 +198,7 @@ composer 原生支持以下4种类型： * **irc:** IRC 聊天频道地址，类似于 irc://server/channel。 * **source:** 网址浏览或下载源。 -一个例如： +一个例： { "support": { @@ -213,7 +213,7 @@ composer 原生支持以下4种类型： 下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#包版本) 的映射对象。 -例如： +例： { "require": { @@ -223,9 +223,9 @@ composer 原生支持以下4种类型： 所有的这些都是可选的。 -`require` 和 `require-dev` 还支持稳定性标签（@，仅针对“root 包”）。这允许你在 [minimum-stability](#minimum-stability) 设定的范围外做进一步的限制或扩展。例如：如果你想允许依赖一个不稳定的包，你可以在一个包的版本约束后使用它，或者是一个空的版本约束内使用它。 +`require` 和 `require-dev` 还支持稳定性标签（@，仅针对“root 包”）。这允许你在 [minimum-stability](#minimum-stability) 设定的范围外做进一步的限制或扩展。例：如果你想允许依赖一个不稳定的包，你可以在一个包的版本约束后使用它，或者是一个空的版本约束内使用它。 -例如： +例： { "require": { @@ -236,7 +236,7 @@ composer 原生支持以下4种类型： 如果你的依赖之一，有对另一个不稳定包的依赖，你最好在 require 中显示的定义它，并带上足够详细的稳定性标识。 -例如： +例： { "require": { @@ -247,7 +247,7 @@ composer 原生支持以下4种类型： `require` 和 `require-dev` 还支持对 dev（开发）版本的明确引用（即：版本控制系统中的提交编号 commit），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 `#` 的标识。 -例如： +例： { "require": { @@ -298,7 +298,7 @@ simply list it in `provide`. 格式如下，版本约束变成了描述信息。 -例如： +例： { "suggest": { @@ -316,11 +316,11 @@ PHP autoloader 的自动加载映射。 在 `psr-0` key 下你定义了一个命名空间到实际路径的映射（相对于包的根目录）。注意，这里同样支持 PEAR-style 方式的约定（与命名空间不同，PEAR 类库在类名上采用了下划线分隔）。 -请注意，命名空间的申明应该以 `\\` 结束，以确保 autoloader 能够准确响应。例如： `Foo` 将会与 `FooBar` 匹配，然而以反斜杠结束就可以解决这样的问题， `Foo\\` 和 `FooBar\\` 将会被区分开来。 +请注意，命名空间的申明应该以 `\\` 结束，以确保 autoloader 能够准确响应。例： `Foo` 将会与 `FooBar` 匹配，然而以反斜杠结束就可以解决这样的问题， `Foo\\` 和 `FooBar\\` 将会被区分开来。 在 install/update 过程中，PSR-0 引用都将被结合为一个单一的键值对数组，存储至 `vendor/composer/autoload_namespaces.php` 文件中。 -例如： +例： { "autoload": { @@ -332,7 +332,7 @@ PHP autoloader 的自动加载映射。 } } -如果你需要搜索多个目录中一个相同的前缀，你可以将它们指定为一个数组，例如： +如果你需要搜索多个目录中一个相同的前缀，你可以将它们指定为一个数组，例： { "autoload": { @@ -362,7 +362,7 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 你可以用 classmap 生成支持支持自定义加载的不遵循 PSR-0 规范的类库。要配置它指向需要的目录，以便能够准确搜索到类文件。 -例如： +例： { "autoload": { @@ -374,7 +374,7 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 如果你想要明确的指定，在每次请求时都要载入某些文件，那么你可以使用 'files' autoloading。通常作为函数库的载入方式（而非类库）。 -例如： +例： { "autoload": { @@ -389,7 +389,7 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 一个追加到 PHP `include_path` 中的列表。 -例如： +例： { "include-path": ["lib/"] @@ -418,40 +418,27 @@ Symfony 就是一个例子。它有一些独立的包作为组件。Yaml 组件 ### minimum-stability (root-only) -This defines the default behavior for filtering packages by stability. This -defaults to `stable`, so if you rely on a `dev` package, you should specify -it in your file to avoid surprises. +这定义了通过稳定性过滤包的默认行为。默认为 `stable`（稳定）。因此如果你依赖于一个 `dev`（开发）包，你应该明确的进行定义。 -All versions of each package are checked for stability, and those that are less -stable than the `minimum-stability` setting will be ignored when resolving -your project dependencies. Specific changes to the stability requirements of -a given package can be done in `require` or `require-dev` (see -[package links](#package-links)). +对每个包的所有版本都会进行稳定性检查，而低于 `minimum-stability` 所设定的最低稳定性的版本，将在解决依赖关系时被忽略。对于个别包的特殊稳定性要求，可以在 `require` 或 `require-dev` 中设定（请参考 [package links](#package-links)）。 -Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`, -and `stable`. +可用的稳定性标识（按字母排序）：`dev`、`alpha`、`beta`、`RC`、`stable`。 ### prefer-stable (root-only) -When this is enabled, Composer will prefer more stable packages over unstable -ones when finding compatible stable packages is possible. If you require a -dev version or only alphas are available for a package, those will still be -selected granted that the minimum-stability allows for it. +当此选项被激活时，Composer 将优先使用更稳定的包版本。 -Use `"prefer-stable": true` to enable. +使用 `"prefer-stable": true` 来激活它。 ### repositories (root-only) -Custom package repositories to use. +使用自定义的包资源库。 -By default composer just uses the packagist repository. By specifying -repositories you can get packages from elsewhere. +默认情况下 composer 只使用 packagist 作为包的资源库。通过指定资源库，你可以从其他地方获取资源包。 -Repositories are not resolved recursively. You can only add them to your main -`composer.json`. Repository declarations of dependencies' `composer.json`s are -ignored. +Repositories 并不是递归调用的，只能在“Root包”的 `composer.json` 中定义。附属包中的 `composer.json` 将被忽略。 -The following repository types are supported: +支持以下类型的包资源库： * **composer:** A composer repository is simply a `packages.json` file served via the network (HTTP, FTP, SSH), that contains a list of `composer.json` @@ -466,9 +453,9 @@ The following repository types are supported: composer whatsoever you can define the package inline using a `package` repository. You basically just inline the `composer.json` object. -For more information on any of these, see [Repositories](05-repositories.md). +更多相关内容，请查看 [资源库](05-repositories.md)。 -Example: +例： { "repositories": [ -- 2.46.2 From 8037c17c0952c6f4f30e9a982df428ce48cd2071 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 00:13:36 +0800 Subject: [PATCH 040/125] update 04-schema.md --- cn-introduction/04-schema.md | 133 +++++++++++------------------------ 1 file changed, 40 insertions(+), 93 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 16f7a6f..cc833e0 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -440,18 +440,10 @@ Repositories 并不是递归调用的，只能在“Root包”的 `composer.json 支持以下类型的包资源库： -* **composer:** A composer repository is simply a `packages.json` file served - via the network (HTTP, FTP, SSH), that contains a list of `composer.json` - objects with additional `dist` and/or `source` information. The `packages.json` - file is loaded using a PHP stream. You can set extra options on that stream - using the `options` parameter. -* **vcs:** The version control system repository can fetch packages from git, - svn and hg repositories. -* **pear:** With this you can import any pear repository into your composer - project. -* **package:** If you depend on a project that does not have any support for - composer whatsoever you can define the package inline using a `package` - repository. You basically just inline the `composer.json` object. +* **composer:** 一个 composer 类型的资源库，是一个简单的网络服务器（HTTP、FTP、SSH）上的 `packages.json` 文件，它包含一个 `composer.json` 对象的列表，有额外的 `dist` 和/或 `source` 信息。这个 `packages.json` 文件是用一个 PHP 流加载的。你可以使用 `options` 参数来设定额外的流信息。 +* **vcs:** 从 git、svn 和 hg 取得资源。 +* **pear:** 从 pear 获取资源。 +* **package:** 如果你依赖于一个项目，它不提供任何对 composer 的支持，你就可以使用这种类型。你基本上就只需要内联一个 `composer.json` 对象。 更多相关内容，请查看 [资源库](05-repositories.md)。 @@ -499,71 +491,34 @@ Repositories 并不是递归调用的，只能在“Root包”的 `composer.json ] } -> **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. -By default Packagist is added last which means that custom repositories can -override packages from it. +> **注意：** 顺序是非常重要的，当 Composer 查找资源包时，它会按照顺序进行。默认情况下 Packagist 是最后加入的，因此自定义设置将可以覆盖 Packagist 上的包。 ### config (root-only) -A set of configuration options. It is only used for projects. +下面的这一组选项，仅用于项目。 -The following options are supported: +支持以下选项： -* **process-timeout:** Defaults to `300`. The duration processes like git clones - can run before Composer assumes they died out. You may need to make this - higher if you have a slow connection or huge vendors. -* **use-include-path:** Defaults to `false`. If true, the Composer autoloader - will also look for classes in the PHP include path. -* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or - `auto`. This option allows you to set the install method Composer will prefer to - use. -* **github-protocols:** Defaults to `["git", "https"]`. 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. -* **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. -* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a - different directory if you want to. -* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they - will be symlinked into this directory. -* **cache-dir:** Defaults to `$home/cache` on unix systems and - `C:\Users\\AppData\Local\Composer` on Windows. Stores all the caches - used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home). -* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives - of packages. -* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata - for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`. -* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for - loading VCS repository metadata for the `git`/`hg` types and to speed up installs. -* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all - dist (zip, tar, ..) packages that it downloads. Those are purged after six - months of being unused by default. This option allows you to tweak this - duration (in seconds) or disable it completely by setting it to 0. -* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all - dist (zip, tar, ..) packages that it downloads. When the garbage collection - is periodically ran, this is the maximum size the cache will be able to use. - Older (less used) files will be removed first until the cache fits. -* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader - will not be prepended to existing autoloaders. This is sometimes required to fix - interoperability issues with other autoloaders. -* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for - the generated Composer autoloader. When null a random one will be generated. -* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in - github mode. This is used for GitHub Enterprise setups. -* **notify-on-install:** Defaults to `true`. Composer allows repositories to - define a notification URL, so that they get notified whenever a package from - that repository is installed. This option allows you to disable that behaviour. -* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or - `"stash"`. This option allows you to set the default style of handling dirty - updates when in non-interactive mode. `true` will always discard changes in - vendors, while `"stash"` will try to stash and reapply. Use this for CI - servers or deploy scripts if you tend to have modified vendors. +* **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 限制。 +* **vendor-dir:** 默认为 `vendor`。通过设置你可以安装依赖到不同的目录。 +* **bin-dir:** 默认为 `vendor/bin`。如果一个项目包含二进制文件，它们将被连接到这个目录。 +* **cache-dir:** unix 下默认为 `$home/cache`，Windows 下默认为 `C:\Users\\AppData\Local\Composer`。用于存储 composer 所有的缓存文件。相关信息请查看 [COMPOSER_HOME](03-cli.md#composer-home)。 +* **cache-files-dir:** 默认为 `$cache-dir/files`。存储包 zip 存档的目录。 +* **cache-repo-dir:** 默认为 `$cache-dir/repo`。存储 `composer` 类型的 VCS（`svn`、`github`、`bitbucket`） repos 目录。 +* **cache-vcs-dir:** 默认为 `$cache-dir/vcs`。此目录用于存储 VCS 克隆的 `git`/`hg` 类型的元数据，并加快安装速度。 +* **cache-files-ttl:** 默认为 `15552000`（6个月）。默认情况下 Composer 缓存的所有数据都将在闲置6个月后被删除，这个选项允许你来调整这个时间，你可以将其设置为0以禁用缓存。 +* **cache-files-maxsize:** 默认为 `300MiB`。Composer 缓存的最大容量，超出后将优先清除旧的缓存数据，直到缓存量低于这个数值。 +* **prepend-autoloader:** 默认为 `true`。如果设置为 false，composer autoloader 将不会附加到现有的自动加载机制中。这有时候用来解决与其它自动加载机制产生的冲突。 +* **autoloader-suffix:** 默认为 `null`。Composer 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. -Example: +例： { "config": { @@ -573,44 +528,37 @@ Example: ### scripts (root-only) -Composer allows you to hook into various parts of the installation process -through the use of scripts. +Composer 允许你在安装过程中的各个阶段挂接脚本。 -See [Scripts](articles/scripts.md) for events details and examples. +更多细节和案例请查看 [脚本](articles/scripts.md)。 ### extra -Arbitrary extra data for consumption by `scripts`. +任意的，供 `scripts` 使用的额外数据。. -This can be virtually anything. To access it from within a script event -handler, you can do: +这可以是几乎任何东西。若要从脚本事件访问处理程序，你可以这样做： $extra = $event->getComposer()->getPackage()->getExtra(); -Optional. +可选。 ### bin -A set of files that should be treated as binaries and symlinked into the `bin-dir` -(from config). +A set of files that should be treated as binaries and symlinked into the `bin-dir` (from config). See [Vendor Binaries](articles/vendor-binaries.md) for more details. -Optional. +可选。 ### archive -A set of options for creating package archives. +这些选项在创建包存档时使用。 -The following options are supported: +支持以下选项： -* **exclude:** Allows configuring a list of patterns for excluded paths. The - pattern syntax matches .gitignore files. A leading exclamation mark (!) will - result in any matching files to be included even if a previous pattern - excluded them. A leading slash will only match at the beginning of the project - relative path. An asterisk will not expand to a directory separator. +* **exclude:** 允许设置一个需要被排除的路径的列表。使用与 .gitignore 文件相同的语法。一个前导的（!）将会使其变成白名单而无视之前相同目录的排除设定。前导斜杠只会在项目的相对路径的开头匹配。星号为通配符。 -Example: +例： { "archive": { @@ -618,9 +566,8 @@ Example: } } -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`. +在这个例子中我们 include `/dir/foo/bar/file`、`/foo/bar/baz`、`/file.php`、`/foo/my.test` 但排除了 `/foo/bar/any`、`/foo/baz`、`/my.test`。 -Optional. +可选。 -← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) → +← [命令行](03-cli.md) | [资源库](05-repositories.md) → -- 2.46.2 From 524ec8e97a6645694cbc4e6c92abf2f2143c59a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 16:18:03 +0800 Subject: [PATCH 041/125] update README.md 04-schema.md 05-repositories.md --- README.md | 10 ++--- cn-introduction/04-schema.md | 40 +++++++++++++++++ cn-introduction/05-repositories.md | 69 +++++++++--------------------- 3 files changed, 66 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index c8bb7d9..cb9a6bd 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,13 @@ Composer 中文文档 - [基本用法](/cn-introduction/01-basic-usage.md) - [库](/cn-introduction/02-libraries.md) - [命令行](/cn-introduction/03-cli.md) -- [Schema](/cn-introduction/04-schema.md) -- [Repositories](/cn-introduction/05-repositories.md) -- [Community](/cn-introduction/06-community.md) +- [架构](/cn-introduction/04-schema.md) +- [资源库](/cn-introduction/05-repositories.md) +- [社区](/cn-introduction/06-community.md) ## Articles -- [Aliases](/cn-introduction/articles/aliases.md) -Alias branch names to versions +- [别名](/cn-introduction/articles/aliases.md) +版本分支名称的别名。 - [自定义安装程序](/cn-introduction/articles/custom-installers.md) 修改某些特殊类型包的安装方式。 - [Handling Private Packages With Satis](/cn-introduction/articles/handling-private-packages-with-satis.md) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index cc833e0..fd82df3 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -2,6 +2,46 @@ 本章将解释所有在 `composer.json` 中可用的字段。 +--- + +- [composer.json](#composerjson) + - [JSON schema](#json-schema) + - [Root 包](#root-包) + - [属性](#属性) + - 包名 `name` + - 描述 `description` + - 版本 `version` + - 安装类型 `type` + - 关键字 `keywords` + - 项目主页 `homepage` + - 版本发布时间 `time` + - 许可协议 `license` + - 作者 `authors` + - 支持 `support` + - [Package links](#package-links) + - [require](#require) + - require-dev (root-only) + - [conflict](#conflict) + - [replace](#replace) + - [provide](#provide) + - suggest + - autoload + - PSR-0 + - Classmap + - Files + - include-path + - target-dir + - minimum-stability (root-only) + - prefer-stable (root-only) + - repositories (root-only) + - config (root-only) + - scripts (root-only) + - extra + - bin + - archive + +--- + ## JSON schema 我们有一个 [JSON schema](http://json-schema.org) 格式化文档，它也可以被用来验证你的 `composer.json` 文件。事实上，它已经被 `validate` 命令所使用。 你可以在这里找到它： [`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index ae947ea..c98bd20 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -1,70 +1,44 @@ -# Repositories +# 资源库 -This chapter will explain the concept of packages and repositories, what kinds -of repositories are available, and how they work. +本章将解释包和库的概念，什么样的存储库是可用的，以及它们如何工作。 -## Concepts +## 概述 -Before we look at the different types of repositories that exist, we need to -understand some of the basic concepts that composer is built on. +在此之前，我们看到存在不同类型的资源库，我们需要了解一些基本概念，以理解 Composer 是如何构建于其上的。 -### Package +### 包 -Composer is a dependency manager. It installs packages locally. A package is -essentially just a directory containing something. In this case it is PHP -code, but in theory it could be anything. And it contains a package -description which has a name and a version. The name and the version are used -to identify the package. +Composer 是一个依赖管理工具。它在本地安装一些资源包。一个包本质上就是一个包含东西的目录。通常情况下它存储 PHP 代码，但在理论上它可以是任何东西。并且它包含一个描述，其中有一个名称和一个版本号，这个名称和版本号用于识别该包。 -In fact, internally composer sees every version as a separate package. While -this distinction does not matter when you are using composer, it's quite -important when you want to change it. +事实上，在 composer 内部将每一个版本都视为一个单独的包。尽管在你使用 composer 时这种区别无关紧要，但当你想改变它时，这就显得至关重要。 -In addition to the name and the version, there is useful metadata. The information -most relevant for installation is the source definition, which describes where -to get the package contents. The package data points to the contents of the -package. And there are two options here: dist and source. +除了名称和版本号，还存放了有用的元数据。与安装关系最密切的是 source 信息，它申明了在哪里可以获得资源包的内容。包数据指向包内容，并有两种指向方式：dist 和 source。 -**Dist:** The dist is a packaged version of the package data. Usually a -released version, usually a stable release. +**Dist:** dist 指向一个存档，该存档是对一个资源包的某个版本的数据进行的打包。通常是已经发行的稳定版本。 -**Source:** The source is used for development. This will usually originate -from a source code repository, such as git. You can fetch this when you want -to modify the downloaded package. +**Source:** source 指向一个开发中的源。这通常是一个源代码仓库，例如 git。当你想要对下载下来的资源包进行修改时，可以这样获取。 -Packages can supply either of these, or even both. Depending on certain -factors, such as user-supplied options and stability of the package, one will -be preferred. +你可以使用其中任意一个，或者同时使用。这取决于其它的一些因素，比如“user-supplied 选项”和“包的稳定性”，前者将会被优先考虑。 -### Repository +### 资源库 -A repository is a package source. It's a list of packages/versions. Composer -will look in all your repositories to find the packages your project requires. +一个资源库是一个包的来源。它是一个 packages/versions 的列表。Composer 将查看所有你定义的 repositories 以找到你项目需要的资源包。 -By default only the Packagist repository is registered in Composer. You can -add more repositories to your project by declaring them in `composer.json`. +默认情况下已经将 Packagist.org 注册到 Composer。你可以在 `composer.json` 中申明更多的资源库，把它们加入你的项目中。 -Repositories are only available to the root package and the repositories -defined in your dependencies will not be loaded. Read the -[FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md) if you -want to learn why. +资源库的定义仅可用于“root 包”，而在你依赖的包中定义的资源库将不会被加载。如果你想了解其中的原因，请阅读 [FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md)。 ## Types ### Composer -The main repository type is the `composer` repository. It uses a single -`packages.json` file that contains all of the package metadata. +主资源库的类型为 `composer`。它使用一个单一的 `packages.json` 文件，包含了所有的资源包元数据。 -This is also the repository type that packagist uses. To reference a -`composer` repository, just supply the path before the `packages.json` file. -In case of packagist, that file is located at `/packages.json`, so the URL of -the repository would be `packagist.org`. For `example.org/packages.json` the -repository URL would be `example.org`. +这也是 packagist.org 所使用的资源类型。要引用一个 `composer` 资源库，只需要提供一个存放 `packages.json` 文件的 **目录路径**。比如要引用 `packagist.org` 下的 `/packages.json`，它的 URL 就应该是 `packagist.org`。而 `example.org/packages.json` 的 URL 应该是 `example.org`。 #### packages -The only required field is `packages`. The JSON structure is as follows: +唯一必须的字段是 `packages`。它的 JSON 结构如下： { "packages": { @@ -77,14 +51,13 @@ The only required field is `packages`. The JSON structure is as follows: } } -The `@composer.json` marker would be the contents of the `composer.json` from -that package version including as a minimum: +`@composer.json` 标记将会从 作为最低版本： would be the contents of the `composer.json` from that package version including as a minimum: * name * version * dist or source -Here is a minimal package definition: +这是一个最小的包定义： { "name": "smarty/smarty", @@ -95,7 +68,7 @@ Here is a minimal package definition: } } -It may include any of the other fields specified in the [schema](04-schema.md). +它可以包含任何在 [架构](04-schema.md) 中介绍的字段。 #### notify-batch -- 2.46.2 From 943c92bbfdef826cdd425b01f6790a91b3061ec5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 17:01:49 +0800 Subject: [PATCH 042/125] update --- README.md | 5 +++++ cn-introduction/04-schema.md | 5 +---- cn-introduction/05-repositories.md | 6 +++--- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index cb9a6bd..b963641 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,11 @@ Composer 中文文档 --- +希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。 +部分内容现阶段无法译全，已在 [issues](https://github.com/5-say/composer-doc-cn/issues) 中列出，如果能够收到您的宝贵建议，必将感激不尽。 + +--- + ## Book - [简介](/cn-introduction/00-intro.md) - [基本用法](/cn-introduction/01-basic-usage.md) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index fd82df3..ba25ed4 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -327,10 +327,7 @@ composer 原生支持以下4种类型： #### provide -List of other packages that are provided by this package. This is mostly -useful for common interfaces. A package could depend on some virtual -`logger` package, any library that implements this logger interface would -simply list it in `provide`. +List of other packages that are provided by this package. This is mostly useful for common interfaces. A package could depend on some virtual `logger` package, any library that implements this logger interface would simply list it in `provide`. ### suggest diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index c98bd20..bd36711 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -51,13 +51,13 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 } } -`@composer.json` 标记将会从 作为最低版本： would be the contents of the `composer.json` from that package version including as a minimum: +`@composer.json` 标记将会从此包的指定版本中读取 `composer.json` 的内容，其内至少应包含以下信息： * name * version * dist or source -这是一个最小的包定义： +这是一个最简单的包定义： { "name": "smarty/smarty", @@ -68,7 +68,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 } } -它可以包含任何在 [架构](04-schema.md) 中介绍的字段。 +它还可以包含任何在 [架构](04-schema.md) 中介绍的字段。 #### notify-batch -- 2.46.2 From 363ee4f91f6415d8bed8bd48f261fa5138ef0053 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 17:08:07 +0800 Subject: [PATCH 043/125] update README.md --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b963641..291ee8b 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ Composer 中文文档 --- -希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。 -部分内容现阶段无法译全，已在 [issues](https://github.com/5-say/composer-doc-cn/issues) 中列出，如果能够收到您的宝贵建议，必将感激不尽。 +- 希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。 +- 部分内容现阶段无法译全，已在 [issues](https://github.com/5-say/composer-doc-cn/issues) 中列出，如果能够收到您的宝贵建议，必将感激不尽。 +- **译者名单：** 卞成武、*期待您的加入* ... --- -- 2.46.2 From 19dec8e16d63967d11801c842934fac589505b4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 17:15:17 +0800 Subject: [PATCH 044/125] update README.md --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 291ee8b..33ff2b1 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ Composer 中文文档 - 希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。 - 部分内容现阶段无法译全，已在 [issues](https://github.com/5-say/composer-doc-cn/issues) 中列出，如果能够收到您的宝贵建议，必将感激不尽。 -- **译者名单：** 卞成武、*期待您的加入* ... --- -- 2.46.2 From d356531af4d9a052003a33efd503c0cc8943ecc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 17:51:26 +0800 Subject: [PATCH 045/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 27 +++++++++------------------ 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index bd36711..13fc93b 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -72,19 +72,15 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 #### notify-batch -The `notify-batch` field allows you to specify an URL that will be called -every time a user installs a package. The URL can be either an absolute path -(that will use the same domain as the repository) or a fully qualified URL. +`notify-batch` 字段允许你指定一个 URL，它将会在用户安装每一个包时被调用。该 URL 可以是（与其资源库相同域名的）绝对路径或者一个完整的 URL 地址。 -An example value: +例如使用下面的值： { "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: +对于 `example.org/packages.json` 包含的 `monolog/monolog` 包，它将会发送一个 `POST` 请求到 `example.org/downloads/`，使用下面的 JSON request body： { "downloads": [ @@ -92,18 +88,15 @@ JSON request body: ] } -The version field will contain the normalized representation of the version -number. +`version` 字段将包含标准化的版本号。 -This field is optional. +`notify-batch` 字段是可选的。 #### includes -For larger repositories it is possible to split the `packages.json` into -multiple files. The `includes` field allows you to reference these additional -files. +对于较大的资源库，可以拆分 `packages.json` 为多个文件。`includes` 字段允许你引用这些额外的文件。 -An example: +例： { "includes": { @@ -119,11 +112,9 @@ An example: } } -The SHA-1 sum of the file allows it to be cached and only re-requested if the -hash changed. +文件的 SHA-1 码允许它被缓存，仅在 hash 值改变时重新请求。 -This field is optional. You probably don't need it for your own custom -repository. +此字段是可选的。你也许并不需要它来自定义存储库。 #### provider-includes and providers-url -- 2.46.2 From ee51629dc00fd8e541dddba51823426312f95a2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 19:22:54 +0800 Subject: [PATCH 046/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 13fc93b..6107ccb 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -118,15 +118,11 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 #### provider-includes and providers-url -For very large repositories like packagist.org using the so-called provider -files is the preferred method. The `provider-includes` field allows you to -list a set of files that list package names provided by this repository. The -hash should be a sha256 of the files in this case. +的对于非常大的资源库，像 packagist.org 使用 so-called provider 文件是首选方法。`provider-includes` 字段允许你设置一个列表，来申明这个资源库提供的包名称。在这种情况下文件的哈希算法必须使用 sha256。 -The `providers-url` describes how provider files are found on the server. It -is an absolute path from the repository root. +`providers-url` 描述了如何在服务器上找到这些 provider 文件。它是以资源库的根目录为起点的绝对路径。 -An example: +例： { "provider-includes": { @@ -140,8 +136,7 @@ An example: "providers-url": "/p/%package%$%hash%.json" } -Those files contain lists of package names and hashes to verify the file -integrity, for example: +这些文件包含资源包的名称以及哈希值，以验证文件的完整性，例如： { "providers": { @@ -154,13 +149,9 @@ integrity, for example: } } -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 -themselves just contain package definitions as described [above](#packages). +上述文件申明了 `acme/foo` 和 `acme/bar` 可以在这个资源库找到，通过加载由 `providers-url` 引用的文件，替换 `%name%` 为包名并且替换 `%hash%` 为 sha256 的值。这些文件本身只包含上文提到的 [packages](#packages) 的定义。 -This field is optional. You probably don't need it for your own custom -repository. +这些字段是可选的。你也许并不需要它们来自定义存储库。 #### stream options -- 2.46.2 From 3b38be01cd4ac096f6df98e33ebee2b8069d1dd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 19:50:44 +0800 Subject: [PATCH 047/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 6107ccb..4cce787 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -155,16 +155,11 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 #### stream options -The `packages.json` file is loaded using a PHP stream. You can set extra options -on that stream using the `options` parameter. You can set any valid PHP stream -context option. See [Context options and parameters](http://php.net/manual/en/context.php) -for more information. +`packages.json` 文件是用一个 PHP 流加载的。你可以使用 `options` 参数来设定额外的流信息。你可以设置任何有效的PHP 流上下文选项。更多相关信息请查看 [Context options and parameters](http://php.net/manual/en/context.php)。 ### VCS -VCS stands for version control system. This includes versioning systems like -git, svn or hg. Composer has a repository type for installing packages from -these systems. +VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管理系统。Composer 有一个资源类型可以从这些系统安装软件包。 #### Loading a package from a VCS repository -- 2.46.2 From 3b5dcc55cee8be9da1567483d5d9379289b53650 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 7 Jan 2014 21:29:54 +0800 Subject: [PATCH 048/125] update --- README.md | 2 +- cn-introduction/01-basic-usage.md | 2 +- cn-introduction/02-libraries.md | 4 ++-- cn-introduction/03-cli.md | 2 +- cn-introduction/05-repositories.md | 28 ++++++---------------------- 5 files changed, 11 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 33ff2b1..80e2b46 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Composer 中文文档 ## Book - [简介](/cn-introduction/00-intro.md) - [基本用法](/cn-introduction/01-basic-usage.md) -- [库](/cn-introduction/02-libraries.md) +- [库（资源包）](/cn-introduction/02-libraries.md) - [命令行](/cn-introduction/03-cli.md) - [架构](/cn-introduction/04-schema.md) - [资源库](/cn-introduction/05-repositories.md) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 40a547f..bdac53e 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -194,4 +194,4 @@ Composer 将注册 [PSR-0](https://github.com/php-fig/fig-standards/blob/master/ > **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_namespaces.php` 文件，它返回一个关联数组映射了命名空间的目录。 -← [简介](00-intro.md) | [库](02-libraries.md) → +← [简介](00-intro.md) | [库（资源包）](02-libraries.md) → diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index 7e9ece2..ca4d7eb 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -1,10 +1,10 @@ -# 库 +# 库（资源包） 本章将告诉你如何通过 Composer 来安装你的库。 --- -- [库](#库) +- [库（资源包）](#库资源包) - [每一个项目都是一个包](#每一个项目都是一个包) - [平台软件包](#平台软件包) - [指明版本](#指明版本) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index b8bb04f..603f653 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -456,4 +456,4 @@ 如果设置为1，这个环境变量将使 Composer 在执行每一个命令时都放弃交互，相当于对所有命令都使用了 `--no-interaction`。可以在搭建 *虚拟机/持续集成服务器* 时这样设置。 -← [库](02-libraries.md) | [架构](04-schema.md) → +← [库（资源包）](02-libraries.md) | [架构](04-schema.md) → diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 4cce787..6b205c3 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -161,19 +161,11 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管理系统。Composer 有一个资源类型可以从这些系统安装软件包。 -#### Loading a package from a VCS repository +#### 从 VCS 资源库加载一个包 -There are a few use cases for this. The most common one is maintaining your -own fork of a third party library. If you are using a certain library for your -project and you decide to change something in the library, you will want your -project to use the patched version. If the library is on GitHub (this is the -case most of the time), you can simply fork it there and push your changes to -your fork. After that you update the project's `composer.json`. All you have -to do is add your fork as a repository and update the version constraint to -point to your custom branch. For version constraint naming conventions see -[Libraries](02-libraries.md) for more information. +这里有几个用例。最常见的是维护自己 fork 的第三方库。如果你在项目中使用某些库，并且你决定改变这些库内的某些东西，你会希望你项目中使用的是你自己的修正版本。如果这个库是在 GitHub 上（这种情况经常出现），你可以简单的 fork 它并 push 你的变更到这个 fork 里。在这之后你更新项目的 `composer.json` 文件，添加你的 fork 作为一个资源库，变更版本约束来指向你的自定义分支。关于版本约束的命名约定请查看 [库（资源包）](02-libraries.md)。 -Example assuming you patched monolog to fix a bug in the `bugfix` branch: +例如，假设你 fork 了 monolog，在 `bugfix` 分支修复了一个 bug： { "repositories": [ @@ -187,19 +179,11 @@ Example assuming you patched monolog to fix a bug in the `bugfix` branch: } } -When you run `php composer.phar update`, you should get your modified version -of `monolog/monolog` instead of the one from packagist. +当你运行 `php composer.phar update` 时，你应该得到你修改的版本，而不是 packagist.org 上的 `monolog/monolog`。 -Note that you should not rename the package unless you really intend to fork -it in the long term, and completely move away from the original package. -Composer will correctly pick your package over the original one since the -custom repository has priority over packagist. If you want to rename the -package, you should do so in the default (often master) branch and not in a -feature branch, since the package name is taken from the default branch. +注意，你不应该对包进行重命名，除非你真的打算摆脱原来的包，并长期的使用你自己的 fork。这样 Composer 就会正确获取你的包了。如果你确定要重命名这个包，你应该在默认分支（通常是 master 分支）上操作，而不是特性分支，因为包的名字取自默认分支。 -If other dependencies rely on the package you forked, it is possible to -inline-alias it so that it matches a constraint that it otherwise would not. -For more information [see the aliases article](articles/aliases.md). +如果其它包依赖你 fork 的这个分支，可能要对它做版本号的行内别名设置，才能够准确的识别版本约束。更多相关信息请查看 [别名](articles/aliases.md)。 #### Using private repositories -- 2.46.2 From 0ae5ab9d77c5ee82c607ccc484ca514bb34a800e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 00:45:30 +0800 Subject: [PATCH 049/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 6b205c3..d70ae2b 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -185,10 +185,9 @@ VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管 如果其它包依赖你 fork 的这个分支，可能要对它做版本号的行内别名设置，才能够准确的识别版本约束。更多相关信息请查看 [别名](articles/aliases.md)。 -#### Using private repositories +#### 使用私有资源库 -Exactly the same solution allows you to work with your private repositories at -GitHub and BitBucket: +完全相同的解决方案，也可以让你使用你 GitHub 和 BitBucket 上的私人代码库进行工作： { "require": { @@ -202,29 +201,24 @@ GitHub and BitBucket: ] } -The only requirement is the installation of SSH keys for a git client. +唯一的要求是为一个 git 客户端安装 SSH 秘钥。 -#### Git alternatives +#### Git 的备选方案 -Git is not the only version control system supported by the VCS repository. -The following are supported: +Git 并不是 VCS 资源库唯一支持的版本管理系统。 + +以下几种都是被支持的： * **Git:** [git-scm.com](http://git-scm.com) * **Subversion:** [subversion.apache.org](http://subversion.apache.org) * **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com) -To get packages from these systems you need to have their respective clients -installed. That can be inconvenient. And for this reason there is special -support for GitHub and BitBucket that use the APIs provided by these sites, to -fetch the packages without having to install the version control system. The -VCS repository provides `dist`s for them that fetch the packages as zips. +为了从这些系统获取资源包，你必须安装对应的客户端，这可能是不方便的。基于这个原因，这里提供了 GitHub 和 BitBucket 的 API 的特殊支持，以便在无需安装版本控制系统的情况下获取资源包。在 VCS 资源库提供的 `dist` 中获取 zip 存档。 * **GitHub:** [github.com](https://github.com) (Git) * **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial) -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`. +VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需要明确的指定一个 `git`、`svn` 或 `hg` 作为资源库类型，而不是 `vcs`。 #### Subversion Options -- 2.46.2 From 995b3431ba5ad34289695e2d11e369b925c59144 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 00:54:55 +0800 Subject: [PATCH 050/125] =?UTF-8?q?=E8=BD=AC=E7=94=A8=E8=8B=B1=E6=96=87?= =?UTF-8?q?=E9=94=9A=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/00-intro.md | 6 ++++-- cn-introduction/04-schema.md | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md index ee958d3..45e303a 100644 --- a/cn-introduction/00-intro.md +++ b/cn-introduction/00-intro.md @@ -1,11 +1,12 @@ + # 简介 Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖的代码库，它会在你的项目中为你安装他们。 --- -- [简介](#简介) - - [依赖管理](#依赖管理) +- [简介](#Introduction) + - [依赖管理](#Dependency management) - [声明依赖关系](#声明依赖关系) - [系统要求](#系统要求) - [安装 - *nix](#安装---nix) @@ -21,6 +22,7 @@ Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖 --- + ## 依赖管理 Composer 不是一个包管理器。是的，它涉及 "packages" 和 "libraries"，但它在每个项目的基础上进行管理，在你项目的某个目录中（例如 `vendor`）进行安装。默认情况下它不会在全局安装任何东西。因此，这仅仅是一个依赖管理。 diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index ba25ed4..d4ebcf2 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -8,8 +8,8 @@ - [JSON schema](#json-schema) - [Root 包](#root-包) - [属性](#属性) - - 包名 `name` - - 描述 `description` + - [包名 `name`](#包名-name) + - [描述 `description`](#描述-description) - 版本 `version` - 安装类型 `type` - 关键字 `keywords` -- 2.46.2 From 91ba8d5804fe75b2534ceae663c12111c2c2573c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 01:05:35 +0800 Subject: [PATCH 051/125] update 00-intro.md --- cn-introduction/00-intro.md | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md index 45e303a..1cc3ca5 100644 --- a/cn-introduction/00-intro.md +++ b/cn-introduction/00-intro.md @@ -7,18 +7,18 @@ Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖 - [简介](#Introduction) - [依赖管理](#Dependency management) - - [声明依赖关系](#声明依赖关系) - - [系统要求](#系统要求) - - [安装 - *nix](#安装---nix) - - [下载 Composer 的可执行文件](#下载-composer-的可执行文件) - - [局部安装](#局部安装) - - [全局安装](#全局安装) - - [全局安装 (on OSX via homebrew)](#全局安装-on-osx-via-homebrew) - - [安装 - Windows](#安装---windows) - - [使用安装程序](#使用安装程序) - - [手动安装](#手动安装) - - [使用 Composer](#使用-composer) - - [自动加载](#自动加载) + - [声明依赖关系](#Declaring dependencies) + - [系统要求](#System Requirements) + - [安装 - *nix](#Installation - *nix) + - [下载 Composer 的可执行文件](#Downloading the Composer Executable) + - [局部安装](#Locally) + - [全局安装](#Globally) + - [全局安装 (on OSX via homebrew)](#Globally on OSX via homebrew) + - [安装 - Windows](#Installation - Windows) + - [使用安装程序](#Using the Installer) + - [手动安装](#Manual Installation) + - [使用 Composer](#Using Composer) + - [自动加载](#Autoloading) --- @@ -40,6 +40,7 @@ c) 你声明你所依赖的东西。 d) Composer 会找出哪个版本的包需要安装，并安装它们（将它们下载到你的项目中）。 + ## 声明依赖关系 比方说，你正在创建一个项目，你需要一个库来做日志记录。你决定使用 [monolog](https://github.com/Seldaek/monolog)。为了将它添加到你的项目中，你所需要做的就是创建一个 `composer.json` 文件，其中描述了项目的依赖关系。 @@ -52,6 +53,7 @@ d) Composer 会找出哪个版本的包需要安装，并安装它们（将它 我们只要指出我们的项目需要一些 `monolog/monolog` 的包，从 `1.2` 开始的任何版本。 + ## 系统要求 运行 Composer 需要 PHP 5.3.2+ 以上版本。一些敏感的 PHP 设置和编译标志也是必须的，但对于任何不兼容项安装程序都会抛出警告。 @@ -60,10 +62,13 @@ d) Composer 会找出哪个版本的包需要安装，并安装它们（将它 Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX 平台上运行的同样出色。 + ## 安装 - *nix + ### 下载 Composer 的可执行文件 + #### 局部安装 要真正获取 Composer，我们需要做两件事。首先安装 Composer （同样的，这意味着它将下载到你的项目中）： @@ -76,6 +81,7 @@ Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX $ curl -sS https://getcomposer.org/installer | php -- --install-dir=bin + #### 全局安装 你可以将此文件放在任何地方。如果你把它放在系统的 `PATH` 目录中，你就能在全局访问它。 在类Unix系统中，你甚至可以在使用时不加 `php` 前缀。 @@ -90,6 +96,7 @@ Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX 现在只需要运行 `composer` 命令就可以使用 Composer 而不需要输入 `php composer.phar`。 + #### 全局安装 (on OSX via homebrew) Composer 是 homebrew-php 项目的一部分。 @@ -101,14 +108,17 @@ Composer 是 homebrew-php 项目的一部分。 > **注意：** 如果你收到一个错误 PHP53 or higher is missing 请执行下面的命令来安装 php > `brew install php53-intl` + ## 安装 - Windows + ### 使用安装程序 这是将 Composer 安装在你机器上的最简单的方法。 下载并且运行 [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe)，它将安装最新版本的 Composer ，并设置好系统的环境变量，因此你可以在任何目录下直接使用 `composer` 命令。 + ### 手动安装 设置系统的环境变量 `PATH` 并运行安装命令下载 composer.phar 文件： @@ -129,6 +139,7 @@ Composer 是 homebrew-php 项目的一部分。 C:\Users\username> + ## 使用 Composer 现在我们将使用 Composer 来安装项目的依赖。如果在当前目录下没有一个 `composer.json` 文件，请查看[基本用法](01-basic-usage.md)章节。 @@ -143,6 +154,7 @@ Composer 是 homebrew-php 项目的一部分。 继续 [上面的例子](#声明依赖关系)，这里将下载 monolog 到 `vendor/monolog/monolog` 目录。 + ## 自动加载 除了库的下载，Composer 还准备了一个自动加载文件，它可以加载 Composer 下载的库中所有的类文件。使用它，你只需要将下面这行代码添加到你项目的引导文件中： -- 2.46.2 From fea663d2233a773fab35162920e69f63d6a0d968 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 01:15:01 +0800 Subject: [PATCH 052/125] update 01-basic-usage.md --- cn-introduction/01-basic-usage.md | 38 ++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index bdac53e..7ddef0a 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -1,22 +1,24 @@ + # 基本用法 --- -- [基本用法](#基本用法) - - [安装](#安装) - - [`composer.json`：项目安装](#composerjson项目安装) - - [关于 `require` Key](#关于-require-key) - - [包名称](#包名称) - - [包版本](#包版本) - - [下一个重要版本（波浪号运算符）](#下一个重要版本波浪号运算符) - - [稳定性](#稳定性) - - [安装依赖关系](#安装依赖关系) - - [`composer.lock` - 锁文件](#composerlock---锁文件) - - [packagist](#packagist) - - [自动加载](#自动加载) +- [基本用法](#Basic usage) + - [安装](#Installation) + - [`composer.json`：项目安装](#composer.json Project Setup) + - [关于 `require` Key](#The require Key) + - [包名称](#Package Names) + - [包版本](#Package Versions) + - [下一个重要版本（波浪号运算符）](#Next Significant Release) + - [稳定性](#Stability) + - [安装依赖关系](#Installing Dependencies) + - [`composer.lock` - 锁文件](#composer.lock - The Lock File) + - [packagist](#Packagist) + - [自动加载](#Autoloading) --- + ## 安装 安装 Composer，你只需要下载 `composer.phar` 可执行文件。 @@ -37,12 +39,14 @@ > $ curl -sS https://getcomposer.org/installer | php -- --check > $ curl -sS https://getcomposer.org/installer | php -- --help + ## `composer.json`：项目安装 要开始在你的项目中使用 Composer，你只需要一个 `composer.json` 文件。该文件包含了项目的依赖和其它的一些元数据。 这个 [JSON format](http://json.org/) 是很容易编写的。它允许你定义嵌套结构。 + ### 关于 `require` Key 第一件事情（并且往往只需要做这一件事），你需要在 `composer.json` 文件中指定 `require` key 的值。你只需要简单的告诉 Composer 你的项目需要依赖哪些包。 @@ -55,12 +59,14 @@ 你可以看到， `require` 需要一个 **包名称** （例如 `monolog/monolog`） 映射到 **包版本** （例如 `1.0.*`） 的对象。 + ### 包名称 包名称由供应商名称和其项目名称构成。通常容易产生相同的项目名称，而供应商名称的存在则很好的解决了命名冲突的问题。它允许两个不同的人创建同样名为 `json` 的库，而之后它们将被命名为 `igorw/json` 和 `seldaek/json`。 这里我们需要引入 `monolog/monolog`，供应商名称与项目的名称相同，对于一个具有唯一名称的项目，我们推荐这么做。它还允许以后在同一个命名空间添加更多的相关项目。如果你维护着一个库，这将使你可以很容易的把它分离成更小的部分。 + ### 包版本 在前面的例子中，我们引入的 monolog 版本指定为 `1.0.*`。这表示任何从 `1.0` 开始的开发分支，它将会匹配 `1.0.0`、`1.0.2` 或者 `1.0.20`。 @@ -104,14 +110,17 @@ + ### 下一个重要版本（波浪号运算符） `~` 最好用例子来解释： `~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应该都没有向后兼容性问题，所以效果很好。你还会看到它的另一种用法，使用 `~` 指定最低版本，但允许版本号的最后一位数字上升。 + ### 稳定性 默认情况下只有稳定的发行版才会被考虑在内。如果你也想获得 RC、beta、alpha 或 dev 版本，你可以使用 [稳定标志](04-schema.md#package-links)。你可以对所有的包做 [最小稳定性](04-schema.md#minimum-stability) 设置，而不是每个依赖逐一设置。 + ## 安装依赖关系 获取定义的依赖到你的本地项目，只需要调用 `composer.phar` 运行 `install` 命令。 @@ -127,6 +136,7 @@ 另一件事是 `install` 命令将创建一个 `composer.lock` 文件到你项目的根目录中。 + ## `composer.lock` - 锁文件 在安装依赖后，Composer 将把安装时确切的版本号列表写入 `composer.lock` 文件。这将锁定改项目的特定版本。 @@ -150,7 +160,8 @@ > **注意：** 对于库，并不一定建议提交锁文件 > 请参考：[库的锁文件](02-libraries.md#lock-file). -## packagist + +## Packagist [packagist](https://packagist.org/) 是 Composer 的主要资源库。 一个 Composer 的库基本上是一个包的源：记录了可以得到包的地方。Packagist 的目标是成为大家使用库资源的中央存储平台。这意味着你可以 `require` 那里的任何包。 @@ -158,6 +169,7 @@ 任何支持 Composer 的开源项目应该发布自己的包在 packagist 上。虽然并不一定要发布在 packagist 上来使用 Composer，但它使我们的编程生活更加轻松。 + ## 自动加载 对于库的自动加载信息，Composer 生成了一个 `vendor/autoload.php` 文件。你可以简单的引入这个文件，你会得到一个免费的自动加载支持。 -- 2.46.2 From 8ec33d5599d9039b2389e983cc4e6e8f17dac918 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 01:21:43 +0800 Subject: [PATCH 053/125] update 02-libraries.md --- cn-introduction/01-basic-usage.md | 2 +- cn-introduction/02-libraries.md | 30 ++++++++++++++++++++---------- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 7ddef0a..65f0f8a 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -13,7 +13,7 @@ - [稳定性](#Stability) - [安装依赖关系](#Installing Dependencies) - [`composer.lock` - 锁文件](#composer.lock - The Lock File) - - [packagist](#Packagist) + - [Packagist](#Packagist) - [自动加载](#Autoloading) --- diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index ca4d7eb..f592a8b 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -1,22 +1,24 @@ + # 库（资源包） 本章将告诉你如何通过 Composer 来安装你的库。 --- -- [库（资源包）](#库资源包) - - [每一个项目都是一个包](#每一个项目都是一个包) - - [平台软件包](#平台软件包) - - [指明版本](#指明版本) - - [标签](#标签) - - [分支](#分支) - - [别名](#别名) - - [锁文件](#锁文件) - - [发布到 VCS（线上版本控制系统）](#发布到-vcs线上版本控制系统) - - [发布到 packagist](#发布到-packagist) +- [库（资源包）](#Libraries) + - [每一个项目都是一个包](#Every project is a package) + - [平台软件包](#Platform packages) + - [指明版本](#Specifying the version) + - [标签](#Tags) + - [分支](#Branches) + - [别名](#Aliases) + - [锁文件](#Lock file) + - [发布到 VCS（线上版本控制系统）](#Publishing to a VCS) + - [发布到 packagist](#Publishing to packagist) --- + ## 每一个项目都是一个包 只要你有一个 `composer.json` 文件在目录中，那么整个目录就是一个包。当你添加一个 `require` 到项目中，你就是在创建一个依赖于其它库的包。你的项目和库之间唯一的区别是，你的项目是一个没有名字的包。 @@ -36,6 +38,7 @@ > 那么使用你 github 上的用户名通常是不错的选择。 > 虽然包名不区分大小写，但惯例是使用小写字母，并用连字符作为单词的分隔。 + ## 平台软件包 Composer 将那些已经安装在系统上，但并不是由 Composer 安装的包视为一个虚拟的平台软件包。这包括PHP本身，PHP扩展和一些系统库。 @@ -48,6 +51,7 @@ Composer 将那些已经安装在系统上，但并不是由 Composer 安装的 你可以使用 `composer show --platform` 命令来获取可用的平台软件包的列表。 + ## 指明版本 你需要一些方法来指明自己开发的包的版本，当你在 Packagist 上发布自己的包，它能够从 VCS (git, svn, @@ -61,6 +65,7 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 > **注意：** 你应该尽量避免手动设置版本号，因为标签的值必须与标签名相匹配。 + ### 标签 对于每一个看起来像版本号的标签，都会相应的创建一个包的版本。它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式，`-patch`、`-alpha`、`-beta` 或 `-RC` 这些后缀是可选的。在后缀之后也可以再跟上一个数字。 @@ -78,6 +83,7 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 > 由于在需要 `require` 一个[版本的约束](01-basic-usage.md#包版本)时是不允许这种前缀的， > 因此 `v` 将被省略（例如标签 `V1.0.0` 将创建 `1.0.0` 版本）。 + ### 分支 对于每一个分支，都会相应的创建一个包的开发版本。如果分支名看起来像一个版本号，那么将创建一个如同 `{分支名}-dev` 的包版本号。例如一个分支 `2.0` 将产生一个 `2.0.x-dev` 包版本（加入了 `.x` 是出于技术的原因，以确保它被识别为一个分支，而 `2.0.x` 的分支名称也是允许的，它同样会被转换为 `2.0.x-dev`）。如果分支名看起来不像一个版本号，它将会创建 `dev-{分支名}` 形式的版本号。例如 `master` 将产生一个 `dev-master` 的版本号。 @@ -91,18 +97,21 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 > **注意：** 当你安装一个新的版本时，将会自动从它 `source` 中拉取。 > 详细请查看 [`install`](03-cli.md#install) 命令。 + ### 别名 它表示一个包版本的别名。例如，你可以为 `dev-master` 设置别名 `1.0.x-dev`，这样就可以通过 require `1.0.x-dev` 来得到 `dev-master` 版本的包。 详细请查看[“别名”](articles/aliases.md)。 + ## 锁文件 如果你愿意，可以在你的项目中提交 `composer.lock` 文件。他将帮助你的团队始终针对同一个依赖版本进行测试。任何时候，这个锁文件都只对于你的项目产生影响。 如果你不想提交锁文件，并且你正在使用 Git，那么请将它添加到 `.gitignore` 文件中。 + ## 发布到 VCS（线上版本控制系统） 一旦你有一个包含 `composer.json` 文件的库存储在线上版本控制系统（例如：Git），你的库就可以被 Composer 所安装。在这个例子中，我们将 `acme/hello-world` 库发布在 GitHub 上的 `github.com/username/hello-world` 中。 @@ -139,6 +148,7 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 **小结：** 任何含有 `composer.json` 的 `GIT`、`SVN`、`HG` 存储库，都可以通过 `require` 字段指定“包来源”和“声明依赖”来添加到你的项目中。 + ## 发布到 packagist 好的，你现在可以发布你的包了，但你不会希望你的用户每次都这样繁琐的指定包的来源。 -- 2.46.2 From 823297db1ed870d7c7e00c5637e736e955bf2ace Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 08:50:51 +0800 Subject: [PATCH 054/125] =?UTF-8?q?update=2003-cli.md=20=E9=87=87=E7=94=A8?= =?UTF-8?q?=E8=8B=B1=E6=96=87=E9=94=9A=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/03-cli.md | 124 ++++++++++++++++++++++++++------------ 1 file changed, 87 insertions(+), 37 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 603f653..e1cca48 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -1,3 +1,4 @@ + # 命令行 你已经学会了如何使用命令行界面做一些事情。本章将向你介绍所有可用的命令。 @@ -6,46 +7,46 @@ --- -- [命令行](#命令行) -- [全局参数](#全局参数) - - [进程退出代码](#进程退出代码) - - [初始化 `init`](#初始化-init) - - [参数](#初始化-参数) - - [安装 `install`](#安装-install) - - [参数](#安装-参数) - - [更新 `update`](#更新-update) - - [参数](#更新-参数) - - [申明依赖 `require`](#申明依赖-require) - - [参数](#申明依赖-参数) - - [全局执行 `global`](#全局执行-global) - - [搜索 `search`](#搜索-search) - - [参数](#搜索-参数) - - [展示 `show`](#展示-show) - - [参数](#展示-参数) - - [依赖性检测 `depends`](#依赖性检测-depends) - - [参数](#依赖性检测-参数) - - [有效性检测 `validate`](#有效性检测-validate) - - [依赖包状态检测 `status`](#依赖包状态检测-status) - - [自我更新 `self-update`](#自我更新-self-update) - - [参数](#自我更新-参数) - - [更改配置 `config`](#更改配置-config) - - [使用方法](#更改配置-使用方法) - - [参数](#更改配置-参数) - - [修改包来源](#修改包来源) - - [创建项目 `create-project`](#创建项目-create-project) - - [参数](#创建项目-参数) - - [打印自动加载索引 `dump-autoload`](#打印自动加载索引-dump-autoload) - - [参数](#打印自动加载索引-参数) - - [查看许可协议 `licenses`](#查看许可协议-licenses) - - [执行脚本 `run-script`](#执行脚本-run-script) - - [诊断 `diagnose`](#诊断-diagnose) - - [归档 `archive`](#归档-archive) - - [参数](#归档-参数) - - [获取帮助信息 `help`](#获取帮助信息-help) - - [环境变量](#环境变量) - - [COMPOSER](#composer) - - [COMPOSER_ROOT_VERSION](#composer_root_version) - - [COMPOSER_VENDOR_DIR](#composer_vendor_dir) - - [COMPOSER_BIN_DIR](#composer_bin_dir) - - [http_proxy or HTTP_PROXY](#http_proxy-or-http_proxy) +- [命令行](#Command-line interface) +- [全局参数](#Global Options) + - [进程退出代码](#Process Exit Codes) + - [初始化 `init`](#init) - - [参数](#init-Options) + - [安装 `install`](#install) - - [参数](#install-Options) + - [更新 `update`](#update) - - [参数](#update-Options) + - [申明依赖 `require`](#require) - - [参数](#require-Options) + - [全局执行 `global`](#global) + - [搜索 `search`](#search) - - [参数](#search-Options) + - [展示 `show`](#show) - - [参数](#show-Options) + - [依赖性检测 `depends`](#depends) - - [参数](#depends-Options) + - [有效性检测 `validate`](#validate) + - [依赖包状态检测 `status`](#status) + - [自我更新 `self-update`](#self-update) - - [参数](#self-update-Options) + - [更改配置 `config`](#config) - - [使用方法](#config-Usage) - - [参数](#config-Options) - - [修改包来源](#Modifying Repositories) + - [创建项目 `create-project`](#create-project) - - [参数](#create-project-Options) + - [打印自动加载索引 `dump-autoload`](#dump-autoload) - - [参数](#dump-autoload-Options) + - [查看许可协议 `licenses`](#licenses) + - [执行脚本 `run-script`](#run-script) + - [诊断 `diagnose`](#diagnose) + - [归档 `archive`](#archive) - - [参数](#archive-Options) + - [获取帮助信息 `help`](#help) + - [环境变量](#Environment variables) + - [COMPOSER](#COMPOSER) + - [COMPOSER_ROOT_VERSION](#COMPOSER_ROOT_VERSION) + - [COMPOSER_VENDOR_DIR](#COMPOSER_VENDOR_DIR) + - [COMPOSER_BIN_DIR](#COMPOSER_BIN_DIR) + - [http_proxy or HTTP_PROXY](#http_proxy or HTTP_PROXY) - [no_proxy](#no_proxy) - - [HTTP_PROXY_REQUEST_FULLURI](#http_proxy_request_fulluri) - - [HTTPS_PROXY_REQUEST_FULLURI](#https_proxy_request_fulluri) - - [COMPOSER_HOME](#composer_home) - - [COMPOSER_HOME/config.json](#composer_homeconfigjson) - - [COMPOSER_CACHE_DIR](#composer_cache_dir) - - [COMPOSER_PROCESS_TIMEOUT](#composer_process_timeout) - - [COMPOSER_DISCARD_CHANGES](#composer_discard_changes) - - [COMPOSER_NO_INTERACTION](#composer_no_interaction) + - [HTTP_PROXY_REQUEST_FULLURI](#HTTP_PROXY_REQUEST_FULLURI) + - [HTTPS_PROXY_REQUEST_FULLURI](#HTTPS_PROXY_REQUEST_FULLURI) + - [COMPOSER_HOME](#COMPOSER_HOME) + - [COMPOSER_HOME/config.json](#COMPOSER_HOME-config.json) + - [COMPOSER_CACHE_DIR](#COMPOSER_CACHE_DIR) + - [COMPOSER_PROCESS_TIMEOUT](#COMPOSER_PROCESS_TIMEOUT) + - [COMPOSER_DISCARD_CHANGES](#COMPOSER_DISCARD_CHANGES) + - [COMPOSER_NO_INTERACTION](#COMPOSER_NO_INTERACTION) --- - + ## 全局参数 下列参数可与每一个命令结合使用： @@ -63,12 +64,14 @@ * **--no-ansi:** 关闭 ANSI 输出。 * **--version (-V):** 显示当前应用程序的版本信息。 + ## 进程退出代码 * **0:** 正常 * **1:** 通用/未知错误 * **2:** 依赖关系处理错误 + ## 初始化 `init` 在 [“库”](02-libraries.md) 那一章我们看到了如何手动创建 `composer.json` 文件。实际上还有一个 `init` 命令可以更容易的做到这一点。 @@ -77,6 +80,7 @@ $ php composer.phar init + ### 初始化-参数 * **--name:** 包的名称。 @@ -87,6 +91,7 @@ * **--require-dev:** 开发版的依赖包，内容格式与 **--require** 相同。 * **--stability (-s):** `minimum-stability` 字段的值。 + ## 安装 `install` `install` 命令从当前目录读取 `composer.json` 文件，处理了依赖关系，并把其安装到 `vendor` 目录下。 @@ -97,6 +102,7 @@ 如果没有 `composer.lock` 文件，composer 将在处理完依赖关系后创建它。 + ### 安装-参数 * **--prefer-source:** 下载包的方式有两种： `source` @@ -110,6 +116,7 @@ * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 * **--optimize-autoloader (-o):** 转换 PSR-0 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。 + ## 更新 `update` 为了获取依赖的最新版本，并且升级 `composer.lock` 文件，你应该使用 `update` 命令。 @@ -126,6 +133,7 @@ $ php composer.phar update vendor/* + ### 更新-参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 @@ -140,6 +148,7 @@ * **--lock:** 仅更新 lock 文件的 hash，取消有关 lock 文件过时的警告。 * **--with-dependencies** 同时更新白名单内包的依赖关系，这将进行递归更新。 + ## 申明依赖 `require` `require` 命令增加新的依赖包到当前目录的 `composer.json` 文件中。 @@ -152,6 +161,7 @@ $ php composer.phar require vendor/package:2.* vendor/package2:dev-master + ### 申明依赖-参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 @@ -160,6 +170,7 @@ * **--no-update:** 禁用依赖关系的自动更新。 * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 + ## 全局执行 `global` `global` 命令允许你在 [COMPOSER_HOME](#composer-home) 目录下执行其它命令，像 `install`、`require` 或 `update`。 @@ -172,6 +183,7 @@ $ php composer.phar global update + ## 搜索 `search` `search` 命令允许你为当前项目搜索依赖包，通常它只搜索 packagist.org 上的包，你可以简单的输入你的搜索条件。 @@ -180,10 +192,12 @@ 您也可以通过传递多个参数来进行多条件搜索。 + ### 搜索-参数 * **--only-name (-N):** 仅针对指定的名称搜索（完全匹配）。 + ## 展示 `show` 列出所有可用的软件包，你可以使用 `show` 命令。 @@ -213,12 +227,14 @@ $ php composer.phar show monolog/monolog 1.0.2 + ### 展示-参数 * **--installed (-i):** 列出已安装的依赖包。 * **--platform (-p):** 仅列出平台软件包（PHP 与它的扩展）。 * **--self (-s):** 仅列出当前项目信息。 + ## 依赖性检测 `depends` `depends` 命令可以查出已安装在你项目中的某个包，是否正在被其它的包所依赖，并列出他们。 @@ -231,16 +247,19 @@ symfony/monolog-bridge symfony/symfony + ### 依赖性检测-参数 * **--link-type:** 检测的类型，默认为 `require` 也可以是 `require-dev`。 + ## 有效性检测 `validate` 在提交 `composer.json` 文件，和创建 tag 前，你应该始终运行 `validate` 命令。它将检测你的 `composer.json` 文件是否是有效的 $ php composer.phar validate + ## 依赖包状态检测 `status` 如果你经常修改依赖包里的代码，并且它们是从 source（自定义源）进行安装的，那么 `status` 命令允许你进行检查，如果你有任何本地的更改它将会给予提示。 @@ -254,6 +273,7 @@ vendor/seld/jsonlint: M README.mdown + ## 自我更新 `self-update` 将 Composer 自身升级到最新版本，只需要运行 `self-update` 命令。它将替换你的 `composer.phar` 文件到最新版本。 @@ -268,17 +288,20 @@ $ sudo composer self-update + ### 自我更新-参数 * **--rollback (-r):** 回滚到你已经安装的最后一个版本。 * **--clean-backups:** 在更新过程中删除旧的备份，这使得更新过后的当前版本是唯一可用的备份。 + ## 更改配置 `config` `config` 命令允许你编辑 Composer 的一些基本设置，无论是本地的 `composer.json` 或者全局的 `config.json` 文件。 $ php composer.phar config --list + ### 更改配置-使用方法 `config [options] [setting-key] [setting-value1] ... [setting-valueN]` @@ -287,6 +310,7 @@ 有效的配置选项，请查看“架构”章节的 [config](04-schema.md#config) 。 + ### 更改配置-参数 * **--global (-g):** 操作位于 `$COMPOSER_HOME/config.json` 的全局配置文件。如果不指定该参数，此命令将影响当前项目的 composer.json 文件，或 `--file` 参数所指向的文件。 @@ -295,12 +319,14 @@ * **--list (-l):** 显示当前配置选项的列表。当存在 `--global` 参数时，将会显示全局配置选项的列表。 * **--file="..." (-f):** 在一个指定的文件上操作，而不是 composer.json。注意：不能与 `--global` 参数一起使用。 + ### 修改包来源 除了修改配置选项， `config` 命令还支持通过以下方法修改来源信息： $ php composer.phar config repositories.foo vcs http://github.com/foo/bar + ## 创建项目 `create-project` 你可以使用 Composer 从现有的包中创建一个新的项目。这相当于执行了一个 `git clone` 或 `svn checkout` 命令后将这个包的依赖安装到它自己的 vendor 目录。 @@ -321,6 +347,7 @@ 默认情况下，这个命令会在 packagist.org 上查找你指定的包。 + ### 创建项目-参数 * **--repository-url:** 提供一个自定义的储存库来搜索包，这将被用来代替 packagist.org。可以是一个指向 `composer` 资源库的 HTTP URL，或者是指向某个 `packages.json` 文件的本地路径。 @@ -334,51 +361,61 @@ * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 * **--keep-vcs:** 创建时跳过缺失的 VCS 。如果你在非交互模式下运行创建命令，这将是非常有用的。 + ## 打印自动加载索引 `dump-autoload` 某些情况下你需要更新 autoloader，例如在你的包中加入了一个新的类。你可以使用 `dump-autoload` 来完成，而不必执行 `install` 或 `update` 命令。 此外，它可以打印一个优化过的，符合 PSR-0 规范的类的索引，这也是出于对性能的可考虑。在大型的应用中会有许多类文件，而 autoloader 会占用每个请求的很大一部分时间，使用 classmaps 或许在开发时不太方便，但它在保证性能的前提下，仍然可以获得 PSR-0 规范带来的便利。 + ### 打印自动加载索引-参数 * **--optimize (-o):** 转换 PSR-0 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。 + ## 查看许可协议 `licenses` 列出已安装的每个包的名称、版本、许可协议。可以使用 `--format=json` 参数来获取 JSON 格式的输出。 + ## 执行脚本 `run-script` 你可以运行此命令来手动执行 [脚本](articles/scripts.md)，只需要指定脚本的名称，可选的 `--no-dev` 参数允许你禁用开发者模式。 + ## 诊断 `diagnose` 如果你觉得发现了一个 bug 或是程序行为变得怪异，你可能需要运行 `diagnose` 命令，来帮助你检测一些常见的问题。 $ php composer.phar diagnose + ## 归档 `archive` 此命令用来对指定包的指定版本进行 zip/tar 归档。它也可以用来归档你的整个项目，不包括 excluded/ignored（排除/忽略）的文件。 $ php composer.phar archive vendor/package 2.0.21 --format=zip + ### 归档-参数 * **--format (-f):** 指定归档格式：tar 或 zip（默认为 tar）。 * **--dir:** 指定归档存放的目录（默认为当前目录）。 + ## 获取帮助信息 `help` 使用 `help` 可以获取指定命令的帮助信息。 $ php composer.phar help install + ## 环境变量 你可以设置一些环境变量来覆盖默认的配置。建议尽可能的在 `composer.json` 的 `config` 字段中设置这些值，而不是通过命令行设置环境变量。值得注意的是环境变量中的值，将始终优先于 `composer.json` 中所指定的值。 + ### COMPOSER 环境变量 `COMPOSER` 可以为 `composer.json` 文件指定其它的文件名。 @@ -387,38 +424,46 @@ $ COMPOSER=composer-other.json php composer.phar install + ### COMPOSER_ROOT_VERSION 通过设置这个环境变量，你可以指定 root 包的版本，如果程序不能从 VCS 上猜测出版本号，并且未在 `composer.json` 文件中申明。 + ### COMPOSER_VENDOR_DIR 通过设置这个环境变量，你可以指定 composer 将依赖安装在 `vendor` 以外的其它目录中。 + ### COMPOSER_BIN_DIR 通过设置这个环境变量，你可以指定 `bin`（[Vendor Binaries](articles/vendor-binaries.md)）目录到 `vendor/bin` 以外的其它目录。 + ### http_proxy or HTTP_PROXY 如果你是通过 HTTP 代理来使用 Composer，你可以使用 `http_proxy` 或 `HTTP_PROXY` 环境变量。只要简单的将它设置为代理服务器的 URL。许多操作系统已经为你的服务设置了此变量。 建议使用 `http_proxy`（小写）或者两者都进行定义。因为某些工具，像 git 或 curl 将使用 `http_proxy` 小写的版本。另外，你还可以使用 `git config --global http.proxy ` 来单独设置 git 的代理。 + ### no_proxy 如果你是使用代理服务器，并且想要对某些域名禁用代理，就可以使用 `no_proxy` 环境变量。只需要输入一个逗号相隔的域名 *排除* 列表。 此环境变量接受域名、IP 以及 CIDR地址块。你可以将它限制到一个端口（例如：`:80`）。你还可以把它设置为 `*` 来忽略所有的 HTTP 代理请求。 + ### HTTP_PROXY_REQUEST_FULLURI 如果你使用了 HTTP 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。 + ### HTTPS_PROXY_REQUEST_FULLURI 如果你使用了 HTTPS 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。 + ### COMPOSER_HOME `COMPOSER_HOME` 环境变量允许你改变 Composer 的主目录。这是一个隐藏的、所有项目共享的全局目录（对本机的所有用户都可用）。 @@ -428,6 +473,7 @@ - OSX `/Users//.composer`。 - Windows `C:\Users\\AppData\Roaming\Composer`。 + #### COMPOSER_HOME/config.json 你可以在 `COMPOSER_HOME` 目录中放置一个 `config.json` 文件。在你执行 `install` 和 `update` 命令时，Composer 会将它与你项目中的 `composer.json` 文件进行合并。 @@ -436,6 +482,7 @@ 若 _全局_ 和 _项目_ 存在相同配置项，那么项目中的 `composer.json` 文件拥有更高的优先级。 + ### COMPOSER_CACHE_DIR `COMPOSER_CACHE_DIR` 环境变量允许你设置 Composer 的缓存目录，这也可以通过 [`cache-dir`](04-schema.md#config) 进行配置。 @@ -444,14 +491,17 @@ - \*nix and OSX `$COMPOSER_HOME/cache`。 - Windows `C:\Users\\AppData\Local\Composer` 或 `%LOCALAPPDATA%/Composer`。 + ### COMPOSER_PROCESS_TIMEOUT 这个环境变量控制着 Composer 执行命令的等待时间（例如：git 命令）。默认值为300秒（5分钟）。 + ### COMPOSER_DISCARD_CHANGES 这个环境变量控制着 discard-changes [config option](04-schema.md#config)。 + ### COMPOSER_NO_INTERACTION 如果设置为1，这个环境变量将使 Composer 在执行每一个命令时都放弃交互，相当于对所有命令都使用了 `--no-interaction`。可以在搭建 *虚拟机/持续集成服务器* 时这样设置。 -- 2.46.2 From bd0b416d3b8ba5d3fc4750f7d95137d51ebee217 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 08:54:51 +0800 Subject: [PATCH 055/125] update 03-cli.md --- cn-introduction/03-cli.md | 102 +++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index e1cca48..f1ea1c5 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -1,4 +1,4 @@ - + # 命令行 你已经学会了如何使用命令行界面做一些事情。本章将向你介绍所有可用的命令。 @@ -46,7 +46,7 @@ - [COMPOSER_NO_INTERACTION](#COMPOSER_NO_INTERACTION) --- - + ## 全局参数 下列参数可与每一个命令结合使用： @@ -64,14 +64,14 @@ * **--no-ansi:** 关闭 ANSI 输出。 * **--version (-V):** 显示当前应用程序的版本信息。 - + ## 进程退出代码 * **0:** 正常 * **1:** 通用/未知错误 * **2:** 依赖关系处理错误 - + ## 初始化 `init` 在 [“库”](02-libraries.md) 那一章我们看到了如何手动创建 `composer.json` 文件。实际上还有一个 `init` 命令可以更容易的做到这一点。 @@ -80,7 +80,7 @@ $ php composer.phar init - + ### 初始化-参数 * **--name:** 包的名称。 @@ -91,7 +91,7 @@ * **--require-dev:** 开发版的依赖包，内容格式与 **--require** 相同。 * **--stability (-s):** `minimum-stability` 字段的值。 - + ## 安装 `install` `install` 命令从当前目录读取 `composer.json` 文件，处理了依赖关系，并把其安装到 `vendor` 目录下。 @@ -102,7 +102,7 @@ 如果没有 `composer.lock` 文件，composer 将在处理完依赖关系后创建它。 - + ### 安装-参数 * **--prefer-source:** 下载包的方式有两种： `source` @@ -116,7 +116,7 @@ * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 * **--optimize-autoloader (-o):** 转换 PSR-0 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。 - + ## 更新 `update` 为了获取依赖的最新版本，并且升级 `composer.lock` 文件，你应该使用 `update` 命令。 @@ -133,7 +133,7 @@ $ php composer.phar update vendor/* - + ### 更新-参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 @@ -148,7 +148,7 @@ * **--lock:** 仅更新 lock 文件的 hash，取消有关 lock 文件过时的警告。 * **--with-dependencies** 同时更新白名单内包的依赖关系，这将进行递归更新。 - + ## 申明依赖 `require` `require` 命令增加新的依赖包到当前目录的 `composer.json` 文件中。 @@ -161,7 +161,7 @@ $ php composer.phar require vendor/package:2.* vendor/package2:dev-master - + ### 申明依赖-参数 * **--prefer-source:** 当有可用的包时，从 `source` 安装。 @@ -170,7 +170,7 @@ * **--no-update:** 禁用依赖关系的自动更新。 * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 - + ## 全局执行 `global` `global` 命令允许你在 [COMPOSER_HOME](#composer-home) 目录下执行其它命令，像 `install`、`require` 或 `update`。 @@ -183,7 +183,7 @@ $ php composer.phar global update - + ## 搜索 `search` `search` 命令允许你为当前项目搜索依赖包，通常它只搜索 packagist.org 上的包，你可以简单的输入你的搜索条件。 @@ -192,12 +192,12 @@ 您也可以通过传递多个参数来进行多条件搜索。 - + ### 搜索-参数 * **--only-name (-N):** 仅针对指定的名称搜索（完全匹配）。 - + ## 展示 `show` 列出所有可用的软件包，你可以使用 `show` 命令。 @@ -227,14 +227,14 @@ $ php composer.phar show monolog/monolog 1.0.2 - + ### 展示-参数 * **--installed (-i):** 列出已安装的依赖包。 * **--platform (-p):** 仅列出平台软件包（PHP 与它的扩展）。 * **--self (-s):** 仅列出当前项目信息。 - + ## 依赖性检测 `depends` `depends` 命令可以查出已安装在你项目中的某个包，是否正在被其它的包所依赖，并列出他们。 @@ -247,19 +247,19 @@ symfony/monolog-bridge symfony/symfony - + ### 依赖性检测-参数 * **--link-type:** 检测的类型，默认为 `require` 也可以是 `require-dev`。 - + ## 有效性检测 `validate` 在提交 `composer.json` 文件，和创建 tag 前，你应该始终运行 `validate` 命令。它将检测你的 `composer.json` 文件是否是有效的 $ php composer.phar validate - + ## 依赖包状态检测 `status` 如果你经常修改依赖包里的代码，并且它们是从 source（自定义源）进行安装的，那么 `status` 命令允许你进行检查，如果你有任何本地的更改它将会给予提示。 @@ -273,7 +273,7 @@ vendor/seld/jsonlint: M README.mdown - + ## 自我更新 `self-update` 将 Composer 自身升级到最新版本，只需要运行 `self-update` 命令。它将替换你的 `composer.phar` 文件到最新版本。 @@ -288,20 +288,20 @@ $ sudo composer self-update - + ### 自我更新-参数 * **--rollback (-r):** 回滚到你已经安装的最后一个版本。 * **--clean-backups:** 在更新过程中删除旧的备份，这使得更新过后的当前版本是唯一可用的备份。 - + ## 更改配置 `config` `config` 命令允许你编辑 Composer 的一些基本设置，无论是本地的 `composer.json` 或者全局的 `config.json` 文件。 $ php composer.phar config --list - + ### 更改配置-使用方法 `config [options] [setting-key] [setting-value1] ... [setting-valueN]` @@ -310,7 +310,7 @@ 有效的配置选项，请查看“架构”章节的 [config](04-schema.md#config) 。 - + ### 更改配置-参数 * **--global (-g):** 操作位于 `$COMPOSER_HOME/config.json` 的全局配置文件。如果不指定该参数，此命令将影响当前项目的 composer.json 文件，或 `--file` 参数所指向的文件。 @@ -319,14 +319,14 @@ * **--list (-l):** 显示当前配置选项的列表。当存在 `--global` 参数时，将会显示全局配置选项的列表。 * **--file="..." (-f):** 在一个指定的文件上操作，而不是 composer.json。注意：不能与 `--global` 参数一起使用。 - + ### 修改包来源 除了修改配置选项， `config` 命令还支持通过以下方法修改来源信息： $ php composer.phar config repositories.foo vcs http://github.com/foo/bar - + ## 创建项目 `create-project` 你可以使用 Composer 从现有的包中创建一个新的项目。这相当于执行了一个 `git clone` 或 `svn checkout` 命令后将这个包的依赖安装到它自己的 vendor 目录。 @@ -347,7 +347,7 @@ 默认情况下，这个命令会在 packagist.org 上查找你指定的包。 - + ### 创建项目-参数 * **--repository-url:** 提供一个自定义的储存库来搜索包，这将被用来代替 packagist.org。可以是一个指向 `composer` 资源库的 HTTP URL，或者是指向某个 `packages.json` 文件的本地路径。 @@ -361,61 +361,61 @@ * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 * **--keep-vcs:** 创建时跳过缺失的 VCS 。如果你在非交互模式下运行创建命令，这将是非常有用的。 - + ## 打印自动加载索引 `dump-autoload` 某些情况下你需要更新 autoloader，例如在你的包中加入了一个新的类。你可以使用 `dump-autoload` 来完成，而不必执行 `install` 或 `update` 命令。 此外，它可以打印一个优化过的，符合 PSR-0 规范的类的索引，这也是出于对性能的可考虑。在大型的应用中会有许多类文件，而 autoloader 会占用每个请求的很大一部分时间，使用 classmaps 或许在开发时不太方便，但它在保证性能的前提下，仍然可以获得 PSR-0 规范带来的便利。 - + ### 打印自动加载索引-参数 * **--optimize (-o):** 转换 PSR-0 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。 - + ## 查看许可协议 `licenses` 列出已安装的每个包的名称、版本、许可协议。可以使用 `--format=json` 参数来获取 JSON 格式的输出。 - + ## 执行脚本 `run-script` 你可以运行此命令来手动执行 [脚本](articles/scripts.md)，只需要指定脚本的名称，可选的 `--no-dev` 参数允许你禁用开发者模式。 - + ## 诊断 `diagnose` 如果你觉得发现了一个 bug 或是程序行为变得怪异，你可能需要运行 `diagnose` 命令，来帮助你检测一些常见的问题。 $ php composer.phar diagnose - + ## 归档 `archive` 此命令用来对指定包的指定版本进行 zip/tar 归档。它也可以用来归档你的整个项目，不包括 excluded/ignored（排除/忽略）的文件。 $ php composer.phar archive vendor/package 2.0.21 --format=zip - + ### 归档-参数 * **--format (-f):** 指定归档格式：tar 或 zip（默认为 tar）。 * **--dir:** 指定归档存放的目录（默认为当前目录）。 - + ## 获取帮助信息 `help` 使用 `help` 可以获取指定命令的帮助信息。 $ php composer.phar help install - + ## 环境变量 你可以设置一些环境变量来覆盖默认的配置。建议尽可能的在 `composer.json` 的 `config` 字段中设置这些值，而不是通过命令行设置环境变量。值得注意的是环境变量中的值，将始终优先于 `composer.json` 中所指定的值。 - + ### COMPOSER 环境变量 `COMPOSER` 可以为 `composer.json` 文件指定其它的文件名。 @@ -424,46 +424,46 @@ $ COMPOSER=composer-other.json php composer.phar install - + ### COMPOSER_ROOT_VERSION 通过设置这个环境变量，你可以指定 root 包的版本，如果程序不能从 VCS 上猜测出版本号，并且未在 `composer.json` 文件中申明。 - + ### COMPOSER_VENDOR_DIR 通过设置这个环境变量，你可以指定 composer 将依赖安装在 `vendor` 以外的其它目录中。 - + ### COMPOSER_BIN_DIR 通过设置这个环境变量，你可以指定 `bin`（[Vendor Binaries](articles/vendor-binaries.md)）目录到 `vendor/bin` 以外的其它目录。 - + ### http_proxy or HTTP_PROXY 如果你是通过 HTTP 代理来使用 Composer，你可以使用 `http_proxy` 或 `HTTP_PROXY` 环境变量。只要简单的将它设置为代理服务器的 URL。许多操作系统已经为你的服务设置了此变量。 建议使用 `http_proxy`（小写）或者两者都进行定义。因为某些工具，像 git 或 curl 将使用 `http_proxy` 小写的版本。另外，你还可以使用 `git config --global http.proxy ` 来单独设置 git 的代理。 - + ### no_proxy 如果你是使用代理服务器，并且想要对某些域名禁用代理，就可以使用 `no_proxy` 环境变量。只需要输入一个逗号相隔的域名 *排除* 列表。 此环境变量接受域名、IP 以及 CIDR地址块。你可以将它限制到一个端口（例如：`:80`）。你还可以把它设置为 `*` 来忽略所有的 HTTP 代理请求。 - + ### HTTP_PROXY_REQUEST_FULLURI 如果你使用了 HTTP 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。 - + ### HTTPS_PROXY_REQUEST_FULLURI 如果你使用了 HTTPS 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。 - + ### COMPOSER_HOME `COMPOSER_HOME` 环境变量允许你改变 Composer 的主目录。这是一个隐藏的、所有项目共享的全局目录（对本机的所有用户都可用）。 @@ -473,7 +473,7 @@ - OSX `/Users//.composer`。 - Windows `C:\Users\\AppData\Roaming\Composer`。 - + #### COMPOSER_HOME/config.json 你可以在 `COMPOSER_HOME` 目录中放置一个 `config.json` 文件。在你执行 `install` 和 `update` 命令时，Composer 会将它与你项目中的 `composer.json` 文件进行合并。 @@ -482,7 +482,7 @@ 若 _全局_ 和 _项目_ 存在相同配置项，那么项目中的 `composer.json` 文件拥有更高的优先级。 - + ### COMPOSER_CACHE_DIR `COMPOSER_CACHE_DIR` 环境变量允许你设置 Composer 的缓存目录，这也可以通过 [`cache-dir`](04-schema.md#config) 进行配置。 @@ -491,17 +491,17 @@ - \*nix and OSX `$COMPOSER_HOME/cache`。 - Windows `C:\Users\\AppData\Local\Composer` 或 `%LOCALAPPDATA%/Composer`。 - + ### COMPOSER_PROCESS_TIMEOUT 这个环境变量控制着 Composer 执行命令的等待时间（例如：git 命令）。默认值为300秒（5分钟）。 - + ### COMPOSER_DISCARD_CHANGES 这个环境变量控制着 discard-changes [config option](04-schema.md#config)。 - + ### COMPOSER_NO_INTERACTION 如果设置为1，这个环境变量将使 Composer 在执行每一个命令时都放弃交互，相当于对所有命令都使用了 `--no-interaction`。可以在搭建 *虚拟机/持续集成服务器* 时这样设置。 -- 2.46.2 From 68f6f10badaec8ea3e7772d8f520e8df12b9ef5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 09:15:05 +0800 Subject: [PATCH 056/125] update 04-schema.md --- cn-introduction/04-schema.md | 97 ++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 31 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index d4ebcf2..1acaef4 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -1,51 +1,54 @@ + # composer.json 本章将解释所有在 `composer.json` 中可用的字段。 --- -- [composer.json](#composerjson) - - [JSON schema](#json-schema) - - [Root 包](#root-包) - - [属性](#属性) - - [包名 `name`](#包名-name) - - [描述 `description`](#描述-description) - - 版本 `version` - - 安装类型 `type` - - 关键字 `keywords` - - 项目主页 `homepage` - - 版本发布时间 `time` - - 许可协议 `license` - - 作者 `authors` - - 支持 `support` - - [Package links](#package-links) +- [composer.json](#composer.json) + - [JSON schema](#JSON schema) + - [Root 包](#Root Package) + - [属性](#Properties) + - [包名 `name`](#name) + - [描述 `description`](#description) + - [版本 `version`](#version) + - [安装类型 `type`](#type) + - [关键字 `keywords`](#keywords) + - [项目主页 `homepage`](#homepage) + - [版本发布时间 `time`](#time) + - [许可协议 `license`](#license) + - [作者 `authors`](#authors) + - [支持 `support`](#support) + - [Package links](#Package links) - [require](#require) - - require-dev (root-only) + - [require-dev (root-only)](#require-dev) - [conflict](#conflict) - [replace](#replace) - [provide](#provide) - - suggest - - autoload - - PSR-0 - - Classmap - - Files - - include-path - - target-dir - - minimum-stability (root-only) - - prefer-stable (root-only) - - repositories (root-only) - - config (root-only) - - scripts (root-only) - - extra - - bin - - archive + - [suggest](#suggest) + - [autoload](#autoload) + - [PSR-0](#PSR-0) + - [Classmap](#Classmap) + - [Files](#Files) + - [include-path](#include-path) + - [target-dir](#target-dir) + - [minimum-stability (root-only)](#minimum-stability) + - [prefer-stable (root-only)](#prefer-stable) + - [repositories (root-only)](#repositories) + - [config (root-only)](#config) + - [scripts (root-only)](#scripts) + - [extra](#extra) + - [bin](#bin) + - [archive](#archive) --- + ## JSON schema 我们有一个 [JSON schema](http://json-schema.org) 格式化文档，它也可以被用来验证你的 `composer.json` 文件。事实上，它已经被 `validate` 命令所使用。 你可以在这里找到它： [`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). + ## Root 包 “root 包”是指由 `composer.json` 定义的在你项目根目录的包。这是 `composer.json` 定义你项目所需的主要条件。（简单的说，你自己的项目就是一个 root 包） @@ -59,8 +62,10 @@ > 但是，如果你从 GitHub 上克隆了 `monolog` 为它修复 bug， > 那么此时 `monolog` 就是“root 包”。 + ## 属性 + ### 包名 `name` 包的名称，它包括供应商名称和项目名称，使用 `/` 分隔。 @@ -72,12 +77,14 @@ 对于需要发布的包（库），这是必须填写的。 + ### 描述 `description` 一个包的简短描述。通常这个最长只有一行。 对于需要发布的包（库），这是必须填写的。 + ### 版本 `version` `version` 不是必须的，并且建议忽略（见下文）。 @@ -101,6 +108,7 @@ > 因此 `version` 定义的版本号必须是真实准确的。 > 自己手动指定的 `version`，最终有可能在某个时候因为人为错误造成问题。 + ### 安装类型 `type` 包的安装类型，默认为 `library`。 @@ -116,6 +124,7 @@ composer 原生支持以下4种类型： 仅在你需要一个自定义的安装逻辑时才使用它。建议忽略这个属性，采用默认的 `library`。 + ### 关键字 `keywords` 该包相关的关键词的数组。这些可用于搜索和过滤。 @@ -130,12 +139,14 @@ composer 原生支持以下4种类型： 可选。 + ### 项目主页 `homepage` 该项目网站的 URL 地址。 可选。 + ### 版本发布时间 `time` 版本发布时间。 @@ -144,6 +155,7 @@ composer 原生支持以下4种类型： 可选。 + ### 许可协议 `license` 包的许可协议，它可以是一个字符串或者字符串数组。 @@ -193,6 +205,7 @@ composer 原生支持以下4种类型： 同样，当有多个许可协议需要结合使用时（"conjunctive license"），它们应该被 "and" 分隔，并写在括号中。 + ### 作者 `authors` 包的作者。这是一个对象数组。 @@ -225,6 +238,7 @@ composer 原生支持以下4种类型： 可选，但强烈建议提供此内容。 + ### 支持 `support` 获取项目支持的向相关信息对象。 @@ -249,6 +263,7 @@ composer 原生支持以下4种类型： 可选。 + ### Package links 下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#包版本) 的映射对象。 @@ -303,20 +318,24 @@ composer 原生支持以下4种类型： 它也可以应用于行内别名，这样它将匹配一个约束，否则不会。更多信息请参考 [别名](articles/aliases.md)。 + #### require 必须的软件包列表，除非这些依赖被满足，否则不会完成安装。 + #### require-dev (root-only) 这个列表是为开发或测试等目的，额外列出的依赖。“root 包”的 require-dev 默认是会被安装的。然而 `install` 或 `update` 支持使用 `--no-dev` 参数来跳过 `require-dev` 字段中列出的包。 + #### conflict 此列表中的包与当前包的这个版本冲突。它们将不允许同时被安装。 请注意，在 `conflict` 中指定类似于 `<1.0, >= 1.1` 的版本范围时，这表示它与小于1.0 *并且* 同时大等于1.1的版本冲突，这很可能不是你想要的。在这种情况下你可能想要表达的是 `<1.0 | >= 1.1` 。 + #### replace 这个列表中的包将被当前包取代。这使你可以 fork 一个包，以不同的名称和版本号发布，同时要求依赖于原包的其它包，在这之后依赖于你 fork 的这个包，因为它取代了原来的包。 @@ -325,10 +344,12 @@ composer 原生支持以下4种类型： 注意，在使用上述方法取代子包时，通常你应该只对子包使用 `self.version` 这一个版本约束，以确保主包仅替换掉子包的准确版本，而不是任何其他版本。 + #### provide List of other packages that are provided by this package. This is mostly useful for common interfaces. A package could depend on some virtual `logger` package, any library that implements this logger interface would simply list it in `provide`. + ### suggest 建议安装的包，它们增强或能够与当前包良好的工作。这些只是信息，并显示在依赖包安装完成之后，给你的用户一个建议，他们可以添加更多的包。 @@ -343,12 +364,14 @@ List of other packages that are provided by this package. This is mostly useful } } + ### 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）。 + #### PSR-0 在 `psr-0` key 下你定义了一个命名空间到实际路径的映射（相对于包的根目录）。注意，这里同样支持 PEAR-style 方式的约定（与命名空间不同，PEAR 类库在类名上采用了下划线分隔）。 @@ -393,6 +416,7 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 } } + #### Classmap `classmap` 引用的所有组合，都会在 install/update 过程中生成，并存储到 `vendor/composer/autoload_classmap.php` 文件中。这个 map 是经过扫描指定目录（同样支持直接精确到文件）中所有的 `.php` 和 `.inc` 文件里内置的类而得到的。 @@ -407,6 +431,7 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 } } + #### Files 如果你想要明确的指定，在每次请求时都要载入某些文件，那么你可以使用 'files' autoloading。通常作为函数库的载入方式（而非类库）。 @@ -419,6 +444,7 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 } } + ### include-path > **不建议**：这是目前唯一支持传统项目的做法，所有新的代码都建议使用自动加载。 @@ -434,6 +460,7 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 可选。 + ### target-dir 定义当前包安装的目标文件夹。 @@ -453,6 +480,7 @@ Symfony 就是一个例子。它有一些独立的包作为组件。Yaml 组件 可选。 + ### minimum-stability (root-only) 这定义了通过稳定性过滤包的默认行为。默认为 `stable`（稳定）。因此如果你依赖于一个 `dev`（开发）包，你应该明确的进行定义。 @@ -461,12 +489,14 @@ Symfony 就是一个例子。它有一些独立的包作为组件。Yaml 组件 可用的稳定性标识（按字母排序）：`dev`、`alpha`、`beta`、`RC`、`stable`。 + ### prefer-stable (root-only) 当此选项被激活时，Composer 将优先使用更稳定的包版本。 使用 `"prefer-stable": true` 来激活它。 + ### repositories (root-only) 使用自定义的包资源库。 @@ -530,6 +560,7 @@ Repositories 并不是递归调用的，只能在“Root包”的 `composer.json > **注意：** 顺序是非常重要的，当 Composer 查找资源包时，它会按照顺序进行。默认情况下 Packagist 是最后加入的，因此自定义设置将可以覆盖 Packagist 上的包。 + ### config (root-only) 下面的这一组选项，仅用于项目。 @@ -563,12 +594,14 @@ Repositories 并不是递归调用的，只能在“Root包”的 `composer.json } } + ### scripts (root-only) Composer 允许你在安装过程中的各个阶段挂接脚本。 更多细节和案例请查看 [脚本](articles/scripts.md)。 + ### extra 任意的，供 `scripts` 使用的额外数据。. @@ -579,6 +612,7 @@ Composer 允许你在安装过程中的各个阶段挂接脚本。 可选。 + ### bin A set of files that should be treated as binaries and symlinked into the `bin-dir` (from config). @@ -587,6 +621,7 @@ See [Vendor Binaries](articles/vendor-binaries.md) for more details. 可选。 + ### archive 这些选项在创建包存档时使用。 -- 2.46.2 From 6a6b10ffcf597bdfa0a29be8e6f00792ea502131 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 10:04:13 +0800 Subject: [PATCH 057/125] update 04-schema.md --- cn-introduction/04-schema.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 1acaef4..78ce4f7 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -9,7 +9,7 @@ - [JSON schema](#JSON schema) - [Root 包](#Root Package) - [属性](#Properties) - - [包名 `name`](#name) + - [包名 `name`](#package name) - [描述 `description`](#description) - [版本 `version`](#version) - [安装类型 `type`](#type) @@ -65,7 +65,7 @@ ## 属性 - + ### 包名 `name` 包的名称，它包括供应商名称和项目名称，使用 `/` 分隔。 -- 2.46.2 From 745c57370146ade0796e822a99badddbab17e790 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 11:31:15 +0800 Subject: [PATCH 058/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 34 +++++++++--------------------- 1 file changed, 10 insertions(+), 24 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index d70ae2b..67668ad 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -220,13 +220,9 @@ Git 并不是 VCS 资源库唯一支持的版本管理系统。 VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需要明确的指定一个 `git`、`svn` 或 `hg` 作为资源库类型，而不是 `vcs`。 -#### Subversion Options +#### Subversion 选项 -Since Subversion has no native concept of branches and tags, Composer assumes -by default that code is located in `$url/trunk`, `$url/branches` and -`$url/tags`. If your repository has a different layout you can change those -values. For example if you used capitalized names you could configure the -repository like this: +由于 Subversion 没有原生的分支和标签的概念，Composer 假设在默认情况下该代码位于 `$url/trunk`、`$url/branches` 和 `$url/tags` 内。如果你的存储库使用了不同的布局，你可以更改这些值。例如，如果你使用大写的名称，你可以像这样配置资源库： { "repositories": [ @@ -240,21 +236,15 @@ repository like this: ] } -If you have no branches or tags directory you can disable them entirely by -setting the `branches-path` or `tags-path` to `false`. +如果你的存储库目录中没有任何分支或标签文件夹，你可以将 `branches-path` 或 `tags-path` 设置为 `false`。 -If the package is in a sub-directory, e.g. `/trunk/foo/bar/composer.json` and -`/tags/1.0/foo/bar/composer.json`, then you can make composer access it by -setting the `"package-path"` option to the sub-directory, in this example it -would be `"package-path": "foo/bar/"`. +如果是一个位于子目录的包，例如， `/trunk/foo/bar/composer.json` 和 `/tags/1.0/foo/bar/composer.json`，那么你可以让 composer 通过 `"package-path"` 选项设置的子目录进行访问，在这个例子中可以将其设置为 `"package-path": "foo/bar/"`。 ### PEAR -It is possible to install packages from any PEAR channel by using the `pear` -repository. Composer will prefix all package names with `pear-{channelName}/` to -avoid conflicts. All packages are also aliased with prefix `pear-{channelAlias}/` +`pear` 类型资源库，使得从任何 PEAR 渠道安装资源包成为可能。Composer 将为所有此类型的包增加前缀（类似于 `pear-{渠道名称}/`）以避免冲突。而在之后使用别名时也增加前缀（如 `pear-{渠道别名}/`）。 -Example using `pear2.php.net`: +例如使用 `pear2.php.net`： { "repositories": [ @@ -269,21 +259,17 @@ Example using `pear2.php.net`: } } -In this case the short name of the channel is `pear2`, so the -`PEAR2_HTTP_Request` package name becomes `pear-pear2/PEAR2_HTTP_Request`. +在这种情况下渠道的简称（别名）是 `pear2`，因此 `PEAR2_HTTP_Request` 包的名称应该写作 `pear-pear2/PEAR2_HTTP_Request`。 -> **Note:** The `pear` repository requires doing quite a few requests per -> package, so this may considerably slow down the installation process. +> **注意：** `pear` 类型的资源库对每个 requires 都要做完整的请求，因此可能大大降低安装速度。 #### Custom vendor alias It is possible to alias PEAR channel packages with a custom vendor name. -Example: +例： -Suppose you have a private PEAR repository and wish to use Composer to -incorporate dependencies from a VCS. Your PEAR repository contains the -following packages: +Suppose you have a private PEAR repository and wish to use Composer to incorporate dependencies from a VCS. Your PEAR repository contains the following packages: * `BasePackage` * `IntermediatePackage`, which depends on `BasePackage` -- 2.46.2 From 98c136b08cea555c71b85c2213908efd60a87d37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 14:36:39 +0800 Subject: [PATCH 059/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 67668ad..1a8463a 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -263,38 +263,30 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 > **注意：** `pear` 类型的资源库对每个 requires 都要做完整的请求，因此可能大大降低安装速度。 -#### Custom vendor alias +#### 自定义供应商别名 It is possible to alias PEAR channel packages with a custom vendor name. 例： -Suppose you have a private PEAR repository and wish to use Composer to incorporate dependencies from a VCS. Your PEAR repository contains the following packages: +假设你有一个私人 PEAR 库，并希望使用 Composer 从 VCS 集成依赖。你的 PEAR 库包含以下资源包： * `BasePackage` * `IntermediatePackage`, which depends on `BasePackage` * `TopLevelPackage1` and `TopLevelPackage2` which both depend on `IntermediatePackage` -Without a vendor alias, Composer will use the PEAR channel name as the -vendor portion of the package name: +如果没有一个供应商别名，Composer 将使用 PEAR 渠道名称作为包名的一部分： * `pear-pear.foobar.repo/BasePackage` * `pear-pear.foobar.repo/IntermediatePackage` * `pear-pear.foobar.repo/TopLevelPackage1` * `pear-pear.foobar.repo/TopLevelPackage2` -Suppose at a later time you wish to migrate your PEAR packages to a -Composer repository and naming scheme, and adopt the vendor name of `foobar`. -Projects using your PEAR packages would not see the updated packages, since -they have a different vendor name (`foobar/IntermediatePackage` vs -`pear-pear.foobar.repo/IntermediatePackage`). +假设之后的某个时间，你希望将你的 PEAR 包迁移，使用 Composer 资源库和命名方案，并且采用 `foobar` 作为供应商名称。使用 PEAR 包的项目将不会看到更新的资源包，因为它们有不同的供应商名称（`foobar/IntermediatePackage` 与 `pear-pear.foobar.repo/IntermediatePackage`）。 -By specifying `vendor-alias` for the PEAR repository from the start, you can -avoid this scenario and future-proof your package names. +你可以通过从一开始就为 PEAR 资源库指定 `vendor-alias` 来避免这种情况的发生，以得到一个不会过时的包名。 -To illustrate, the following example would get the `BasePackage`, -`TopLevelPackage1`, and `TopLevelPackage2` packages from your PEAR repository -and `IntermediatePackage` from a Github repository: +为了说明这一点，下面的例子会从你的 PEAR 资源库中得到 `BasePackage`、`TopLevelPackage1` 和 `TopLevelPackage2` 资源包，并从 Github 资源库中获取 `IntermediatePackage` 资源包： { "repositories": [ -- 2.46.2 From 059001d770feec7fbf35cc10b66aebc270ea5ab4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 16:04:04 +0800 Subject: [PATCH 060/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 34 ++++++++++++------------------ 1 file changed, 13 insertions(+), 21 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 1a8463a..117d55b 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -265,15 +265,15 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 #### 自定义供应商别名 -It is possible to alias PEAR channel packages with a custom vendor name. +通过自定义供应商名称，对 PEAR 渠道包进行别名是允许的。 例： 假设你有一个私人 PEAR 库，并希望使用 Composer 从 VCS 集成依赖。你的 PEAR 库包含以下资源包： - * `BasePackage` - * `IntermediatePackage`, which depends on `BasePackage` - * `TopLevelPackage1` and `TopLevelPackage2` which both depend on `IntermediatePackage` + * `BasePackage`。 + * `IntermediatePackage` 依赖于 `BasePackage`。 + * `TopLevelPackage1` 和 `TopLevelPackage2` 都依赖于 `IntermediatePackage`。 如果没有一个供应商别名，Composer 将使用 PEAR 渠道名称作为包名的一部分： @@ -282,7 +282,7 @@ It is possible to alias PEAR channel packages with a custom vendor name. * `pear-pear.foobar.repo/TopLevelPackage1` * `pear-pear.foobar.repo/TopLevelPackage2` -假设之后的某个时间，你希望将你的 PEAR 包迁移，使用 Composer 资源库和命名方案，并且采用 `foobar` 作为供应商名称。使用 PEAR 包的项目将不会看到更新的资源包，因为它们有不同的供应商名称（`foobar/IntermediatePackage` 与 `pear-pear.foobar.repo/IntermediatePackage`）。 +假设之后的某个时间，你希望将你的 PEAR 包迁移，使用 Composer 资源库和命名方案，并且采用 `foobar` 作为供应商名称。这样之前使用 PEAR 包的项目将不会看到更新的资源包，因为它们有不同的供应商名称（`foobar/IntermediatePackage` 与 `pear-pear.foobar.repo/IntermediatePackage`）。 你可以通过从一开始就为 PEAR 资源库指定 `vendor-alias` 来避免这种情况的发生，以得到一个不会过时的包名。 @@ -308,16 +308,11 @@ It is possible to alias PEAR channel packages with a custom vendor name. ### Package -If you want to use a project that does not support composer through any of the -means above, you still can define the package yourself by using a `package` -repository. +如果你想使用一个项目，它无法通过上述任何一种方式支持 composer，你仍然可以使用 `package` 类型定义资源库。 -Basically, you define the same information that is included in the `composer` -repository's `packages.json`, but only for a single package. Again, the -minimum required fields are `name`, `version`, and either of `dist` or -`source`. +基本上，你可以定义与 `packages.json` 中 `composer` 类型资源库相同的信息，但需要为每个这样的资源包分别定义。同样，至少应该包含以下信息：`name`、`version`、（`dist` 或 `source`）。 -Here is an example for the smarty template engine: +这是一个 smarty 模板引擎的例子： { "repositories": [ @@ -346,15 +341,12 @@ Here is an example for the smarty template engine: } } -Typically you would leave the source part off, as you don't really need it. +通常你不需要去定义 `source`，因为你并不是真的需要它。 -> **Note**: This repository type has a few limitations and should be avoided -> whenever possible: +> **注意：** 该资源库类型存在以下限制，因此应尽可能避免使用： > -> - Composer will not update the package unless you change the `version` field. -> - Composer will not update the commit references, so if you use `master` as -> reference you will have to delete the package to force an update, and will -> have to deal with an unstable lock file. +> - Composer 将不会更新资源包，除非你修改了 `version` 字段。 +> - Composer 将不会更新 commit references，因此如果你使用 `master` reference，将不得不删除该程序包以强制更新，并且将不得不面对一个不稳定的锁定文件。 ## Hosting your own @@ -452,4 +444,4 @@ You can disable the default Packagist repository by adding this to your } -← [Schema](04-schema.md) | [Community](06-community.md) → +← [架构](04-schema.md) | [社区](06-community.md) → -- 2.46.2 From b2f6e37c1bf5af75f8c75b50b842e69514c873d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 18:43:31 +0800 Subject: [PATCH 061/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 44 ++++++++---------------------- 1 file changed, 12 insertions(+), 32 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 117d55b..f6a464b 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -346,55 +346,35 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 > **注意：** 该资源库类型存在以下限制，因此应尽可能避免使用： > > - Composer 将不会更新资源包，除非你修改了 `version` 字段。 -> - Composer 将不会更新 commit references，因此如果你使用 `master` reference，将不得不删除该程序包以强制更新，并且将不得不面对一个不稳定的锁定文件。 +> - Composer 将不会更新 commit references，因此如果你使用 `master` reference，将不得不删除该程序包以强制更新，并且将不得不面对一个不稳定的 lock 文件。 ## Hosting your own -While you will probably want to put your packages on packagist most of the time, -there are some use cases for hosting your own repository. +尽管大部分的时间，你大概都会把资源包放在 packagist.org 上，但这里还将告诉你一些用例，以便你可以自行托管资源库。 -* **Private company packages:** If you are part of a company that uses composer - for their packages internally, you might want to keep those packages private. +* **Private company packages:** 如果你是一个公司的职员，对公司内部的资源包使用 composer，你可能会想让这些包保持私有的状态。 -* **Separate ecosystem:** If you have a project which has its own ecosystem, - and the packages aren't really reusable by the greater PHP community, you - might want to keep them separate to packagist. An example of this would be - wordpress plugins. +* **Separate ecosystem:** 如果你的项目有自己的生态系统，并且自己的资源包不需要被其它项目所复用，你可能会想将它们从 packagist.org 上分离出来。其中一个例子就是 wordpress 的插件。 -For hosting your own packages, a native `composer` type of repository is -recommended, which provides the best performance. +对于自行托管的软件包，建议使用 `composer` 类型资源库设置，它将提供最佳的性能。 -There are a few tools that can help you create a `composer` repository. +这里有一些工具，可以帮助你创建 `composer` 类型的资源库。 ### Packagist -The underlying application used by packagist is open source. This means that you -can just install your own copy of packagist, re-brand, and use it. It's really -quite straight-forward to do. However due to its size and complexity, for most -small and medium sized companies willing to track a few packages will be better -off using Satis. +packagist 的底层是开源的。这意味着你可以只安装你自己拷贝的 packagist，改造并使用它。这真的是很直接简单的事情。然而，由于其规模和复杂性，对于大多数中小型企业还是建议使用 Satis。 -Packagist is a Symfony2 application, and it is [available on -GitHub](https://github.com/composer/packagist). It uses composer internally and -acts as a proxy between VCS repositories and the composer users. It holds a list -of all VCS packages, periodically re-crawls them, and exposes them as a composer -repository. +Packagist 是一个 Symfony2 应用程序，并且托管在 GitHub 上 [github.com/composer/packagist](https://github.com/composer/packagist)。它内部使用了 composer 并作为 VCS 资源库与 composer 用户之间的代理。它拥有所有 VCS 资源包的列表，定期重新抓取它们，并将其作为一个 composer 资源库。 -To set your own copy, simply follow the instructions from the [packagist -github repository](https://github.com/composer/packagist). +要设置你的副本，只需要按照 [github.com/composer/packagist](https://github.com/composer/packagist) 的说明进行操作。 ### Satis -Satis is a static `composer` repository generator. It is a bit like an ultra- -lightweight, static file-based version of packagist. +Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻量级的、基于静态文件的 packagist 版本。 -You give it a `composer.json` containing repositories, typically VCS and -package repository definitions. It will fetch all the packages that are -`require`d and dump a `packages.json` that is your `composer` repository. +你给它一个包含 `composer.json` 的存储库，定义好 VCS 和 资源库。它会获取所有你列出的包，并打印 `packages.json` 文件，作为你的 `composer` 资源库。 -Check [the satis GitHub repository](https://github.com/composer/satis) and -the [Satis article](articles/handling-private-packages-with-satis.md) for more -information. +更多详细信息请查看 [github.com/composer/satis](https://github.com/composer/satis) 和 [Satis article](articles/handling-private-packages-with-satis.md)。 ### Artifact -- 2.46.2 From 1ad655dd552e473e3247a660f5b4deb7578c1ed6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 8 Jan 2014 20:13:27 +0800 Subject: [PATCH 062/125] update 05-repositories.md --- cn-introduction/05-repositories.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index f6a464b..44a828b 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -372,18 +372,13 @@ Packagist 是一个 Symfony2 应用程序，并且托管在 GitHub 上 [github.c Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻量级的、基于静态文件的 packagist 版本。 -你给它一个包含 `composer.json` 的存储库，定义好 VCS 和 资源库。它会获取所有你列出的包，并打印 `packages.json` 文件，作为你的 `composer` 资源库。 +你给它一个包含 `composer.json` 的存储库，定义好 VCS 和 资源库。它会获取所有你列出的包，并打印 `packages.json` 文件，作为 `composer` 类型的资源库。 更多详细信息请查看 [github.com/composer/satis](https://github.com/composer/satis) 和 [Satis article](articles/handling-private-packages-with-satis.md)。 ### Artifact -There are some cases, when there is no ability to have one of the previously -mentioned repository types online, even the VCS one. Typical example could be -cross-organisation library exchange through built artifacts. Of course, most -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: +在某些情况下，或许没有能力拥有之前提到的任何一种线上资源库。Typical example could be cross-organisation library exchange through built artifacts。当然大部分的时间他们都是私有的。为了简化维护，可以简单的使用 `artifact` 资源库类型，来引用一个包含那些私有包的 ZIP 存档的文件夹： { "repositories": [ @@ -399,7 +394,7 @@ private packages: } } -Each zip artifact is just a ZIP archive with `composer.json` in root folder: +每个 zip artifact 都只是一个 ZIP 存档，放置在 `composer.json` 所在的根目录： $ unzip -l acme-corp-parser-10.3.5.zip composer.json @@ -412,8 +407,7 @@ update to the latest version. ## Disabling Packagist -You can disable the default Packagist repository by adding this to your -`composer.json`: +你可以在 `composer.json` 中禁用默认的 Packagist 资源库。 { "repositories": [ -- 2.46.2 From 68f5eaa033383f8026cabc2492016007b6fcd393 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 08:55:50 +0800 Subject: [PATCH 063/125] update 05-repositories.md 06-community.md --- cn-introduction/05-repositories.md | 35 +++++++++++++++++++++++++----- cn-introduction/06-community.md | 35 +++++++++++------------------- 2 files changed, 43 insertions(+), 27 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 44a828b..c58696d 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -2,6 +2,34 @@ 本章将解释包和库的概念，什么样的存储库是可用的，以及它们如何工作。 +--- + +- 资源库 + - 概述 + - 包 + - 资源库 + - Types + - Composer + - packages + - notify-batch + - includes + - provider-includes and providers-url + - stream options + - VCS + - 从 VCS 资源库加载一个包 + - 使用私有资源库 + - Git 的备选方案 + - Subversion 选项 + - PEAR + - 自定义供应商别名 + - Package + - Hosting your own + - Packagist + - Satis + - Artifact + - 禁用 Packagist + +--- ## 概述 在此之前，我们看到存在不同类型的资源库，我们需要了解一些基本概念，以理解 Composer 是如何构建于其上的。 @@ -400,12 +428,9 @@ Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻 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 -and you run `update`, that version will be imported as well and Composer will -update to the latest version. +如果有两个不同版本的资源包，它们都会被导入。当有一个新版本的存档被添加到 artifact 文件夹，并且你运行了 `update` 命令，该版本就会被导入，并且 Composer 将更新到最新版本。 -## Disabling Packagist +## 禁用 Packagist 你可以在 `composer.json` 中禁用默认的 Packagist 资源库。 diff --git a/cn-introduction/06-community.md b/cn-introduction/06-community.md index 10ef31b..e5ccb81 100644 --- a/cn-introduction/06-community.md +++ b/cn-introduction/06-community.md @@ -1,34 +1,25 @@ -# Community +# 社区 -There are many people using composer already, and quite a few of them are -contributing. +已经后很多人在使用 composer，也有很多人为它做出了贡献。 -## Contributing +## 贡献 -If you would like to contribute to composer, please read the -[README](https://github.com/composer/composer). +如果你想为 composer 做出自己的贡献，请阅读 [README](https://github.com/composer/composer). -The most important guidelines are described as follows: +最重要的原则介绍如下： -> All code contributions - including those of people having commit access - must -> go through a pull request and approved by a core developer before being -> merged. This is to ensure proper review of all the code. +> 所有贡献的代码 - 包括那些具有提交权限的人 - 必须通过一个 pull request 提交，并在合并前由核心开发人员的核准。 > -> Fork the project, create a feature branch, and send us a pull request. +> Fork 这个项目名称，创建一个特性分支，并给我们发送 pull request。 > -> To ensure a consistent code base, you should make sure the code follows -> the [Coding Standards](http://symfony.com/doc/2.0/contributing/code/standards.html) -> which we borrowed from Symfony. +> 为了与基础代码保持一致，你应该确保代码遵循 [编码规范](http://symfony.com/doc/2.0/contributing/code/standards.html)。 -## IRC / mailing list +## IRC频道 / 邮件列表 -Mailing lists for [user support](http://groups.google.com/group/composer-users) and -[development](http://groups.google.com/group/composer-dev). +邮件列表：[用户支持](http://groups.google.com/group/composer-users) / [开发者](http://groups.google.com/group/composer-dev)。 -IRC channels are on irc.freenode.org: [#composer](irc://irc.freenode.org/composer) -for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development. +irc.freenode.org 上的 IRC 频道：[#composer](irc://irc.freenode.org/composer) （用户）/ [#composer-dev](irc://irc.freenode.org/composer-dev)（开发者）。 -Stack Overflow has a growing collection of -[Composer related questions](http://stackoverflow.com/questions/tagged/composer-php). +Stack Overflow 上有越来越多 [Composer 相关问题](http://stackoverflow.com/questions/tagged/composer-php)的收藏。 -← [Repositories](05-repositories.md) +← [资源库](05-repositories.md) -- 2.46.2 From fef0c47be99ec087d50b0b3e304255b2f00ffbb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 08:57:40 +0800 Subject: [PATCH 064/125] update 06-community.md --- cn-introduction/06-community.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cn-introduction/06-community.md b/cn-introduction/06-community.md index e5ccb81..2c74dd9 100644 --- a/cn-introduction/06-community.md +++ b/cn-introduction/06-community.md @@ -1,16 +1,16 @@ # 社区 -已经后很多人在使用 composer，也有很多人为它做出了贡献。 +已经有很多人在使用 composer，也有很多人为它做出了贡献。 ## 贡献 -如果你想为 composer 做出自己的贡献，请阅读 [README](https://github.com/composer/composer). +如果你想为 composer 做出自己的贡献，请阅读 [README](https://github.com/composer/composer)。 最重要的原则介绍如下： > 所有贡献的代码 - 包括那些具有提交权限的人 - 必须通过一个 pull request 提交，并在合并前由核心开发人员的核准。 > -> Fork 这个项目名称，创建一个特性分支，并给我们发送 pull request。 +> Fork 这个项目，创建一个特性分支，并给我们发送 pull request。 > > 为了与基础代码保持一致，你应该确保代码遵循 [编码规范](http://symfony.com/doc/2.0/contributing/code/standards.html)。 -- 2.46.2 From 6144f81241414ab54d8e6367acf1386642b6b626 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 09:12:24 +0800 Subject: [PATCH 065/125] =?UTF-8?q?update=2005-repositories.md=20=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/05-repositories.md | 73 ++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 24 deletions(-) diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index c58696d..fdb8c3e 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -1,39 +1,43 @@ + # 资源库 本章将解释包和库的概念，什么样的存储库是可用的，以及它们如何工作。 --- -- 资源库 - - 概述 - - 包 - - 资源库 - - Types - - Composer - - packages - - notify-batch - - includes - - provider-includes and providers-url - - stream options - - VCS - - 从 VCS 资源库加载一个包 - - 使用私有资源库 - - Git 的备选方案 - - Subversion 选项 - - PEAR - - 自定义供应商别名 - - Package - - Hosting your own - - Packagist - - Satis - - Artifact - - 禁用 Packagist +- [资源库](#Repositories) + - [概述](#Concepts) + - [包](#Package) + - [资源库](#Repository) + - [Types](#Types) + - [Composer](#Composer) + - [packages](#packages) + - [notify-batch](#notify-batch) + - [includes](#includes) + - [provider-includes and providers-url](#provider-includes) + - [stream options](#stream options) + - [VCS](#VCS) + - [从 VCS 资源库加载一个包](#from a VCS) + - [使用私有资源库](#Using private) + - [Git 的备选方案](#Git alternatives) + - [Subversion 选项](#Subversion Options) + - [PEAR](#PEAR) + - [自定义供应商别名](#Custom vendor alias) + - [Package](#Package) + - [Hosting your own](#Hosting your own) + - [Packagist](#Packagist) + - [Satis](#Satis) + - [Artifact](#Artifact) + - [禁用 Packagist](#Disabling Packagist) --- + + ## 概述 在此之前，我们看到存在不同类型的资源库，我们需要了解一些基本概念，以理解 Composer 是如何构建于其上的。 + ### 包 Composer 是一个依赖管理工具。它在本地安装一些资源包。一个包本质上就是一个包含东西的目录。通常情况下它存储 PHP 代码，但在理论上它可以是任何东西。并且它包含一个描述，其中有一个名称和一个版本号，这个名称和版本号用于识别该包。 @@ -48,6 +52,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 你可以使用其中任意一个，或者同时使用。这取决于其它的一些因素，比如“user-supplied 选项”和“包的稳定性”，前者将会被优先考虑。 + ### 资源库 一个资源库是一个包的来源。它是一个 packages/versions 的列表。Composer 将查看所有你定义的 repositories 以找到你项目需要的资源包。 @@ -56,14 +61,17 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 资源库的定义仅可用于“root 包”，而在你依赖的包中定义的资源库将不会被加载。如果你想了解其中的原因，请阅读 [FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md)。 + ## Types + ### Composer 主资源库的类型为 `composer`。它使用一个单一的 `packages.json` 文件，包含了所有的资源包元数据。 这也是 packagist.org 所使用的资源类型。要引用一个 `composer` 资源库，只需要提供一个存放 `packages.json` 文件的 **目录路径**。比如要引用 `packagist.org` 下的 `/packages.json`，它的 URL 就应该是 `packagist.org`。而 `example.org/packages.json` 的 URL 应该是 `example.org`。 + #### packages 唯一必须的字段是 `packages`。它的 JSON 结构如下： @@ -98,6 +106,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 它还可以包含任何在 [架构](04-schema.md) 中介绍的字段。 + #### notify-batch `notify-batch` 字段允许你指定一个 URL，它将会在用户安装每一个包时被调用。该 URL 可以是（与其资源库相同域名的）绝对路径或者一个完整的 URL 地址。 @@ -120,6 +129,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 `notify-batch` 字段是可选的。 + #### includes 对于较大的资源库，可以拆分 `packages.json` 为多个文件。`includes` 字段允许你引用这些额外的文件。 @@ -144,6 +154,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 此字段是可选的。你也许并不需要它来自定义存储库。 + #### provider-includes and providers-url 的对于非常大的资源库，像 packagist.org 使用 so-called provider 文件是首选方法。`provider-includes` 字段允许你设置一个列表，来申明这个资源库提供的包名称。在这种情况下文件的哈希算法必须使用 sha256。 @@ -181,14 +192,17 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 这些字段是可选的。你也许并不需要它们来自定义存储库。 + #### stream options `packages.json` 文件是用一个 PHP 流加载的。你可以使用 `options` 参数来设定额外的流信息。你可以设置任何有效的PHP 流上下文选项。更多相关信息请查看 [Context options and parameters](http://php.net/manual/en/context.php)。 + ### VCS VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管理系统。Composer 有一个资源类型可以从这些系统安装软件包。 + #### 从 VCS 资源库加载一个包 这里有几个用例。最常见的是维护自己 fork 的第三方库。如果你在项目中使用某些库，并且你决定改变这些库内的某些东西，你会希望你项目中使用的是你自己的修正版本。如果这个库是在 GitHub 上（这种情况经常出现），你可以简单的 fork 它并 push 你的变更到这个 fork 里。在这之后你更新项目的 `composer.json` 文件，添加你的 fork 作为一个资源库，变更版本约束来指向你的自定义分支。关于版本约束的命名约定请查看 [库（资源包）](02-libraries.md)。 @@ -213,6 +227,7 @@ VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管 如果其它包依赖你 fork 的这个分支，可能要对它做版本号的行内别名设置，才能够准确的识别版本约束。更多相关信息请查看 [别名](articles/aliases.md)。 + #### 使用私有资源库 完全相同的解决方案，也可以让你使用你 GitHub 和 BitBucket 上的私人代码库进行工作： @@ -231,6 +246,7 @@ VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管 唯一的要求是为一个 git 客户端安装 SSH 秘钥。 + #### Git 的备选方案 Git 并不是 VCS 资源库唯一支持的版本管理系统。 @@ -248,6 +264,7 @@ Git 并不是 VCS 资源库唯一支持的版本管理系统。 VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需要明确的指定一个 `git`、`svn` 或 `hg` 作为资源库类型，而不是 `vcs`。 + #### Subversion 选项 由于 Subversion 没有原生的分支和标签的概念，Composer 假设在默认情况下该代码位于 `$url/trunk`、`$url/branches` 和 `$url/tags` 内。如果你的存储库使用了不同的布局，你可以更改这些值。例如，如果你使用大写的名称，你可以像这样配置资源库： @@ -268,6 +285,7 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 如果是一个位于子目录的包，例如， `/trunk/foo/bar/composer.json` 和 `/tags/1.0/foo/bar/composer.json`，那么你可以让 composer 通过 `"package-path"` 选项设置的子目录进行访问，在这个例子中可以将其设置为 `"package-path": "foo/bar/"`。 + ### PEAR `pear` 类型资源库，使得从任何 PEAR 渠道安装资源包成为可能。Composer 将为所有此类型的包增加前缀（类似于 `pear-{渠道名称}/`）以避免冲突。而在之后使用别名时也增加前缀（如 `pear-{渠道别名}/`）。 @@ -291,6 +309,7 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 > **注意：** `pear` 类型的资源库对每个 requires 都要做完整的请求，因此可能大大降低安装速度。 + #### 自定义供应商别名 通过自定义供应商名称，对 PEAR 渠道包进行别名是允许的。 @@ -334,6 +353,7 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 } } + ### Package 如果你想使用一个项目，它无法通过上述任何一种方式支持 composer，你仍然可以使用 `package` 类型定义资源库。 @@ -376,6 +396,7 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 > - Composer 将不会更新资源包，除非你修改了 `version` 字段。 > - Composer 将不会更新 commit references，因此如果你使用 `master` reference，将不得不删除该程序包以强制更新，并且将不得不面对一个不稳定的 lock 文件。 + ## Hosting your own 尽管大部分的时间，你大概都会把资源包放在 packagist.org 上，但这里还将告诉你一些用例，以便你可以自行托管资源库。 @@ -388,6 +409,7 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 这里有一些工具，可以帮助你创建 `composer` 类型的资源库。 + ### Packagist packagist 的底层是开源的。这意味着你可以只安装你自己拷贝的 packagist，改造并使用它。这真的是很直接简单的事情。然而，由于其规模和复杂性，对于大多数中小型企业还是建议使用 Satis。 @@ -396,6 +418,7 @@ Packagist 是一个 Symfony2 应用程序，并且托管在 GitHub 上 [github.c 要设置你的副本，只需要按照 [github.com/composer/packagist](https://github.com/composer/packagist) 的说明进行操作。 + ### Satis Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻量级的、基于静态文件的 packagist 版本。 @@ -404,6 +427,7 @@ Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻 更多详细信息请查看 [github.com/composer/satis](https://github.com/composer/satis) 和 [Satis article](articles/handling-private-packages-with-satis.md)。 + ### Artifact 在某些情况下，或许没有能力拥有之前提到的任何一种线上资源库。Typical example could be cross-organisation library exchange through built artifacts。当然大部分的时间他们都是私有的。为了简化维护，可以简单的使用 `artifact` 资源库类型，来引用一个包含那些私有包的 ZIP 存档的文件夹： @@ -430,6 +454,7 @@ Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻 如果有两个不同版本的资源包，它们都会被导入。当有一个新版本的存档被添加到 artifact 文件夹，并且你运行了 `update` 命令，该版本就会被导入，并且 Composer 将更新到最新版本。 + ## 禁用 Packagist 你可以在 `composer.json` 中禁用默认的 Packagist 资源库。 -- 2.46.2 From cd9781a59343af1c16bfde9e58ed30a019f6818a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 13:35:41 +0800 Subject: [PATCH 066/125] update faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md --- README.md | 2 +- cn-introduction/articles/custom-installers.md | 2 +- ...ng-comparisons-and-wildcards-a-bad-idea.md | 23 ++++++------------- 3 files changed, 9 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 80e2b46..2311e66 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Expose command-line scripts from packages - [How Do I Install A Package To A Custom Path For My Framework](/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md) - [Should I Commit The Dependencies In My Vendor Directory](/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md) -- [Why Are Version Constraints Combining Comparisons And Wildcards A Bad Idea](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) +- [为什么说“比较符”和“通配符”相结合的版本约束是坏主意？](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) - [Why Can't Composer Load Repositories Recursively](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) ## PDF 文档 diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index 794d0c4..5c88848 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -174,7 +174,7 @@ different installation path. > _Instead of being installed in `/vendor` any package installed using this > Installer will be put in the `/data/templates/` folder._ -[1]: ../04-schema.md#安装类型-type +[1]: ../04-schema.md#type [2]: ../04-schema.md#extra [3]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/PluginInterface.php [4]: https://github.com/composer/composer/blob/master/src/Composer/Installer/InstallerInterface.php diff --git a/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md b/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md index bac633a..749fa11 100644 --- a/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md +++ b/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md @@ -1,21 +1,12 @@ -# Why are version constraints combining comparisons and wildcards a bad idea? +# 为什么说“比较符”和“通配符”相结合的版本约束是坏主意？ -This is a fairly common mistake people make, defining version constraints in -their package requires like `>=2.*` or `>=1.1.*`. +这是人们常犯的一个错误，定义了类似 `>=2.*` 或 `>=1.1.*` 的版本约束。 -If you think about it and what it really means though, you will quickly -realize that it does not make much sense. If we decompose `>=2.*`, you -have two parts: +通过思考它所表示的真正含义，你很快就会发现，它并没有多大意义。如果我们分解 `>=2.*`，你会得到两个部分： -- `>=2` which says the package should be in version 2.0.0 or above. -- `2.*` which says the package should be between version 2.0.0 (inclusive) - and 3.0.0 (exclusive). +- `>=2` 表示资源包应该是 2.0.0 或以上版本。 +- `2.*` 表示资源包版本应该介于 2.0.0 （含）和 3.0.0（不含）之间。 -As you see, both rules agree on the fact that the package must be >=2.0.0, -but it is not possible to determine if when you wrote that you were thinking -of a package in version 3.0.0 or not. Should it match because you asked for -`>=2` or should it not match because you asked for a `2.*`? +正如你所看到的，要同时满足这两个规则包版本必须 >=2.0.0，但它是无法判断的，因为当你这么写的时候，你究竟是想要包含 3.0.0 版本还是不包含？它应该进行匹配吗？因为你定义了 `>=2`，但同时你又限制它为 `2.*`。 -For this reason, Composer just throws an error and says that this is invalid. -The easy way to fix it is to think about what you really mean, and use only -one of those rules. \ No newline at end of file +出于这个原因，Composer 将抛出一个错误，并告诉你这是无效的。想要确切的表达你意思，最简单的方法就是仅使用“比较符”和“通配符”其中的一种来定义约束。 \ No newline at end of file -- 2.46.2 From de3d724332e7bbf7613e1942a4b9eaa56a694b96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 17:40:37 +0800 Subject: [PATCH 067/125] update should-i-commit-the-dependencies-in-my-vendor-directory.md --- ...the-dependencies-in-my-vendor-directory.md | 33 +++++++------------ 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md index 8e50f72..e6c01f8 100644 --- a/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md +++ b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md @@ -1,31 +1,20 @@ -# Should I commit the dependencies in my vendor directory? +# 我应该提交 vendor 目录中的依赖包吗？ -The general recommendation is **no**. The vendor directory (or wherever your -dependencies are installed) should be added to `.gitignore`/`svn:ignore`/etc. +一般情况下 **不建议**。vendor 目录（或者你安装依赖的其它目录）都应该被添加进 `.gitignore`/`svn:ignore`/等等。 -The best practice is to then have all the developers use Composer to install -the dependencies. Similarly, the build server, CI, deployment tools etc should -be adapted to run Composer as part of their project bootstrapping. +最好这么做，然后让所有开发人员使用 Composer 来安装依赖关系。同样，build server、CI、deployment tools 等等，应进行修改，使运行 Composer 成为其项目引导的一部分。 -While it can be tempting to commit it in some environment, it leads to a few -problems: +虽然在某些环境下提交它是很让人心动的，但它将导致一些问题： -- Large VCS repository size and diffs when you update code. -- Duplication of the history of all your dependencies in your own VCS. +- 当你更新代码时，将极大的增加 VCS 仓库的体积和差异。 +- 在你自己的 VCS 中将产生与你依赖的资源包重复的历史记录。 - Adding dependencies installed via git to a git repo will show them as submodules. This is problematic because they are not real submodules, and you will run into issues. -If you really feel like you must do this, you have a few options: +如果你真的觉得你必须这样做，你有几个选择： -1. Limit yourself to installing tagged releases (no dev versions), so that you - only get zipped installs, and avoid problems with the git "submodules". -2. Use --prefer-dist or set `preferred-install` to `dist` in your - [config](../04-schema.md#config). -3. Remove the `.git` directory of every dependency after the installation, then - you can add them to your git repo. You can do that with `rm -rf vendor/**/.git` - but this means you will have to delete those dependencies from disk before - running composer update. -4. Add a .gitignore rule (`vendor/.git`) to ignore all the vendor `.git` folders. - This approach does not require that you delete dependencies from disk prior to - running a composer update. +1. Limit yourself to installing tagged releases (no dev versions), so that you only get zipped installs, and avoid problems with the git "submodules". +2. 使用 --prefer-dist 或在 [config](../04-schema.md#config) 选项中设置 `preferred-install` 为 `dist`。 +3. 在每一个依赖安装后删除其下的 `.git` 文件夹，然后你就可以添加它们到你的 git repo 中。你可以运行 `rm -rf vendor/**/.git` 命令快捷的操作，但这意味着你在运行 composer update 命令前需要先删除磁盘中的依赖文件。 +4. 新增一个 .gitignore 规则（`vendor/.git`）来忽略 vendor 下所有 `.git` 目录。这种方法不需要你在运行 composer update 命令前删除你磁盘中的依赖文件。 -- 2.46.2 From 461034e570e999735aad15714e864fad0ea4c895 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 18:50:58 +0800 Subject: [PATCH 068/125] update should-i-commit-the-dependencies-in-my-vendor-directory.md --- README.md | 2 +- ...ould-i-commit-the-dependencies-in-my-vendor-directory.md | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2311e66..a7d9a96 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Expose command-line scripts from packages ## FAQs - [How Do I Install A Package To A Custom Path For My Framework](/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md) -- [Should I Commit The Dependencies In My Vendor Directory](/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md) +- [我应该提交 vendor 目录中的依赖包吗？](/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md) - [为什么说“比较符”和“通配符”相结合的版本约束是坏主意？](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) - [Why Can't Composer Load Repositories Recursively](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) diff --git a/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md index e6c01f8..5aca046 100644 --- a/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md +++ b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md @@ -8,13 +8,11 @@ - 当你更新代码时，将极大的增加 VCS 仓库的体积和差异。 - 在你自己的 VCS 中将产生与你依赖的资源包重复的历史记录。 -- Adding dependencies installed via git to a git repo will show them as - submodules. This is problematic because they are not real submodules, and you - will run into issues. +- 通过 git 的一个 git 仓库安装添加依赖，将把它们视作子模块。这是有问题的，因为它们并不是真正的子模块，并且你将会遇到这些问题。 如果你真的觉得你必须这样做，你有几个选择： -1. Limit yourself to installing tagged releases (no dev versions), so that you only get zipped installs, and avoid problems with the git "submodules". +1. 限制自己安装标记版本（无 dev 版本），这样你只会得到 zip 压缩的安装，并避免 git“子模块”出现的问题。 2. 使用 --prefer-dist 或在 [config](../04-schema.md#config) 选项中设置 `preferred-install` 为 `dist`。 3. 在每一个依赖安装后删除其下的 `.git` 文件夹，然后你就可以添加它们到你的 git repo 中。你可以运行 `rm -rf vendor/**/.git` 命令快捷的操作，但这意味着你在运行 composer update 命令前需要先删除磁盘中的依赖文件。 4. 新增一个 .gitignore 规则（`vendor/.git`）来忽略 vendor 下所有 `.git` 目录。这种方法不需要你在运行 composer update 命令前删除你磁盘中的依赖文件。 -- 2.46.2 From 20962b42faf75631975bdaece9b4d54cc347d64d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 21:37:55 +0800 Subject: [PATCH 069/125] update README.md cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md --- README.md | 2 +- ...ckage-to-a-custom-path-for-my-framework.md | 31 +++++-------------- 2 files changed, 8 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index a7d9a96..5b8bc6f 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Expose command-line scripts from packages ## FAQs -- [How Do I Install A Package To A Custom Path For My Framework](/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md) +- [如何为我的框架自定义一个资源包安装目录？](/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md) - [我应该提交 vendor 目录中的依赖包吗？](/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md) - [为什么说“比较符”和“通配符”相结合的版本约束是坏主意？](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) - [Why Can't Composer Load Repositories Recursively](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) diff --git a/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md b/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md index b5956ca..927ee4a 100644 --- a/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md +++ b/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md @@ -1,15 +1,8 @@ -# How do I install a package to a custom path for my framework? +# 如何为我的框架自定义一个资源包安装目录？ -Each framework may have one or many different required package installation -paths. Composer can be configured to install packages to a folder other than -the default `vendor` folder by using -[composer/installers](https://github.com/composer/installers). +每个框架都可能有一个或多个不同的依赖包安装目录。Composer 可以通过使用 [composer/installers](https://github.com/composer/installers) 来配置，安装依赖到其它的目录，而不是默认的 `vendor` 目录。 -If you are a **package author** and want your package installed to a custom -directory, simply require `composer/installers` and set the appropriate `type`. -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: +如果你是一个 **包作者** 并且希望自己的资源包被安装到自定义的目录中，简单的 require `composer/installers` 依赖，并设置适当的 `type` 属性。这是常见的方式，如果你的资源包专门用于一个框架，如 CakePHP、Drupal 或 WordPress。这是一个 WordPress 主题的 composer.json 文件的例子： { "name": "you/themename", @@ -19,16 +12,9 @@ WordPress theme: } } -Now when your theme is installed with Composer it will be placed into -`wp-content/themes/themename/` folder. Check the -[current supported types](https://github.com/composer/installers#current-supported-types) -for your package. +现在当你用 Composer 安装这个主题时，它就会被放置在 `wp-content/themes/themename/` 目录。目前已被支持的 `type` 类型请查看 [current supported types](https://github.com/composer/installers#current-supported-types)。 -As a **package consumer** you can set or override the install path for a package -that requires composer/installers by configuring the `installer-paths` extra. A -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: +对于一个 **包使用者** 你可以为一个包设置或覆盖安装路径，requires composer/installers 并在 extra 下设置 `installer-paths` 属性。Drupal 的多站点设置就是一个很好的例子，其中的资源包应该被安装到各自网站的子目录。在这里我们使用 composer/installers 来覆盖安装路径： { "extra": { @@ -38,9 +24,6 @@ for a module that uses composer/installers: } } -Now the package would be installed to your folder location, rather than the default -composer/installers determined location. +现在该资源包将被安装到你指定的目录，并替换 `$name` 变量，而不是默认目录。 -> **Note:** You cannot use this to change the path of any package. This is only -> applicable to packages that require `composer/installers` and use a custom type -> that it handles. +> **注意：** 你不能通过它改变所有包的安装目录。这仅适用于引入 `composer/installers` 依赖，自定义了 type 属性的资源包。 -- 2.46.2 From 814ae40d72d6176f5abda172f0ee0f15329bd8a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 9 Jan 2014 22:43:54 +0800 Subject: [PATCH 070/125] =?UTF-8?q?FAQ=20=E7=BF=BB=E8=AF=91=E7=BB=93?= =?UTF-8?q?=E6=9D=9F=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- ...-composer-load-repositories-recursively.md | 35 ++++--------------- 2 files changed, 8 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 5b8bc6f..f24ac5e 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Expose command-line scripts from packages - [如何为我的框架自定义一个资源包安装目录？](/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md) - [我应该提交 vendor 目录中的依赖包吗？](/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md) - [为什么说“比较符”和“通配符”相结合的版本约束是坏主意？](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) -- [Why Can't Composer Load Repositories Recursively](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) +- [为什么 Composer 不递归加载储存库？](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) ## PDF 文档 diff --git a/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md b/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md index d81a0f0..4b95922 100644 --- a/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md +++ b/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md @@ -1,34 +1,13 @@ -# Why can't Composer load repositories recursively? +# 为什么 Composer 不递归加载储存库？ -You may run into problems when using custom repositories because Composer does -not load the repositories of your requirements, so you have to redefine those -repositories in all your `composer.json` files. +当你使用自定义库时，你可能会碰到问题，因为 Composer 不会递归加载你要求的储存库，所以你必须修改这些储存库中所有的 `composer.json` 文件。 -Before going into details as to why this is like that, you have to understand -that the main use of custom VCS & package repositories is to temporarily try -some things, or use a fork of a project until your pull request is merged, etc. -You should not use them to keep track of private packages. For that you should -look into [setting up Satis](../articles/handling-private-packages-with-satis.md) -for your company or even for yourself. +在详细说明为什么是这样之前，你需要明白：使用自定义 VCS & 包储存库去尝试某些事情，或者使用你 fork 的一个分支，直到你的 pull request 被合并，等等。你不应该使用它们来跟踪你的私人资源包，关于这点你应该看看 [setting up Satis](../articles/handling-private-packages-with-satis.md) 来为你的公司甚至自己处理私人资源包。 -There are three ways the dependency solver could work with custom repositories: +这里有三个途径可以使依赖解析器使用你自定义的储存库： -- Fetch the repositories of root package, get all the packages from the defined -repositories, resolve requirements. This is the current state and it works well -except for the limitation of not loading repositories recursively. +- 读取根包的存储库，从定义的存储库得到所有的软件包，解析依赖需求。这是目前的状态，它工作得很好，除了有“无法递归的加载储存库”这个限制。 -- Fetch the repositories of root package, while initializing packages from the -defined repos, initialize recursively all repos found in those packages, and -their package's packages, etc, then resolve requirements. It could work, but it -slows down the initialization a lot since VCS repos can each take a few seconds, -and it could end up in a completely broken state since many versions of a package -could define the same packages inside a package repository, but with different -dist/source. There are many many ways this could go wrong. +- 读取根包的存储库，同时从定义的 repos 初始化资源包，递归的初始化，根据所有依赖包中定义的 repos，以及这些依赖包所依赖的其它包中定义的 repos，等等，然后再解析依赖需求。这可能可以工作，但会严重影响初始化的速度，因为每读取一个 VCS repos 都需要几秒钟。它可能最终执行失败，因为一个包的不同版本，可能来自一个包资源库中一个相同的包，但来至不同的 dist/source 。这样有太多的可能会出错。 -- Fetch the repositories of root package, then fetch the repositories of the -first level dependencies, then fetch the repositories of their dependencies, etc, -then resolve requirements. This sounds more efficient, but it suffers from the -same problems than the second solution, because loading the repositories of the -dependencies is not as easy as it sounds. You need to load all the repos of all -the potential matches for a requirement, which again might have conflicting -package definitions. +- 读取根包的存储库，然后读取第一级依赖，接着读取这些依赖包所依赖的其它包，等等，然后再解析依赖需求。这样听起来更有效率，但仍然存在第二种解决方案中的问题。因为加载依赖的储存库并不像听起来那么容易。你需要加载所有可能匹配依赖关系的 repos，而这些包的定义又可能是互相冲突的。 -- 2.46.2 From b7321bbc503b387bc85f89fafb65c0a3694b32d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 14 Jan 2014 20:06:41 +0800 Subject: [PATCH 071/125] update aliases.md --- cn-introduction/articles/aliases.md | 36 ++++++++--------------------- 1 file changed, 10 insertions(+), 26 deletions(-) diff --git a/cn-introduction/articles/aliases.md b/cn-introduction/articles/aliases.md index f8eab03..c9c4707 100644 --- a/cn-introduction/articles/aliases.md +++ b/cn-introduction/articles/aliases.md @@ -6,27 +6,17 @@ ## 为什么使用别名？ -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 -will get a `dev-master` version. For your `bugfix` branch, you will get a -`dev-bugfix` version. +当你使用 VCS 资源库，你将只会得到类似于这样的版本号：从分支发布的标签获取，它看起来像 `2.0`。比较特殊的是，对于你的 `master` 分支，你会得到一个最新提交的 `dev-master` 版本。对于你的 `bugfix` 分支，你会得到一个最新提交的 `dev-bugfix` 版本。以此类推，这些特殊的版本标识可以用来获取最新的分支源码。 -If your `master` branch is used to tag releases of the `1.0` development line, -i.e. `1.0.1`, `1.0.2`, `1.0.3`, etc., any package depending on it will -probably require version `1.0.*`. +如果你的 `master` 分支使用标签发布了 `1.0` 系列版本，即 `1.0.1`、`1.0.2`、`1.0.3` 等等，任何依赖它的资源包都可能会 require `1.0.*` 这个版本约束。 -If anyone wants to require the latest `dev-master`, they have a problem: Other -packages may require `1.0.*`, so requiring that dev version will lead to -conflicts, since `dev-master` does not match the `1.0.*` constraint. +如果有人想要最新的 `dev-master` 版本，他们将会碰到一个问题：其它的包可能还使用了 `1.0.*` 这个版本约束，因此在 require 这个开发版本时将会产生冲突，因为 `dev-master` 不符合 `1.0.*` 的约束。 -Enter aliases. +这时，就可以使用别名。 -## Branch alias +## 分支别名 -The `dev-master` branch is one in your main VCS repo. It is rather common that -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`: +`dev-master` 分支是一个在你 VCS 项目上的主分支。有些用户会想要使用最新的开发版本，这是相当常见的情况。因此，Composer 允许你别名你的 `dev-master` 分支为一个 `1.0.x-dev` 的版本。这是通过在 `composer.json` 文件中的 `extra` 下指定 `branch-alias` 字段来完成的： { "extra": { @@ -36,19 +26,13 @@ specifying a `branch-alias` field under `extra` in `composer.json`: } } -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 -`.x-dev`). The `branch-alias` must be present on the branch that it references. -For `dev-master`, you need to commit it on the `master` branch. +此处的分支版本必须以 `dev-` 开头（不可比较的版本名称），对应的别名必须是可比较的开发版本名称（即，以数字开头，并以 `.x-dev` 结束）。`branch-alias` 所引用的分支必须是存在的。对于 `dev-master` 你需要在 `master` 分支上提交它。 -As a result, anyone can now require `1.0.*` and it will happily install -`dev-master`. +其结果是，任何人都可以 require `1.0.*` 版本，并且他们实际将会得到 `dev-master` 版本。 -In order to use branch aliasing, you must own the repository of the package -being aliased. If you want to alias a third party package without maintaining -a fork of it, use inline aliases as described below. +为了定义分支别名，你必须是需要别名的包的所有者。如果你想别名一个第三方包，而又不想 fork 它到自己的版本库，可以使用行内别名，我们在接下来就会提到它。 -## Require inline alias +## Require 中使用行内别名 Branch aliases are great for aliasing main development lines. But in order to use them you need to have control over the source repository, and you need to -- 2.46.2 From a5f3ba2e56b81264f6bc1b595068bd1c06b8b616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 14 Jan 2014 20:52:01 +0800 Subject: [PATCH 072/125] update aliases.md --- cn-introduction/articles/aliases.md | 31 ++++++++++------------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/cn-introduction/articles/aliases.md b/cn-introduction/articles/aliases.md index c9c4707..1fb8ae8 100644 --- a/cn-introduction/articles/aliases.md +++ b/cn-introduction/articles/aliases.md @@ -8,15 +8,15 @@ 当你使用 VCS 资源库，你将只会得到类似于这样的版本号：从分支发布的标签获取，它看起来像 `2.0`。比较特殊的是，对于你的 `master` 分支，你会得到一个最新提交的 `dev-master` 版本。对于你的 `bugfix` 分支，你会得到一个最新提交的 `dev-bugfix` 版本。以此类推，这些特殊的版本标识可以用来获取最新的分支源码。 -如果你的 `master` 分支使用标签发布了 `1.0` 系列版本，即 `1.0.1`、`1.0.2`、`1.0.3` 等等，任何依赖它的资源包都可能会 require `1.0.*` 这个版本约束。 +如果你的 `master` 分支使用标签发布了 `1.0` 系列版本，即 `1.0.1`、`1.0.2`、`1.0.3` 等等，任何依赖它的资源包都可能会使用 `1.0.*` 这个版本约束。 -如果有人想要最新的 `dev-master` 版本，他们将会碰到一个问题：其它的包可能还使用了 `1.0.*` 这个版本约束，因此在 require 这个开发版本时将会产生冲突，因为 `dev-master` 不符合 `1.0.*` 的约束。 +如果有人想要最新的 `dev-master` 版本，他们将会碰到一个问题：另一些依赖它的包可能使用了 `1.0.*` 这个版本约束，因此在 require 这个开发版本时将会产生冲突，因为 `dev-master` 不符合 `1.0.*` 的约束。 这时，就可以使用别名。 ## 分支别名 -`dev-master` 分支是一个在你 VCS 项目上的主分支。有些用户会想要使用最新的开发版本，这是相当常见的情况。因此，Composer 允许你别名你的 `dev-master` 分支为一个 `1.0.x-dev` 的版本。这是通过在 `composer.json` 文件中的 `extra` 下指定 `branch-alias` 字段来完成的： +`dev-master` 指向一个在你 VCS 项目上的主分支。有些用户会想要使用最新的开发版本，这是相当常见的情况。因此，Composer 允许你别名你的 `dev-master` 版本为一个 `1.0.x-dev` 的版本号。这是通过在 `composer.json` 文件中的 `extra` 下指定 `branch-alias` 字段来完成的： { "extra": { @@ -28,29 +28,21 @@ 此处的分支版本必须以 `dev-` 开头（不可比较的版本名称），对应的别名必须是可比较的开发版本名称（即，以数字开头，并以 `.x-dev` 结束）。`branch-alias` 所引用的分支必须是存在的。对于 `dev-master` 你需要在 `master` 分支上提交它。 -其结果是，任何人都可以 require `1.0.*` 版本，并且他们实际将会得到 `dev-master` 版本。 +其结果是，任何人都可以使用 `1.0.*` 版本约束来得到 `dev-master` 版本。 为了定义分支别名，你必须是需要别名的包的所有者。如果你想别名一个第三方包，而又不想 fork 它到自己的版本库，可以使用行内别名，我们在接下来就会提到它。 -## Require 中使用行内别名 +## 使用行内别名 -Branch aliases are great for aliasing main development lines. But in order to -use them you need to have control over the source repository, and you need to -commit changes to version control. +分支别名是非常适合用于主开发分支的。但为了使用它们，你需要拥有对源码的控制权，并且你需要提交别名修改到你控制的版本库。 -This is not really fun when you just want to try a bugfix of some library that -is a dependency of your local project. +当你只想在本地项目中尝试一些依赖库的 bug 修正时，这并不是最好的方式。 -For this reason, you can alias packages in your `require` and `require-dev` -fields. Let's say you found a bug in the `monolog/monolog` package. You cloned -[Monolog](https://github.com/Seldaek/monolog) on GitHub and fixed the issue in -a branch named `bugfix`. Now you want to install that version of monolog in your -local project. +出于这个原因，你可以在 `require` 和 `require-dev` 字段中直接别名你需要的包。比方说那你找到了 `monolog/monolog` 的一个 bug。你在 GitHub 上克隆了 [Monolog](https://github.com/Seldaek/monolog) 并在名为 `bugfix` 的分支上修正了一个问题。现在你想安装这个版本到你的本地项目。 -You are using `symfony/monolog-bundle` which requires `monolog/monolog` version -`1.*`. So you need your `dev-bugfix` to match that constraint. +你所使用的 `symfony/monolog-bundle` require 了 `monolog/monolog` 并约束了版本 `1.*`. 因此你需要让你的 `dev-bugfix` 满足该版本约束。 -Just add this to your project's root `composer.json`: +只要在你项目根目录的 `composer.json` 文件中加入以下内容： { "repositories": [ @@ -65,8 +57,7 @@ Just add this to your project's root `composer.json`: } } -That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub -and alias it to `1.0.x-dev`. +它将会在你的 GitHub 上获取 `monolog/monolog` 的 `dev-bugfix` 版本并将其版本别名为 `1.0.x-dev`。 > **Note:** If a package with inline aliases is required, the alias (right of > the `as`) is used as the version constraint. The part left of the `as` is -- 2.46.2 From cf3fc8ea68e1fa848a975c240cff0a7cdb4055cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 14 Jan 2014 21:10:43 +0800 Subject: [PATCH 073/125] =?UTF-8?q?=E5=88=AB=E5=90=8D=20=E7=AB=A0=E8=8A=82?= =?UTF-8?q?=E7=BF=BB=E8=AF=91=E7=BB=93=E6=9D=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/articles/aliases.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/cn-introduction/articles/aliases.md b/cn-introduction/articles/aliases.md index 1fb8ae8..71f90b5 100644 --- a/cn-introduction/articles/aliases.md +++ b/cn-introduction/articles/aliases.md @@ -59,13 +59,7 @@ 它将会在你的 GitHub 上获取 `monolog/monolog` 的 `dev-bugfix` 版本并将其版本别名为 `1.0.x-dev`。 -> **Note:** If a package with inline aliases is required, the alias (right of -> the `as`) is used as the version constraint. The part left of the `as` is -> discarded. As a consequence, if A requires B and B requires `monolog/monolog` -> version `dev-bugfix as 1.0.x-dev`, installing A will make B require -> `1.0.x-dev`, which may exist as a branch alias or an actual `1.0` branch. If -> it does not, it must be re-inline-aliased in A's `composer.json`. +> **注意：** 如果要对一个资源包使用行内别名，这个别名（`as` 的右边）必须能够使用版本约束。`as` 左边的部分在这之后将被丢弃。因此，如果 A 依赖 B 而 B 又依赖 `monolog/monolog` 且版本约束为 `dev-bugfix as 1.0.x-dev`，那么安装 A 时将使用 B 的版本约束，并识别为 `1.0.x-dev`，此时必须真实存在一个“分支别名”或“1.0 系列分支”。否则就必须在 A 的 `composer.json` 文件中再次定义行内别名。 + +> **注意：** 应该尽量避免行内别名，特别是对已经发布的包。如果你发现了一个 bug，请尝试将你的修复合并到上游分支。这将避免使用你资源包的用户出现问题。 -> **Note:** Inline aliasing should be avoided, especially for published -> packages. If you found a bug, try and get your fix merged upstream. This -> helps to avoid issues for users of your package. -- 2.46.2 From bd88ab8976fa665dc8f26c42bb529c7928aca7d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Tue, 14 Jan 2014 21:44:01 +0800 Subject: [PATCH 074/125] Update README.md --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f24ac5e..7a03b46 100644 --- a/README.md +++ b/README.md @@ -48,4 +48,8 @@ Expose command-line scripts from packages ## API 文档 -如果你需要在工作中使用 composer 作为库的管理，你或许也想看看 [API 文档](http://getcomposer.org/apidoc/master/index.html)。 \ No newline at end of file +如果你需要在工作中使用 composer 作为库的管理，你或许也想看看 [API 文档](http://getcomposer.org/apidoc/master/index.html)。 + +## 相关文章推荐 + +- [PHP 开发者该知道的5个 Composer 小技巧](http://segmentfault.com/a/1190000000355928) -- 2.46.2 From 2bb050e42b78682a9dc5bf7353c74ae9d069f41b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 15 Jan 2014 21:08:15 +0800 Subject: [PATCH 075/125] update custom-installers.md --- cn-introduction/articles/custom-installers.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index 5c88848..8a9c5c7 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -12,22 +12,17 @@ ## 调用自定义安装程序 -假设你的项目已经有了一个自定义的安装模块，那么如何根据 [type][1] 正确调用你包文件中的安装程序就成为了一个问题。 +假设你的项目已经有了一个自定义的安装模块，那么如何根据 [安装类型][1] 正确调用你包文件中的安装程序就成为了一个问题。 > _参见见下一章，如何通过指令创建自定义安装程序。_ -Every Custom Installer defines which [type][1] string it will recognize. Once -recognized it will completely override the default installer and only apply its -own logic. +任何自定义安装程序都要通过 [type][1] 属性来识别。一旦被确认，它将完全覆盖默认的安装程序，并执行自己的安装逻辑。 -An example use-case would be: +一个实际用例： -> phpDocumentor features Templates that need to be installed outside of the -> default /vendor folder structure. As such they have chosen to adopt the -> `phpdocumentor-template` [type][1] and create a plugin providing the Custom -> Installer to send these templates to the correct folder. +> phpDocumentor 的特殊模板需要安装在 /vendor 以外的其它目录中。因此他们选择 `phpdocumentor-template` [安装类型][1] 并为此类型创建了一个插件，以便将他们的模板发送到正确的目录中。 -An example composer.json of such a template package would be: +在这样一个模板包的例子中 composer.json 将使用以下设置： { "name": "phpdocumentor/template-responsive", @@ -37,9 +32,7 @@ An example composer.json of such a template package would be: } } -> **IMPORTANT**: to make sure that the template installer is present at the -> time the template package is installed, template packages should require -> the plugin package. +> **重要提示：** 为了确保这个模板安装程序在安装模板包之前就已存在，模板包必须写入对此安装程序包的依赖。 ## Creating an Installer -- 2.46.2 From 5a2d3dce562c7a560cab76ac49d06b4b89b03716 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 15 Jan 2014 21:37:24 +0800 Subject: [PATCH 076/125] update custom-installers.md --- cn-introduction/articles/custom-installers.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index 8a9c5c7..8a6bc9d 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -34,17 +34,15 @@ > **重要提示：** 为了确保这个模板安装程序在安装模板包之前就已存在，模板包必须写入对此安装程序包的依赖。 -## Creating an Installer +## 创建一个安装程序 -A Custom Installer is defined as a class that implements the -[`Composer\Installer\InstallerInterface`][3] and is usually distributed in a -Composer Plugin. +一个自定义安装程序通常是以 Composer 插件的形式存在，并包含有一个类，它实现了 [`Composer\Installer\InstallerInterface`][3] 这个接口。 -A basic Installer Plugin would thus compose of three files: +一个基本的安装程序插件必须由3个文件组成： -1. the package file: composer.json -2. The Plugin class, e.g.: `My\Project\Composer\Plugin.php`, containing a class that implements `Composer\Plugin\PluginInterface`. -3. The Installer class, e.g.: `My\Project\Composer\Installer.php`, containing a class that implements `Composer\Installer\InstallerInterface`. +1. 包文件：composer.json +2. 插件类，例如：`My\Project\Composer\Plugin.php`，其中的类必须实现 `Composer\Plugin\PluginInterface` 接口。 +3. 安装程序类，例如：`My\Project\Composer\Installer.php`，其中的类必须实现 `Composer\Installer\InstallerInterface` 接口。 ### composer.json -- 2.46.2 From 4864d237b6f02a23c837b28c961d97e181d00104 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 15 Jan 2014 22:14:09 +0800 Subject: [PATCH 077/125] update custom-installers.md --- cn-introduction/articles/custom-installers.md | 37 +++++++------------ 1 file changed, 13 insertions(+), 24 deletions(-) diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index 8a6bc9d..2d69a8b 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -46,15 +46,12 @@ ### composer.json -The package file is the same as any other package file but with the following -requirements: +此处的包文件和普通资源包是相同的，但需要满足以下条件： -1. the [type][1] attribute must be `composer-plugin`. -2. the [extra][2] attribute must contain an element `class` defining the - class name of the plugin (including namespace). If a package contains - multiple plugins this can be array of class names. +1. [type][1] 属性必须是 `composer-plugin`。 +2. [extra][2] 属性必须包含 `class` 元素，它定义了插件类的名称（包含命名空间）。如果这个包有多个插件类，可以使用数组的形式进行定义。 -Example: +例： { "name": "phpdocumentor/template-installer-plugin", @@ -71,16 +68,13 @@ Example: } } -### The Plugin class +### 插件类 -The class defining the Composer plugin must implement the -[`Composer\Plugin\PluginInterface`][3]. It can then register the Custom -Installer in its `activate()` method. +这个类定义了 Composer 的插件，它必须实现 [`Composer\Plugin\PluginInterface`][3] 这个接口。它可以在 `activate()` 方法中注册自定义安装程序。 -The class may be placed in any location and have any name, as long as it is -autoloadable and matches the `extra.class` element in the package definition. +这个类可以被放在任何位置、使用任何名字，只要能够根据 `extra.class` 中的定义被自动加载即可。 -Example: +例： namespace phpDocumentor\Composer; @@ -97,18 +91,13 @@ Example: } } -### The Custom Installer class +### 自定义安装程序类 -The class that executes the custom installation should implement the -[`Composer\Installer\InstallerInterface`][4] (or extend another installer that -implements that interface). It defines the [type][1] string as it will be -recognized by packages that will use this installer in the `supports()` method. +这个类用于执行自定义的安装过程，它必须实现 [`Composer\Installer\InstallerInterface`][4] 这个接口（或者继承了另一个实现此接口的安装程序类）。It defines the [type][1] string as it will be recognized by packages that will use this installer in the `supports()` method. -> **NOTE**: _choose your [type][1] name carefully, it is recommended to follow -> the format: `vendor-type`_. For example: `phpdocumentor-template`. +> **注意：** _请慎重选择你的 [安装类型][1] 名称，建议遵循这样的格式：`vendor-type`_。例如：`phpdocumentor-template`。 -The InstallerInterface class defines the following methods (please see the -source for the exact signature): +InstallerInterface 类定义了以下方法（请查阅源码以获得更详细的信息）： * **supports()**, here you test whether the passed [type][1] matches the name that you declared for this installer (see the example). @@ -122,7 +111,7 @@ source for the exact signature): * **getInstallPath()**, this method should return the location where the package is to be installed, _relative from the location of composer.json._ -Example: +例： namespace phpDocumentor\Composer; -- 2.46.2 From e4e76ded4c155c19ebca16ddf73a36dacc8f67d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 15 Jan 2014 22:57:32 +0800 Subject: [PATCH 078/125] update custom-installers.md --- cn-introduction/articles/custom-installers.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index 2d69a8b..c64363e 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -146,13 +146,9 @@ InstallerInterface 类定义了以下方法（请查阅源码以获得更详细 } } -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 -different installation path. +这个例子演示了，简单的继承 [`Composer\Installer\LibraryInstaller`][5] 类来剥离 `phpdocumentor/template-` 前缀，并用剩余的部分重新组装了一个完全不同的安装路径。 -> _Instead of being installed in `/vendor` any package installed using this -> Installer will be put in the `/data/templates/` folder._ +> _并非安装在 `/vendor` 目录，任何使用这个安装程序的资源包，将被放置在 `/data/templates/` 目录中。_ [1]: ../04-schema.md#type [2]: ../04-schema.md#extra -- 2.46.2 From f366a02b7052212da26ec660a202850fa2a9ca5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Wed, 15 Jan 2014 23:41:41 +0800 Subject: [PATCH 079/125] update custom-installers.md --- cn-introduction/articles/custom-installers.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index c64363e..deae586 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -93,23 +93,19 @@ ### 自定义安装程序类 -这个类用于执行自定义的安装过程，它必须实现 [`Composer\Installer\InstallerInterface`][4] 这个接口（或者继承了另一个实现此接口的安装程序类）。It defines the [type][1] string as it will be recognized by packages that will use this installer in the `supports()` method. +这个类用于执行自定义的安装过程，它必须实现 [`Composer\Installer\InstallerInterface`][4] 这个接口（或者继承了另一个实现此接口的安装程序类）。它将会对 [安装类型][1] 中定义的字符串执行 `supports()` 方法验证，一旦通过就采用对应的安装程序。 > **注意：** _请慎重选择你的 [安装类型][1] 名称，建议遵循这样的格式：`vendor-type`_。例如：`phpdocumentor-template`。 InstallerInterface 类定义了以下方法（请查阅源码以获得更详细的信息）： -* **supports()**, here you test whether the passed [type][1] matches the name - that you declared for this installer (see the example). -* **isInstalled()**, determines whether a supported package is installed or not. -* **install()**, here you can determine the actions that need to be executed - upon installation. +* **supports()** 在这里测试你发布的这个安装程序名称是否通过 [安装类型][1] 匹配（参见示例）。只有正确匹配的资源包才会使用此安装程序进行安装。 +* **isInstalled()** 确定支持的资源包是否已安装。 +* **install()** 这里你可以定义在安装时需要执行的动作。 * **update()**, here you define the behavior that is required when Composer is invoked with the update argument. -* **uninstall()**, here you can determine the actions that need to be executed - when the package needs to be removed. -* **getInstallPath()**, this method should return the location where the - package is to be installed, _relative from the location of composer.json._ +* **uninstall()** 这里你可以定义在移除一个包时需要执行的动作。 +* **getInstallPath()** 这个方法需要返回一个资源包将要安装的位置。_相对于 composer.json 文件的位置。_ 例： -- 2.46.2 From ab944c2ee96f7f809f7d2a65815be20e87e010f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 16 Jan 2014 00:01:23 +0800 Subject: [PATCH 080/125] =?UTF-8?q?=E8=AE=BE=E7=BD=AE=E5=92=8C=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E8=87=AA=E5=AE=9A=E4=B9=89=E5=AE=89=E8=A3=85=E7=B1=BB?= =?UTF-8?q?=E5=9E=8B=20=E7=BF=BB=E8=AF=91=E7=BB=93=E6=9D=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/articles/custom-installers.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index deae586..8f22e16 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -102,8 +102,7 @@ InstallerInterface 类定义了以下方法（请查阅源码以获得更详细 * **supports()** 在这里测试你发布的这个安装程序名称是否通过 [安装类型][1] 匹配（参见示例）。只有正确匹配的资源包才会使用此安装程序进行安装。 * **isInstalled()** 确定支持的资源包是否已安装。 * **install()** 这里你可以定义在安装时需要执行的动作。 -* **update()**, here you define the behavior that is required when Composer is - invoked with the update argument. +* **update()** 这里你可以定义在更新时需要执行的动作。当 Composer 调用更新参数时这是必须的。 * **uninstall()** 这里你可以定义在移除一个包时需要执行的动作。 * **getInstallPath()** 这个方法需要返回一个资源包将要安装的位置。_相对于 composer.json 文件的位置。_ -- 2.46.2 From 2f9b3e40468ec5622dffbfe578ee40464c4f5e49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 20 Jan 2014 14:03:25 +0800 Subject: [PATCH 081/125] update plugins.md --- cn-introduction/articles/plugins.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md index 75706f7..e508bd8 100644 --- a/cn-introduction/articles/plugins.md +++ b/cn-introduction/articles/plugins.md @@ -2,17 +2,13 @@ tagline: Modify and extend Composer's functionality --> -# Setting up and using plugins +# 设置和使用插件 -## Synopsis +## 概述 -You may wish to alter or expand Composer's functionality with your own. For -example if your environment poses special requirements on the behaviour of -Composer which do not apply to the majority of its users or if you wish to -accomplish something with composer in a way that is not desired by most users. +你可能需要改变和扩展 Composer 加入自定义的功能。例如：如果你的环境对 Composer 的行为有特殊要求，而这并不适用于普通用户。又或者，你想使用 Composer 完成某些事情，而又不希望对普通用户造成影响。 -In these cases you could consider creating a plugin to handle your -specific logic. +在这些情况下，你可以考虑创建一个插件来处理特定的逻辑。 ## Creating a Plugin -- 2.46.2 From b2399d9b37d2e3b2223d7b08f6b2eaeb9c05da65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 20 Jan 2014 15:38:33 +0800 Subject: [PATCH 082/125] update plugins.md --- cn-introduction/articles/plugins.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md index e508bd8..2746cc8 100644 --- a/cn-introduction/articles/plugins.md +++ b/cn-introduction/articles/plugins.md @@ -10,20 +10,16 @@ 在这些情况下，你可以考虑创建一个插件来处理特定的逻辑。 -## Creating a Plugin +## 创建一个插件 -A plugin is a regular composer package which ships its code as part of the -package and may also depend on further packages. +一个插件就是一个普通的 Composer 资源包，插件的主要代码都位于这个包中，并且还可以依赖更多其它的资源包。 -### Plugin Package +### 插件包 -The package file is the same as any other package file but with the following -requirements: +插件包内的文件和普通资源包相同，但必须满足下列要求： -1. the [type][1] attribute must be `composer-plugin`. -2. the [extra][2] attribute must contain an element `class` defining the - class name of the plugin (including namespace). If a package contains - multiple plugins this can be array of class names. +1. [type][1] 属性必须是 `composer-plugin`。 +2. [extra][2] 属性必须包含一个元素 `class`，它定义了插件类的名称（包含命名空间）。如果一个包中含有多个插件，则可以使用数组来定义类名。 Additionally you must require the special package called `composer-plugin-api` to define which composer API versions your plugin is compatible with. The -- 2.46.2 From 01dc8f8133f296185240e97edaf6ce2c530bd1e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 20 Jan 2014 15:50:19 +0800 Subject: [PATCH 083/125] update plugins.md --- cn-introduction/articles/plugins.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md index 2746cc8..c05e0b8 100644 --- a/cn-introduction/articles/plugins.md +++ b/cn-introduction/articles/plugins.md @@ -21,11 +21,9 @@ 1. [type][1] 属性必须是 `composer-plugin`。 2. [extra][2] 属性必须包含一个元素 `class`，它定义了插件类的名称（包含命名空间）。如果一个包中含有多个插件，则可以使用数组来定义类名。 -Additionally you must require the special package called `composer-plugin-api` -to define which composer API versions your plugin is compatible with. The -current composer plugin API version is 1.0.0. +此外，你必须 require 一个特殊的资源包 `composer-plugin-api`，定义与你的插件相兼容的 composer plugin API 版本。目前 composer plugin API 的版本为1.0.0。 -For example +例如： { "name": "my/plugin-package", @@ -35,7 +33,7 @@ For example } } -### Plugin Class +### 插件类 Every plugin has to supply a class which implements the [`Composer\Plugin\PluginInterface`][3]. The `activate()` method of the plugin -- 2.46.2 From 2a31df93308efb64cf1e38d6e7312f82bc7979b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 20 Jan 2014 16:38:50 +0800 Subject: [PATCH 084/125] update plugins.md --- cn-introduction/articles/plugins.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md index c05e0b8..9592930 100644 --- a/cn-introduction/articles/plugins.md +++ b/cn-introduction/articles/plugins.md @@ -35,14 +35,9 @@ ### 插件类 -Every plugin has to supply a class which implements the -[`Composer\Plugin\PluginInterface`][3]. The `activate()` method of the plugin -is called after the plugin is loaded and receives an instance of -[`Composer\Composer`][4] as well as an instance of -[`Composer\IO\IOInterface`][5]. Using these two objects all configuration can -be read and all internal objects and state can be manipulated as desired. +每一个插件都必须提供一个实现了 [`Composer\Plugin\PluginInterface`][3] 接口的类。类中的 `activate()` 方法在插件载入后被调用，并接收两个类的实例：[`Composer\Composer`][4] 和 [`Composer\IO\IOInterface`][5]。使用这两个对象可以读取所有的配置，操作所有的内部对象和状态。 -Example: +例如： namespace phpDocumentor\Composer; -- 2.46.2 From 571287e2ef46a878feb562ee479de28936520aeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 20 Jan 2014 17:41:08 +0800 Subject: [PATCH 085/125] update plugins.md --- cn-introduction/articles/plugins.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md index 9592930..daea30e 100644 --- a/cn-introduction/articles/plugins.md +++ b/cn-introduction/articles/plugins.md @@ -54,22 +54,16 @@ } } -## Event Handler +## 事件处理程序 -Furthermore plugins may implement the -[`Composer\EventDispatcher\EventSubscriberInterface`][6] in order to have its -event handlers automatically registered with the `EventDispatcher` when the -plugin is loaded. +此外，插件还可以实现 [`Composer\EventDispatcher\EventSubscriberInterface`][6] 接口，为了在插件载入后自动注册事件处理程序到 `EventDispatcher`。 -The events available for plugins are: +插件可用事件如下： -* **COMMAND**, is called at the beginning of all commands that load plugins. - It provides you with access to the input and output objects of the program. -* **PRE_FILE_DOWNLOAD**, is triggered before files are downloaded and allows - you to manipulate the `RemoteFilesystem` object prior to downloading files - based on the URL to be downloaded. +* **COMMAND** 在载入插件的所有命令前被调用。它为你提供了访问程序输入输出的对象。 +* **PRE_FILE_DOWNLOAD** 在文件下载前被触发，它允许你在下载前根据目标 URL 操作 `RemoteFilesystem` 对象。 -> A plugin can also subscribe to [script events][7]. +> 一个插件也可以订阅 [脚本事件][7]。 Example: @@ -114,7 +108,7 @@ Example: } } -## Using Plugins +## 使用插件 Plugin packages are automatically loaded as soon as they are installed and will be loaded when composer starts up if they are found in the current project's -- 2.46.2 From 566936807432e6b27750d647a35d78de91d8edc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Mon, 20 Jan 2014 19:01:07 +0800 Subject: [PATCH 086/125] =?UTF-8?q?=E2=80=9C=E6=8F=92=E4=BB=B6=E2=80=9D?= =?UTF-8?q?=E7=AB=A0=E8=8A=82=E7=BF=BB=E8=AF=91=E7=BB=93=E6=9D=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 ++-- cn-introduction/articles/plugins.md | 16 +++++----------- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 7a03b46..332127e 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,8 @@ Composer 中文文档 修改某些特殊类型包的安装方式。 - [Handling Private Packages With Satis](/cn-introduction/articles/handling-private-packages-with-satis.md) Host your own composer repository -- [Plugins](/cn-introduction/articles/plugins.md) -Modify and extend Composer's functionality +- [插件](/cn-introduction/articles/plugins.md) +修改和扩展 Composer 的功能。 - [Scripts](/cn-introduction/articles/scripts.md) Script are callbacks that are called before/after installing packages - [Troubleshooting](/cn-introduction/articles/troubleshooting.md) diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md index daea30e..240a838 100644 --- a/cn-introduction/articles/plugins.md +++ b/cn-introduction/articles/plugins.md @@ -23,7 +23,7 @@ 此外，你必须 require 一个特殊的资源包 `composer-plugin-api`，定义与你的插件相兼容的 composer plugin API 版本。目前 composer plugin API 的版本为1.0.0。 -例如： +例： { "name": "my/plugin-package", @@ -37,7 +37,7 @@ 每一个插件都必须提供一个实现了 [`Composer\Plugin\PluginInterface`][3] 接口的类。类中的 `activate()` 方法在插件载入后被调用，并接收两个类的实例：[`Composer\Composer`][4] 和 [`Composer\IO\IOInterface`][5]。使用这两个对象可以读取所有的配置，操作所有的内部对象和状态。 -例如： +例： namespace phpDocumentor\Composer; @@ -65,7 +65,7 @@ > 一个插件也可以订阅 [脚本事件][7]。 -Example: +例： namespace Naderman\Composer\AWS; @@ -110,15 +110,9 @@ Example: ## 使用插件 -Plugin packages are automatically loaded as soon as they are installed and will -be loaded when composer starts up if they are found in the current project's -list of installed packages. Additionally all plugin packages installed in the -`COMPOSER_HOME` directory using the composer global command are loaded before -local project plugins are loaded. +插件包是优先被安装和加载的，在 Composer 启动时，如果在已安装资源包的当前项目列表中被找到，它们将被自动加载。此外，所有的插件包将被安装在 `COMPOSER_HOME` 目录，以便在 Composer 全局命令前载入，在操作本地项目前插件就已经被载入。 -> You may pass the `--no-plugins` option to composer commands to disable all -> installed commands. This may be particularly helpful if any of the plugins -> causes errors and you wish to update or uninstall it. +> 你可以通过 `--no-plugins` 选项让 composer 的命令禁用所有已经安装的插件。这或许是特别有用的，如果任何插件会导致错误，而你想要升级或卸载它。 [1]: ../04-schema.md#type [2]: ../04-schema.md#extra -- 2.46.2 From 21706723a53fbd4201a1c2136be501e1f7f8c30d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 30 Jan 2014 19:29:52 +0800 Subject: [PATCH 087/125] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E9=94=9A=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/00-intro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md index 1cc3ca5..556ecd4 100644 --- a/cn-introduction/00-intro.md +++ b/cn-introduction/00-intro.md @@ -6,7 +6,7 @@ Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖 --- - [简介](#Introduction) - - [依赖管理](#Dependency management) + - [依赖管理](#Dependency-management) - [声明依赖关系](#Declaring dependencies) - [系统要求](#System Requirements) - [安装 - *nix](#Installation - *nix) @@ -22,7 +22,7 @@ Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖 --- - + ## 依赖管理 Composer 不是一个包管理器。是的，它涉及 "packages" 和 "libraries"，但它在每个项目的基础上进行管理，在你项目的某个目录中（例如 `vendor`）进行安装。默认情况下它不会在全局安装任何东西。因此，这仅仅是一个依赖管理。 -- 2.46.2 From 8c49b942feeb6ae86c4a7d8da391218bc4f1e0f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Thu, 30 Jan 2014 21:41:43 +0800 Subject: [PATCH 088/125] update custom-installers.md --- cn-introduction/articles/custom-installers.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index 8f22e16..d5f04b1 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -20,7 +20,8 @@ 一个实际用例： -> phpDocumentor 的特殊模板需要安装在 /vendor 以外的其它目录中。因此他们选择 `phpdocumentor-template` [安装类型][1] 并为此类型创建了一个插件，以便将他们的模板发送到正确的目录中。 +> phpDocumentor 的特殊模板需要安装在 /vendor 以外的其它目录中。 +> 因此他们选择 `phpdocumentor-template` [安装类型][1] 并为此类型创建了一个插件，以便将他们的模板发送到正确的目录中。 在这样一个模板包的例子中 composer.json 将使用以下设置： -- 2.46.2 From f76612ea1b19db6ee82d4613c3e19bd7a2ca9ea2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 31 Jan 2014 00:20:36 +0800 Subject: [PATCH 089/125] update --- cn-introduction/00-intro.md | 38 +++++++++++++++---------------- cn-introduction/01-basic-usage.md | 32 +++++++++++++------------- 2 files changed, 35 insertions(+), 35 deletions(-) diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md index 556ecd4..ede543e 100644 --- a/cn-introduction/00-intro.md +++ b/cn-introduction/00-intro.md @@ -7,17 +7,17 @@ Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖 - [简介](#Introduction) - [依赖管理](#Dependency-management) - - [声明依赖关系](#Declaring dependencies) - - [系统要求](#System Requirements) - - [安装 - *nix](#Installation - *nix) - - [下载 Composer 的可执行文件](#Downloading the Composer Executable) + - [声明依赖关系](#Declaring-dependencies) + - [系统要求](#System-Requirements) + - [安装 - *nix](#Installation-*nix) + - [下载 Composer 的可执行文件](#Downloading-the-Composer-Executable) - [局部安装](#Locally) - [全局安装](#Globally) - - [全局安装 (on OSX via homebrew)](#Globally on OSX via homebrew) - - [安装 - Windows](#Installation - Windows) - - [使用安装程序](#Using the Installer) - - [手动安装](#Manual Installation) - - [使用 Composer](#Using Composer) + - [全局安装 (on OSX via homebrew)](#Globally-on-OSX-via-homebrew) + - [安装 - Windows](#Installation-Windows) + - [使用安装程序](#Using-the-Installer) + - [手动安装](#Manual-Installation) + - [使用 Composer](#Using-Composer) - [自动加载](#Autoloading) --- @@ -40,7 +40,7 @@ c) 你声明你所依赖的东西。 d) Composer 会找出哪个版本的包需要安装，并安装它们（将它们下载到你的项目中）。 - + ## 声明依赖关系 比方说，你正在创建一个项目，你需要一个库来做日志记录。你决定使用 [monolog](https://github.com/Seldaek/monolog)。为了将它添加到你的项目中，你所需要做的就是创建一个 `composer.json` 文件，其中描述了项目的依赖关系。 @@ -53,7 +53,7 @@ d) Composer 会找出哪个版本的包需要安装，并安装它们（将它 我们只要指出我们的项目需要一些 `monolog/monolog` 的包，从 `1.2` 开始的任何版本。 - + ## 系统要求 运行 Composer 需要 PHP 5.3.2+ 以上版本。一些敏感的 PHP 设置和编译标志也是必须的，但对于任何不兼容项安装程序都会抛出警告。 @@ -62,10 +62,10 @@ d) Composer 会找出哪个版本的包需要安装，并安装它们（将它 Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX 平台上运行的同样出色。 - + ## 安装 - *nix - + ### 下载 Composer 的可执行文件 @@ -96,7 +96,7 @@ Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX 现在只需要运行 `composer` 命令就可以使用 Composer 而不需要输入 `php composer.phar`。 - + #### 全局安装 (on OSX via homebrew) Composer 是 homebrew-php 项目的一部分。 @@ -108,17 +108,17 @@ Composer 是 homebrew-php 项目的一部分。 > **注意：** 如果你收到一个错误 PHP53 or higher is missing 请执行下面的命令来安装 php > `brew install php53-intl` - + ## 安装 - Windows - + ### 使用安装程序 这是将 Composer 安装在你机器上的最简单的方法。 下载并且运行 [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe)，它将安装最新版本的 Composer ，并设置好系统的环境变量，因此你可以在任何目录下直接使用 `composer` 命令。 - + ### 手动安装 设置系统的环境变量 `PATH` 并运行安装命令下载 composer.phar 文件： @@ -139,7 +139,7 @@ Composer 是 homebrew-php 项目的一部分。 C:\Users\username> - + ## 使用 Composer 现在我们将使用 Composer 来安装项目的依赖。如果在当前目录下没有一个 `composer.json` 文件，请查看[基本用法](01-basic-usage.md)章节。 @@ -152,7 +152,7 @@ Composer 是 homebrew-php 项目的一部分。 $ composer install -继续 [上面的例子](#声明依赖关系)，这里将下载 monolog 到 `vendor/monolog/monolog` 目录。 +继续 [上面的例子](#Declaring-dependencies)，这里将下载 monolog 到 `vendor/monolog/monolog` 目录。 ## 自动加载 diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 65f0f8a..69db52f 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -1,18 +1,18 @@ - + # 基本用法 --- -- [基本用法](#Basic usage) +- [基本用法](#Basic-usage) - [安装](#Installation) - - [`composer.json`：项目安装](#composer.json Project Setup) - - [关于 `require` Key](#The require Key) - - [包名称](#Package Names) - - [包版本](#Package Versions) - - [下一个重要版本（波浪号运算符）](#Next Significant Release) + - [`composer.json`：项目安装](#composer.json-Project-Setup) + - [关于 `require` Key](#The-require-Key) + - [包名称](#Package-Names) + - [包版本](#Package-Versions) + - [下一个重要版本（波浪号运算符）](#Next-Significant-Release) - [稳定性](#Stability) - - [安装依赖关系](#Installing Dependencies) - - [`composer.lock` - 锁文件](#composer.lock - The Lock File) + - [安装依赖关系](#Installing-Dependencies) + - [`composer.lock` - 锁文件](#composer.lock-The-Lock-File) - [Packagist](#Packagist) - [自动加载](#Autoloading) @@ -39,14 +39,14 @@ > $ curl -sS https://getcomposer.org/installer | php -- --check > $ curl -sS https://getcomposer.org/installer | php -- --help - + ## `composer.json`：项目安装 要开始在你的项目中使用 Composer，你只需要一个 `composer.json` 文件。该文件包含了项目的依赖和其它的一些元数据。 这个 [JSON format](http://json.org/) 是很容易编写的。它允许你定义嵌套结构。 - + ### 关于 `require` Key 第一件事情（并且往往只需要做这一件事），你需要在 `composer.json` 文件中指定 `require` key 的值。你只需要简单的告诉 Composer 你的项目需要依赖哪些包。 @@ -59,14 +59,14 @@ 你可以看到， `require` 需要一个 **包名称** （例如 `monolog/monolog`） 映射到 **包版本** （例如 `1.0.*`） 的对象。 - + ### 包名称 包名称由供应商名称和其项目名称构成。通常容易产生相同的项目名称，而供应商名称的存在则很好的解决了命名冲突的问题。它允许两个不同的人创建同样名为 `json` 的库，而之后它们将被命名为 `igorw/json` 和 `seldaek/json`。 这里我们需要引入 `monolog/monolog`，供应商名称与项目的名称相同，对于一个具有唯一名称的项目，我们推荐这么做。它还允许以后在同一个命名空间添加更多的相关项目。如果你维护着一个库，这将使你可以很容易的把它分离成更小的部分。 - + ### 包版本 在前面的例子中，我们引入的 monolog 版本指定为 `1.0.*`。这表示任何从 `1.0` 开始的开发分支，它将会匹配 `1.0.0`、`1.0.2` 或者 `1.0.20`。 @@ -110,7 +110,7 @@ - + ### 下一个重要版本（波浪号运算符） `~` 最好用例子来解释： `~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应该都没有向后兼容性问题，所以效果很好。你还会看到它的另一种用法，使用 `~` 指定最低版本，但允许版本号的最后一位数字上升。 @@ -120,7 +120,7 @@ 默认情况下只有稳定的发行版才会被考虑在内。如果你也想获得 RC、beta、alpha 或 dev 版本，你可以使用 [稳定标志](04-schema.md#package-links)。你可以对所有的包做 [最小稳定性](04-schema.md#minimum-stability) 设置，而不是每个依赖逐一设置。 - + ## 安装依赖关系 获取定义的依赖到你的本地项目，只需要调用 `composer.phar` 运行 `install` 命令。 @@ -136,7 +136,7 @@ 另一件事是 `install` 命令将创建一个 `composer.lock` 文件到你项目的根目录中。 - + ## `composer.lock` - 锁文件 在安装依赖后，Composer 将把安装时确切的版本号列表写入 `composer.lock` 文件。这将锁定改项目的特定版本。 -- 2.46.2 From 68b67e0034768bc86fad88d0c4cf56a64fb6ebf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 31 Jan 2014 01:09:29 +0800 Subject: [PATCH 090/125] update --- cn-introduction/01-basic-usage.md | 4 +-- cn-introduction/02-libraries.md | 33 ++++++++++---------- cn-introduction/03-cli.md | 50 +++++++++++++++---------------- cn-introduction/04-schema.md | 4 +-- 4 files changed, 46 insertions(+), 45 deletions(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 69db52f..5730e3b 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -118,7 +118,7 @@ ### 稳定性 -默认情况下只有稳定的发行版才会被考虑在内。如果你也想获得 RC、beta、alpha 或 dev 版本，你可以使用 [稳定标志](04-schema.md#package-links)。你可以对所有的包做 [最小稳定性](04-schema.md#minimum-stability) 设置，而不是每个依赖逐一设置。 +默认情况下只有稳定的发行版才会被考虑在内。如果你也想获得 RC、beta、alpha 或 dev 版本，你可以使用 [稳定标志](04-schema.md#Package-links)。你可以对所有的包做 [最小稳定性](04-schema.md#minimum-stability) 设置，而不是每个依赖逐一设置。 ## 安装依赖关系 @@ -158,7 +158,7 @@ $ php composer.phar update monolog/monolog [...] > **注意：** 对于库，并不一定建议提交锁文件 -> 请参考：[库的锁文件](02-libraries.md#lock-file). +> 请参考：[库的锁文件](02-libraries.md#Lock-file). ## Packagist diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index f592a8b..16eb09e 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -6,19 +6,19 @@ --- - [库（资源包）](#Libraries) - - [每一个项目都是一个包](#Every project is a package) - - [平台软件包](#Platform packages) - - [指明版本](#Specifying the version) + - [每一个项目都是一个包](#Every-project-is-a-package) + - [平台软件包](#Platform-packages) + - [指明版本](#Specifying-the-version) - [标签](#Tags) - [分支](#Branches) - [别名](#Aliases) - - [锁文件](#Lock file) - - [发布到 VCS（线上版本控制系统）](#Publishing to a VCS) - - [发布到 packagist](#Publishing to packagist) + - [锁文件](#Lock-file) + - [发布到 VCS（线上版本控制系统）](#Publishing-to-a-VCS) + - [发布到 packagist](#Publishing-to-packagist) --- - + ## 每一个项目都是一个包 只要你有一个 `composer.json` 文件在目录中，那么整个目录就是一个包。当你添加一个 `require` 到项目中，你就是在创建一个依赖于其它库的包。你的项目和库之间唯一的区别是，你的项目是一个没有名字的包。 @@ -38,7 +38,7 @@ > 那么使用你 github 上的用户名通常是不错的选择。 > 虽然包名不区分大小写，但惯例是使用小写字母，并用连字符作为单词的分隔。 - + ## 平台软件包 Composer 将那些已经安装在系统上，但并不是由 Composer 安装的包视为一个虚拟的平台软件包。这包括PHP本身，PHP扩展和一些系统库。 @@ -47,15 +47,16 @@ Composer 将那些已经安装在系统上，但并不是由 Composer 安装的 * `ext-` 可以帮你指定需要的 PHP 扩展（包括核心扩展）。通常 PHP 拓展的版本可以是不一致的，将它们的版本约束为 `*` 是一个不错的主意。一个 PHP 扩展包的例子：包名可以写成 `ext-gd`。 -* `lib-` 允许对 PHP 库的版本进行限制。以下是可供使用的名称：`curl`、`iconv`、`libxml`、`openssl`、`pcre`、`uuid`、`xsl`。 +* `lib-` 允许对 PHP 库的版本进行限制。 +以下是可供使用的名称：`curl`、`iconv`、`libxml`、`openssl`、`pcre`、`uuid`、`xsl`。 你可以使用 `composer show --platform` 命令来获取可用的平台软件包的列表。 - + ## 指明版本 你需要一些方法来指明自己开发的包的版本，当你在 Packagist 上发布自己的包，它能够从 VCS (git, svn, -hg) 的信息推断出包的版本，因此你不必手动指明版本号，并且也不建议这样做。请查看 [标签](#标签) 和 [分支](#分支) 来了解版本号是如何被提取的。 +hg) 的信息推断出包的版本，因此你不必手动指明版本号，并且也不建议这样做。请查看 [标签](#Tags) 和 [分支](#Branches) 来了解版本号是如何被提取的。 如果你想要手动创建并且真的要明确指定它，你只需要添加一个 `version` 字段： @@ -80,7 +81,7 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 v2.0.4-p1 > **注意：** 即使你的标签带有前缀 `v`， -> 由于在需要 `require` 一个[版本的约束](01-basic-usage.md#包版本)时是不允许这种前缀的， +> 由于在需要 `require` 一个[版本的约束](01-basic-usage.md#Package-Versions)时是不允许这种前缀的， > 因此 `v` 将被省略（例如标签 `V1.0.0` 将创建 `1.0.0` 版本）。 @@ -104,14 +105,14 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 详细请查看[“别名”](articles/aliases.md)。 - + ## 锁文件 如果你愿意，可以在你的项目中提交 `composer.lock` 文件。他将帮助你的团队始终针对同一个依赖版本进行测试。任何时候，这个锁文件都只对于你的项目产生影响。 如果你不想提交锁文件，并且你正在使用 Git，那么请将它添加到 `.gitignore` 文件中。 - + ## 发布到 VCS（线上版本控制系统） 一旦你有一个包含 `composer.json` 文件的库存储在线上版本控制系统（例如：Git），你的库就可以被 Composer 所安装。在这个例子中，我们将 `acme/hello-world` 库发布在 GitHub 上的 `github.com/username/hello-world` 中。 @@ -142,13 +143,13 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 } } -更多关于包的来源是如何工作的，以及还有什么其他的类型可供选择，请查看[来源](05-repositories.md)。 +更多关于包的来源是如何工作的，以及还有什么其他的类型可供选择，请查看[资源库](05-repositories.md)。 这就是全部了。你现在可以使用 Composer 的 `install` 命令来安装你的依赖关系了！ **小结：** 任何含有 `composer.json` 的 `GIT`、`SVN`、`HG` 存储库，都可以通过 `require` 字段指定“包来源”和“声明依赖”来添加到你的项目中。 - + ## 发布到 packagist 好的，你现在可以发布你的包了，但你不会希望你的用户每次都这样繁琐的指定包的来源。 diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index f1ea1c5..94c02a1 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -1,4 +1,4 @@ - + # 命令行 你已经学会了如何使用命令行界面做一些事情。本章将向你介绍所有可用的命令。 @@ -7,9 +7,9 @@ --- -- [命令行](#Command-line interface) -- [全局参数](#Global Options) - - [进程退出代码](#Process Exit Codes) +- [命令行](#Command-line-interface) +- [全局参数](#Global-Options) + - [进程退出代码](#Process-Exit-Codes) - [初始化 `init`](#init) - - [参数](#init-Options) - [安装 `install`](#install) - - [参数](#install-Options) - [更新 `update`](#update) - - [参数](#update-Options) @@ -21,7 +21,7 @@ - [有效性检测 `validate`](#validate) - [依赖包状态检测 `status`](#status) - [自我更新 `self-update`](#self-update) - - [参数](#self-update-Options) - - [更改配置 `config`](#config) - - [使用方法](#config-Usage) - - [参数](#config-Options) - - [修改包来源](#Modifying Repositories) + - [更改配置 `config`](#config) - - [使用方法](#config-Usage) - - [参数](#config-Options) - - [修改包来源](#Modifying-Repositories) - [创建项目 `create-project`](#create-project) - - [参数](#create-project-Options) - [打印自动加载索引 `dump-autoload`](#dump-autoload) - - [参数](#dump-autoload-Options) - [查看许可协议 `licenses`](#licenses) @@ -29,24 +29,24 @@ - [诊断 `diagnose`](#diagnose) - [归档 `archive`](#archive) - - [参数](#archive-Options) - [获取帮助信息 `help`](#help) - - [环境变量](#Environment variables) - - [COMPOSER](#COMPOSER) - - [COMPOSER_ROOT_VERSION](#COMPOSER_ROOT_VERSION) - - [COMPOSER_VENDOR_DIR](#COMPOSER_VENDOR_DIR) - - [COMPOSER_BIN_DIR](#COMPOSER_BIN_DIR) - - [http_proxy or HTTP_PROXY](#http_proxy or HTTP_PROXY) - - [no_proxy](#no_proxy) - - [HTTP_PROXY_REQUEST_FULLURI](#HTTP_PROXY_REQUEST_FULLURI) - - [HTTPS_PROXY_REQUEST_FULLURI](#HTTPS_PROXY_REQUEST_FULLURI) - - [COMPOSER_HOME](#COMPOSER_HOME) - - [COMPOSER_HOME/config.json](#COMPOSER_HOME-config.json) - - [COMPOSER_CACHE_DIR](#COMPOSER_CACHE_DIR) - - [COMPOSER_PROCESS_TIMEOUT](#COMPOSER_PROCESS_TIMEOUT) - - [COMPOSER_DISCARD_CHANGES](#COMPOSER_DISCARD_CHANGES) - - [COMPOSER_NO_INTERACTION](#COMPOSER_NO_INTERACTION) + - [环境变量](#Environment-variables) + - [COMPOSER](#COMPOSER) + - [COMPOSER_ROOT_VERSION](#COMPOSER_ROOT_VERSION) + - [COMPOSER_VENDOR_DIR](#COMPOSER_VENDOR_DIR) + - [COMPOSER_BIN_DIR](#COMPOSER_BIN_DIR) + - [http_proxy or HTTP_PROXY](#http_proxy-or-HTTP_PROXY) + - [no_proxy](#no_proxy) + - [HTTP_PROXY_REQUEST_FULLURI](#HTTP_PROXY_REQUEST_FULLURI) + - [HTTPS_PROXY_REQUEST_FULLURI](#HTTPS_PROXY_REQUEST_FULLURI) + - [COMPOSER_HOME](#COMPOSER_HOME) + - [COMPOSER_HOME/config.json](#COMPOSER_HOME-config.json) + - [COMPOSER_CACHE_DIR](#COMPOSER_CACHE_DIR) + - [COMPOSER_PROCESS_TIMEOUT](#COMPOSER_PROCESS_TIMEOUT) + - [COMPOSER_DISCARD_CHANGES](#COMPOSER_DISCARD_CHANGES) + - [COMPOSER_NO_INTERACTION](#COMPOSER_NO_INTERACTION) --- - + ## 全局参数 下列参数可与每一个命令结合使用： @@ -64,7 +64,7 @@ * **--no-ansi:** 关闭 ANSI 输出。 * **--version (-V):** 显示当前应用程序的版本信息。 - + ## 进程退出代码 * **0:** 正常 @@ -319,7 +319,7 @@ * **--list (-l):** 显示当前配置选项的列表。当存在 `--global` 参数时，将会显示全局配置选项的列表。 * **--file="..." (-f):** 在一个指定的文件上操作，而不是 composer.json。注意：不能与 `--global` 参数一起使用。 - + ### 修改包来源 除了修改配置选项， `config` 命令还支持通过以下方法修改来源信息： @@ -410,7 +410,7 @@ $ php composer.phar help install - + ## 环境变量 你可以设置一些环境变量来覆盖默认的配置。建议尽可能的在 `composer.json` 的 `config` 字段中设置这些值，而不是通过命令行设置环境变量。值得注意的是环境变量中的值，将始终优先于 `composer.json` 中所指定的值。 @@ -439,7 +439,7 @@ 通过设置这个环境变量，你可以指定 `bin`（[Vendor Binaries](articles/vendor-binaries.md)）目录到 `vendor/bin` 以外的其它目录。 - + ### http_proxy or HTTP_PROXY 如果你是通过 HTTP 代理来使用 Composer，你可以使用 `http_proxy` 或 `HTTP_PROXY` 环境变量。只要简单的将它设置为代理服务器的 URL。许多操作系统已经为你的服务设置了此变量。 diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 78ce4f7..182aeca 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -19,7 +19,7 @@ - [许可协议 `license`](#license) - [作者 `authors`](#authors) - [支持 `support`](#support) - - [Package links](#Package links) + - [Package links](#Package-links) - [require](#require) - [require-dev (root-only)](#require-dev) - [conflict](#conflict) @@ -263,7 +263,7 @@ composer 原生支持以下4种类型： 可选。 - + ### Package links 下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#包版本) 的映射对象。 -- 2.46.2 From f4ca12652ef6e95aa3d1549136dae1d080585da6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 31 Jan 2014 01:28:36 +0800 Subject: [PATCH 091/125] update --- cn-introduction/03-cli.md | 4 ++-- cn-introduction/04-schema.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 94c02a1..35df29d 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -173,7 +173,7 @@ ## 全局执行 `global` -`global` 命令允许你在 [COMPOSER_HOME](#composer-home) 目录下执行其它命令，像 `install`、`require` 或 `update`。 +`global` 命令允许你在 [COMPOSER_HOME](#COMPOSER_HOME) 目录下执行其它命令，像 `install`、`require` 或 `update`。 并且如果你将 `$COMPOSER_HOME/vendor/bin` 加入到了 `$PATH` 环境变量中，你就可以用它在命令行中安装全局应用，下面是一个例子： @@ -478,7 +478,7 @@ 你可以在 `COMPOSER_HOME` 目录中放置一个 `config.json` 文件。在你执行 `install` 和 `update` 命令时，Composer 会将它与你项目中的 `composer.json` 文件进行合并。 -该文件允许你为用户的项目设置 [配置信息](04-schema.md#config) 和 [资源地址](05-repositories.md)。 +该文件允许你为用户的项目设置 [配置信息](04-schema.md#config) 和 [资源库](05-repositories.md)。 若 _全局_ 和 _项目_ 存在相同配置项，那么项目中的 `composer.json` 文件拥有更高的优先级。 diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 182aeca..a45463a 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -6,10 +6,10 @@ --- - [composer.json](#composer.json) - - [JSON schema](#JSON schema) - - [Root 包](#Root Package) + - [JSON schema](#JSON-schema) + - [Root 包](#Root-Package) - [属性](#Properties) - - [包名 `name`](#package name) + - [包名 `name`](#package-name) - [描述 `description`](#description) - [版本 `version`](#version) - [安装类型 `type`](#type) @@ -43,12 +43,12 @@ --- - + ## JSON schema 我们有一个 [JSON schema](http://json-schema.org) 格式化文档，它也可以被用来验证你的 `composer.json` 文件。事实上，它已经被 `validate` 命令所使用。 你可以在这里找到它： [`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). - + ## Root 包 “root 包”是指由 `composer.json` 定义的在你项目根目录的包。这是 `composer.json` 定义你项目所需的主要条件。（简单的说，你自己的项目就是一个 root 包） @@ -65,7 +65,7 @@ ## 属性 - + ### 包名 `name` 包的名称，它包括供应商名称和项目名称，使用 `/` 分隔。 @@ -266,7 +266,7 @@ composer 原生支持以下4种类型： ### Package links -下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#包版本) 的映射对象。 +下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#Package-Versions) 的映射对象。 例： @@ -485,7 +485,7 @@ Symfony 就是一个例子。它有一些独立的包作为组件。Yaml 组件 这定义了通过稳定性过滤包的默认行为。默认为 `stable`（稳定）。因此如果你依赖于一个 `dev`（开发）包，你应该明确的进行定义。 -对每个包的所有版本都会进行稳定性检查，而低于 `minimum-stability` 所设定的最低稳定性的版本，将在解决依赖关系时被忽略。对于个别包的特殊稳定性要求，可以在 `require` 或 `require-dev` 中设定（请参考 [package links](#package-links)）。 +对每个包的所有版本都会进行稳定性检查，而低于 `minimum-stability` 所设定的最低稳定性的版本，将在解决依赖关系时被忽略。对于个别包的特殊稳定性要求，可以在 `require` 或 `require-dev` 中设定（请参考 [Package links](#Package-links)）。 可用的稳定性标识（按字母排序）：`dev`、`alpha`、`beta`、`RC`、`stable`。 -- 2.46.2 From 9651df19fea295b5a1f511c711c3a4a6d6170c61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 31 Jan 2014 01:49:33 +0800 Subject: [PATCH 092/125] =?UTF-8?q?=E6=95=B4=E5=90=88=E8=87=B3=20laravel-l?= =?UTF-8?q?ocal-website?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/04-schema.md | 2 +- cn-introduction/05-repositories.md | 34 ++++++++++++++--------------- cn-introduction/articles/scripts.md | 2 +- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index a45463a..2082a19 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -1,5 +1,5 @@ -# composer.json +# composer.json 架构 本章将解释所有在 `composer.json` 中可用的字段。 diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index fdb8c3e..7bd7879 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -15,20 +15,20 @@ - [notify-batch](#notify-batch) - [includes](#includes) - [provider-includes and providers-url](#provider-includes) - - [stream options](#stream options) + - [stream options](#stream-options) - [VCS](#VCS) - - [从 VCS 资源库加载一个包](#from a VCS) - - [使用私有资源库](#Using private) - - [Git 的备选方案](#Git alternatives) - - [Subversion 选项](#Subversion Options) + - [从 VCS 资源库加载一个包](#from-a-VCS) + - [使用私有资源库](#Using-private) + - [Git 的备选方案](#Git-alternatives) + - [Subversion 选项](#Subversion-Options) - [PEAR](#PEAR) - - [自定义供应商别名](#Custom vendor alias) + - [自定义供应商别名](#Custom-vendor-alias) - [Package](#Package) - - [Hosting your own](#Hosting your own) + - [Hosting your own](#Hosting-your-own) - [Packagist](#Packagist) - [Satis](#Satis) - [Artifact](#Artifact) - - [禁用 Packagist](#Disabling Packagist) + - [禁用 Packagist](#Disabling-Packagist) --- @@ -104,7 +104,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 } } -它还可以包含任何在 [架构](04-schema.md) 中介绍的字段。 +它还可以包含任何在 [composer.json 架构](04-schema.md) 中介绍的字段。 #### notify-batch @@ -192,7 +192,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 这些字段是可选的。你也许并不需要它们来自定义存储库。 - + #### stream options `packages.json` 文件是用一个 PHP 流加载的。你可以使用 `options` 参数来设定额外的流信息。你可以设置任何有效的PHP 流上下文选项。更多相关信息请查看 [Context options and parameters](http://php.net/manual/en/context.php)。 @@ -202,7 +202,7 @@ Composer 是一个依赖管理工具。它在本地安装一些资源包。一 VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管理系统。Composer 有一个资源类型可以从这些系统安装软件包。 - + #### 从 VCS 资源库加载一个包 这里有几个用例。最常见的是维护自己 fork 的第三方库。如果你在项目中使用某些库，并且你决定改变这些库内的某些东西，你会希望你项目中使用的是你自己的修正版本。如果这个库是在 GitHub 上（这种情况经常出现），你可以简单的 fork 它并 push 你的变更到这个 fork 里。在这之后你更新项目的 `composer.json` 文件，添加你的 fork 作为一个资源库，变更版本约束来指向你的自定义分支。关于版本约束的命名约定请查看 [库（资源包）](02-libraries.md)。 @@ -227,7 +227,7 @@ VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管 如果其它包依赖你 fork 的这个分支，可能要对它做版本号的行内别名设置，才能够准确的识别版本约束。更多相关信息请查看 [别名](articles/aliases.md)。 - + #### 使用私有资源库 完全相同的解决方案，也可以让你使用你 GitHub 和 BitBucket 上的私人代码库进行工作： @@ -246,7 +246,7 @@ VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管 唯一的要求是为一个 git 客户端安装 SSH 秘钥。 - + #### Git 的备选方案 Git 并不是 VCS 资源库唯一支持的版本管理系统。 @@ -264,7 +264,7 @@ Git 并不是 VCS 资源库唯一支持的版本管理系统。 VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需要明确的指定一个 `git`、`svn` 或 `hg` 作为资源库类型，而不是 `vcs`。 - + #### Subversion 选项 由于 Subversion 没有原生的分支和标签的概念，Composer 假设在默认情况下该代码位于 `$url/trunk`、`$url/branches` 和 `$url/tags` 内。如果你的存储库使用了不同的布局，你可以更改这些值。例如，如果你使用大写的名称，你可以像这样配置资源库： @@ -309,7 +309,7 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 > **注意：** `pear` 类型的资源库对每个 requires 都要做完整的请求，因此可能大大降低安装速度。 - + #### 自定义供应商别名 通过自定义供应商名称，对 PEAR 渠道包进行别名是允许的。 @@ -396,7 +396,7 @@ VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需 > - Composer 将不会更新资源包，除非你修改了 `version` 字段。 > - Composer 将不会更新 commit references，因此如果你使用 `master` reference，将不得不删除该程序包以强制更新，并且将不得不面对一个不稳定的 lock 文件。 - + ## Hosting your own 尽管大部分的时间，你大概都会把资源包放在 packagist.org 上，但这里还将告诉你一些用例，以便你可以自行托管资源库。 @@ -454,7 +454,7 @@ Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻 如果有两个不同版本的资源包，它们都会被导入。当有一个新版本的存档被添加到 artifact 文件夹，并且你运行了 `update` 命令，该版本就会被导入，并且 Composer 将更新到最新版本。 - + ## 禁用 Packagist 你可以在 `composer.json` 中禁用默认的 Packagist 资源库。 diff --git a/cn-introduction/articles/scripts.md b/cn-introduction/articles/scripts.md index 06e7c78..ef923ed 100644 --- a/cn-introduction/articles/scripts.md +++ b/cn-introduction/articles/scripts.md @@ -15,7 +15,7 @@ the Composer execution process. executed. If a dependency of the root package specifies its own scripts, Composer does not execute those additional scripts.** - + ## Event names Composer fires the following named events during its execution process: -- 2.46.2 From 9d100a983378dafcc4239dcdd8bafbfd0bd8e8f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sun, 2 Feb 2014 00:48:25 +0800 Subject: [PATCH 093/125] Rename 00-intro.md to 00-intro.html --- cn-introduction/{00-intro.md => 00-intro.html} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename cn-introduction/{00-intro.md => 00-intro.html} (100%) diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.html similarity index 100% rename from cn-introduction/00-intro.md rename to cn-introduction/00-intro.html -- 2.46.2 From 903783d7c509d4bd1bc4e67e32b1509982164d90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Sun, 2 Feb 2014 00:53:50 +0800 Subject: [PATCH 094/125] update --- cn-introduction/{00-intro.html => 00-intro.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename cn-introduction/{00-intro.html => 00-intro.md} (100%) diff --git a/cn-introduction/00-intro.html b/cn-introduction/00-intro.md similarity index 100% rename from cn-introduction/00-intro.html rename to cn-introduction/00-intro.md -- 2.46.2 From 131c7ef0e1e0262f6545e98f49204d1562a0387b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=90=E6=AD=A6?= Date: Fri, 21 Feb 2014 14:05:10 +0800 Subject: [PATCH 095/125] =?UTF-8?q?=E8=84=9A=E6=9C=AC=20=E7=AB=A0=E8=8A=82?= =?UTF-8?q?=E7=BF=BB=E8=AF=91=E7=BB=93=E6=9D=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 +- cn-introduction/articles/scripts.md | 111 +++++++++++----------------- 2 files changed, 47 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 332127e..7c547e7 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,8 @@ Composer 中文文档 Host your own composer repository - [插件](/cn-introduction/articles/plugins.md) 修改和扩展 Composer 的功能。 -- [Scripts](/cn-introduction/articles/scripts.md) -Script are callbacks that are called before/after installing packages +- [脚本](/cn-introduction/articles/scripts.md) +脚本是指一些 Composer 事件的回调，它们在安装资源包的过程中被触发执行。 - [Troubleshooting](/cn-introduction/articles/troubleshooting.md) Solving problems - [Vendor Binaries](/cn-introduction/articles/vendor-binaries.md) diff --git a/cn-introduction/articles/scripts.md b/cn-introduction/articles/scripts.md index ef923ed..257f3a7 100644 --- a/cn-introduction/articles/scripts.md +++ b/cn-introduction/articles/scripts.md @@ -2,68 +2,51 @@ tagline: Script are callbacks that are called before/after installing packages --> -# Scripts +# 脚本 -## What is a script? +## 什么是脚本？ -A script, in Composer's terms, can either be a PHP callback (defined as a -static method) or any command-line executable command. Scripts are useful -for executing a package's custom code or package-specific commands during -the Composer execution process. +一个脚本，在 Composer 中，可以是一个 PHP 回调（定义为静态方法）或任何命令行可执行的命令。脚本对于在 Composer 运行过程中，执行一个资源包的自定义代码或包专用命令是非常有用的。 -**NOTE: Only scripts defined in the root package's `composer.json` are -executed. If a dependency of the root package specifies its own scripts, -Composer does not execute those additional scripts.** +> **注意：**只有在根包的 `composer.json` 中定义的脚本才会被执行。即便根包的外部依赖定义了其自身的脚本，Composer 也不会去执行这些额外的脚本。 -## Event names +## 事件名称 -Composer fires the following named events during its execution process: +Composer 在运行过程中将会触发以下事件： -- **pre-install-cmd**: occurs before the `install` command is executed. -- **post-install-cmd**: occurs after the `install` command is executed. -- **pre-update-cmd**: occurs before the `update` command is executed. -- **post-update-cmd**: occurs after the `update` command is executed. -- **pre-status-cmd**: occurs before the `status` command is executed. -- **post-status-cmd**: occurs after the `status` command is executed. -- **pre-package-install**: occurs before a package is installed. -- **post-package-install**: occurs after a package is installed. -- **pre-package-update**: occurs before a package is updated. -- **post-package-update**: occurs after a package is updated. -- **pre-package-uninstall**: occurs before a package has been uninstalled. -- **post-package-uninstall**: occurs after a package has been uninstalled. -- **pre-autoload-dump**: occurs before the autoloader is dumped, either - during `install`/`update`, or via the `dump-autoload` command. -- **post-autoload-dump**: occurs after the autoloader is dumped, either - during `install`/`update`, or via the `dump-autoload` command. -- **post-root-package-install**: occurs after the root package has been - installed, during the `create-project` command. -- **post-create-project-cmd**: occurs after the `create-project` command is - executed. +|事件名称|详细说明 +|---|--- +| **pre-install-cmd** | 在 `install` 命令执行前触发。 +| **post-install-cmd** | 在 `install` 命令执行后触发。 +| **pre-update-cmd** | 在 `update` 命令执行前触发。 +| **post-update-cmd** | 在 `update` 命令执行后触发。 +| **pre-status-cmd** | 在 `status` 命令执行前触发。 +| **post-status-cmd** | 在 `status` 命令执行后触发。 +| **pre-package-install** | 在资源包安装前触发。 +| **post-package-install** | 在资源包安装后触发。 +| **pre-package-update** | 在资源包更新前触发。 +| **post-package-update** | 在资源包更新后触发。 +| **pre-package-uninstall** | 在资源包被卸载前触发。 +| **post-package-uninstall** | 在资源包被卸载后触发。 +| **pre-autoload-dump** | 在自动加载器被转储前触发，无论是 `install`/`update` 还是 `dump-autoload` 命令都会触发。 +| **post-autoload-dump** | 在自动加载器被转储后触发，无论是 `install`/`update` 还是 `dump-autoload` 命令都会触发。 +| **post-root-package-install** | 在 `create-project` 命令期间，根包安装完成后触发。 +| **post-create-project-cmd** | 在 `create-project` 命令执行后触发。 -**NOTE: Composer makes no assumptions about the state of your dependencies -prior to `install` or `update`. Therefore, you should not specify scripts that -require Composer-managed dependencies in the `pre-update-cmd` or -`pre-install-cmd` event hooks. If you need to execute scripts prior to -`install` or `update` please make sure they are self-contained within your -root package.** +> **注意：**Composer 不会去执行任何依赖包中定义的 `install` 或 `update` 相关脚本。因此你不应该在依赖包中申明 `pre-update-cmd` 或 `pre-install-cmd`。如果你需要在执行 `install` 或 `update` 命令前使用脚本，请确保它们已被定义在根包中。 -## Defining scripts +## 定义脚本 -The root JSON object in `composer.json` should have a property called -`"scripts"`, which contains pairs of named events and each event's -corresponding scripts. An event's scripts can be defined as either as a string -(only for a single script) or an array (for single or multiple scripts.) +在 `composer.json` 的根 JSON 对象中应该有一个名为 `"scripts"` 的属性，它包含有一系列的事件名称，以及对应的事件脚本。一个事件的脚本可以被定义为一个字符串（仅适用于单个脚本）或数组（单个或多个脚本）。 -For any given event: +对于任何给定的事件： -- Scripts execute in the order defined when their corresponding event is fired. -- An array of scripts wired to a single event can contain both PHP callbacks -and command-line executables commands. -- PHP classes containing defined callbacks must be autoloadable via Composer's -autoload functionality. +- 脚本将按照事件和定义的顺序触发。 +- 一个脚本数组可以包含 PHP 回调和命令行可执行命令。 +- 由 PHP 类文件包含的回调，其存放的位置必须确保 Composer 能够正确的载入。 -Script definition example: +脚本定义实例： { "scripts": { @@ -78,15 +61,14 @@ Script definition example: } } -Using the previous definition example, here's the class `MyVendor\MyClass` -that might be used to execute the PHP callbacks: +使用前面定义的例子，这里的 `MyVendor\MyClass` 类，就可以被使用来执行 PHP 的回调： 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: +当一个事件被触发，Composer 的内部事件处理程序将接收一个 `Composer\Script\Event` 对象，这是传递给您的 PHP 回调的第一个参数。这个 `Event` 对象拥有一些 getter 方法来帮助你取得当前事件的上下文： -- `getComposer()`: returns the current instance of `Composer\Composer` -- `getName()`: returns the name of the event being fired as a string -- `getIO()`: returns the current input/output stream which implements -`Composer\IO\IOInterface` for writing to the console +- `getComposer()`: 返回当前的 `Composer\Composer` 对象实例。 +- `getName()`: 返回事件名称的字符串。 +- `getIO()`: 返回当前的 输入\输出 流，它实现了 `Composer\IO\IOInterface` 接口，以便在控制台中使用。 -## Running scripts manually +## 手动运行脚本 -If you would like to run the scripts for an event manually, the syntax is: +如果你想手动运行事件脚本，可以使用下面的语法结构： $ 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. +例如 `composer run-script post-install-cmd` 将会运行所有 **post-install-cmd** 事件下定义的脚本。 -- 2.46.2 From 5c906852c4e00aca3404217e06e98941fe52eee0 Mon Sep 17 00:00:00 2001 From: wangsai Date: Sat, 24 May 2014 01:10:46 +0800 Subject: [PATCH 096/125] =?UTF-8?q?=E5=90=8C=E6=AD=A5=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E5=AE=98=E6=96=B9=E8=8B=B1=E6=96=87=E6=96=87=E6=A1=A3=EF=BC=9B?= =?UTF-8?q?=E5=B9=B6=E5=AF=B9=E4=B8=AD=E6=96=87=E6=96=87=E6=A1=A3=E5=81=9A?= =?UTF-8?q?=E7=9B=B8=E5=BA=94=E7=9A=84=E5=90=8C=E6=AD=A5=EF=BC=9B=E5=B0=91?= =?UTF-8?q?=E9=87=8F=E5=A2=9E=E5=8A=A0=E4=BA=86=E9=83=A8=E5=88=86=E7=BF=BB?= =?UTF-8?q?=E8=AF=91=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/00-intro.md | 75 ++- cn-introduction/01-basic-usage.md | 75 ++- cn-introduction/02-libraries.md | 77 +-- cn-introduction/03-cli.md | 163 ++++-- cn-introduction/04-schema.md | 502 +++++++++++------- cn-introduction/05-repositories.md | 346 ++++++------ cn-introduction/articles/aliases.md | 36 +- cn-introduction/articles/custom-installers.md | 128 +++-- .../handling-private-packages-with-satis.md | 132 ++--- cn-introduction/articles/plugins.md | 112 ++-- cn-introduction/articles/scripts.md | 78 +-- cn-introduction/articles/troubleshooting.md | 67 ++- cn-introduction/articles/vendor-binaries.md | 41 +- ...ckage-to-a-custom-path-for-my-framework.md | 26 +- ...-unbound-version-constraints-a-bad-idea.md | 21 + en-back/00-intro.md | 77 ++- en-back/01-basic-usage.md | 81 ++- en-back/02-libraries.md | 83 +-- en-back/03-cli.md | 166 ++++-- en-back/04-schema.md | 476 +++++++++++------ en-back/05-repositories.md | 343 ++++++------ en-back/articles/aliases.md | 36 +- en-back/articles/custom-installers.md | 122 +++-- .../handling-private-packages-with-satis.md | 132 ++--- en-back/articles/plugins.md | 106 ++-- en-back/articles/scripts.md | 72 +-- en-back/articles/troubleshooting.md | 67 ++- en-back/articles/vendor-binaries.md | 41 +- ...ckage-to-a-custom-path-for-my-framework.md | 26 +- ...-unbound-version-constraints-a-bad-idea.md | 21 + 30 files changed, 2278 insertions(+), 1450 deletions(-) create mode 100644 cn-introduction/faqs/why-are-unbound-version-constraints-a-bad-idea.md create mode 100644 en-back/faqs/why-are-unbound-version-constraints-a-bad-idea.md diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md index ede543e..d145a9c 100644 --- a/cn-introduction/00-intro.md +++ b/cn-introduction/00-intro.md @@ -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 +``` #### 全局安装 @@ -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 +``` ## 安装 - 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 +``` ## 使用 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 的知识，请查看“基本用法”章节。 diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 5730e3b..2a9c054 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -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 +> ``` ## `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.` 部分是固定的。 + ### 稳定性 @@ -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。 ← [简介](00-intro.md) | [库（资源包）](02-libraries.md) → diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index 16eb09e..ec9f1ca 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -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-` 可以帮你指定需要的 PHP 扩展（包括核心扩展）。通常 PHP 拓展的版本可以是不一致的，将它们的版本约束为 `*` 是一个不错的主意。一个 PHP 扩展包的例子：包名可以写成 `ext-gd`。 * `lib-` 允许对 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)。 diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 35df29d..72f8da4 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -78,7 +78,9 @@ 当您运行该命令，它会以交互方式要求您填写一些信息，同时聪明的使用一些默认值。 - $ php composer.phar init +```sh +php composer.phar init +``` ### 初始化-参数 @@ -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 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。 ## 更新 `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/* +``` ### 更新-参数 @@ -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 +``` ### 申明依赖-参数 @@ -169,6 +183,7 @@ * **--dev:** 安装 `require-dev` 字段中列出的包。 * **--no-update:** 禁用依赖关系的自动更新。 * **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。 +* **--update-with-dependencies** 一并更新新装包的依赖。 ## 全局执行 `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 +``` ## 搜索 `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 +``` ### 展示-参数 @@ -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 +``` ### 依赖性检测-参数 @@ -257,36 +286,53 @@ 在提交 `composer.json` 文件，和创建 tag 前，你应该始终运行 `validate` 命令。它将检测你的 `composer.json` 文件是否是有效的 - $ php composer.phar validate +```sh +php composer.phar validate +``` + +### 有效性检测参数 + +* **--no-check-all:** Composer 是否进行完整的校验。 ## 依赖包状态检测 `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 +``` ## 自我更新 `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 +``` ### 自我更新-参数 @@ -299,7 +345,9 @@ `config` 命令允许你编辑 Composer 的一些基本设置，无论是本地的 `composer.json` 或者全局的 `config.json` 文件。 - $ php composer.phar config --list +```sh +php composer.phar config --list +``` ### 更改配置-使用方法 @@ -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 +``` ## 创建项目 `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 规范带来的便利。 ### 打印自动加载索引-参数 -* **--optimize (-o):** 转换 PSR-0 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。 +* **--optimize (-o):** 转换 PSR-0/4 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。 +* **--no-dev:** 禁用 autoload-dev 规则。 ## 查看许可协议 `licenses` @@ -388,14 +441,18 @@ 如果你觉得发现了一个 bug 或是程序行为变得怪异，你可能需要运行 `diagnose` 命令，来帮助你检测一些常见的问题。 - $ php composer.phar diagnose +```sh +php composer.phar diagnose +``` ## 归档 `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 +``` ### 归档-参数 @@ -408,7 +465,9 @@ 使用 `help` 可以获取指定命令的帮助信息。 - $ php composer.phar help install +```sh +php composer.phar help install +``` ## 环境变量 @@ -422,7 +481,9 @@ 例如： - $ COMPOSER=composer-other.json php composer.phar install +```sh +COMPOSER=composer-other.json php composer.phar install +``` ### COMPOSER_ROOT_VERSION diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 2082a19..6c46a0e 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -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），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 `#` 的标识。 -例： +实例： - { - "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" } +} +``` ### 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/" } + } +} +``` #### 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/" } } +} +``` #### 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"] } +} +``` #### Files 如果你想要明确的指定，在每次请求时都要载入某些文件，那么你可以使用 'files' autoloading。通常作为函数库的载入方式（而非类库）。 -例： +实例： - { - "autoload": { - "files": ["src/MyLibrary/functions.php"] - } +```json +{ + "autoload": { + "files": ["src/MyLibrary/functions.php"] } +} +``` + +### autoload-dev (root-only) + +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 @@ -452,17 +562,23 @@ PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别 一个追加到 PHP `include_path` 中的列表。 -例： +实例： - { - "include-path": ["lib/"] - } +```json +{ + "include-path": ["lib/"] +} +``` 可选。 ### 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\\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" } +} +``` ### scripts (root-only) @@ -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`。 diff --git a/cn-introduction/05-repositories.md b/cn-introduction/05-repositories.md index 7bd7879..9c2fe61 100644 --- a/cn-introduction/05-repositories.md +++ b/cn-introduction/05-repositories.md @@ -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. + #### 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": "*" } +} +``` ### 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 + } + ] +} +``` ← [架构](04-schema.md) | [社区](06-community.md) → diff --git a/cn-introduction/articles/aliases.md b/cn-introduction/articles/aliases.md index 71f90b5..493f643 100644 --- a/cn-introduction/articles/aliases.md +++ b/cn-introduction/articles/aliases.md @@ -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`。 diff --git a/cn-introduction/articles/custom-installers.md b/cn-introduction/articles/custom-installers.md index d5f04b1..cb532d2 100644 --- a/cn-introduction/articles/custom-installers.md +++ b/cn-introduction/articles/custom-installers.md @@ -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 +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 +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/` 目录中。_ diff --git a/cn-introduction/articles/handling-private-packages-with-satis.md b/cn-introduction/articles/handling-private-packages-with-satis.md index 0219f81..69da381 100644 --- a/cn-introduction/articles/handling-private-packages-with-satis.md +++ b/cn-introduction/articles/handling-private-packages-with-satis.md @@ -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 `. 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 } diff --git a/cn-introduction/articles/plugins.md b/cn-introduction/articles/plugins.md index 240a838..f5fbb3f 100644 --- a/cn-introduction/articles/plugins.md +++ b/cn-introduction/articles/plugins.md @@ -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 +getInstallationManager()->addInstaller($installer); - } + $installer = new TemplateInstaller($io, $composer); + $composer->getInstallationManager()->addInstaller($installer); } +} +``` ## 事件处理程序 @@ -65,48 +71,52 @@ > 一个插件也可以订阅 [脚本事件][7]。 -例： +实例： - namespace Naderman\Composer\AWS; +```php +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); } } +} +``` ## 使用插件 diff --git a/cn-introduction/articles/scripts.md b/cn-introduction/articles/scripts.md index 257f3a7..0c51b26 100644 --- a/cn-introduction/articles/scripts.md +++ b/cn-introduction/articles/scripts.md @@ -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 的回调： - 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** 事件下定义的脚本。 diff --git a/cn-introduction/articles/troubleshooting.md b/cn-introduction/articles/troubleshooting.md index 3483b1c..838b761 100644 --- a/cn-introduction/articles/troubleshooting.md +++ b/cn-introduction/articles/troubleshooting.md @@ -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 ` + +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 +``` diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index b258dcc..75087b5 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -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 diff --git a/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md b/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md index 927ee4a..699dee1 100644 --- a/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md +++ b/cn-introduction/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md @@ -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` 变量，而不是默认目录。 diff --git a/cn-introduction/faqs/why-are-unbound-version-constraints-a-bad-idea.md b/cn-introduction/faqs/why-are-unbound-version-constraints-a-bad-idea.md new file mode 100644 index 0000000..1834039 --- /dev/null +++ b/cn-introduction/faqs/why-are-unbound-version-constraints-a-bad-idea.md @@ -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. diff --git a/en-back/00-intro.md b/en-back/00-intro.md index 7b62fee..3435462 100644 --- a/en-back/00-intro.md +++ b/en-back/00-intro.md @@ -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. diff --git a/en-back/01-basic-usage.md b/en-back/01-basic-usage.md index c353b8b..270a6d5 100644 --- a/en-back/01-basic-usage.md +++ b/en-back/01-basic-usage.md @@ -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. ← [Intro](00-intro.md) | [Libraries](02-libraries.md) → diff --git a/en-back/02-libraries.md b/en-back/02-libraries.md index 2742806..81ec3ed 100644 --- a/en-back/02-libraries.md +++ b/en-back/02-libraries.md @@ -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-` 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-` 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). diff --git a/en-back/03-cli.md b/en-back/03-cli.md index 84539b4..517c964 100644 --- a/en-back/03-cli.md +++ b/en-back/03-cli.md @@ -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 diff --git a/en-back/04-schema.md b/en-back/04-schema.md index 56e7871..0ce4d4f 100644 --- a/en-back/04-schema.md +++ b/en-back/04-schema.md @@ -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 `#`. 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 (root-only) + +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 (root-only) @@ -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`. diff --git a/en-back/05-repositories.md b/en-back/05-repositories.md index ae947ea..049a051 100644 --- a/en-back/05-repositories.md +++ b/en-back/05-repositories.md @@ -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 + } + ] +} +``` ← [Schema](04-schema.md) | [Community](06-community.md) → diff --git a/en-back/articles/aliases.md b/en-back/articles/aliases.md index 26a9c46..2b43632 100644 --- a/en-back/articles/aliases.md +++ b/en-back/articles/aliases.md @@ -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`. diff --git a/en-back/articles/custom-installers.md b/en-back/articles/custom-installers.md index feeebe5..98a9a22 100644 --- a/en-back/articles/custom-installers.md +++ b/en-back/articles/custom-installers.md @@ -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 +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 +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 diff --git a/en-back/articles/handling-private-packages-with-satis.md b/en-back/articles/handling-private-packages-with-satis.md index 0219f81..69da381 100644 --- a/en-back/articles/handling-private-packages-with-satis.md +++ b/en-back/articles/handling-private-packages-with-satis.md @@ -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 `. 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 } diff --git a/en-back/articles/plugins.md b/en-back/articles/plugins.md index 75706f7..65884fd 100644 --- a/en-back/articles/plugins.md +++ b/en-back/articles/plugins.md @@ -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 +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 +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 diff --git a/en-back/articles/scripts.md b/en-back/articles/scripts.md index 06e7c78..ccd8caf 100644 --- a/en-back/articles/scripts.md +++ b/en-back/articles/scripts.md @@ -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: - 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. diff --git a/en-back/articles/troubleshooting.md b/en-back/articles/troubleshooting.md index 3483b1c..838b761 100644 --- a/en-back/articles/troubleshooting.md +++ b/en-back/articles/troubleshooting.md @@ -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 ` + +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 +``` diff --git a/en-back/articles/vendor-binaries.md b/en-back/articles/vendor-binaries.md index b258dcc..75087b5 100644 --- a/en-back/articles/vendor-binaries.md +++ b/en-back/articles/vendor-binaries.md @@ -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 diff --git a/en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md b/en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md index b5956ca..bd38d1e 100644 --- a/en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md +++ b/en-back/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md @@ -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. diff --git a/en-back/faqs/why-are-unbound-version-constraints-a-bad-idea.md b/en-back/faqs/why-are-unbound-version-constraints-a-bad-idea.md new file mode 100644 index 0000000..1834039 --- /dev/null +++ b/en-back/faqs/why-are-unbound-version-constraints-a-bad-idea.md @@ -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. -- 2.46.2 From 59ac3a2f9c945a1e8804c0feac80123096066031 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E6=96=B9=E5=AD=A4=E6=80=9D=E5=AD=90=EF=BC=88Pari?= =?UTF-8?q?s=C2=B7QianSen=EF=BC=89?= Date: Mon, 26 May 2014 22:59:16 +0800 Subject: [PATCH 097/125] Fix 5-say/composer-doc-cn #2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 您看一下，这样翻译可以么？ --- cn-introduction/04-schema.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 6c46a0e..2b593cf 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -745,9 +745,9 @@ $extra = $event->getComposer()->getPackage()->getExtra(); ### bin -A set of files that should be treated as binaries and symlinked into the `bin-dir` (from config). +一组可视为二进制执行文件的文件集合，他们应该（在配置文件中）被连接到 `bin-dir` 文件夹。 -See [Vendor Binaries](articles/vendor-binaries.md) for more details. +详情请见 [Vendor Binaries](https://github.com/5-say/composer-doc-cn/issues/articles/vendor-binaries.md) 可选。 -- 2.46.2 From 0afe595f11f5f7fe905354a6b21a3d6cb9da435e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E6=96=B9=E5=AD=A4=E6=80=9D=E5=AD=90=EF=BC=88Pari?= =?UTF-8?q?s=C2=B7QianSen=EF=BC=89?= Date: Tue, 27 May 2014 15:47:24 +0800 Subject: [PATCH 098/125] Update 04-schema.md --- cn-introduction/04-schema.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 2b593cf..70d7537 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -745,9 +745,9 @@ $extra = $event->getComposer()->getPackage()->getExtra(); ### bin -一组可视为二进制执行文件的文件集合，他们应该（在配置文件中）被连接到 `bin-dir` 文件夹。 +这个属性告知系统有一组文件，它们应该被视为二进制文件，并（在 config 属性中设置）被软链接到 `bin-dir` 目录。 -详情请见 [Vendor Binaries](https://github.com/5-say/composer-doc-cn/issues/articles/vendor-binaries.md) +详细请查看 [Vendor Binaries](https://github.com/5-say/composer-doc-cn/issues/articles/vendor-binaries.md)。 可选。 -- 2.46.2 From e5d7fc0441803ec1b23f1dd10d196ab0d0ce2072 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E6=96=B9=E5=AD=A4=E6=80=9D=E5=AD=90=EF=BC=88Pari?= =?UTF-8?q?s=C2=B7QianSen=EF=BC=89?= Date: Wed, 28 May 2014 11:18:07 +0800 Subject: [PATCH 099/125] =?UTF-8?q?=E6=B6=88=E9=99=A4=E5=AF=B9bin=E5=B1=9E?= =?UTF-8?q?=E6=80=A7=E7=BF=BB=E8=AF=91=E6=89=80=E9=80=A0=E6=88=90=E7=9A=84?= =?UTF-8?q?=E6=AD=A7=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/04-schema.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index 70d7537..deaa642 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -745,9 +745,9 @@ $extra = $event->getComposer()->getPackage()->getExtra(); ### bin -这个属性告知系统有一组文件，它们应该被视为二进制文件，并（在 config 属性中设置）被软链接到 `bin-dir` 目录。 +该属性用于标注一组应被视为二进制脚本的文件，他们会被软链接到（config 对象中的）`bin-dir` 属性所标注的目录，以供其他依赖库调用。 -详细请查看 [Vendor Binaries](https://github.com/5-say/composer-doc-cn/issues/articles/vendor-binaries.md)。 +详细请查看 [Vendor Binaries](articles/vendor-binaries.md)。 可选。 -- 2.46.2 From 9a3572622c5886387cb5f2859342f611ea7dd10e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E6=96=B9=E5=AD=A4=E6=80=9D=E5=AD=90=EF=BC=88Pari?= =?UTF-8?q?s=C2=B7QianSen=EF=BC=89?= Date: Wed, 28 May 2014 12:02:17 +0800 Subject: [PATCH 100/125] =?UTF-8?q?=E7=B2=97=E7=BF=BB=20vendor-binaries.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 大部分地方保留了原文，方便成武兄审阅校对。 --- cn-introduction/articles/vendor-binaries.md | 66 +++++++++++++++++---- 1 file changed, 54 insertions(+), 12 deletions(-) diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index 75087b5..0e8e7ed 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -2,31 +2,41 @@ tagline: Expose command-line scripts from packages --> -# Vendor binaries and the `vendor/bin` directory +# Vendor binaries 和 `vendor/bin` 目录 -## What is a vendor binary? +## 什么是 vendor binary？ Any command line script that a Composer package would like to pass along to a user who installs the package should be listed as a vendor binary. +一个 Composer 包应该传递给安装它的用户的每一个**命令行脚本** +都应该作为一个 vendor binary 罗列下来。 + If a package contains other scripts that are not needed by the package users (like build or compile scripts) that code should not be listed as a vendor binary. +若一个包包含有不被用户所需要的其他脚本（比如 build 或 编译脚本） +那么这些代码不应该被列为 vendor binary。 -## How is it defined? + +## 如何定义？ 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. +它是通过在项目的 `composer.json` 里添加一个 `bin` 键定义的。 +它是以一种文件的数组的形式定义的，这样任意给定项目 +都可以添加多个二进制文件。 + ```json { "bin": ["bin/my-script", "bin/my-other-script"] } ``` -## What does defining a vendor binary in composer.json do? +## 在 composer.json 里定义 vendor binary 的作用是？ It instructs Composer to install the package's binaries to `vendor/bin` for any project that **depends** on that project. @@ -35,18 +45,25 @@ This is a convenient way to expose useful scripts that would otherwise be hidden deep in the `vendor/` directory. -## What happens when Composer is run on a composer.json that defines vendor binaries? +## 当 Composer 运行于定义了 vendor binaries 的 composer.json 时发生了什么？ For the binaries that a package defines directly, nothing happens. +对于由某个包直接定义的二进制库，什么也没发生。 -## What happens when Composer is run on a composer.json that has dependencies with vendor binaries listed? + +## 当 Composer 运行于标明依赖于某 vendor binaries 的 composer.json 时发生了什么？ Composer looks for the binaries defined in all of the dependencies. A symlink is created from each dependency's binaries to `vendor/bin`. +Composer会检查所有依赖库里定义的二进制文件。 +并为每一个依赖的二进制库设立一个指向 `vendor/bin` 的软连接。 + Say package `my-vendor/project-a` has binaries setup like this: +比如 `my-vendor/project-a` 包的二进制库就是这样安装的： + ```json { "name": "my-vendor/project-a", @@ -57,8 +74,14 @@ Say package `my-vendor/project-a` has binaries setup like this: Running `composer install` for this `composer.json` will not do anything with `bin/project-a-bin`. +在该 `composer.json` 上执行 `composer install` 命令， +不会对 `bin/project-a-bin` 造成任何影响。 + Say project `my-vendor/project-b` has requirements setup like this: +但是如果 `my-vendor/project-b` 项目定义有这样的需求： + + ```json { "name": "my-vendor/project-b", @@ -71,34 +94,53 @@ Say project `my-vendor/project-b` has requirements setup like this: Running `composer install` for this `composer.json` will look at all of project-b's dependencies and install them to `vendor/bin`. +在该 `composer.json` 上执行 `composer install` 命令时， +会检查 project-b 的所有依赖，并把它们中的二进制库安装到 `vendor/bin`。 + In this case, Composer will make `vendor/my-vendor/project-a/bin/project-a-bin` available as `vendor/bin/project-a-bin`. On a Unix-like platform this is accomplished by creating a symlink. +这种情况下，Composer 会允许以 `vendor/bin/project-a-bin` 格式访问 +`vendor/my-vendor/project-a/bin/project-a-bin`。在类-Unix 的平台上， +这是通过创建 symlink 软连接实现的。 -## What about Windows and .bat files? + +## 对于 Windows 环境和 .bat 文件呢？ Packages managed entirely by Composer do not *need* to contain any `.bat` files for Windows compatibility. Composer handles installation of binaries in a special way when run in a Windows environment: +完全由 Composer 管理的包并不*需要*包含任何用以兼容 Windows 的 +`.bat`文件。在 Windows 环境下运行时，Composer 会用一种特殊的方式处理 +二进制文件的安装： + * A `.bat` file is generated automatically to reference the binary * A Unix-style proxy file with the same name as the binary is generated automatically (useful for Cygwin or Git Bash) + * 一个用以引用此二进制文件的 `.bat` 文件会自动生成 + * 一个与该二进制文件同名的 Unix-风格的代理文件也会自动生成 + （方便 Cygwin 或 Git Bash使用） + Packages that need to support workflows that may not include Composer are welcome to maintain custom `.bat` files. In this case, the package should **not** list the `.bat` file as a binary as it is not needed. +若某包存在不涉及 Composer 的工作流程， +那么它也可以维护一些定制的 `.bat` 文件。这种情况下，该包 +**不**应该把它们作为二进制文件罗列，因为 Composer 不需要知道它们。 -## Can vendor binaries be installed somewhere other than vendor/bin? -Yes, there are two ways an alternate vendor binary location can be specified: +## vendor binaries 可以安装在不是 vendor/bin 的地方么？ - 1. Setting the `bin-dir` configuration setting in `composer.json` - 1. Setting the environment variable `COMPOSER_BIN_DIR` +当然，这里有两种指定 vendor binary 的其他可选位置的方法： -An example of the former looks like this: + 1. 在 `composer.json` 文件中的 `bin-dir` 配置属性处设置 + 1. 设置环境变量 `COMPOSER_BIN_DIR` + +前者的案例如下： ```json { -- 2.46.2 From d8d3e3f01bc3ebb2d2cf97df3ec934734e7f66e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E6=96=B9=E5=AD=A4=E6=80=9D=E5=AD=90=EF=BC=88Pari?= =?UTF-8?q?s=C2=B7QianSen=EF=BC=89?= Date: Thu, 29 May 2014 00:17:29 +0800 Subject: [PATCH 101/125] =?UTF-8?q?=E6=89=80=E6=9C=89vendor=20binary?= =?UTF-8?q?=E4=B8=B4=E6=97=B6=E7=BF=BB=E8=AF=91=E4=B8=BA=E4=BA=8C=E8=BF=9B?= =?UTF-8?q?=E5=88=B6=E4=BE=9B=E5=BA=94=E5=BA=93=EF=BC=8C=E6=9F=A5=E7=BC=BA?= =?UTF-8?q?=E8=A1=A5=E6=BC=8F=EF=BC=8C=E7=AE=80=E5=8D=95=E6=B6=A6=E8=89=B2?= =?UTF-8?q?=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 尽管如此，感觉质量还是不高。 --- cn-introduction/articles/vendor-binaries.md | 34 +++++++++++++-------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index 0e8e7ed..21af779 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -2,22 +2,22 @@ tagline: Expose command-line scripts from packages --> -# Vendor binaries 和 `vendor/bin` 目录 +# 二进制供应库和 `vendor/bin` 目录 -## 什么是 vendor binary？ +## 什么是二进制供应库？ Any command line script that a Composer package would like to pass along to a user who installs the package should be listed as a vendor binary. -一个 Composer 包应该传递给安装它的用户的每一个**命令行脚本** -都应该作为一个 vendor binary 罗列下来。 +一个 Composer 资源包，想要传递给安装它的用户的任何命令行脚本， +都应该被列为 `二进制供应库`。 If a package contains other scripts that are not needed by the package users (like build or compile scripts) that code should not be listed as a vendor binary. -若一个包包含有不被用户所需要的其他脚本（比如 build 或 编译脚本） -那么这些代码不应该被列为 vendor binary。 +若一个资源包包含有不被用户所需要的其他脚本（比如 build 或 编译脚本） +那么这些代码不应该被列为二进制供应库。 ## 如何定义？ @@ -36,23 +36,28 @@ for any given project. } ``` -## 在 composer.json 里定义 vendor binary 的作用是？ +## 在 composer.json 里定义二进制供应库的作用是？ It instructs Composer to install the package's binaries to `vendor/bin` for any project that **depends** on that project. +他指导 Composer 如何安装资源包里的二进制文件到 `vendor/bin`， +以方便所有**依赖于**该项目的项目引用。 + This is a convenient way to expose useful scripts that would otherwise be hidden deep in the `vendor/` directory. +这是一个不错的，只暴露有用的脚本，同时把其他用不上的脚本深深地隐藏在 `vendor/` 目录里的 +方法。 -## 当 Composer 运行于定义了 vendor binaries 的 composer.json 时发生了什么？ +## 当 Composer 运行于定义了二进制供应库的 composer.json 时发生了什么？ For the binaries that a package defines directly, nothing happens. -对于由某个包直接定义的二进制库，什么也没发生。 +对于被某个包直接定义的二进制库，什么也不会发生。 -## 当 Composer 运行于标明依赖于某 vendor binaries 的 composer.json 时发生了什么？ +## 当 Composer 运行于标明依赖于某二进制供应库的 composer.json 时发生了什么？ Composer looks for the binaries defined in all of the dependencies. A symlink is created from each dependency's binaries to `vendor/bin`. @@ -62,7 +67,7 @@ Composer会检查所有依赖库里定义的二进制文件。 Say package `my-vendor/project-a` has binaries setup like this: -比如 `my-vendor/project-a` 包的二进制库就是这样安装的： +比如 `my-vendor/project-a` 资源包的二进制库就是这样安装的： ```json { @@ -133,9 +138,9 @@ should **not** list the `.bat` file as a binary as it is not needed. **不**应该把它们作为二进制文件罗列，因为 Composer 不需要知道它们。 -## vendor binaries 可以安装在不是 vendor/bin 的地方么？ +## 二进制供应库可以安装在不是 vendor/bin 的地方么？ -当然，这里有两种指定 vendor binary 的其他可选位置的方法： +当然，这里有两种指定二进制供应库的其他可选位置的方法： 1. 在 `composer.json` 文件中的 `bin-dir` 配置属性处设置 1. 设置环境变量 `COMPOSER_BIN_DIR` @@ -153,3 +158,6 @@ should **not** list the `.bat` file as a binary as it is not needed. Running `composer install` for this `composer.json` will result in all of the vendor binaries being installed in `scripts/` instead of `vendor/bin/`. + +在这个 `composer.json` 上运行 `composer install` 会把所有的二进制供应库 +都安装在 `scripts/` 目录，而不是缺省的 `vendor/bin/` 目录。 -- 2.46.2 From e2b025f8f0767741ad6592b8a1ad0080d0221e11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E6=96=B9=E5=AD=A4=E6=80=9D=E5=AD=90=EF=BC=88Pari?= =?UTF-8?q?s=C2=B7QianSen=EF=BC=89?= Date: Thu, 29 May 2014 19:38:27 +0800 Subject: [PATCH 102/125] =?UTF-8?q?=E5=BC=80=E5=A7=8B=E7=B2=97=E7=BF=BB=20?= =?UTF-8?q?handling-private-packages-with-satis.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../articles/handling-private-packages-with-satis.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/cn-introduction/articles/handling-private-packages-with-satis.md b/cn-introduction/articles/handling-private-packages-with-satis.md index 69da381..6988441 100644 --- a/cn-introduction/articles/handling-private-packages-with-satis.md +++ b/cn-introduction/articles/handling-private-packages-with-satis.md @@ -2,7 +2,7 @@ tagline: Host your own composer repository --> -# Handling private packages with Satis +# 用 Satis 处理私有资源包 Satis is a static `composer` repository generator. It is a bit like an ultra- lightweight, static file-based version of packagist and can be used to host the @@ -11,6 +11,8 @@ a micro-packagist. You can get it from [GitHub](http://github.com/composer/satis) or install via CLI: `composer.phar create-project composer/satis --stability=dev`. +Satis 是一个静态的 `composer` 代码库生成器。 + ## Setup For example let's assume you have a few packages you want to reuse across your -- 2.46.2 From ff6b0aca384ab87f7ed213166e8b5e710254dfa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E6=96=B9=E5=AD=A4=E6=80=9D=E5=AD=90=EF=BC=88Pari?= =?UTF-8?q?s=C2=B7QianSen=EF=BC=89?= Date: Thu, 29 May 2014 20:27:03 +0800 Subject: [PATCH 103/125] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E6=9C=AF=E8=AF=AD?= =?UTF-8?q?=E8=A1=A8=E5=92=8Cgitignore?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 1 + glossary.md | 10 ++++++++++ 2 files changed, 11 insertions(+) create mode 100644 .gitignore create mode 100644 glossary.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9f11b75 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea/ diff --git a/glossary.md b/glossary.md new file mode 100644 index 0000000..04feddb --- /dev/null +++ b/glossary.md @@ -0,0 +1,10 @@ +# P + +## Package 资源包 + +# V + +## Vendor 供应商 + +## Vendor Binary 二进制供应库 + -- 2.46.2 From 10bb30bf144db05ae0c7c119fbfd411867cff028 Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 18:01:25 +0800 Subject: [PATCH 104/125] =?UTF-8?q?=E6=A0=A1=E5=AF=B9=EF=BC=8C=E6=B6=A6?= =?UTF-8?q?=E7=A8=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/articles/vendor-binaries.md | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index 21af779..d5a5ab1 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -6,28 +6,17 @@ ## 什么是二进制供应库？ -Any command line script that a Composer package would like to pass along -to a user who installs the package should be listed as a vendor binary. - 一个 Composer 资源包，想要传递给安装它的用户的任何命令行脚本， -都应该被列为 `二进制供应库`。 +都应该被列入 `二进制供应库`。 -If a package contains other scripts that are not needed by the package -users (like build or compile scripts) that code should not be listed -as a vendor binary. - -若一个资源包包含有不被用户所需要的其他脚本（比如 build 或 编译脚本） -那么这些代码不应该被列为二进制供应库。 +如果一个资源包，含有不被用户所需要的其他脚本（比如构建或编译脚本） +那么这些代码不应该被列入二进制供应库。 ## 如何定义？ -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. - 它是通过在项目的 `composer.json` 里添加一个 `bin` 键定义的。 -它是以一种文件的数组的形式定义的，这样任意给定项目 +它是以一种文件的数组的形式定义的，这样任何给定的项目 都可以添加多个二进制文件。 ```json -- 2.46.2 From 3d3e021ae057e8e5a227568e2601ccc4b4906e01 Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 18:12:40 +0800 Subject: [PATCH 105/125] =?UTF-8?q?=E6=A0=A1=E5=AF=B9=EF=BC=8C=E6=B6=A6?= =?UTF-8?q?=E7=A8=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/articles/vendor-binaries.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index d5a5ab1..4abfd96 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -27,17 +27,12 @@ ## 在 composer.json 里定义二进制供应库的作用是？ -It instructs Composer to install the package's binaries to `vendor/bin` -for any project that **depends** on that project. +对于任何 **依赖于** 该资源包的项目， +它将引导 Composer 安装资源包里的二进制文件到 `vendor/bin` 目录。 -他指导 Composer 如何安装资源包里的二进制文件到 `vendor/bin`， -以方便所有**依赖于**该项目的项目引用。 +这是一个便捷的途径来暴露有用的脚本， +否则它们将会被隐藏在 `vendor/` 目录的深处。 -This is a convenient way to expose useful scripts that would -otherwise be hidden deep in the `vendor/` directory. - -这是一个不错的，只暴露有用的脚本，同时把其他用不上的脚本深深地隐藏在 `vendor/` 目录里的 -方法。 ## 当 Composer 运行于定义了二进制供应库的 composer.json 时发生了什么？ -- 2.46.2 From 53949d3d76cd46e930d6a5f722e7943b5caa083f Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 18:46:48 +0800 Subject: [PATCH 106/125] update --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7c547e7..1bc675c 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,8 @@ Host your own composer repository 脚本是指一些 Composer 事件的回调，它们在安装资源包的过程中被触发执行。 - [Troubleshooting](/cn-introduction/articles/troubleshooting.md) Solving problems -- [Vendor Binaries](/cn-introduction/articles/vendor-binaries.md) -Expose command-line scripts from packages +- [二进制供应库](/cn-introduction/articles/vendor-binaries.md) +从资源包中暴露命令行脚本。 ## FAQs -- 2.46.2 From 454ddc3b24fabb2013b93ebc05fc21c96b9dbab7 Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 19:30:14 +0800 Subject: [PATCH 107/125] update --- cn-introduction/01-basic-usage.md | 4 +-- cn-introduction/02-libraries.md | 2 +- cn-introduction/04-schema.md | 2 +- cn-introduction/articles/aliases.md | 2 +- cn-introduction/articles/vendor-binaries.md | 25 +++++-------------- ...the-dependencies-in-my-vendor-directory.md | 2 +- ...-composer-load-repositories-recursively.md | 2 +- glossary.md | 4 +++ 8 files changed, 17 insertions(+), 26 deletions(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 2a9c054..93ef681 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -11,7 +11,7 @@ - [包版本](#Package-Versions) - [下一个重要版本（波浪号运算符）](#Next-Significant-Release) - [稳定性](#Stability) - - [安装依赖关系](#Installing-Dependencies) + - [安装依赖包](#Installing-Dependencies) - [`composer.lock` - 锁文件](#composer.lock-The-Lock-File) - [Packagist](#Packagist) - [自动加载](#Autoloading) @@ -132,7 +132,7 @@ php composer.phar 默认情况下只有稳定的发行版才会被考虑在内。如果你也想获得 RC、beta、alpha 或 dev 版本，你可以使用 [稳定标志](04-schema.md#Package-links)。你可以对所有的包做 [最小稳定性](04-schema.md#minimum-stability) 设置，而不是每个依赖逐一设置。 -## 安装依赖关系 +## 安装依赖包 获取定义的依赖到你的本地项目，只需要调用 `composer.phar` 运行 `install` 命令。 diff --git a/cn-introduction/02-libraries.md b/cn-introduction/02-libraries.md index ec9f1ca..e716db4 100644 --- a/cn-introduction/02-libraries.md +++ b/cn-introduction/02-libraries.md @@ -156,7 +156,7 @@ hg) 的信息推断出包的版本，因此你不必手动指明版本号，并 更多关于包的来源是如何工作的，以及还有什么其他的类型可供选择，请查看[资源库](05-repositories.md)。 -这就是全部了。你现在可以使用 Composer 的 `install` 命令来安装你的依赖关系了！ +这就是全部了。你现在可以使用 Composer 的 `install` 命令来安装你的依赖包了！ **小结：** 任何含有 `composer.json` 的 `GIT`、`SVN`、`HG` 存储库，都可以通过 `require` 字段指定“包来源”和“声明依赖”来添加到你的项目中。 diff --git a/cn-introduction/04-schema.md b/cn-introduction/04-schema.md index deaa642..bedc4e5 100644 --- a/cn-introduction/04-schema.md +++ b/cn-introduction/04-schema.md @@ -745,7 +745,7 @@ $extra = $event->getComposer()->getPackage()->getExtra(); ### bin -该属性用于标注一组应被视为二进制脚本的文件，他们会被软链接到（config 对象中的）`bin-dir` 属性所标注的目录，以供其他依赖库调用。 +该属性用于标注一组应被视为二进制脚本的文件，他们会被软链接到（config 对象中的）`bin-dir` 属性所标注的目录，以供其他依赖包调用。 详细请查看 [Vendor Binaries](articles/vendor-binaries.md)。 diff --git a/cn-introduction/articles/aliases.md b/cn-introduction/articles/aliases.md index 493f643..2f68414 100644 --- a/cn-introduction/articles/aliases.md +++ b/cn-introduction/articles/aliases.md @@ -38,7 +38,7 @@ 分支别名是非常适合用于主开发分支的。但为了使用它们，你需要拥有对源码的控制权，并且你需要提交别名修改到你控制的版本库。 -当你只想在本地项目中尝试一些依赖库的 bug 修正时，这并不是最好的方式。 +当你只想在本地项目中尝试一些依赖包的 bug 修正时，这并不是最好的方式。 出于这个原因，你可以在 `require` 和 `require-dev` 字段中直接别名你需要的包。比方说那你找到了 `monolog/monolog` 的一个 bug。你在 GitHub 上克隆了 [Monolog](https://github.com/Seldaek/monolog) 并在名为 `bugfix` 的分支上修正了一个问题。现在你想安装这个版本到你的本地项目。 diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index 4abfd96..ed73a46 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -34,23 +34,16 @@ 否则它们将会被隐藏在 `vendor/` 目录的深处。 -## 当 Composer 运行于定义了二进制供应库的 composer.json 时发生了什么？ +## 当 Composer 运行到定义了二进制供应库的 composer.json 文件时发生了什么？ -For the binaries that a package defines directly, nothing happens. - -对于被某个包直接定义的二进制库，什么也不会发生。 +对于被某个资源包直接定义的二进制供应库，什么也不会发生。 -## 当 Composer 运行于标明依赖于某二进制供应库的 composer.json 时发生了什么？ +## 当 Composer 运行到，列出了二进制供应库依赖关系的 composer.json 文件时发生了什么？ -Composer looks for the binaries defined in all of the dependencies. A -symlink is created from each dependency's binaries to `vendor/bin`. - -Composer会检查所有依赖库里定义的二进制文件。 +Composer 会检查所有依赖包里定义的二进制文件。 并为每一个依赖的二进制库设立一个指向 `vendor/bin` 的软连接。 -Say package `my-vendor/project-a` has binaries setup like this: - 比如 `my-vendor/project-a` 资源包的二进制库就是这样安装的： ```json @@ -60,16 +53,10 @@ Say package `my-vendor/project-a` has binaries setup like this: } ``` -Running `composer install` for this `composer.json` will not do -anything with `bin/project-a-bin`. - 在该 `composer.json` 上执行 `composer install` 命令， 不会对 `bin/project-a-bin` 造成任何影响。 -Say project `my-vendor/project-b` has requirements setup like this: - -但是如果 `my-vendor/project-b` 项目定义有这样的需求： - +再比如项目 `my-vendor/project-b` 有这样的需求定义： ```json { @@ -84,7 +71,7 @@ Running `composer install` for this `composer.json` will look at all of project-b's dependencies and install them to `vendor/bin`. 在该 `composer.json` 上执行 `composer install` 命令时， -会检查 project-b 的所有依赖，并把它们中的二进制库安装到 `vendor/bin`。 +将会检查 project-b 的所有依赖包，并把它们中定义的二进制库安装到 `vendor/bin`。 In this case, Composer will make `vendor/my-vendor/project-a/bin/project-a-bin` available as `vendor/bin/project-a-bin`. On a Unix-like platform diff --git a/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md index 5aca046..43534aa 100644 --- a/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md +++ b/cn-introduction/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md @@ -2,7 +2,7 @@ 一般情况下 **不建议**。vendor 目录（或者你安装依赖的其它目录）都应该被添加进 `.gitignore`/`svn:ignore`/等等。 -最好这么做，然后让所有开发人员使用 Composer 来安装依赖关系。同样，build server、CI、deployment tools 等等，应进行修改，使运行 Composer 成为其项目引导的一部分。 +最好这么做，然后让所有开发人员使用 Composer 来安装依赖包。同样，build server、CI、deployment tools 等等，应进行修改，使运行 Composer 成为其项目引导的一部分。 虽然在某些环境下提交它是很让人心动的，但它将导致一些问题： diff --git a/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md b/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md index 4b95922..781e6e9 100644 --- a/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md +++ b/cn-introduction/faqs/why-can't-composer-load-repositories-recursively.md @@ -10,4 +10,4 @@ - 读取根包的存储库，同时从定义的 repos 初始化资源包，递归的初始化，根据所有依赖包中定义的 repos，以及这些依赖包所依赖的其它包中定义的 repos，等等，然后再解析依赖需求。这可能可以工作，但会严重影响初始化的速度，因为每读取一个 VCS repos 都需要几秒钟。它可能最终执行失败，因为一个包的不同版本，可能来自一个包资源库中一个相同的包，但来至不同的 dist/source 。这样有太多的可能会出错。 -- 读取根包的存储库，然后读取第一级依赖，接着读取这些依赖包所依赖的其它包，等等，然后再解析依赖需求。这样听起来更有效率，但仍然存在第二种解决方案中的问题。因为加载依赖的储存库并不像听起来那么容易。你需要加载所有可能匹配依赖关系的 repos，而这些包的定义又可能是互相冲突的。 +- 读取根包的存储库，然后读取第一级依赖，接着读取这些依赖包所依赖的其它包，等等，然后再解析依赖需求。这样听起来更有效率，但仍然存在第二种解决方案中的问题。因为加载依赖的储存库并不像听起来那么容易。你需要加载所有可能匹配的依赖包的 repos，而这些包的定义又可能是互相冲突的。 diff --git a/glossary.md b/glossary.md index 04feddb..c09498c 100644 --- a/glossary.md +++ b/glossary.md @@ -1,3 +1,7 @@ +# D + +## dependencies 依赖包、依赖关系 + # P ## Package 资源包 -- 2.46.2 From 7cba646ce91c1bf146efbe88187869f83f83e74e Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 19:43:23 +0800 Subject: [PATCH 108/125] update --- cn-introduction/articles/vendor-binaries.md | 2 +- glossary.md | 22 ++++++++++++++------- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index ed73a46..97ed254 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -56,7 +56,7 @@ Composer 会检查所有依赖包里定义的二进制文件。 在该 `composer.json` 上执行 `composer install` 命令， 不会对 `bin/project-a-bin` 造成任何影响。 -再比如项目 `my-vendor/project-b` 有这样的需求定义： +再比如项目 `my-vendor/project-b` 有这样的 require 定义： ```json { diff --git a/glossary.md b/glossary.md index c09498c..8b88d13 100644 --- a/glossary.md +++ b/glossary.md @@ -1,14 +1,22 @@ -# D +术语表 +=============== -## dependencies 依赖包、依赖关系 -# P +## D -## Package 资源包 +### dependencies 依赖包、依赖关系 -# V +## P -## Vendor 供应商 +### Package 资源包 -## Vendor Binary 二进制供应库 +## S + +### symlink 软链接 + +## V + +### Vendor 供应商 + +### Vendor Binary 二进制供应库 -- 2.46.2 From 7d98b000dabfa259e934f0fc350ab75df12a4e9e Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 19:51:40 +0800 Subject: [PATCH 109/125] update --- README.md | 1 + glossary.md | 1 + 2 files changed, 2 insertions(+) diff --git a/README.md b/README.md index 1bc675c..c50c746 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Composer 中文文档 - 希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。 - 部分内容现阶段无法译全，已在 [issues](https://github.com/5-say/composer-doc-cn/issues) 中列出，如果能够收到您的宝贵建议，必将感激不尽。 +- [翻译术语对照表](/glossary.md) --- diff --git a/glossary.md b/glossary.md index 8b88d13..120a217 100644 --- a/glossary.md +++ b/glossary.md @@ -1,6 +1,7 @@ 术语表 =============== +> [D](#d) || [P](#p) || [S](#s) || [V](#v) ## D -- 2.46.2 From f1d53666d6bb8483f339601c5b4e589ff5ed66bd Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 20:15:07 +0800 Subject: [PATCH 110/125] update --- README.md | 1 + contributors.md | 19 +++++++++++++++++++ glossary.md | 2 +- 3 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 contributors.md diff --git a/README.md b/README.md index c50c746..dff0c4a 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Composer 中文文档 - 希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。 - 部分内容现阶段无法译全，已在 [issues](https://github.com/5-say/composer-doc-cn/issues) 中列出，如果能够收到您的宝贵建议，必将感激不尽。 - [翻译术语对照表](/glossary.md) +- [中文翻译贡献者名单](/contributors.md) --- diff --git a/contributors.md b/contributors.md new file mode 100644 index 0000000..31cccf0 --- /dev/null +++ b/contributors.md @@ -0,0 +1,19 @@ +# 中文翻译贡献者名单 + +> 项目持续至今，从一个人苦撑，到渐渐有了朋友的加入，感谢大家的辛劳与付出，同时也期待结识更多的新朋友。 + +- [王赛](#wangsai) + + +## 王赛 +- 邮箱：wangsai@bootcss.com +- 网址： [Bootstrap中文网](http://www.bootcss.com) & [Laravel中文网](http://www.golaravel.com) +- Github: [https://github.com/wangsai/](https://github.com/wangsai/) + + +- [东方孤思子](#dongfanggusizi) + + +## 东方孤思子 +- 邮箱：qiansen1386@gmail.com +- Github: [https://github.com/qiansen1386](https://github.com/qiansen1386) diff --git a/glossary.md b/glossary.md index 120a217..f5a1116 100644 --- a/glossary.md +++ b/glossary.md @@ -1,4 +1,4 @@ -术语表 +翻译术语对照表 =============== > [D](#d) || [P](#p) || [S](#s) || [V](#v) -- 2.46.2 From ebc7f1b01b5bc7260d75f0a5163c9365e1a630e2 Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 20:17:08 +0800 Subject: [PATCH 111/125] update --- contributors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributors.md b/contributors.md index 31cccf0..c7f0642 100644 --- a/contributors.md +++ b/contributors.md @@ -3,6 +3,8 @@ > 项目持续至今，从一个人苦撑，到渐渐有了朋友的加入，感谢大家的辛劳与付出，同时也期待结识更多的新朋友。 - [王赛](#wangsai) +- [东方孤思子](#dongfanggusizi) + ## 王赛 @@ -11,8 +13,6 @@ - Github: [https://github.com/wangsai/](https://github.com/wangsai/) -- [东方孤思子](#dongfanggusizi) - ## 东方孤思子 - 邮箱：qiansen1386@gmail.com -- 2.46.2 From 24cf19b7dd362e7ab2be1ce5ca7bb47b6d856f77 Mon Sep 17 00:00:00 2001 From: bcw Date: Sun, 22 Jun 2014 21:08:35 +0800 Subject: [PATCH 112/125] =?UTF-8?q?=E6=A0=A1=E5=AF=B9=E5=8F=8A=E6=B6=A6?= =?UTF-8?q?=E7=A8=BF=E7=BB=93=E6=9D=9F=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/articles/vendor-binaries.md | 50 ++++++--------------- 1 file changed, 13 insertions(+), 37 deletions(-) diff --git a/cn-introduction/articles/vendor-binaries.md b/cn-introduction/articles/vendor-binaries.md index 97ed254..903b27f 100644 --- a/cn-introduction/articles/vendor-binaries.md +++ b/cn-introduction/articles/vendor-binaries.md @@ -67,56 +67,36 @@ Composer 会检查所有依赖包里定义的二进制文件。 } ``` -Running `composer install` for this `composer.json` will look at -all of project-b's dependencies and install them to `vendor/bin`. - 在该 `composer.json` 上执行 `composer install` 命令时， -将会检查 project-b 的所有依赖包，并把它们中定义的二进制库安装到 `vendor/bin`。 +将会检查 project-b 的所有依赖包，并安装它们的二进制库到 `vendor/bin` 目录。 -In this case, Composer will make `vendor/my-vendor/project-a/bin/project-a-bin` -available as `vendor/bin/project-a-bin`. On a Unix-like platform -this is accomplished by creating a symlink. - -这种情况下，Composer 会允许以 `vendor/bin/project-a-bin` 格式访问 -`vendor/my-vendor/project-a/bin/project-a-bin`。在类-Unix 的平台上， -这是通过创建 symlink 软连接实现的。 +这种情况下，Composer 将使 `vendor/bin/project-a-bin` 可以作为 +`vendor/my-vendor/project-a/bin/project-a-bin` 的访问路径。在类 Unix 平台上， +这是通过创建软链接实现的。 ## 对于 Windows 环境和 .bat 文件呢？ -Packages managed entirely by Composer do not *need* to contain any -`.bat` files for Windows compatibility. Composer handles installation -of binaries in a special way when run in a Windows environment: - -完全由 Composer 管理的包并不*需要*包含任何用以兼容 Windows 的 -`.bat`文件。在 Windows 环境下运行时，Composer 会用一种特殊的方式处理 +完全由 Composer 管理的包并不 *需要* 包含任何用以兼容 Windows 的 +`.bat` 文件。在 Windows 环境下运行时，Composer 会用一种特殊的方式处理 二进制文件的安装： - * A `.bat` file is generated automatically to reference the binary - * A Unix-style proxy file with the same name as the binary is generated - automatically (useful for Cygwin or Git Bash) - * 一个用以引用此二进制文件的 `.bat` 文件会自动生成 - * 一个与该二进制文件同名的 Unix-风格的代理文件也会自动生成 - （方便 Cygwin 或 Git Bash使用） + * 一个与该二进制文件同名的 Unix 风格的代理文件也会自动生成 + （方便 Cygwin 或 Git Bash 使用） -Packages that need to support workflows that may not include Composer -are welcome to maintain custom `.bat` files. In this case, the package -should **not** list the `.bat` file as a binary as it is not needed. - -若某包存在不涉及 Composer 的工作流程， -那么它也可以维护一些定制的 `.bat` 文件。这种情况下，该包 -**不**应该把它们作为二进制文件罗列，因为 Composer 不需要知道它们。 +有时资源包需要维护自定义的 `.bat` 文件来支持工作流，它可以不包含在 Composer 中。 +这种情况下，该资源包 **不** 应该把它们作为二进制文件列出，因为 Composer 不需要知道它们。 -## 二进制供应库可以安装在不是 vendor/bin 的地方么？ +## 二进制供应库可以安装在 vendor/bin 以外的其它地方么？ 当然，这里有两种指定二进制供应库的其他可选位置的方法： 1. 在 `composer.json` 文件中的 `bin-dir` 配置属性处设置 - 1. 设置环境变量 `COMPOSER_BIN_DIR` + 2. 设置环境变量 `COMPOSER_BIN_DIR` -前者的案例如下： +前者的实例如下： ```json { @@ -126,9 +106,5 @@ should **not** list the `.bat` file as a binary as it is not needed. } ``` -Running `composer install` for this `composer.json` will result in -all of the vendor binaries being installed in `scripts/` instead of -`vendor/bin/`. - 在这个 `composer.json` 上运行 `composer install` 会把所有的二进制供应库 都安装在 `scripts/` 目录，而不是缺省的 `vendor/bin/` 目录。 -- 2.46.2 From fc758a5a643225faf70f030442fb5418659318aa Mon Sep 17 00:00:00 2001 From: 5-say Date: Sat, 17 Oct 2015 18:04:53 +0800 Subject: [PATCH 113/125] update --- cn-introduction/00-intro.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md index d145a9c..23e9f9a 100644 --- a/cn-introduction/00-intro.md +++ b/cn-introduction/00-intro.md @@ -27,8 +27,8 @@ Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖 Composer 不是一个包管理器。是的，它涉及 "packages" 和 "libraries"，但它在每个项目的基础上进行管理，在你项目的某个目录中（例如 `vendor`）进行安装。默认情况下它不会在全局安装任何东西。因此，这仅仅是一个依赖管理。 -这种想法并不新鲜，Composer 受到了 node's [npm](http://npmjs.org/) -和 ruby's [bundler](http://gembundler.com/) 的强烈启发。而当时 PHP 下并没有类似的工具。 +这种想法并不新鲜，Composer 受到了 node 的 [npm](http://npmjs.org/) +和 ruby 的 [bundler](http://gembundler.com/) 的强烈启发。而当时 PHP 下并没有类似的工具。 Composer 将这样为你解决问题： @@ -53,7 +53,7 @@ d) Composer 会找出哪个版本的包需要安装，并安装它们（将它 } ``` -我们只要指出我们的项目需要一些 `monolog/monolog` 的包，从 `1.2` 开始的任何版本。 +我们只要指出我们的项目需要一些 `monolog/monolog` 的包，从 `1.2` 到 `1.3` 之间的最高版本。 ## 系统要求 -- 2.46.2 From f5e2a356b9e1e2064e63a71fb626ef313067c06f Mon Sep 17 00:00:00 2001 From: 5-say Date: Sat, 17 Oct 2015 21:14:46 +0800 Subject: [PATCH 114/125] update --- cn-introduction/01-basic-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 93ef681..b097c02 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -182,7 +182,7 @@ php composer.phar update monolog/monolog [...] [packagist](https://packagist.org/) 是 Composer 的主要资源库。 一个 Composer 的库基本上是一个包的源：记录了可以得到包的地方。Packagist 的目标是成为大家使用库资源的中央存储平台。这意味着你可以 `require` 那里的任何包。 -当你访问 [packagist website](https://packagist.org/) (packagist.org)，你可以浏览和搜索资源包。 +当你访问 [packagist](https://packagist.org/) 网站 (packagist.org)，你可以浏览和搜索资源包。 任何支持 Composer 的开源项目应该发布自己的包在 packagist 上。虽然并不一定要发布在 packagist 上来使用 Composer，但它使我们的编程生活更加轻松。 -- 2.46.2 From f97aae1819d9c438b39e73cc1f1f512520251ce5 Mon Sep 17 00:00:00 2001 From: dongjiawei Date: Wed, 6 Jan 2016 21:44:20 +0800 Subject: [PATCH 115/125] change PSR-0 with PSR-4 --- cn-introduction/01-basic-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index b097c02..e89a9fc 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -227,7 +227,7 @@ $loader = require 'vendor/autoload.php'; $loader->add('Acme\\Test\\', __DIR__); ``` -除了 PSR-4 自动加载，classmap 也是支持的。这允许类被自动加载，即使不符合 PSR-0 规范。详细请查看 [自动加载-参考](04-schema.md#autoload)。 +除了 PSR-4 自动加载，classmap 也是支持的。这允许类被自动加载，即使不符合 PSR-4 规范。详细请查看 [自动加载-参考](04-schema.md#autoload)。 > **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_*.php` 文件，它返回一个关联数组，你可以通过这个关联数组配置自己的 autoloader。 -- 2.46.2 From e16fcb9e193242e01be033be5ddde81951aacbb9 Mon Sep 17 00:00:00 2001 From: dongjiawei Date: Wed, 6 Jan 2016 21:56:03 +0800 Subject: [PATCH 116/125] sync for new version --- en-back/00-intro.md | 169 +++++++--------- en-back/01-basic-usage.md | 186 +++++++---------- en-back/02-libraries.md | 86 ++++---- en-back/03-cli.md | 198 ++++++++++++++----- en-back/04-schema.md | 194 +++++++++--------- en-back/05-repositories.md | 131 +++++++++--- en-back/06-config.md | 189 ++++++++++++++++++ en-back/{06-community.md => 07-community.md} | 19 +- 8 files changed, 747 insertions(+), 425 deletions(-) create mode 100644 en-back/06-config.md rename en-back/{06-community.md => 07-community.md} (54%) diff --git a/en-back/00-intro.md b/en-back/00-intro.md index 3435462..d984eb7 100644 --- a/en-back/00-intro.md +++ b/en-back/00-intro.md @@ -1,54 +1,41 @@ # Introduction Composer is a tool for dependency management in PHP. It allows you to declare -the dependent libraries your project needs and it will install them in your -project for you. +the libraries your project depends on and it will manage (install/update) them +for you. ## Dependency management -Composer is not a package manager. Yes, it deals with "packages" or libraries, but -it manages them on a per-project basis, installing them in a directory (e.g. `vendor`) -inside your project. By default it will never install anything globally. Thus, -it is a dependency manager. +Composer is **not** a package manager in the same sense as Yum or Apt are. Yes, +it deals with "packages" or libraries, but it manages them on a per-project +basis, installing them in a directory (e.g. `vendor`) inside your project. By +default it will never install anything globally. Thus, it is a dependency +manager. -This idea is not new and Composer is strongly inspired by node's [npm](http://npmjs.org/) -and ruby's [bundler](http://gembundler.com/). But there has not been such a tool -for PHP. +This idea is not new and Composer is strongly inspired by node's +[npm](https://npmjs.org/) and ruby's [bundler](http://bundler.io/). -The problem that Composer solves is this: +Suppose: a) You have a project that depends on a number of libraries. b) Some of those libraries depend on other libraries. -c) You declare the things you depend on. +Composer: -d) Composer finds out which versions of which packages need to be installed, and +c) Enables you to declare the libraries you depend on. + +d) Finds out which versions of which packages can and need to be installed, and installs them (meaning it downloads them into your project). -## Declaring dependencies - -Let's say you are creating a project, and you need a library that does logging. -You decide to use [monolog](https://github.com/Seldaek/monolog). In order to -add it to your project, all you need to do is create a `composer.json` file -which describes the project's dependencies. - -```json -{ - "require": { - "monolog/monolog": "1.2.*" - } -} -``` - -We are simply stating that our project requires some `monolog/monolog` package, -any version beginning with `1.2`. +See the [Basic usage](01-basic-usage.md) chapter for more details on declaring +dependencies. ## System Requirements Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile -flags are also required, but the installer will warn you about any -incompatibilities. +flags are also required, but when using the installer you will be warned about +any incompatibilities. To install packages from sources instead of simple zip archives, you will need git, svn or hg depending on how the package is version-controlled. @@ -56,14 +43,23 @@ git, svn or hg depending on how the package is version-controlled. Composer is multi-platform and we strive to make it run equally well on Windows, Linux and OSX. -## Installation - *nix +## Installation - Linux / Unix / OSX ### Downloading the Composer Executable +Composer offers a convenient installer that you can execute directly from the +commandline. Feel free to [download this file](https://getcomposer.org/installer) +or review it on [GitHub](https://github.com/composer/getcomposer.org/blob/master/web/installer) +if you wish to know more about the inner workings of the installer. The source +is plain PHP. + +There are in short, two ways to install Composer. Locally as part of your +project, or globally as a system wide executable. + #### Locally -To actually get Composer, we need to do two things. The first one is installing -Composer (again, this means downloading it into your project): +Installing Composer locally is a matter of just running the installer in your +project directory: ```sh curl -sS https://getcomposer.org/installer | php @@ -76,69 +72,81 @@ curl -sS https://getcomposer.org/installer | php php -r "readfile('https://getcomposer.org/installer');" | php ``` -This will just check a few PHP settings and then download `composer.phar` to -your working directory. This file is the Composer binary. It is a PHAR (PHP -archive), which is an archive format for PHP which can be run on the command -line, amongst other things. +The installer will just check a few PHP settings and then download +`composer.phar` to your working directory. This file is the Composer binary. It +is a PHAR (PHP archive), which is an archive format for PHP which can be run on +the command line, amongst other things. + +Now just run `php composer.phar` in order to run Composer. You can install Composer to a specific directory by using the `--install-dir` -option and providing a target directory (it can be an absolute or relative path): +option and additionally (re)name it as well using the `--filename` option: ```sh -curl -sS https://getcomposer.org/installer | php -- --install-dir=bin +curl -sS https://getcomposer.org/installer | php -- --install-dir=bin --filename=composer ``` +Now just run `php bin/composer` in order to run Composer. + #### Globally -You can place this file anywhere you wish. If you put it in your `PATH`, -you can access it globally. On unixy systems you can even make it -executable and invoke it without `php`. +You can place the Composer PHAR anywhere you wish. If you put it in a directory +that is part of your `PATH`, you can access it globally. On unixy systems you +can even make it executable and invoke it without directly using the `php` +interpreter. -You can run these commands to easily access `composer` from anywhere on your system: +Run these commands to globally install `composer` on your system: ```sh curl -sS https://getcomposer.org/installer | php mv composer.phar /usr/local/bin/composer ``` -> **Note:** If the above fails due to permissions, run the `mv` line -> again with sudo. +> **Note:** If the above fails due to permissions, run the `mv` line again +> with sudo. -Then, just run `composer` in order to run Composer instead of `php composer.phar`. - -#### Globally (on OSX via homebrew) - -Composer is part of the homebrew-php project. +A quick copy-paste version including sudo: ```sh -brew update -brew tap josegonzalez/homebrew-php -brew tap homebrew/versions -brew install php55-intl -brew install josegonzalez/php/composer +curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer ``` +> **Note:** On some versions of OSX the `/usr` directory does not exist by +> default. If you receive the error "/usr/local/bin/composer: No such file or +> directory" then you must create the directory manually before proceeding: +> `mkdir -p /usr/local/bin`. + +> **Note:** For information on changing your PATH, please read the +> [Wikipedia article](https://en.wikipedia.org/wiki/PATH_(variable)) and/or use Google. + +Now just run `composer` in order to run Composer instead of `php composer.phar`. + ## Installation - Windows ### Using the Installer This is the easiest way to get Composer set up on your machine. -Download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe), -it will install the latest Composer version and set up your PATH so that you can -just call `composer` from any directory in your command line. +Download and run +[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will +install the latest Composer version and set up your PATH so that you can just +call `composer` from any directory in your command line. + +> **Note:** Close your current terminal. Test usage with a new terminal: This is +> important since the PATH only gets loaded when the terminal starts. ### Manual Installation Change to a directory on your `PATH` and run the install snippet to download -composer.phar: +`composer.phar`: ```sh C:\Users\username>cd C:\bin C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php ``` -> **Note:** If the above fails due to readfile, use the `http` url or enable php_openssl.dll in php.ini +> **Note:** If the above fails due to readfile, use the `http` url or enable +> php_openssl.dll in php.ini Create a new `composer.bat` file alongside `composer.phar`: @@ -146,6 +154,8 @@ Create a new `composer.bat` file alongside `composer.phar`: C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat ``` +Add the directory to your PATH environment variable if it isn't already. + Close your current terminal. Test usage with a new terminal: ```sh @@ -155,38 +165,7 @@ Composer version 27d8904 ## Using Composer -We will now use Composer to install the dependencies of the project. If you -don't have a `composer.json` file in the current directory please skip to the -[Basic Usage](01-basic-usage.md) chapter. +Now that you've installed Composer, you are ready to use it! Head on over to the +next chapter for a short and simple demonstration. -To resolve and download dependencies, run the `install` command: - -```sh -php composer.phar install -``` - -If you did a global install and do not have the phar in that directory -run this instead: - -```sh -composer install -``` - -Following the [example above](#declaring-dependencies), this will download -monolog into the `vendor/monolog/monolog` directory. - -## Autoloading - -Besides downloading the library, Composer also prepares an autoload file that's -capable of autoloading all of the classes in any of the libraries that it -downloads. To use it, just add the following line to your code's bootstrap -process: - -```php -require 'vendor/autoload.php'; -``` - -Woah! Now start using monolog! To keep learning more about Composer, keep -reading the "Basic Usage" chapter. - -[Basic Usage](01-basic-usage.md) → +[Basic usage](01-basic-usage.md) → diff --git a/en-back/01-basic-usage.md b/en-back/01-basic-usage.md index 270a6d5..b33f06a 100644 --- a/en-back/01-basic-usage.md +++ b/en-back/01-basic-usage.md @@ -1,29 +1,13 @@ # Basic usage -## Installation +## Introduction -To install Composer, you just need to download the `composer.phar` executable. +For our basic usage introduction, we will be installing `monolog/monolog`, +a logging library. If you have not yet installed Composer, refer to the +[Intro](00-intro.md) chapter. -```sh -curl -sS https://getcomposer.org/installer | php -``` - -For the details, see the [Introduction](00-intro.md) chapter. - -To check if Composer is working, just run the PHAR through `php`: - -```sh -php composer.phar -``` - -This should give you a list of available commands. - -> **Note:** You can also perform the checks only without downloading Composer -> by using the `--check` option. For more information, just use `--help`. -> -> ```sh -> curl -sS https://getcomposer.org/installer | php -- --help -> ``` +> **Note:** for the sake of simplicity, this introduction will assume you +> have performed a [local](00-intro.md#locally) install of Composer. ## `composer.json`: Project Setup @@ -31,14 +15,11 @@ To start using Composer in your project, all you need is a `composer.json` file. This file describes the dependencies of your project and may contain other metadata as well. -The [JSON format](http://json.org/) is quite easy to write. It allows you to -define nested structures. - ### The `require` Key The first (and often only) thing you specify in `composer.json` is the -`require` key. You're simply telling Composer which packages your project -depends on. +[`require`](04-schema.md#require) key. You're simply telling Composer which +packages your project depends on. ```json { @@ -48,15 +29,16 @@ depends on. } ``` -As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`) -to **package versions** (e.g. `1.0.*`). +As you can see, [`require`](04-schema.md#require) takes an object that maps +**package names** (e.g. `monolog/monolog`) to **version constraints** (e.g. +`1.0.*`). ### Package Names The package name consists of a vendor name and the project's name. Often these -will be identical - the vendor name just exists to prevent naming clashes. It allows -two different people to create a library named `json`, which would then just be -named `igorw/json` and `seldaek/json`. +will be identical - the vendor name just exists to prevent naming clashes. It +allows two different people to create a library named `json`, which would then +just be named `igorw/json` and `seldaek/json`. Here we are requiring `monolog/monolog`, so the vendor name is the same as the project's name. For projects with a unique name this is recommended. It also @@ -66,46 +48,26 @@ smaller decoupled parts. ### Package Versions -In the previous example we were requiring version `1.0.*` of monolog. This -means any version in the `1.0` development branch. It would match `1.0.0`, -`1.0.2` or `1.0.20`. +In the previous example we were requiring version +[`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of +Monolog. This means any version in the `1.0` development branch. It is the +equivalent of saying versions that match `>=1.0 <1.1`. -Version constraints can be specified in a few different ways. - -Name | Example | Description --------------- | --------------------- | ----------- -Exact version | `1.0.2` | You can specify the exact version of a package. -Range | `>=1.0` `>=1.0,<2.0` `>=1.0,<1.1 | >=1.2` | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`.
You can define multiple ranges, separated by a comma, which will be treated as a **logical AND**. A pipe symbol `|` will be treated as a **logical OR**.
AND has higher precedence than OR. -Wildcard | `1.0.*` | You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0,<1.1`. -Tilde Operator | `~1.2` | Very useful for projects that follow semantic versioning. `~1.2` is equivalent to `>=1.2,<2.0`. For more details, read the next section below. - -### Next Significant Release (Tilde Operator) - -The `~` operator is best explained by example: `~1.2` is equivalent to -`>=1.2,<2.0`, while `~1.2.3` is equivalent to `>=1.2.3,<1.3`. As you can see -it is mostly useful for projects respecting [semantic -versioning](http://semver.org/). A common usage would be to mark the minimum -minor version you depend on, like `~1.2` (which allows anything up to, but not -including, 2.0). Since in theory there should be no backwards compatibility -breaks until 2.0, that works well. Another way of looking at it is that using -`~` specifies a minimum version, but allows the last digit specified to go up. - -> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint -> like `~1.2` would not install it. As said above `~1.2` only means the `.2` -> can change but the `1.` part is fixed. +Version constraints can be specified in several ways, read +[versions](articles/versions.md) for more in-depth information on this topic. ### Stability -By default only stable releases are taken into consideration. If you would like -to also get RC, beta, alpha or dev versions of your dependencies you can do -so using [stability flags](04-schema.md#package-links). To change that for all -packages instead of doing per dependency you can also use the +By default only stable releases are taken into consideration. If you would +like to also get RC, beta, alpha or dev versions of your dependencies you can +do so using [stability flags](04-schema.md#package-links). To change that for +all packages instead of doing per dependency you can also use the [minimum-stability](04-schema.md#minimum-stability) setting. ## Installing Dependencies -To fetch the defined dependencies into your local project, just run the -`install` command of `composer.phar`. +To install the defined dependencies for your project, just run the +[`install`](03-cli.md#install) command. ```sh php composer.phar install @@ -114,14 +76,14 @@ php composer.phar install This will find the latest version of `monolog/monolog` that matches the supplied version constraint and download it into the `vendor` directory. It's a convention to put third party code into a directory named `vendor`. -In case of monolog it will put it into `vendor/monolog/monolog`. +In case of Monolog it will put it into `vendor/monolog/monolog`. > **Tip:** If you are using git for your project, you probably want to add -> `vendor` into your `.gitignore`. You really don't want to add all of that +> `vendor` in your `.gitignore`. You really don't want to add all of that > code to your repository. -Another thing that the `install` command does is it adds a `composer.lock` -file into your project root. +You will notice the [`install`](03-cli.md#install) command also created a +`composer.lock` file. ## `composer.lock` - The Lock File @@ -129,31 +91,36 @@ After installing the dependencies, Composer writes the list of the exact versions it installed into a `composer.lock` file. This locks the project to those specific versions. -**Commit your application's `composer.lock` (along with `composer.json`) into version control.** +**Commit your application's `composer.lock` (along with `composer.json`) +into version control.** -This is important because the `install` command checks if a lock file is present, -and if it is, it downloads the versions specified there (regardless of what `composer.json` -says). +This is important because the [`install`](03-cli.md#install) command checks +if a lock file is present, and if it is, it downloads the versions specified +there (regardless of what `composer.json` says). -This means that anyone who sets up the project will download the exact -same version of the dependencies. Your CI server, production machines, other -developers in your team, everything and everyone runs on the same dependencies, which -mitigates the potential for bugs affecting only some parts of the deployments. Even if you -develop alone, in six months when reinstalling the project you can feel confident the -dependencies installed are still working even if your dependencies released -many new versions since then. +This means that anyone who sets up the project will download the exact same +version of the dependencies. Your CI server, production machines, other +developers in your team, everything and everyone runs on the same dependencies, +which mitigates the potential for bugs affecting only some parts of the +deployments. Even if you develop alone, in six months when reinstalling the +project you can feel confident the dependencies installed are still working even +if your dependencies released many new versions since then. If no `composer.lock` file exists, Composer will read the dependencies and -versions from `composer.json` and create the lock file. +versions from `composer.json` and create the lock file after executing the +[`update`](03-cli.md#update) or the [`install`](03-cli.md#install) command. -This means that if any of the dependencies get a new version, you won't get the updates -automatically. To update to the new version, use `update` command. This will fetch -the latest matching versions (according to your `composer.json` file) and also update -the lock file with the new version. +This means that if any of the dependencies get a new version, you won't get the +updates automatically. To update to the new version, use the +[`update`](03-cli.md#update) command. This will fetch the latest matching +versions (according to your `composer.json` file) and also update the lock file +with the new version. ```sh php composer.phar update ``` +> **Note:** Composer will display a Warning when executing an `install` command +> if `composer.lock` and `composer.json` are not synchronized. If you only want to install or update one dependency, you can whitelist them: @@ -161,47 +128,45 @@ If you only want to install or update one dependency, you can whitelist them: php composer.phar update monolog/monolog [...] ``` -> **Note:** For libraries it is not necessarily recommended to commit the lock file, -> see also: [Libraries - Lock file](02-libraries.md#lock-file). +> **Note:** For libraries it is not necessary to commit the lock +> file, see also: [Libraries - Lock file](02-libraries.md#lock-file). ## Packagist [Packagist](https://packagist.org/) is the main Composer repository. A Composer repository is basically a package source: a place where you can get packages from. Packagist aims to be the central repository that everybody uses. This -means that you can automatically `require` any package that is available -there. +means that you can automatically `require` any package that is available there. -If you go to the [packagist website](https://packagist.org/) (packagist.org), +If you go to the [Packagist website](https://packagist.org/) (packagist.org), you can browse and search for packages. -Any open source project using Composer should publish their packages on -packagist. A library doesn't need to be on packagist to be used by Composer, -but it makes life quite a bit simpler. +Any open source project using Composer is recommended to publish their packages +on Packagist. A library doesn't need to be on Packagist to be used by Composer, +but it enables discovery and adoption by other developers more quickly. ## Autoloading For libraries that specify autoload information, Composer generates a -`vendor/autoload.php` file. You can simply include this file and you -will get autoloading for free. +`vendor/autoload.php` file. You can simply include this file and you will get +autoloading for free. ```php -require 'vendor/autoload.php'; +require __DIR__ . '/vendor/autoload.php'; ``` -This makes it really easy to use third party code. For example: If your -project depends on monolog, you can just start using classes from it, and they -will be autoloaded. +This makes it really easy to use third party code. For example: If your project +depends on Monolog, you can just start using classes from it, and they will be +autoloaded. ```php $log = new Monolog\Logger('name'); $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); - $log->addWarning('Foo'); ``` -You can even add your own code to the autoloader by adding an `autoload` field -to `composer.json`. +You can even add your own code to the autoloader by adding an +[`autoload`](04-schema.md#autoload) field to `composer.json`. ```json { @@ -218,24 +183,25 @@ You define a mapping from namespaces to directories. The `src` directory would be in your project root, on the same level as `vendor` directory is. An example filename would be `src/Foo.php` containing an `Acme\Foo` class. -After adding the `autoload` field, you have to re-run `install` to re-generate -the `vendor/autoload.php` file. +After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run +[`dump-autoload`](03-cli.md#dump-autoload) to re-generate the +`vendor/autoload.php` file. Including that file will also return the autoloader instance, so you can store the return value of the include call in a variable and add more namespaces. This can be useful for autoloading classes in a test suite, for example. ```php -$loader = require 'vendor/autoload.php'; +$loader = require __DIR__ . '/vendor/autoload.php'; $loader->add('Acme\\Test\\', __DIR__); ``` -In addition to PSR-4 autoloading, classmap is also supported. This allows -classes to be autoloaded even if they do not conform to PSR-4. See the -[autoload reference](04-schema.md#autoload) for more details. +In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and +files autoloading. See the [`autoload`](04-schema.md#autoload) reference for +more information. -> **Note:** Composer provides its own autoloader. If you don't want to use -that one, you can just include `vendor/composer/autoload_*.php` files, -which return associative arrays allowing you to configure your own autoloader. +> **Note:** Composer provides its own autoloader. If you don't want to use that +> one, you can just include `vendor/composer/autoload_*.php` files, which return +> associative arrays allowing you to configure your own autoloader. ← [Intro](00-intro.md) | [Libraries](02-libraries.md) → diff --git a/en-back/02-libraries.md b/en-back/02-libraries.md index 81ec3ed..da5725e 100644 --- a/en-back/02-libraries.md +++ b/en-back/02-libraries.md @@ -1,16 +1,17 @@ # Libraries -This chapter will tell you how to make your library installable through Composer. +This chapter will tell you how to make your library installable through +Composer. ## Every project is a package As soon as you have a `composer.json` in a directory, that directory is a -package. When you add a `require` to a project, you are making a package that -depends on other packages. The only difference between your project and -libraries is that your project is a package without a name. +package. When you add a [`require`](04-schema.md#require) to a project, you are +making a package that depends on other packages. The only difference between +your project and libraries is that your project is a package without a name. In order to make that package installable you need to give it a name. You do -this by adding a `name` to `composer.json`: +this by adding the [`name`](04-schema.md#name) property in `composer.json`: ```json { @@ -21,12 +22,12 @@ this by adding a `name` to `composer.json`: } ``` -In this case the project name is `acme/hello-world`, where `acme` is the -vendor name. Supplying a vendor name is mandatory. +In this case the project name is `acme/hello-world`, where `acme` is the vendor +name. Supplying a vendor name is mandatory. > **Note:** If you don't know what to use as a vendor name, your GitHub -username is usually a good bet. While package names are case insensitive, the -convention is all lowercase and dashes for word separation. +> username is usually a good bet. While package names are case insensitive, the +> convention is all lowercase and dashes for word separation. ## Platform packages @@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries. PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`, `openssl`, `pcre`, `uuid`, `xsl`. -You can use `composer show --platform` to get a list of your locally available -platform packages. +You can use [`show --platform`](03-cli.md#show) to get a list of your locally +available platform packages. ## Specifying the version -You need to specify the package's version some way. When you publish your -package on Packagist, it is able to infer the version from the VCS (git, svn, -hg) information, so in that case you do not have to specify it, and it is -recommended not to. See [tags](#tags) and [branches](#branches) to see how +When you publish your package on Packagist, it is able to infer the version +from the VCS (git, svn, hg) information. This means you don't have to +explicitly declare it. Read [tags](#tags) and [branches](#branches) to see how version numbers are extracted from these. If you are creating packages by hand and really have to specify it explicitly, @@ -76,32 +76,33 @@ you can just add a `version` field: ### Tags For every tag that looks like a version, a package version of that tag will be -created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix -of `-patch`, `-alpha`, `-beta` or `-RC`. The suffixes can also be followed by -a number. +created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix of +`-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffix can also +be followed by a number. Here are a few examples of valid tag names: - 1.0.0 - v1.0.0 - 1.10.5-RC1 -- v4.4.4beta2 +- v4.4.4-beta2 - v2.0.0-alpha - v2.0.4-p1 -> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions) -> in a `require` statement has to be specified without prefix -> (e.g. tag `v1.0.0` will result in version `1.0.0`). +> **Note:** Even if your tag is prefixed with `v`, a +> [version constraint](01-basic-usage.md#package-versions) in a `require` +> statement has to be specified without prefix (e.g. tag `v1.0.0` will result +> in version `1.0.0`). ### Branches For every branch, a package development version will be created. If the branch -name looks like a version, the version will be `{branchname}-dev`. For example -a branch `2.0` will get a version `2.0.x-dev` (the `.x` is added for technical -reasons, to make sure it is recognized as a branch, a `2.0.x` branch would also -be valid and be turned into `2.0.x-dev` as well. If the branch does not look -like a version, it will be `dev-{branchname}`. `master` results in a -`dev-master` version. +name looks like a version, the version will be `{branchname}-dev`. For example, +the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for +technical reasons, to make sure it is recognized as a branch). The `2.0.x` +branch would also be valid and be turned into `2.0.x-dev` as well. If the +branch does not look like a version, it will be `dev-{branchname}`. `master` +results in a `dev-master` version. Here are some examples of version branch names: @@ -116,8 +117,8 @@ Here are some examples of version branch names: ### Aliases It is possible to alias branch names to versions. For example, you could alias -`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all -the packages. +`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in +all the packages. See [Aliases](articles/aliases.md) for more information. @@ -133,7 +134,7 @@ the `.gitignore`. ## Publishing to a VCS -Once you have a vcs repository (version control system, e.g. git) containing a +Once you have a VCS repository (version control system, e.g. git) containing a `composer.json` file, your library is already composer-installable. In this example we will publish the `acme/hello-world` library on GitHub under `github.com/username/hello-world`. @@ -180,31 +181,32 @@ For more details on how package repositories work and what other types are available, see [Repositories](05-repositories.md). That's all. You can now install the dependencies by running Composer's -`install` command! +[`install`](03-cli.md#install) command! **Recap:** Any git/svn/hg repository containing a `composer.json` can be added to your project by specifying the package repository and declaring the -dependency in the `require` field. +dependency in the [`require`](04-schema.md#require) field. ## Publishing to packagist -Alright, so now you can publish packages. But specifying the vcs repository +Alright, so now you can publish packages. But specifying the VCS repository every time is cumbersome. You don't want to force all your users to do that. The other thing that you may have noticed is that we did not specify a package -repository for `monolog/monolog`. How did that work? The answer is packagist. +repository for `monolog/monolog`. How did that work? The answer is Packagist. [Packagist](https://packagist.org/) is the main package repository for Composer, and it is enabled by default. Anything that is published on -packagist is available automatically through Composer. Since monolog -[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend -on it without having to specify any additional repositories. +Packagist is available automatically through Composer. Since +[Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we +can depend on it without having to specify any additional repositories. If we wanted to share `hello-world` with the world, we would publish it on -packagist as well. Doing so is really easy. +Packagist as well. Doing so is really easy. -You simply hit the big "Submit Package" button and sign up. Then you submit -the URL to your VCS repository, at which point packagist will start crawling -it. Once it is done, your package will be available to anyone. +You simply visit [Packagist](https://packagist.org) and hit the "Submit". This +will prompt you to sign up if you haven't already, and then allows you to +submit the URL to your VCS repository, at which point Packagist will start +crawling it. Once it is done, your package will be available to anyone! ← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) → diff --git a/en-back/03-cli.md b/en-back/03-cli.md index 517c964..b5f066c 100644 --- a/en-back/03-cli.md +++ b/en-back/03-cli.md @@ -1,4 +1,4 @@ -# Command-line interface +# Command-line interface / Commands You've already learned how to use the command-line interface to do some things. This chapter documents all the available commands. @@ -64,27 +64,32 @@ If there is a `composer.lock` file in the current directory, it will use the exact versions from there instead of resolving them. This ensures that everyone using the library will get the same versions of the dependencies. -If there is no `composer.lock` file, composer will create one after dependency +If there is no `composer.lock` file, Composer will create one after dependency resolution. ### Options * **--prefer-source:** There are two ways of downloading a package: `source` - and `dist`. For stable versions composer will use the `dist` by default. + and `dist`. For stable versions Composer will use the `dist` by default. The `source` is a version control repository. If `--prefer-source` is - enabled, composer will install from `source` if there is one. This is + enabled, Composer will install from `source` if there is one. This is useful if you want to make a bugfix to a project and get a local git clone of the dependency directly. -* **--prefer-dist:** Reverse of `--prefer-source`, composer will install +* **--prefer-dist:** Reverse of `--prefer-source`, Composer will install from `dist` if possible. This can speed up installs substantially on build servers and other use cases where you typically do not run updates of the vendors. It is also a way to circumvent problems with git if you do not have a proper setup. +* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*` + requirements and force the installation even if the local machine does not + fulfill these. See also the [`platform`](06-config.md#platform) config option. * **--dry-run:** If you want to run through an installation without actually installing a package, you can use `--dry-run`. This will simulate the installation and show you what would happen. * **--dev:** Install packages listed in `require-dev` (this is the default behavior). -* **--no-dev:** Skip installing packages listed in `require-dev`. +* **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader + generation skips the `autoload-dev` rules. +* **--no-autoloader:** Skips autoloader generation. * **--no-scripts:** Skips execution of scripts defined in `composer.json`. * **--no-plugins:** Disables plugins. * **--no-progress:** Removes the progress display that can mess with some @@ -92,6 +97,8 @@ resolution. * **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster autoloader. This is recommended especially for production, but can take a bit of time to run so it is currently not done by default. +* **--classmap-authoritative (-a):** Autoload classes from the classmap only. + Implicitly enables `--optimize-autoloader`. ## update @@ -121,9 +128,13 @@ php composer.phar update vendor/* * **--prefer-source:** Install packages from `source` when available. * **--prefer-dist:** Install packages from `dist` when available. +* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*` + requirements and force the installation even if the local machine does not + fulfill these. See also the [`platform`](06-config.md#platform) config option. * **--dry-run:** Simulate the command without actually doing anything. * **--dev:** Install packages listed in `require-dev` (this is the default behavior). -* **--no-dev:** Skip installing packages listed in `require-dev`. +* **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader generation skips the `autoload-dev` rules. +* **--no-autoloader:** Skips autoloader generation. * **--no-scripts:** Skips execution of scripts defined in `composer.json`. * **--no-plugins:** Disables plugins. * **--no-progress:** Removes the progress display that can mess with some @@ -131,15 +142,19 @@ php composer.phar update vendor/* * **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster autoloader. This is recommended especially for production, but can take a bit of time to run so it is currently not done by default. +* **--classmap-authoritative (-a):** Autoload classes from the classmap only. + Implicitly enables `--optimize-autoloader`. * **--lock:** Only updates the lock file hash to suppress warning about the lock file being out of date. -* **--with-dependencies** Add also all dependencies of whitelisted packages to the whitelist. - So all packages with their dependencies are updated recursively. +* **--with-dependencies:** Add also all dependencies of whitelisted packages to the whitelist. +* **--prefer-stable:** Prefer stable versions of dependencies. +* **--prefer-lowest:** Prefer lowest versions of dependencies. Useful for testing minimal + versions of requirements, generally used with `--prefer-stable`. ## require The `require` command adds new packages to the `composer.json` file from -the current directory. +the current directory. If no file exists one will be created on the fly. ```sh php composer.phar require @@ -159,12 +174,50 @@ php composer.phar require vendor/package:2.* vendor/package2:dev-master * **--prefer-source:** Install packages from `source` when available. * **--prefer-dist:** Install packages from `dist` when available. +* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*` + requirements and force the installation even if the local machine does not + fulfill these. See also the [`platform`](06-config.md#platform) config option. * **--dev:** Add packages to `require-dev`. * **--no-update:** Disables the automatic update of the dependencies. * **--no-progress:** Removes the progress display that can mess with some terminals or scripts which don't handle backspace characters. -* **--update-with-dependencies** Also update dependencies of the newly +* **--update-no-dev:** Run the dependency update with the `--no-dev` option. +* **--update-with-dependencies:** Also update dependencies of the newly required packages. +* **--sort-packages:** Keep packages sorted in `composer.json`. +* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to + get a faster autoloader. This is recommended especially for production, but + can take a bit of time to run so it is currently not done by default. +* **--classmap-authoritative (-a):** Autoload classes from the classmap only. + Implicitly enables `--optimize-autoloader`. + +## remove + +The `remove` command removes packages from the `composer.json` file from +the current directory. + +```sh +php composer.phar remove vendor/package vendor/package2 +``` + +After removing the requirements, the modified requirements will be +uninstalled. + +### Options +* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*` + requirements and force the installation even if the local machine does not + fulfill these. See also the [`platform`](06-config.md#platform) config option. +* **--dev:** Remove packages from `require-dev`. +* **--no-update:** Disables the automatic update of the dependencies. +* **--no-progress:** Removes the progress display that can mess with some + terminals or scripts which don't handle backspace characters. +* **--update-no-dev:** Run the dependency update with the --no-dev option. +* **--update-with-dependencies:** Also update dependencies of the removed packages. +* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to + get a faster autoloader. This is recommended especially for production, but + can take a bit of time to run so it is currently not done by default. +* **--classmap-authoritative (-a):** Autoload classes from the classmap only. + Implicitly enables `--optimize-autoloader`. ## global @@ -222,8 +275,8 @@ name : monolog/monolog versions : master-dev, 1.0.2, 1.0.1, 1.0.0, 1.0.0-RC1 type : library names : monolog/monolog -source : [git] http://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da -dist : [zip] http://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da +source : [git] https://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da +dist : [zip] https://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da license : MIT autoload @@ -246,6 +299,28 @@ php composer.phar show monolog/monolog 1.0.2 * **--installed (-i):** List the packages that are installed. * **--platform (-p):** List only platform packages (php & extensions). * **--self (-s):** List the root package info. +* **--tree (-t):** List the dependencies as a tree. Only usable when giving a single package name or combined with `-i`. + +## browse / home + +The `browse` (aliased to `home`) opens a package's repository URL or homepage +in your browser. + +### Options + +* **--homepage (-H):** Open the homepage instead of the repository URL. + +## suggests + +Lists all packages suggested by currently installed set of packages. You can +optionally pass one or multiple package names in the format of `vendor/package` +to limit output to suggestions made by those packages only. + +### Options + +* **--no-dev:** Excludes suggestions from `require-dev` packages. +* **--verbose (-v):** Increased verbosity adds suggesting package name and + reason for suggestion. ## depends @@ -256,11 +331,11 @@ should be included in the listing. By default both are used. ```sh php composer.phar depends --link-type=require monolog/monolog -nrk/monolog-fluent -poc/poc -propel/propel -symfony/monolog-bridge -symfony/symfony +nrk/monolog-fluent requires monolog/monolog (~1.8) +poc/poc requires monolog/monolog (^1.6) +propel/propel requires monolog/monolog (1.*) +symfony/monolog-bridge requires monolog/monolog (>=1.2) +symfony/symfony requires monolog/monolog (~1) ``` ### Options @@ -280,7 +355,9 @@ php composer.phar validate ### Options -* **--no-check-all:** Wether or not composer do a complete validation. +* **--no-check-all:** Do not emit a warning if requirements in `composer.json` use unbound version constraints. +* **--no-check-lock:** Do not emit an error if `composer.lock` exists and is not up to date. +* **--no-check-publish:** Do not emit an error if `composer.json` is unsuitable for publishing as a package on Packagist but is otherwise valid. ## status @@ -305,7 +382,7 @@ vendor/seld/jsonlint: ## self-update -To update composer itself to the latest version, just run the `self-update` +To update Composer itself to the latest version, just run the `self-update` command. It will replace your `composer.phar` with the latest version. ```sh @@ -318,7 +395,7 @@ If you would like to instead update to a specific release simply specify it: php composer.phar self-update 1.0.0-alpha7 ``` -If you have installed composer for your entire system (see [global installation](00-intro.md#globally)), +If you have installed Composer for your entire system (see [global installation](00-intro.md#globally)), you may have to run the command with `root` privileges ```sh @@ -328,11 +405,12 @@ sudo composer self-update ### Options * **--rollback (-r):** Rollback to the last version you had installed. -* **--clean-backups:** Delete old backups during an update. This makes the current version of composer the only backup available after the update. +* **--clean-backups:** Delete old backups during an update. This makes the + current version of Composer the only backup available after the update. ## config -The `config` command allows you to edit some basic composer settings in either +The `config` command allows you to edit some basic Composer settings in either the local composer.json file or the global config.json file. ```sh @@ -347,22 +425,23 @@ php composer.phar config --list configuration value. For settings that can take an array of values (like `github-protocols`), more than one setting-value arguments are allowed. -See the [config schema section](04-schema.md#config) for valid configuration -options. +See the [Config](06-config.md) chapter for valid configuration options. ### Options * **--global (-g):** Operate on the global config file located at -`$COMPOSER_HOME/config.json` by default. Without this option, this command -affects the local composer.json file or a file specified by `--file`. + `$COMPOSER_HOME/config.json` by default. Without this option, this command + affects the local composer.json file or a file specified by `--file`. * **--editor (-e):** Open the local composer.json file using in a text editor as -defined by the `EDITOR` env variable. With the `--global` option, this opens -the global config file. + defined by the `EDITOR` env variable. With the `--global` option, this opens + the global config file. * **--unset:** Remove the configuration element named by `setting-key`. * **--list (-l):** Show the list of current config variables. With the `--global` - option this lists the global configuration only. + option this lists the global configuration only. * **--file="..." (-f):** Operate on a specific file instead of composer.json. Note - that this cannot be used in conjunction with the `--global` option. + that this cannot be used in conjunction with the `--global` option. +* **--absolute:** Returns absolute paths when fetching *-dir config values + instead of relative. ### Modifying Repositories @@ -370,13 +449,13 @@ In addition to modifying the config section, the `config` command also supports changes to the repositories section by using it the following way: ```sh -php composer.phar config repositories.foo vcs http://github.com/foo/bar +php composer.phar config repositories.foo vcs https://github.com/foo/bar ``` ## create-project You can use Composer to create new projects from an existing package. This is -the equivalent of doing a git clone/svn checkout followed by a composer install +the equivalent of doing a git clone/svn checkout followed by a "composer install" of the vendors. There are several applications for this: @@ -386,7 +465,7 @@ There are several applications for this: 3. Projects with multiple developers can use this feature to bootstrap the initial application for development. -To create a new project using composer you can use the "create-project" command. +To create a new project using Composer you can use the "create-project" command. Pass it a package name, and the directory to create the project in. You can also provide a version as third argument, otherwise the latest version is used. @@ -419,6 +498,9 @@ By default the command checks for the packages on packagist.org. * **--keep-vcs:** Skip the deletion of the VCS metadata for the created project. This is mostly useful if you run the command in non-interactive mode. +* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*` + requirements and force the installation even if the local machine does not + fulfill these. ## dump-autoload @@ -438,17 +520,33 @@ performance. * **--optimize (-o):** Convert PSR-0/4 autoloading to classmap to get a faster autoloader. This is recommended especially for production, but can take a bit of time to run so it is currently not done by default. +* **--classmap-authoritative (-a):** Autoload classes from the classmap only. + Implicitly enables `--optimize`. * **--no-dev:** Disables autoload-dev rules. +## clear-cache + +Deletes all content from Composer's cache directories. + ## licenses Lists the name, version and license of every package installed. Use `--format=json` to get machine readable output. +### Options + +* **--no-dev:** Remove dev dependencies from the output +* **--format:** Format of the output: text or json (default: "text") + ## run-script +### Options + +* **--no-dev:** Disable dev mode +* **--list:** List user defined scripts + To run [scripts](articles/scripts.md) manually you can use this command, -just give it the script name and optionally --no-dev to disable the dev mode. +just give it the script name and optionally any required arguments. ## diagnose @@ -502,6 +600,8 @@ For example: COMPOSER=composer-other.json php composer.phar install ``` +The generated lock file will use the same name: `composer-other.lock` in this example. + ### COMPOSER_ROOT_VERSION By setting this var you can specify the version of the root package, if it can @@ -509,7 +609,7 @@ not be guessed from VCS info and is not present in `composer.json`. ### COMPOSER_VENDOR_DIR -By setting this var you can make composer install the dependencies into a +By setting this var you can make Composer install the dependencies into a directory other than `vendor`. ### COMPOSER_BIN_DIR @@ -519,7 +619,7 @@ directory to something other than `vendor/bin`. ### http_proxy or HTTP_PROXY -If you are using composer from behind an HTTP proxy, you can use the standard +If you are using Composer from behind an HTTP proxy, you can use the standard `http_proxy` or `HTTP_PROXY` env vars. Simply set it to the URL of your proxy. Many operating systems already set this variable for you. @@ -541,18 +641,18 @@ can also set it to `*` to ignore the proxy for all HTTP requests. ### HTTP_PROXY_REQUEST_FULLURI If you use a proxy but it does not support the request_fulluri flag, then you -should set this env var to `false` or `0` to prevent composer from setting the +should set this env var to `false` or `0` to prevent Composer from setting the request_fulluri option. ### HTTPS_PROXY_REQUEST_FULLURI If you use a proxy but it does not support the request_fulluri flag for HTTPS -requests, then you should set this env var to `false` or `0` to prevent composer +requests, then you should set this env var to `false` or `0` to prevent Composer from setting the request_fulluri option. ### COMPOSER_HOME -The `COMPOSER_HOME` var allows you to change the composer home directory. This +The `COMPOSER_HOME` var allows you to change the Composer home directory. This is a hidden, global (per-user on the machine) directory that is shared between all projects. @@ -566,32 +666,36 @@ You may put a `config.json` file into the location which `COMPOSER_HOME` points to. Composer will merge this configuration with your project's `composer.json` when you run the `install` and `update` commands. -This file allows you to set [configuration](04-schema.md#config) and -[repositories](05-repositories.md) for the user's projects. +This file allows you to set [repositories](05-repositories.md) and +[configuration](06-config.md) for the user's projects. In case global configuration matches _local_ configuration, the _local_ configuration in the project's `composer.json` always wins. ### COMPOSER_CACHE_DIR -The `COMPOSER_CACHE_DIR` var allows you to change the composer cache directory, -which is also configurable via the [`cache-dir`](04-schema.md#config) option. +The `COMPOSER_CACHE_DIR` var allows you to change the Composer cache directory, +which is also configurable via the [`cache-dir`](06-config.md#cache-dir) option. By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and `C:\Users\\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows. ### COMPOSER_PROCESS_TIMEOUT -This env var controls the time composer waits for commands (such as git +This env var controls the time Composer waits for commands (such as git commands) to finish executing. The default value is 300 seconds (5 minutes). ### COMPOSER_DISCARD_CHANGES -This env var controls the discard-changes [config option](04-schema.md#config). +This env var controls the [`discard-changes`](06-config.md#discard-changes) config option. ### COMPOSER_NO_INTERACTION -If set to 1, this env var will make composer behave as if you passed the +If set to 1, this env var will make Composer behave as if you passed the `--no-interaction` flag to every command. This can be set on build boxes/CI. +### COMPOSER_DISABLE_XDEBUG_WARN + +If set to 1, this env disables the warning about having xdebug enabled. + ← [Libraries](02-libraries.md) | [Schema](04-schema.md) → diff --git a/en-back/04-schema.md b/en-back/04-schema.md index 0ce4d4f..023e7b8 100644 --- a/en-back/04-schema.md +++ b/en-back/04-schema.md @@ -1,4 +1,4 @@ -# composer.json +# The composer.json Schema This chapter will explain all of the fields available in `composer.json`. @@ -20,9 +20,6 @@ this is the `config` field. Only the root package can define configuration. The config of dependencies is ignored. This makes the `config` field `root-only`. -If you clone one of those dependencies to work on it, then that package is the -root package. The `composer.json` is identical, but the context is different. - > **Note:** A package can be the root package or not, depending on the context. > For example, if your project depends on the `monolog` library, your project > is the root package. However, if you clone `monolog` from GitHub in order to @@ -54,8 +51,8 @@ The version of the package. In most cases this is not required and should be omitted (see below). This must follow the format of `X.Y.Z` or `vX.Y.Z` with an optional suffix -of `-dev`, `-patch`, `-alpha`, `-beta` or `-RC`. The patch, alpha, beta and -RC suffixes can also be followed by a number. +of `-dev`, `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. +The patch, alpha, beta and RC suffixes can also be followed by a number. Examples: @@ -67,6 +64,7 @@ Examples: - 1.0.0-alpha3 - 1.0.0-beta2 - 1.0.0-RC5 +- v2.0.4-p1 Optional if the package repository can infer the version from somewhere, such as the VCS tag name in the VCS repository. In that case it is also recommended @@ -86,7 +84,7 @@ that needs some special logic, you can define a custom type. This could be a all be specific to certain projects, and they will need to provide an installer capable of installing packages of that type. -Out of the box, composer supports four types: +Out of the box, Composer supports four types: - **library:** This is the default. It will simply copy the files to `vendor`. - **project:** This denotes a project rather than a library. For example @@ -156,7 +154,7 @@ The recommended notation for the most common licenses is (alphabetical): - MIT Optional, but it is highly recommended to supply this. More identifiers are -listed at the [SPDX Open Source License Registry](http://www.spdx.org/licenses/). +listed at the [SPDX Open Source License Registry](https://www.spdx.org/licenses/). For closed-source software, you may use `"proprietary"` as the license identifier. @@ -234,11 +232,12 @@ Various information to get support about the project. Support information includes the following: * **email:** Email address for support. -* **issues:** URL to the Issue Tracker. -* **forum:** URL to the Forum. -* **wiki:** URL to the Wiki. +* **issues:** URL to the issue tracker. +* **forum:** URL to the forum. +* **wiki:** URL to the wiki. * **irc:** IRC channel for support, as irc://server/channel. * **source:** URL to browse or download the sources. +* **docs:** URL to the documentation. An example: @@ -270,7 +269,7 @@ Example: All links are optional fields. -`require` and `require-dev` additionally support stability flags (root-only). +`require` and `require-dev` additionally support stability flags ([root-only](04-schema.md#root-package)). These allow you to further restrict or expand the stability of a package beyond the scope of the [minimum-stability](#minimum-stability) setting. You can apply them to a constraint, or just apply them to an empty constraint if you want to @@ -328,12 +327,26 @@ It is also possible to inline-alias a package constraint so that it matches a constraint that it otherwise would not. For more information [see the aliases article](articles/aliases.md). +`require` and `require-dev` also support references to specific PHP versions +and PHP extensions your project needs to run successfully. + +Example: + +```json +{ + "require" : { + "php" : "^5.5 || ^7.0", + "ext-mbstring": "*" + } +} +``` + #### require Lists packages required by this package. The package will not be installed unless those requirements can be met. -#### require-dev (root-only) +#### require-dev ([root-only](04-schema.md#root-package)) Lists packages required for developing this package, or running tests, etc. The dev requirements of the root package are installed by default. @@ -345,10 +358,10 @@ dependencies from being installed. Lists packages that conflict with this version of this package. They will not be allowed to be installed together with your package. -Note that when specifying ranges like `<1.0, >= 1.1` in a `conflict` link, +Note that when specifying ranges like `<1.0 >=1.1` in a `conflict` link, this will state a conflict with all versions that are less than 1.0 *and* equal or newer than 1.1 at the same time, which is probably not what you want. You -probably want to go for `<1.0 | >= 1.1` in this case. +probably want to go for `<1.0 | >=1.1` in this case. #### replace @@ -375,7 +388,7 @@ useful for common interfaces. A package could depend on some virtual `logger` package, any library that implements this logger interface would simply list it in `provide`. -### suggest +#### suggest Suggested packages that can enhance or work well with this package. These are just informational and are displayed after the package is installed, to give @@ -553,7 +566,27 @@ Example: } ``` -### autoload-dev (root-only) +#### Exclude files from classmaps + +If you want to exclude some files or folders from the classmap you can use the 'exclude-from-classmap' property. +This might be useful to exclude test classes in your live environment, for example, as those will be skipped +from the classmap even when building an optimized autoloader. + +The classmap generator will ignore all files in the paths configured here. The paths are absolute from the package +root directory (i.e. composer.json location), and support `*` to match anything but a slash, and `**` to +match anything. `**` is implicitly added to the end of the paths. + +Example: + +```json +{ + "autoload": { + "exclude-from-classmap": ["/Tests/", "/test/", "/tests/"] + } +} +``` + +### autoload-dev ([root-only](04-schema.md#root-package)) This section allows to define autoload rules for development purposes. @@ -626,7 +659,7 @@ To do that, `autoload` and `target-dir` are defined as follows: Optional. -### minimum-stability (root-only) +### minimum-stability ([root-only](04-schema.md#root-package)) This defines the default behavior for filtering packages by stability. This defaults to `stable`, so if you rely on a `dev` package, you should specify @@ -641,7 +674,7 @@ a given package can be done in `require` or `require-dev` (see Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`, and `stable`. -### prefer-stable (root-only) +### prefer-stable ([root-only](04-schema.md#root-package)) When this is enabled, Composer will prefer more stable packages over unstable ones when finding compatible stable packages is possible. If you require a @@ -650,11 +683,11 @@ selected granted that the minimum-stability allows for it. Use `"prefer-stable": true` to enable. -### repositories (root-only) +### repositories ([root-only](04-schema.md#root-package)) Custom package repositories to use. -By default composer just uses the packagist repository. By specifying +By default Composer just uses the packagist repository. By specifying repositories you can get packages from elsewhere. Repositories are not resolved recursively. You can only add them to your main @@ -663,14 +696,14 @@ ignored. The following repository types are supported: -* **composer:** A composer repository is simply a `packages.json` file served +* **composer:** A Composer repository is simply a `packages.json` file served via the network (HTTP, FTP, SSH), that contains a list of `composer.json` objects with additional `dist` and/or `source` information. The `packages.json` file is loaded using a PHP stream. You can set extra options on that stream using the `options` parameter. * **vcs:** The version control system repository can fetch packages from git, svn and hg repositories. -* **pear:** With this you can import any pear repository into your composer +* **pear:** With this you can import any pear repository into your Composer project. * **package:** If you depend on a project that does not have any support for composer whatsoever you can define the package inline using a `package` @@ -702,7 +735,7 @@ Example: }, { "type": "pear", - "url": "http://pear2.php.net" + "url": "https://pear2.php.net" }, { "type": "package", @@ -714,7 +747,7 @@ Example: "type": "zip" }, "source": { - "url": "http://smarty-php.googlecode.com/svn/", + "url": "https://smarty-php.googlecode.com/svn/", "type": "svn", "reference": "tags/Smarty_3_1_7/distribution/" } @@ -729,80 +762,12 @@ will look from the first to the last repository, and pick the first match. By default Packagist is added last which means that custom repositories can override packages from it. -### config (root-only) +### config ([root-only](04-schema.md#root-package)) -A set of configuration options. It is only used for projects. +A set of configuration options. It is only used for projects. See +[Config](06-config.md) for a description of each individual option. -The following options are supported: - -* **process-timeout:** Defaults to `300`. The duration processes like git clones - can run before Composer assumes they died out. You may need to make this - higher if you have a slow connection or huge vendors. -* **use-include-path:** Defaults to `false`. If true, the Composer autoloader - will also look for classes in the PHP include path. -* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or - `auto`. This option allows you to set the install method Composer will prefer to - use. -* **github-protocols:** Defaults to `["git", "https", "ssh"]`. A list of protocols to - use when cloning from github.com, in priority order. You can reconfigure it to - for example prioritize the https protocol if you are behind a proxy or have somehow - bad performances with the git protocol. -* **github-oauth:** A list of domain names and oauth keys. For example using - `{"github.com": "oauthtoken"}` as the value of this option will use `oauthtoken` - to access private repositories on github and to circumvent the low IP-based - rate limiting of their API. - [Read more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) - on how to get an OAuth token for GitHub. -* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a - different directory if you want to. -* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they - will be symlinked into this directory. -* **cache-dir:** Defaults to `$home/cache` on unix systems and - `C:\Users\\AppData\Local\Composer` on Windows. Stores all the caches - used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home). -* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives - of packages. -* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata - for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`. -* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for - loading VCS repository metadata for the `git`/`hg` types and to speed up installs. -* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all - dist (zip, tar, ..) packages that it downloads. Those are purged after six - months of being unused by default. This option allows you to tweak this - duration (in seconds) or disable it completely by setting it to 0. -* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all - dist (zip, tar, ..) packages that it downloads. When the garbage collection - is periodically ran, this is the maximum size the cache will be able to use. - Older (less used) files will be removed first until the cache fits. -* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader - will not be prepended to existing autoloaders. This is sometimes required to fix - interoperability issues with other autoloaders. -* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for - the generated Composer autoloader. When null a random one will be generated. -* **optimize-autoloader** Defaults to `false`. Always optimize when dumping - the autoloader. -* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in - github mode. This is used for GitHub Enterprise setups. -* **notify-on-install:** Defaults to `true`. Composer allows repositories to - define a notification URL, so that they get notified whenever a package from - that repository is installed. This option allows you to disable that behaviour. -* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or - `"stash"`. This option allows you to set the default style of handling dirty - updates when in non-interactive mode. `true` will always discard changes in - vendors, while `"stash"` will try to stash and reapply. Use this for CI - servers or deploy scripts if you tend to have modified vendors. - -Example: - -```json -{ - "config": { - "bin-dir": "bin" - } -} -``` - -### scripts (root-only) +### scripts ([root-only](04-schema.md#root-package)) Composer allows you to hook into various parts of the installation process through the use of scripts. @@ -858,4 +823,39 @@ The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`, Optional. +### non-feature-branches + +A list of regex patterns of branch names that are non-numeric (e.g. "latest" or something), +that will NOT be handled as feature branches. This is an array of strings. + +If you have non-numeric branch names, for example like "latest", "current", "latest-stable" +or something, that do not look like a version number, then Composer handles such branches +as feature branches. This means it searches for parent branches, that look like a version +or ends at special branches (like master) and the root package version number becomes the +version of the parent branch or at least master or something. + +To handle non-numeric named branches as versions instead of searching for a parent branch +with a valid version or special branch name like master, you can set patterns for branch +names, that should be handled as dev version branches. + +This is really helpful when you have dependencies using "self.version", so that not dev-master, +but the same branch is installed (in the example: latest-testing). + +An example: + +If you have a testing branch, that is heavily maintained during a testing phase and is +deployed to your staging environment, normally "composer show -s" will give you `versions : * dev-master`. + +If you configure `latest-.*` as a pattern for non-feature-branches like this: + +```json +{ + "non-feature-branches": ["latest-.*"] +} +``` + +Then "composer show -s" will give you `versions : * dev-latest-testing`. + +Optional. + ← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) → diff --git a/en-back/05-repositories.md b/en-back/05-repositories.md index 049a051..7541f2a 100644 --- a/en-back/05-repositories.md +++ b/en-back/05-repositories.md @@ -6,7 +6,7 @@ of repositories are available, and how they work. ## Concepts Before we look at the different types of repositories that exist, we need to -understand some of the basic concepts that composer is built on. +understand some of the basic concepts that Composer is built on. ### Package @@ -16,8 +16,8 @@ code, but in theory it could be anything. And it contains a package description which has a name and a version. The name and the version are used to identify the package. -In fact, internally composer sees every version as a separate package. While -this distinction does not matter when you are using composer, it's quite +In fact, internally Composer sees every version as a separate package. While +this distinction does not matter when you are using Composer, it's quite important when you want to change it. In addition to the name and the version, there is useful metadata. The information @@ -103,7 +103,7 @@ It may include any of the other fields specified in the [schema](04-schema.md). #### notify-batch -The `notify-batch` field allows you to specify an URL that will be called +The `notify-batch` field allows you to specify a URL that will be called every time a user installs a package. The URL can be either an absolute path (that will use the same domain as the repository) or a fully qualified URL. @@ -122,7 +122,7 @@ JSON request body: ```json { "downloads": [ - {"name": "monolog/monolog", "version": "1.2.1.0"}, + {"name": "monolog/monolog", "version": "1.2.1.0"} ] } ``` @@ -216,7 +216,7 @@ repository. The `packages.json` file is loaded using a PHP stream. You can set extra options on that stream using the `options` parameter. You can set any valid PHP stream -context option. See [Context options and parameters](http://php.net/manual/en/context.php) +context option. See [Context options and parameters](https://php.net/manual/en/context.php) for more information. ### VCS @@ -234,7 +234,7 @@ project to use the patched version. If the library is on GitHub (this is the case most of the time), you can simply fork it there and push your changes to your fork. After that you update the project's `composer.json`. All you have to do is add your fork as a repository and update the version constraint to -point to your custom branch. For version constraint naming conventions see +point to your custom branch. Your custom branch name must be prefixed with `"dev-"`. For version constraint naming conventions see [Libraries](02-libraries.md) for more information. Example assuming you patched monolog to fix a bug in the `bugfix` branch: @@ -263,6 +263,10 @@ custom repository has priority over packagist. If you want to rename the package, you should do so in the default (often master) branch and not in a feature branch, since the package name is taken from the default branch. +Also note that the override will not work if you change the `name` property +in your forked repository's composer.json file as this needs to match the +original for the override to work. + If other dependencies rely on the package you forked, it is possible to inline-alias it so that it matches a constraint that it otherwise would not. For more information [see the aliases article](articles/aliases.md). @@ -293,8 +297,8 @@ The only requirement is the installation of SSH keys for a git client. Git is not the only version control system supported by the VCS repository. The following are supported: -* **Git:** [git-scm.com](http://git-scm.com) -* **Subversion:** [subversion.apache.org](http://subversion.apache.org) +* **Git:** [git-scm.com](https://git-scm.com) +* **Subversion:** [subversion.apache.org](https://subversion.apache.org) * **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com) To get packages from these systems you need to have their respective clients @@ -312,7 +316,7 @@ should you need to specify one for whatever reason, you can use `git`, `svn` or If you set the `no-api` key to `true` on a github repository it will clone the repository as it would with any other git repository instead of using the -GitHub API. But unlike using the `git` driver directly, composer will still +GitHub API. But unlike using the `git` driver directly, Composer will still attempt to use github's zip files. #### Subversion Options @@ -341,10 +345,41 @@ If you have no branches or tags directory you can disable them entirely by setting the `branches-path` or `tags-path` to `false`. If the package is in a sub-directory, e.g. `/trunk/foo/bar/composer.json` and -`/tags/1.0/foo/bar/composer.json`, then you can make composer access it by +`/tags/1.0/foo/bar/composer.json`, then you can make Composer access it by setting the `"package-path"` option to the sub-directory, in this example it would be `"package-path": "foo/bar/"`. +If you have a private Subversion repository you can save credentials in the +http-basic section of your config (See [Schema](04-schema.md)): + +```json +{ + "http-basic": { + "svn.example.org": { + "username": "username", + "password": "password" + } + } +} +``` + +If your Subversion client is configured to store credentials by default these +credentials will be saved for the current user and existing saved credentials +for this server will be overwritten. To change this behavior by setting the +`"svn-cache-credentials"` option in your repository configuration: + +```json +{ + "repositories": [ + { + "type": "vcs", + "url": "http://svn.example.org/projectA/", + "svn-cache-credentials": false + } + ] +} +``` + ### PEAR It is possible to install packages from any PEAR channel by using the `pear` @@ -358,7 +393,7 @@ Example using `pear2.php.net`: "repositories": [ { "type": "pear", - "url": "http://pear2.php.net" + "url": "https://pear2.php.net" } ], "require": { @@ -431,7 +466,7 @@ and `IntermediatePackage` from a Github repository: ### Package -If you want to use a project that does not support composer through any of the +If you want to use a project that does not support Composer through any of the means above, you still can define the package yourself by using a `package` repository. @@ -486,7 +521,7 @@ Typically you would leave the source part off, as you don't really need it. While you will probably want to put your packages on packagist most of the time, there are some use cases for hosting your own repository. -* **Private company packages:** If you are part of a company that uses composer +* **Private company packages:** If you are part of a company that uses Composer for their packages internally, you might want to keep those packages private. * **Separate ecosystem:** If you have a project which has its own ecosystem, @@ -494,7 +529,7 @@ there are some use cases for hosting your own repository. might want to keep them separate to packagist. An example of this would be wordpress plugins. -For hosting your own packages, a native `composer` type of repository is +For hosting your own packages, a native `composer` type of repository is recommended, which provides the best performance. There are a few tools that can help you create a `composer` repository. @@ -502,19 +537,22 @@ There are a few tools that can help you create a `composer` repository. ### Packagist The underlying application used by packagist is open source. This means that you -can just install your own copy of packagist, re-brand, and use it. It's really -quite straight-forward to do. However due to its size and complexity, for most -small and medium sized companies willing to track a few packages will be better -off using Satis. +can technically install your own copy of packagist. However it is not a +supported use case and changes will happen without caring for third parties +using the code. Packagist is a Symfony2 application, and it is [available on -GitHub](https://github.com/composer/packagist). It uses composer internally and -acts as a proxy between VCS repositories and the composer users. It holds a list -of all VCS packages, periodically re-crawls them, and exposes them as a composer +GitHub](https://github.com/composer/packagist). It uses Composer internally and +acts as a proxy between VCS repositories and the Composer users. It holds a list +of all VCS packages, periodically re-crawls them, and exposes them as a Composer repository. -To set your own copy, simply follow the instructions from the [packagist -github repository](https://github.com/composer/packagist). +### Toran Proxy + +[Toran Proxy](https://toranproxy.com/) is a web app much like Packagist but +providing private package hosting as well as mirroring/proxying of GitHub and +packagist.org. Check its homepage and the [Satis/Toran Proxy article](articles/handling-private-packages-with-satis.md) +for more information. ### Satis @@ -568,6 +606,49 @@ imported. When an archive with a newer version is added in the artifact folder and you run `update`, that version will be imported as well and Composer will update to the latest version. +### Path + +In addition to the artifact repository, you can use the path one, which allows +you to depend on a relative directory. This can be especially useful when dealing +with monolith repositories. + +For instance, if you have the following directory structure in your repository: +``` +- apps +\_ my-app + \_ composer.json +- packages +\_ my-package + \_ composer.json +``` + +Then, to add the package `my/package` as a dependency, in your `apps/my-app/composer.json` +file, you can use the following configuration: + +```json +{ + "repositories": [ + { + "type": "path", + "url": "../../packages/my-package" + } + ], + "require": { + "my/package": "*" + } +} +``` + +The local package will be symlinked if possible, in which case the output in +the console will read `Symlinked from ../../packages/my-package`. If symlinking +is _not_ possible the package will be copied. In that case, the console will +output `Mirrored from ../../packages/my-package`. + +Instead of using a relative path, an absolute path can also be used. + +> **Note:** Repository paths can also contain wildcards like ``*`` and ``?``. +> For details, see the [PHP glob function](http://php.net/glob). + ## Disabling Packagist You can disable the default Packagist repository by adding this to your @@ -583,4 +664,4 @@ You can disable the default Packagist repository by adding this to your } ``` -← [Schema](04-schema.md) | [Community](06-community.md) → +← [Schema](04-schema.md) | [Config](06-config.md) → diff --git a/en-back/06-config.md b/en-back/06-config.md new file mode 100644 index 0000000..ec1203d --- /dev/null +++ b/en-back/06-config.md @@ -0,0 +1,189 @@ +# Config + +This chapter will describe the `config` section of the `composer.json` +[schema](04-schema.md). + +## process-timeout + +Defaults to `300`. The duration processes like git clones can run before +Composer assumes they died out. You may need to make this higher if you have a +slow connection or huge vendors. + +## use-include-path + +Defaults to `false`. If `true`, the Composer autoloader will also look for classes +in the PHP include path. + +## preferred-install + +Defaults to `auto` and can be any of `source`, `dist` or `auto`. This option +allows you to set the install method Composer will prefer to use. + +## store-auths + +What to do after prompting for authentication, one of: `true` (always store), +`false` (do not store) and `"prompt"` (ask every time), defaults to `"prompt"`. + +## github-protocols + +Defaults to `["git", "https", "ssh"]`. A list of protocols to use when cloning +from github.com, in priority order. You can reconfigure it to for example +prioritize the https protocol if you are behind a proxy or have somehow bad +performances with the git protocol. + +## github-oauth + +A list of domain names and oauth keys. For example using `{"github.com": +"oauthtoken"}` as the value of this option will use `oauthtoken` to access +private repositories on github and to circumvent the low IP-based rate limiting +of their API. [Read +more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) on how to get +an OAuth token for GitHub. + +## http-basic + +A list of domain names and username/passwords to authenticate against them. For +example using `{"example.org": {"username": "alice", "password": "foo"}` as the +value of this option will let Composer authenticate against example.org. + +> **Note:** Authentication-related config options like `http-basic` and +> `github-oauth` can also be specified inside a `auth.json` file that goes +> besides your `composer.json`. That way you can gitignore it and every +> developer can place their own credentials in there. + +## platform + +Lets you fake platform packages (PHP and extensions) so that you can emulate a +production env or define your target platform in the config. Example: `{"php": +"5.4", "ext-something": "4.0"}`. + +## vendor-dir + +Defaults to `vendor`. You can install dependencies into a different directory if +you want to. `$HOME` and `~` will be replaced by your home directory's path in +vendor-dir and all `*-dir` options below. + +## bin-dir + +Defaults to `vendor/bin`. If a project includes binaries, they will be symlinked +into this directory. + +## cache-dir + +Defaults to `$COMPOSER_HOME/cache` on unix systems and +`C:\Users\\AppData\Local\Composer` on Windows. Stores all the caches used +by Composer. See also [COMPOSER_HOME](03-cli.md#composer-home). + +## cache-files-dir + +Defaults to `$cache-dir/files`. Stores the zip archives of packages. + +## cache-repo-dir + +Defaults to `$cache-dir/repo`. Stores repository metadata for the `composer` +type and the VCS repos of type `svn`, `github` and `bitbucket`. + +## cache-vcs-dir + +Defaults to `$cache-dir/vcs`. Stores VCS clones for loading VCS repository +metadata for the `git`/`hg` types and to speed up installs. + +## cache-files-ttl + +Defaults to `15552000` (6 months). Composer caches all dist (zip, tar, ..) +packages that it downloads. Those are purged after six months of being unused by +default. This option allows you to tweak this duration (in seconds) or disable +it completely by setting it to 0. + +## cache-files-maxsize + +Defaults to `300MiB`. Composer caches all dist (zip, tar, ..) packages that it +downloads. When the garbage collection is periodically ran, this is the maximum +size the cache will be able to use. Older (less used) files will be removed +first until the cache fits. + +## bin-compat + +Defaults to `auto`. Determines the compatibility of the binaries to be installed. +If it is `auto` then Composer only installs .bat proxy files when on Windows. If +set to `full` then both .bat files for Windows and scripts for Unix-based +operating systems will be installed for each binary. This is mainly useful if you +run Composer inside a linux VM but still want the .bat proxies available for use +in the Windows host OS. + +## prepend-autoloader + +Defaults to `true`. If `false`, the Composer autoloader will not be prepended to +existing autoloaders. This is sometimes required to fix interoperability issues +with other autoloaders. + +## autoloader-suffix + +Defaults to `null`. String to be used as a suffix for the generated Composer +autoloader. When null a random one will be generated. + +## optimize-autoloader + +Defaults to `false`. If `true`, always optimize when dumping the autoloader. + +## sort-packages + +Defaults to `false`. If `true`, the `require` command keeps packages sorted +by name in `composer.json` when adding a new package. + +## classmap-authoritative + +Defaults to `false`. If `true`, the Composer autoloader will only load classes +from the classmap. Implies `optimize-autoloader`. + +## github-domains + +Defaults to `["github.com"]`. A list of domains to use in github mode. This is +used for GitHub Enterprise setups. + +## github-expose-hostname + +Defaults to `true`. If `false`, the OAuth tokens created to access the +github API will have a date instead of the machine hostname. + +## gitlab-domains + +Defaults to `["gitlab.com"]`. A list of domains of GitLab servers. +This is used if you use the `gitlab` repository type. + +## notify-on-install + +Defaults to `true`. Composer allows repositories to define a notification URL, +so that they get notified whenever a package from that repository is installed. +This option allows you to disable that behaviour. + +## discard-changes + +Defaults to `false` and can be any of `true`, `false` or `"stash"`. This option +allows you to set the default style of handling dirty updates when in +non-interactive mode. `true` will always discard changes in vendors, while +`"stash"` will try to stash and reapply. Use this for CI servers or deploy +scripts if you tend to have modified vendors. + +## archive-format + +Defaults to `tar`. Composer allows you to add a default archive format when the +workflow needs to create a dedicated archiving format. + +## archive-dir + +Defaults to `.`. Composer allows you to add a default archive directory when the +workflow needs to create a dedicated archiving format. Or for easier development +between modules. + +Example: + +```json +{ + "config": { + "archive-dir": "/home/user/.composer/repo" + } +} +``` + +← [Repositories](05-repositories.md) | [Community](07-community.md) → diff --git a/en-back/06-community.md b/en-back/07-community.md similarity index 54% rename from en-back/06-community.md rename to en-back/07-community.md index 10ef31b..d5bfc55 100644 --- a/en-back/06-community.md +++ b/en-back/07-community.md @@ -1,12 +1,14 @@ # Community -There are many people using composer already, and quite a few of them are +There are many people using Composer already, and quite a few of them are contributing. ## Contributing -If you would like to contribute to composer, please read the -[README](https://github.com/composer/composer). +If you would like to contribute to Composer, please read the +[README](https://github.com/composer/composer) and +[CONTRIBUTING](https://github.com//composer/composer/blob/master/CONTRIBUTING.md) +documents. The most important guidelines are described as follows: @@ -17,18 +19,17 @@ The most important guidelines are described as follows: > Fork the project, create a feature branch, and send us a pull request. > > To ensure a consistent code base, you should make sure the code follows -> the [Coding Standards](http://symfony.com/doc/2.0/contributing/code/standards.html) -> which we borrowed from Symfony. +> the [PSR-2 Coding Standards](http://www.php-fig.org/psr/psr-2/). ## IRC / mailing list -Mailing lists for [user support](http://groups.google.com/group/composer-users) and -[development](http://groups.google.com/group/composer-dev). +Mailing lists for [user support](https://groups.google.com/group/composer-users) and +[development](https://groups.google.com/group/composer-dev). IRC channels are on irc.freenode.org: [#composer](irc://irc.freenode.org/composer) for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development. Stack Overflow has a growing collection of -[Composer related questions](http://stackoverflow.com/questions/tagged/composer-php). +[Composer related questions](https://stackoverflow.com/questions/tagged/composer-php). -← [Repositories](05-repositories.md) +← [Config](06-config.md) -- 2.46.2 From 94513ae9fbaaba03669392bc5f57b39703242a44 Mon Sep 17 00:00:00 2001 From: dongjiawei Date: Thu, 7 Jan 2016 23:55:52 +0800 Subject: [PATCH 117/125] new basic usage --- cn-introduction/01-basic-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index e89a9fc..c37f7d5 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -227,7 +227,7 @@ $loader = require 'vendor/autoload.php'; $loader->add('Acme\\Test\\', __DIR__); ``` -除了 PSR-4 自动加载，classmap 也是支持的。这允许类被自动加载，即使不符合 PSR-4 规范。详细请查看 [自动加载-参考](04-schema.md#autoload)。 +除了 PSR-4 自动加载，Composer 同时支持PSR-0、classmap 和 files自动加载。详细请查看 [自动加载-参考](04-schema.md#autoload)。 > **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_*.php` 文件，它返回一个关联数组，你可以通过这个关联数组配置自己的 autoloader。 -- 2.46.2 From 5d5a84ef6bb2edaf446d125582e2809573a03d87 Mon Sep 17 00:00:00 2001 From: zhaomingliang <248278242@qq.com> Date: Mon, 4 Apr 2016 00:12:48 +0800 Subject: [PATCH 118/125] Update 01-basic-usage.md --- cn-introduction/01-basic-usage.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index b097c02..328d70c 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -65,7 +65,15 @@ php composer.phar ``` 你可以看到， `require` 需要一个 **包名称** （例如 `monolog/monolog`） 映射到 **包版本** （例如 `1.0.*`） 的对象。 - +同时你还可以声明项目所需的环境版本支持（例下） +```json +{ + "require" : { + "php" : "^5.5 || ^7.0", + "ext-mbstring": "*" + } +} +``` ### 包名称 -- 2.46.2 From 5c96663d3c37990c45bcee701c0492d0bf3d10bc Mon Sep 17 00:00:00 2001 From: zhaomingliang <248278242@qq.com> Date: Mon, 4 Apr 2016 00:38:27 +0800 Subject: [PATCH 119/125] Update 01-basic-usage.md --- cn-introduction/01-basic-usage.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index 328d70c..930a1be 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -65,7 +65,7 @@ php composer.phar ``` 你可以看到， `require` 需要一个 **包名称** （例如 `monolog/monolog`） 映射到 **包版本** （例如 `1.0.*`） 的对象。 -同时你还可以声明项目所需的环境版本支持（例下） +同时你还可以声明需要开发支持特定版本的PHP和PHP扩展你的项目需要成功运行的参考（例下） ```json { "require" : { @@ -122,6 +122,12 @@ php composer.phar ~1.2 这对于遵循语义化版本号的项目非常有用。~1.2相当于>=1.2,<2.0。想要了解更多，请阅读下一小节。 + + + 插入符号 + ^1.2.3 + ^操作符的行为很相似，但它更接近于语义，并将永远让不间断更新。例如^1.2.3相当于>=1.2.3<2.0.0如没有释放到2.0应该打破向后兼容性。同时也可以使用限制版本，如^0.3为>=0.3.0<0.4.0 。 + -- 2.46.2 From b9f6d6f8d8bba3426c59071635f4cfb4a0fdcc34 Mon Sep 17 00:00:00 2001 From: Dwwwwww Date: Sun, 11 Dec 2016 10:02:28 +0800 Subject: [PATCH 120/125] =?UTF-8?q?replace=20'=E4=B8=8A=E8=AF=89'=20with?= =?UTF-8?q?=20'=E4=B8=8A=E8=BF=B0'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fix a spelling mistake --- cn-introduction/00-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/00-intro.md b/cn-introduction/00-intro.md index 23e9f9a..0e351c6 100644 --- a/cn-introduction/00-intro.md +++ b/cn-introduction/00-intro.md @@ -105,7 +105,7 @@ curl -sS https://getcomposer.org/installer | php mv composer.phar /usr/local/bin/composer ``` -> **注意：** 如果上诉命令因为权限执行失败， +> **注意：** 如果上述命令因为权限执行失败， > 请使用 sudo 再次尝试运行 `mv` 那行命令。 现在只需要运行 `composer` 命令就可以使用 Composer 而不需要输入 `php composer.phar`。 -- 2.46.2 From 28a09b467bbd62db0e582b5d4f556d2b653e9df1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E6=9E=97?= Date: Sun, 12 Mar 2017 16:48:22 +0800 Subject: [PATCH 121/125] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E4=B8=80=E4=B8=AA?= =?UTF-8?q?=E5=AD=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cn-introduction/01-basic-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index c986b9a..6f16e1b 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -166,7 +166,7 @@ php composer.phar install ## `composer.lock` - 锁文件 -在安装依赖后，Composer 将把安装时确切的版本号列表写入 `composer.lock` 文件。这将锁定改项目的特定版本。 +在安装依赖后，Composer 将把安装时确切的版本号列表写入 `composer.lock` 文件。这将锁定该项目的特定版本。 **请提交你应用程序的 `composer.lock` （包括 `composer.json`）到你的版本库中** -- 2.46.2 From 9571be7f7604afb688387e2b837f2d7a53a408c8 Mon Sep 17 00:00:00 2001 From: primex <> Date: Mon, 12 Mar 2018 19:06:52 +0800 Subject: [PATCH 122/125] autoload addPsr4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 自己试验发现有误，参照了官方原版发现这里应该是 addPsr4 --- cn-introduction/01-basic-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/01-basic-usage.md b/cn-introduction/01-basic-usage.md index c986b9a..090c27a 100644 --- a/cn-introduction/01-basic-usage.md +++ b/cn-introduction/01-basic-usage.md @@ -238,7 +238,7 @@ Composer 将注册一个 [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader ```php $loader = require 'vendor/autoload.php'; -$loader->add('Acme\\Test\\', __DIR__); +$loader->addPsr4('Acme\\Test\\', __DIR__); ``` 除了 PSR-4 自动加载，Composer 同时支持PSR-0、classmap 和 files自动加载。详细请查看 [自动加载-参考](04-schema.md#autoload)。 -- 2.46.2 From 6d9a3207d5ae7d7712f22ef2151a00d1fe2e0262 Mon Sep 17 00:00:00 2001 From: FiveSay Date: Mon, 19 Mar 2018 12:09:50 +0800 Subject: [PATCH 123/125] update --- README.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index dff0c4a..fb80c38 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ Composer 中文文档 --- - 希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。 -- 部分内容现阶段无法译全，已在 [issues](https://github.com/5-say/composer-doc-cn/issues) 中列出，如果能够收到您的宝贵建议，必将感激不尽。 -- [翻译术语对照表](/glossary.md) +- 新版本文档翻译缓慢进行中，详见 [1.6分支](https://github.com/5-say/composer-doc-cn/blob/1.6/README.md) +- 当前文档基本不影响新版 Composer 的使用，新文档在结构以及章节内容上做了比较大的调整，针对性的翻译会逐步完善。 - [中文翻译贡献者名单](/contributors.md) --- @@ -44,14 +44,6 @@ Solving problems - [为什么说“比较符”和“通配符”相结合的版本约束是坏主意？](/cn-introduction/faqs/why-are-version-constraints-combining-comparisons-and-wildcards-a-bad-idea.md) - [为什么 Composer 不递归加载储存库？](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md) -## PDF 文档 - -整个文档也可以作为 [PDF 下载](http://getcomposer.org/book.pdf)。 - -## API 文档 - -如果你需要在工作中使用 composer 作为库的管理，你或许也想看看 [API 文档](http://getcomposer.org/apidoc/master/index.html)。 - ## 相关文章推荐 - [PHP 开发者该知道的5个 Composer 小技巧](http://segmentfault.com/a/1190000000355928) -- 2.46.2 From 0d447fbe4f7d332bbd71c7e9562a9eee2434559c Mon Sep 17 00:00:00 2001 From: nobody <1035948193@qq.com> Date: Wed, 12 Dec 2018 10:00:11 +0800 Subject: [PATCH 124/125] Update 03-cli.md --- cn-introduction/03-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cn-introduction/03-cli.md b/cn-introduction/03-cli.md index 72f8da4..bc28218 100644 --- a/cn-introduction/03-cli.md +++ b/cn-introduction/03-cli.md @@ -102,7 +102,7 @@ php composer.phar init php composer.phar install ``` -如果当前目录下存在 `composer.lock` 文件，它会从此文件读取依赖版本，而不是根据 `composer.json` 文件去获取依赖。这确保了该库的每个使用者都能得到相同的依赖版本。 +如果当前目录存在 `composer.lock` 文件，它会从此文件读取依赖版本，而不是根据 `composer.json` 文件去获取依赖。这确保了该库的每个使用者都能得到相同的依赖版本。 如果没有 `composer.lock` 文件，composer 将在处理完依赖关系后创建它。 -- 2.46.2 From ad5f44a149994c2197c706c60b07751b43af668f Mon Sep 17 00:00:00 2001 From: YuCheng Hu Date: Mon, 8 Apr 2024 18:32:30 -0400 Subject: [PATCH 125/125] =?UTF-8?q?=E4=BB=8E=E5=85=B6=E4=BB=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E4=B8=AD=E6=8B=B7=E8=B4=9D=E9=A1=B9=E7=9B=AE=E7=BB=93?= =?UTF-8?q?=E6=9E=84=EF=BC=8C=E5=85=88=E5=AE=8C=E6=88=90=E7=AC=AC=E4=B8=80?= =?UTF-8?q?=E6=AD=A5=E7=9A=84=E6=8F=90=E4=BA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- composer-docs.iml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 composer-docs.iml diff --git a/composer-docs.iml b/composer-docs.iml new file mode 100644 index 0000000..8021953 --- /dev/null +++ b/composer-docs.iml @@ -0,0 +1,9 @@ + + + + + + + + + \ No newline at end of file -- 2.46.2