根据历史文件中的内容拷贝 #1
|
|
@ -1,392 +1 @@
|
|||
### Gradle ###
|
||||
.gradle
|
||||
build/
|
||||
|
||||
# Ignore Gradle GUI config
|
||||
gradle-app.setting
|
||||
|
||||
# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
|
||||
!gradle-wrapper.jar
|
||||
|
||||
# Cache of project
|
||||
.gradletasknamecache
|
||||
|
||||
# # Work around https://youtrack.jetbrains.com/issue/IDEA-116898
|
||||
# gradle/wrapper/gradle-wrapper.properties
|
||||
|
||||
### Gradle Patch ###
|
||||
**/build/
|
||||
|
||||
### Intellij ###
|
||||
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm
|
||||
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
|
||||
|
||||
# User-specific stuff
|
||||
.idea/**/workspace.xml
|
||||
.idea/**/tasks.xml
|
||||
.idea/**/usage.statistics.xml
|
||||
.idea/**/dictionaries
|
||||
.idea/**/shelf
|
||||
|
||||
# Generated files
|
||||
.idea/**/contentModel.xml
|
||||
|
||||
# Sensitive or high-churn files
|
||||
.idea/**/dataSources/
|
||||
.idea/**/dataSources.ids
|
||||
.idea/**/dataSources.local.xml
|
||||
.idea/**/sqlDataSources.xml
|
||||
.idea/**/dynamic.xml
|
||||
.idea/**/uiDesigner.xml
|
||||
.idea/**/dbnavigator.xml
|
||||
|
||||
# Gradle
|
||||
.idea/**/gradle.xml
|
||||
.idea/**/libraries
|
||||
|
||||
# Gradle and Maven with auto-import
|
||||
# When using Gradle or Maven with auto-import, you should exclude module files,
|
||||
# since they will be recreated, and may cause churn. Uncomment if using
|
||||
# auto-import.
|
||||
# .idea/modules.xml
|
||||
# .idea/*.iml
|
||||
# .idea/modules
|
||||
# *.iml
|
||||
# *.ipr
|
||||
|
||||
# CMake
|
||||
cmake-build-*/
|
||||
|
||||
# Mongo Explorer plugin
|
||||
.idea/**/mongoSettings.xml
|
||||
|
||||
# File-based project format
|
||||
*.iws
|
||||
|
||||
# IntelliJ
|
||||
out/
|
||||
|
||||
# mpeltonen/sbt-idea plugin
|
||||
.idea_modules/
|
||||
|
||||
# JIRA plugin
|
||||
atlassian-ide-plugin.xml
|
||||
|
||||
# Cursive Clojure plugin
|
||||
.idea/replstate.xml
|
||||
|
||||
# Crashlytics plugin (for Android Studio and IntelliJ)
|
||||
com_crashlytics_export_strings.xml
|
||||
crashlytics.properties
|
||||
crashlytics-build.properties
|
||||
fabric.properties
|
||||
|
||||
# Editor-based Rest Client
|
||||
.idea/httpRequests
|
||||
|
||||
# Android studio 3.1+ serialized cache file
|
||||
.idea/caches/build_file_checksums.ser
|
||||
|
||||
### Intellij Patch ###
|
||||
# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
|
||||
|
||||
# *.iml
|
||||
# modules.xml
|
||||
# .idea/misc.xml
|
||||
# *.ipr
|
||||
|
||||
# Sonarlint plugin
|
||||
.idea/sonarlint
|
||||
|
||||
|
||||
### Intellij+iml ###
|
||||
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm
|
||||
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
|
||||
|
||||
# User-specific stuff
|
||||
.idea/**/workspace.xml
|
||||
.idea/**/tasks.xml
|
||||
.idea/**/usage.statistics.xml
|
||||
.idea/**/dictionaries
|
||||
.idea/**/shelf
|
||||
|
||||
# Generated files
|
||||
.idea/**/contentModel.xml
|
||||
|
||||
# Sensitive or high-churn files
|
||||
.idea/**/dataSources/
|
||||
.idea/**/dataSources.ids
|
||||
.idea/**/dataSources.local.xml
|
||||
.idea/**/sqlDataSources.xml
|
||||
.idea/**/dynamic.xml
|
||||
.idea/**/uiDesigner.xml
|
||||
.idea/**/dbnavigator.xml
|
||||
|
||||
# Gradle
|
||||
.idea/**/gradle.xml
|
||||
.idea/**/libraries
|
||||
|
||||
# Gradle and Maven with auto-import
|
||||
# When using Gradle or Maven with auto-import, you should exclude module files,
|
||||
# since they will be recreated, and may cause churn. Uncomment if using
|
||||
# auto-import.
|
||||
# .idea/modules.xml
|
||||
# .idea/*.iml
|
||||
# .idea/modules
|
||||
# *.iml
|
||||
# *.ipr
|
||||
|
||||
# CMake
|
||||
cmake-build-*/
|
||||
|
||||
# Mongo Explorer plugin
|
||||
.idea/**/mongoSettings.xml
|
||||
|
||||
# File-based project format
|
||||
*.iws
|
||||
|
||||
# IntelliJ
|
||||
out/
|
||||
|
||||
# mpeltonen/sbt-idea plugin
|
||||
.idea_modules/
|
||||
|
||||
# JIRA plugin
|
||||
atlassian-ide-plugin.xml
|
||||
|
||||
# Cursive Clojure plugin
|
||||
.idea/replstate.xml
|
||||
|
||||
# Crashlytics plugin (for Android Studio and IntelliJ)
|
||||
com_crashlytics_export_strings.xml
|
||||
crashlytics.properties
|
||||
crashlytics-build.properties
|
||||
fabric.properties
|
||||
|
||||
# Editor-based Rest Client
|
||||
.idea/httpRequests
|
||||
|
||||
# Android studio 3.1+ serialized cache file
|
||||
.idea/caches/build_file_checksums.ser
|
||||
|
||||
### Intellij+iml Patch ###
|
||||
# Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023
|
||||
|
||||
*.iml
|
||||
modules.xml
|
||||
.idea/misc.xml
|
||||
*.ipr
|
||||
|
||||
### Maven ###
|
||||
target/
|
||||
pom.xml.tag
|
||||
pom.xml.releaseBackup
|
||||
pom.xml.versionsBackup
|
||||
pom.xml.next
|
||||
release.properties
|
||||
dependency-reduced-pom.xml
|
||||
buildNumber.properties
|
||||
.mvn/timing.properties
|
||||
.mvn/wrapper/maven-wrapper.jar
|
||||
.flattened-pom.xml
|
||||
|
||||
# CMake
|
||||
cmake-build-*/
|
||||
|
||||
# Mongo Explorer plugin
|
||||
.idea/**/mongoSettings.xml
|
||||
|
||||
# File-based project format
|
||||
*.iws
|
||||
|
||||
# IntelliJ
|
||||
out/
|
||||
|
||||
# mpeltonen/sbt-idea plugin
|
||||
.idea_modules/
|
||||
|
||||
# JIRA plugin
|
||||
atlassian-ide-plugin.xml
|
||||
|
||||
# Cursive Clojure plugin
|
||||
.idea/replstate.xml
|
||||
|
||||
# Crashlytics plugin (for Android Studio and IntelliJ)
|
||||
com_crashlytics_export_strings.xml
|
||||
crashlytics.properties
|
||||
crashlytics-build.properties
|
||||
fabric.properties
|
||||
|
||||
# Editor-based Rest Client
|
||||
.idea/httpRequests
|
||||
|
||||
# Android studio 3.1+ serialized cache file
|
||||
.idea/caches/build_file_checksums.ser
|
||||
|
||||
### Intellij Patch ###
|
||||
# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
|
||||
|
||||
# *.iml
|
||||
# modules.xml
|
||||
# .idea/misc.xml
|
||||
# *.ipr
|
||||
|
||||
# Sonarlint plugin
|
||||
.idea/sonarlint
|
||||
|
||||
### Node ###
|
||||
# Logs
|
||||
logs
|
||||
*.log
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
lerna-debug.log*
|
||||
.pnpm-debug.log*
|
||||
|
||||
# Diagnostic reports (https://nodejs.org/api/report.html)
|
||||
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
|
||||
|
||||
# Runtime data
|
||||
pids
|
||||
*.pid
|
||||
*.seed
|
||||
*.pid.lock
|
||||
|
||||
# Directory for instrumented libs generated by jscoverage/JSCover
|
||||
lib-cov
|
||||
|
||||
# Coverage directory used by tools like istanbul
|
||||
coverage
|
||||
*.lcov
|
||||
|
||||
# nyc test coverage
|
||||
.nyc_output
|
||||
|
||||
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
|
||||
.grunt
|
||||
|
||||
# Bower dependency directory (https://bower.io/)
|
||||
bower_components
|
||||
|
||||
# node-waf configuration
|
||||
.lock-wscript
|
||||
|
||||
# Compiled binary addons (https://nodejs.org/api/addons.html)
|
||||
build/Release
|
||||
|
||||
# Dependency directories
|
||||
node_modules/
|
||||
jspm_packages/
|
||||
|
||||
# Snowpack dependency directory (https://snowpack.dev/)
|
||||
web_modules/
|
||||
|
||||
# TypeScript cache
|
||||
*.tsbuildinfo
|
||||
|
||||
# Optional npm cache directory
|
||||
.npm
|
||||
|
||||
# Optional eslint cache
|
||||
.eslintcache
|
||||
|
||||
# Optional stylelint cache
|
||||
.stylelintcache
|
||||
|
||||
# Microbundle cache
|
||||
.rpt2_cache/
|
||||
.rts2_cache_cjs/
|
||||
.rts2_cache_es/
|
||||
.rts2_cache_umd/
|
||||
|
||||
# Optional REPL history
|
||||
.node_repl_history
|
||||
|
||||
# Output of 'npm pack'
|
||||
*.tgz
|
||||
|
||||
# Yarn Integrity file
|
||||
.yarn-integrity
|
||||
|
||||
# dotenv environment variable files
|
||||
.env
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
.env.local
|
||||
|
||||
# parcel-bundler cache (https://parceljs.org/)
|
||||
.cache
|
||||
.parcel-cache
|
||||
|
||||
# Next.js build output
|
||||
.next
|
||||
out
|
||||
|
||||
# Nuxt.js build / generate output
|
||||
.nuxt
|
||||
dist
|
||||
|
||||
# Gatsby files
|
||||
.cache/
|
||||
# Comment in the public line in if your project uses Gatsby and not Next.js
|
||||
# https://nextjs.org/blog/next-9-1#public-directory-support
|
||||
# public
|
||||
|
||||
# vuepress build output
|
||||
.vuepress/dist
|
||||
|
||||
# vuepress v2.x temp and cache directory
|
||||
.temp
|
||||
|
||||
# Docusaurus cache and generated files
|
||||
.docusaurus
|
||||
|
||||
# Serverless directories
|
||||
.serverless/
|
||||
|
||||
# FuseBox cache
|
||||
.fusebox/
|
||||
|
||||
# DynamoDB Local files
|
||||
.dynamodb/
|
||||
|
||||
# TernJS port file
|
||||
.tern-port
|
||||
|
||||
# Stores VSCode versions used for testing VSCode extensions
|
||||
.vscode-test
|
||||
|
||||
# yarn v2
|
||||
.yarn/cache
|
||||
.yarn/unplugged
|
||||
.yarn/build-state.yml
|
||||
.yarn/install-state.gz
|
||||
.pnp.*
|
||||
|
||||
### Node Patch ###
|
||||
# Serverless Webpack directories
|
||||
.webpack/
|
||||
|
||||
# Optional stylelint cache
|
||||
|
||||
# SvelteKit build / generate output
|
||||
.svelte-kit
|
||||
|
||||
|
||||
### yarn ###
|
||||
|
||||
.yarn/*
|
||||
!.yarn/releases
|
||||
!.yarn/patches
|
||||
!.yarn/plugins
|
||||
!.yarn/sdks
|
||||
!.yarn/versions
|
||||
|
||||
# if you are NOT using Zero-installs, then:
|
||||
# comment the following lines
|
||||
!.yarn/cache
|
||||
|
||||
# and uncomment the following lines
|
||||
# .pnp.*
|
||||
.idea/
|
||||
|
|
|
|||
50
README.md
50
README.md
|
|
@ -1,3 +1,49 @@
|
|||
# Composer Docs
|
||||
composer-doc-cn
|
||||
===============
|
||||
|
||||
Composer 中文文档
|
||||
Composer 中文文档
|
||||
|
||||
---
|
||||
|
||||
- 希望更多的朋友能够参与此文档的翻译、勘误（您可以 Fork 本项目，并提交 Pull Request）。
|
||||
- 新版本文档翻译缓慢进行中，详见 [1.6分支](https://github.com/5-say/composer-doc-cn/blob/1.6/README.md)
|
||||
- 当前文档基本不影响新版 Composer 的使用，新文档在结构以及章节内容上做了比较大的调整，针对性的翻译会逐步完善。
|
||||
- [中文翻译贡献者名单](/contributors.md)
|
||||
|
||||
---
|
||||
|
||||
## Book
|
||||
- [简介](/cn-introduction/00-intro.md)
|
||||
- [基本用法](/cn-introduction/01-basic-usage.md)
|
||||
- [库（资源包）](/cn-introduction/02-libraries.md)
|
||||
- [命令行](/cn-introduction/03-cli.md)
|
||||
- [架构](/cn-introduction/04-schema.md)
|
||||
- [资源库](/cn-introduction/05-repositories.md)
|
||||
- [社区](/cn-introduction/06-community.md)
|
||||
|
||||
## Articles
|
||||
- [别名](/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)
|
||||
Host your own composer repository
|
||||
- [插件](/cn-introduction/articles/plugins.md)
|
||||
修改和扩展 Composer 的功能。
|
||||
- [脚本](/cn-introduction/articles/scripts.md)
|
||||
脚本是指一些 Composer 事件的回调，它们在安装资源包的过程中被触发执行。
|
||||
- [Troubleshooting](/cn-introduction/articles/troubleshooting.md)
|
||||
Solving problems
|
||||
- [二进制供应库](/cn-introduction/articles/vendor-binaries.md)
|
||||
从资源包中暴露命令行脚本。
|
||||
|
||||
## FAQs
|
||||
|
||||
- [如何为我的框架自定义一个资源包安装目录？](/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)
|
||||
- [为什么 Composer 不递归加载储存库？](/cn-introduction/faqs/why-can%27t-composer-load-repositories-recursively.md)
|
||||
|
||||
## 相关文章推荐
|
||||
|
||||
- [PHP 开发者该知道的5个 Composer 小技巧](http://segmentfault.com/a/1190000000355928)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,191 @@
|
|||
<a name="Introduction"></a>
|
||||
# 简介
|
||||
|
||||
Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖的代码库，它会在你的项目中为你安装他们。
|
||||
|
||||
---
|
||||
|
||||
- [简介](#Introduction)
|
||||
- [依赖管理](#Dependency-management)
|
||||
- [声明依赖关系](#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)
|
||||
|
||||
---
|
||||
|
||||
<a name="Dependency-management"></a>
|
||||
## 依赖管理
|
||||
|
||||
Composer 不是一个包管理器。是的，它涉及 "packages" 和 "libraries"，但它在每个项目的基础上进行管理，在你项目的某个目录中（例如 `vendor`）进行安装。默认情况下它不会在全局安装任何东西。因此，这仅仅是一个依赖管理。
|
||||
|
||||
这种想法并不新鲜，Composer 受到了 node 的 [npm](http://npmjs.org/)
|
||||
和 ruby 的 [bundler](http://gembundler.com/) 的强烈启发。而当时 PHP 下并没有类似的工具。
|
||||
|
||||
Composer 将这样为你解决问题：
|
||||
|
||||
a) 你有一个项目依赖于若干个库。
|
||||
|
||||
b) 其中一些库依赖于其他库。
|
||||
|
||||
c) 你声明你所依赖的东西。
|
||||
|
||||
d) Composer 会找出哪个版本的包需要安装，并安装它们（将它们下载到你的项目中）。
|
||||
|
||||
<a name="Declaring-dependencies"></a>
|
||||
## 声明依赖关系
|
||||
|
||||
比方说，你正在创建一个项目，你需要一个库来做日志记录。你决定使用 [monolog](https://github.com/Seldaek/monolog)。为了将它添加到你的项目中，你所需要做的就是创建一个 `composer.json` 文件，其中描述了项目的依赖关系。
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "1.2.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
我们只要指出我们的项目需要一些 `monolog/monolog` 的包，从 `1.2` 到 `1.3` 之间的最高版本。
|
||||
|
||||
<a name="System-Requirements"></a>
|
||||
## 系统要求
|
||||
|
||||
运行 Composer 需要 PHP 5.3.2+ 以上版本。一些敏感的 PHP 设置和编译标志也是必须的，但对于任何不兼容项安装程序都会抛出警告。
|
||||
|
||||
我们将从包的来源直接安装，而不是简单的下载 zip 文件，你需要 git 、 svn 或者 hg ，这取决于你载入的包所使用的版本管理系统。
|
||||
|
||||
Composer 是多平台的，我们努力使它在 Windows 、 Linux 以及 OSX 平台上运行的同样出色。
|
||||
|
||||
<a name="Installation-*nix"></a>
|
||||
## 安装 - *nix
|
||||
|
||||
<a name="Downloading-the-Composer-Executable"></a>
|
||||
### 下载 Composer 的可执行文件
|
||||
|
||||
<a name="Locally"></a>
|
||||
#### 局部安装
|
||||
|
||||
要真正获取 Composer，我们需要做两件事。首先安装 Composer （同样的，这意味着它将下载到你的项目中）：
|
||||
|
||||
```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 的安装目录（它可以是一个绝对或相对路径）：
|
||||
|
||||
```sh
|
||||
curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
|
||||
```
|
||||
|
||||
<a name="Globally"></a>
|
||||
#### 全局安装
|
||||
|
||||
你可以将此文件放在任何地方。如果你把它放在系统的 `PATH` 目录中，你就能在全局访问它。 在类Unix系统中，你甚至可以在使用时不加 `php` 前缀。
|
||||
|
||||
你可以执行这些命令让 `composer` 在你的系统中进行全局调用：
|
||||
|
||||
```sh
|
||||
curl -sS https://getcomposer.org/installer | php
|
||||
mv composer.phar /usr/local/bin/composer
|
||||
```
|
||||
|
||||
> **注意：** 如果上述命令因为权限执行失败，
|
||||
> 请使用 sudo 再次尝试运行 `mv` 那行命令。
|
||||
|
||||
现在只需要运行 `composer` 命令就可以使用 Composer 而不需要输入 `php composer.phar`。
|
||||
|
||||
<a name="Globally-on-OSX-via-homebrew"></a>
|
||||
#### 全局安装 (on OSX via homebrew)
|
||||
|
||||
Composer 是 homebrew-php 项目的一部分。
|
||||
|
||||
```sh
|
||||
brew update
|
||||
brew tap josegonzalez/homebrew-php
|
||||
brew tap homebrew/versions
|
||||
brew install php55-intl
|
||||
brew install josegonzalez/php/composer
|
||||
```
|
||||
|
||||
<a name="Installation-Windows"></a>
|
||||
## 安装 - Windows
|
||||
|
||||
<a name="Using-the-Installer"></a>
|
||||
### 使用安装程序
|
||||
|
||||
这是将 Composer 安装在你机器上的最简单的方法。
|
||||
|
||||
下载并且运行 [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe)，它将安装最新版本的 Composer ，并设置好系统的环境变量，因此你可以在任何目录下直接使用 `composer` 命令。
|
||||
|
||||
<a name="Manual-Installation"></a>
|
||||
### 手动安装
|
||||
|
||||
设置系统的环境变量 `PATH` 并运行安装命令下载 composer.phar 文件：
|
||||
|
||||
```sh
|
||||
C:\Users\username>cd C:\bin
|
||||
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
|
||||
```
|
||||
|
||||
> **注意：** 如果收到 readfile 错误提示，请使用 `http` 链接或者在 php.ini 中开启 php_openssl.dll 。
|
||||
|
||||
在 `composer.phar` 同级目录下新建文件 `composer.bat` ：
|
||||
|
||||
```sh
|
||||
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
|
||||
```
|
||||
|
||||
关闭当前的命令行窗口，打开新的命令行窗口进行测试：
|
||||
|
||||
```sh
|
||||
C:\Users\username>composer -V
|
||||
Composer version 27d8904
|
||||
```
|
||||
|
||||
<a name="Using-Composer"></a>
|
||||
## 使用 Composer
|
||||
|
||||
现在我们将使用 Composer 来安装项目的依赖。如果在当前目录下没有一个 `composer.json` 文件，请查看[基本用法](01-basic-usage.md)章节。
|
||||
|
||||
要解决和下载依赖，请执行 `install` 命令：
|
||||
|
||||
```sh
|
||||
php composer.phar install
|
||||
```
|
||||
|
||||
如果你进行了全局安装，并且没有 phar 文件在当前目录，请使用下面的命令代替：
|
||||
|
||||
```sh
|
||||
composer install
|
||||
```
|
||||
|
||||
继续 [上面的例子](#Declaring-dependencies)，这里将下载 monolog 到 `vendor/monolog/monolog` 目录。
|
||||
|
||||
<a name="Autoloading"></a>
|
||||
## 自动加载
|
||||
|
||||
除了库的下载，Composer 还准备了一个自动加载文件，它可以加载 Composer 下载的库中所有的类文件。使用它，你只需要将下面这行代码添加到你项目的引导文件中：
|
||||
|
||||
```php
|
||||
require 'vendor/autoload.php';
|
||||
```
|
||||
|
||||
现在我们就可以使用 monolog 了！想要学习更多关于 Composer 的知识，请查看“基本用法”章节。
|
||||
|
||||
[基本用法](01-basic-usage.md) →
|
||||
|
|
@ -0,0 +1,248 @@
|
|||
<a name="Basic-usage"></a>
|
||||
# 基本用法
|
||||
|
||||
---
|
||||
|
||||
- [基本用法](#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)
|
||||
|
||||
---
|
||||
|
||||
<a name="Installation"></a>
|
||||
## 安装
|
||||
|
||||
安装 Composer，你只需要下载 `composer.phar` 可执行文件。
|
||||
|
||||
```sh
|
||||
curl -sS https://getcomposer.org/installer | php
|
||||
```
|
||||
|
||||
详细请查看 [简介](00-intro.md) 章节。
|
||||
|
||||
要检查 Composer 是否正常工作，只需要通过 `php` 来执行 PHAR：
|
||||
|
||||
```sh
|
||||
php composer.phar
|
||||
```
|
||||
|
||||
这将返回给你一个可执行的命令列表。
|
||||
|
||||
> **注意：** 你也可以仅执行 `--check` 选项而无需下载 Composer。
|
||||
> 要获取更多的信息请使用 `--help`。
|
||||
>
|
||||
> ```sh
|
||||
> curl -sS https://getcomposer.org/installer | php -- --help
|
||||
> ```
|
||||
|
||||
<a name="composer.json-Project-Setup"></a>
|
||||
## `composer.json`：项目安装
|
||||
|
||||
要开始在你的项目中使用 Composer，你只需要一个 `composer.json` 文件。该文件包含了项目的依赖和其它的一些元数据。
|
||||
|
||||
这个 [JSON format](http://json.org/) 是很容易编写的。它允许你定义嵌套结构。
|
||||
|
||||
<a name="The-require-Key"></a>
|
||||
### 关于 `require` Key
|
||||
|
||||
第一件事情（并且往往只需要做这一件事），你需要在 `composer.json` 文件中指定 `require` key 的值。你只需要简单的告诉 Composer 你的项目需要依赖哪些包。
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "1.0.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
你可以看到， `require` 需要一个 **包名称** （例如 `monolog/monolog`） 映射到 **包版本** （例如 `1.0.*`） 的对象。
|
||||
同时你还可以声明需要开发支持特定版本的PHP和PHP扩展你的项目需要成功运行的参考（例下）
|
||||
```json
|
||||
{
|
||||
"require" : {
|
||||
"php" : "^5.5 || ^7.0",
|
||||
"ext-mbstring": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
<a name="Package-Names"></a>
|
||||
### 包名称
|
||||
|
||||
包名称由供应商名称和其项目名称构成。通常容易产生相同的项目名称，而供应商名称的存在则很好的解决了命名冲突的问题。它允许两个不同的人创建同样名为 `json` 的库，而之后它们将被命名为 `igorw/json` 和 `seldaek/json`。
|
||||
|
||||
这里我们需要引入 `monolog/monolog`，供应商名称与项目的名称相同，对于一个具有唯一名称的项目，我们推荐这么做。它还允许以后在同一个命名空间添加更多的相关项目。如果你维护着一个库，这将使你可以很容易的把它分离成更小的部分。
|
||||
|
||||
<a name="Package-Versions"></a>
|
||||
### 包版本
|
||||
|
||||
在前面的例子中，我们引入的 monolog 版本指定为 `1.0.*`。这表示任何从 `1.0` 开始的开发分支，它将会匹配 `1.0.0`、`1.0.2` 或者 `1.0.20`。
|
||||
|
||||
版本约束可以用几个不同的方法来指定。
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>名称</th><th>实例</th><th>描述</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>确切的版本号</td>
|
||||
<td><code>1.0.2</code></td>
|
||||
<td>你可以指定包的确切版本。</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>范围</td>
|
||||
<td>
|
||||
<code>>=1.0</code>
|
||||
<code>>=1.0,<2.0</code>
|
||||
<code>>=1.0,<1.1|>=1.2</code>
|
||||
</td>
|
||||
<td>通过使用比较操作符可以指定有效的版本范围。
|
||||
<br />有效的运算符：<code>></code>、<code>>=</code>、<code><</code>、<code><=</code>、<code>!=</code>。
|
||||
<br />你可以定义多个范围，用逗号隔开，这将被视为一个<strong>逻辑AND</strong>处理。一个管道符号<code>|</code>将作为<strong>逻辑OR</strong>处理。
|
||||
<br />AND 的优先级高于 OR。</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>通配符</td>
|
||||
<td><code>1.0.*</code></td>
|
||||
<td>你可以使用通配符<code>*</code>来指定一种模式。<code>1.0.*</code>与<code>>=1.0,<1.1</code>是等效的。</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>赋值运算符</td>
|
||||
<td><code>~1.2</code></td>
|
||||
<td>这对于遵循语义化版本号的项目非常有用。<code>~1.2</code>相当于<code>>=1.2,<2.0</code>。想要了解更多，请阅读下一小节。</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>插入符号</td>
|
||||
<td><code> ^1.2.3</code></td>
|
||||
<td>^操作符的行为很相似，但它更接近于语义，并将永远让不间断更新。例如<code>^1.2.3</code>相当于<code>>=1.2.3<2.0.0</code>如没有释放到2.0应该打破向后兼容性。同时也可以使用限制版本，如<code>^0.3</code>为<code>>=0.3.0<0.4.0 </code>。</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<a name="Next-Significant-Release"></a>
|
||||
### 下一个重要版本（波浪号运算符）
|
||||
|
||||
`~` 最好用例子来解释： `~1.2` 相当于 `>=1.2,<2.0`，而 `~1.2.3` 相当于 `>=1.2.3,<1.3`。正如你所看到的这对于遵循 [语义化版本号](http://semver.org/) 的项目最有用。一个常见的用法是标记你所依赖的最低版本，像 `~1.2` （允许1.2以上的任何版本，但不包括2.0）。由于理论上直到2.0应该都没有向后兼容性问题，所以效果很好。你还会看到它的另一种用法，使用 `~` 指定最低版本，但允许版本号的最后一位数字上升。
|
||||
|
||||
> **注意：** 虽然 `2.0-beta.1` 严格地说是早于 `2.0`，但是，根据版本约束条件，
|
||||
> 例如 `~1.2` 却不会安装这个版本。就像前面所讲的 `~1.2` 只意味着 `.2`
|
||||
> 部分可以改变，但是 `1.` 部分是固定的。
|
||||
|
||||
<a name="Stability"></a>
|
||||
### 稳定性
|
||||
|
||||
默认情况下只有稳定的发行版才会被考虑在内。如果你也想获得 RC、beta、alpha 或 dev 版本，你可以使用 [稳定标志](04-schema.md#Package-links)。你可以对所有的包做 [最小稳定性](04-schema.md#minimum-stability) 设置，而不是每个依赖逐一设置。
|
||||
|
||||
<a name="Installing-Dependencies"></a>
|
||||
## 安装依赖包
|
||||
|
||||
获取定义的依赖到你的本地项目，只需要调用 `composer.phar` 运行 `install` 命令。
|
||||
|
||||
```sh
|
||||
php composer.phar install
|
||||
```
|
||||
|
||||
接着前面的例子，这将会找到 `monolog/monolog` 的最新版本，并将它下载到 `vendor` 目录。
|
||||
这是一个惯例把第三方的代码到一个指定的目录 `vendor`。如果是 monolog 将会创建 `vendor/monolog/monolog` 目录。
|
||||
|
||||
> **小技巧：** 如果你正在使用Git来管理你的项目，
|
||||
> 你可能要添加 `vendor` 到你的 `.gitignore` 文件中。
|
||||
> 你不会希望将所有的代码都添加到你的版本库中。
|
||||
|
||||
另一件事是 `install` 命令将创建一个 `composer.lock` 文件到你项目的根目录中。
|
||||
|
||||
<a name="composer.lock-The-Lock-File"></a>
|
||||
## `composer.lock` - 锁文件
|
||||
|
||||
在安装依赖后，Composer 将把安装时确切的版本号列表写入 `composer.lock` 文件。这将锁定该项目的特定版本。
|
||||
|
||||
**请提交你应用程序的 `composer.lock` （包括 `composer.json`）到你的版本库中**
|
||||
|
||||
这是非常重要的，因为 `install` 命令将会检查锁文件是否存在，如果存在，它将下载指定的版本（忽略 `composer.json` 文件中的定义）。
|
||||
|
||||
这意味着，任何人建立项目都将下载与指定版本完全相同的依赖。你的持续集成服务器、生产环境、你团队中的其他开发人员、每件事、每个人都使用相同的依赖，从而减轻潜在的错误对部署的影响。即使你独自开发项目，在六个月内重新安装项目时，你也可以放心的继续工作，即使从那时起你的依赖已经发布了许多新的版本。
|
||||
|
||||
如果不存在 `composer.lock` 文件，Composer 将读取 `composer.json` 并创建锁文件。
|
||||
|
||||
这意味着如果你的依赖更新了新的版本，你将不会获得任何更新。此时要更新你的依赖版本请使用 `update` 命令。这将获取最新匹配的版本（根据你的 `composer.json` 文件）并将新版本更新进锁文件。
|
||||
|
||||
```sh
|
||||
php composer.phar update
|
||||
```
|
||||
|
||||
如果只想安装或更新一个依赖，你可以白名单它们：
|
||||
|
||||
```sh
|
||||
php composer.phar update monolog/monolog [...]
|
||||
```
|
||||
|
||||
> **注意：** 对于库，并不一定建议提交锁文件
|
||||
> 请参考：[库的锁文件](02-libraries.md#Lock-file).
|
||||
|
||||
<a name="Packagist"></a>
|
||||
## Packagist
|
||||
|
||||
[packagist](https://packagist.org/) 是 Composer 的主要资源库。 一个 Composer 的库基本上是一个包的源：记录了可以得到包的地方。Packagist 的目标是成为大家使用库资源的中央存储平台。这意味着你可以 `require` 那里的任何包。
|
||||
|
||||
当你访问 [packagist](https://packagist.org/) 网站 (packagist.org)，你可以浏览和搜索资源包。
|
||||
|
||||
任何支持 Composer 的开源项目应该发布自己的包在 packagist 上。虽然并不一定要发布在 packagist 上来使用 Composer，但它使我们的编程生活更加轻松。
|
||||
|
||||
<a name="Autoloading"></a>
|
||||
## 自动加载
|
||||
|
||||
对于库的自动加载信息，Composer 生成了一个 `vendor/autoload.php` 文件。你可以简单的引入这个文件，你会得到一个免费的自动加载支持。
|
||||
|
||||
```php
|
||||
require 'vendor/autoload.php';
|
||||
```
|
||||
|
||||
这使得你可以很容易的使用第三方代码。例如：如果你的项目依赖 monolog，你就可以像这样开始使用这个类库，并且他们将被自动加载。
|
||||
|
||||
```php
|
||||
$log = new Monolog\Logger('name');
|
||||
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
|
||||
|
||||
$log->addWarning('Foo');
|
||||
```
|
||||
|
||||
你可以在 `composer.json` 的 `autoload` 字段中增加自己的 autoloader。
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-4": {"Acme\\": "src/"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Composer 将注册一个 [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader 到 `Acme` 命名空间。
|
||||
|
||||
你可以定义一个从命名空间到目录的映射。此时 `src` 会在你项目的根目录，与 `vendor` 文件夹同级。例如 `src/Foo.php` 文件应该包含 `Acme\Foo` 类。
|
||||
|
||||
添加 `autoload` 字段后，你应该再次运行 `install` 命令来生成 `vendor/autoload.php` 文件。
|
||||
|
||||
引用这个文件也将返回 autoloader 的实例，你可以将包含调用的返回值存储在变量中，并添加更多的命名空间。这对于在一个测试套件中自动加载类文件是非常有用的，例如。
|
||||
|
||||
```php
|
||||
$loader = require 'vendor/autoload.php';
|
||||
$loader->addPsr4('Acme\\Test\\', __DIR__);
|
||||
```
|
||||
|
||||
除了 PSR-4 自动加载，Composer 同时支持PSR-0、classmap 和 files自动加载。详细请查看 [自动加载-参考](04-schema.md#autoload)。
|
||||
|
||||
> **注意：** Composer 提供了自己的 autoloader。如果你不想使用它，你可以仅仅引入 `vendor/composer/autoload_*.php` 文件，它返回一个关联数组，你可以通过这个关联数组配置自己的 autoloader。
|
||||
|
||||
← [简介](00-intro.md) | [库（资源包）](02-libraries.md) →
|
||||
|
|
@ -0,0 +1,177 @@
|
|||
<a name="Libraries"></a>
|
||||
# 库（资源包）
|
||||
|
||||
本章将告诉你如何通过 Composer 来安装你的库。
|
||||
|
||||
---
|
||||
|
||||
- [库（资源包）](#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)
|
||||
|
||||
---
|
||||
|
||||
<a name="Every-project-is-a-package"></a>
|
||||
## 每一个项目都是一个包
|
||||
|
||||
只要你有一个 `composer.json` 文件在目录中，那么整个目录就是一个包。当你添加一个 `require` 到项目中，你就是在创建一个依赖于其它库的包。你的项目和库之间唯一的区别是，你的项目是一个没有名字的包。
|
||||
|
||||
为了使它成为一个可安装的包，你需要给它一个名称。你可以通过 `composer.json` 中的 `name` 来定义：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "acme/hello-world",
|
||||
"require": {
|
||||
"monolog/monolog": "1.0.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在这种情况下项目的名称为 `acme/hello-world`，其中 `acme` 是供应商的名称。供应商的名称是必须填写的。
|
||||
|
||||
> **注意：** 如果你不知道拿什么作为供应商的名称，
|
||||
> 那么使用你 github 上的用户名通常是不错的选择。
|
||||
> 虽然包名不区分大小写，但惯例是使用小写字母，并用连字符作为单词的分隔。
|
||||
|
||||
<a name="Platform-packages"></a>
|
||||
## 平台软件包
|
||||
|
||||
Composer 将那些已经安装在系统上，但并不是由 Composer 安装的包视为一个虚拟的平台软件包。这包括PHP本身，PHP扩展和一些系统库。
|
||||
|
||||
* `php` 表示用户的 PHP 版本要求，你可以对其做出限制。例如 `>=5.4.0`。如果需要64位版本的 PHP，你可以使用 `php-64bit` 进行限制。
|
||||
|
||||
* `hhvm` 代表的是 HHVM（也就是 HipHop Virtual
|
||||
Machine） 运行环境的版本，并且允许你设置一个版本限制，例如，'>=2.3.3'。
|
||||
|
||||
* `ext-<name>` 可以帮你指定需要的 PHP 扩展（包括核心扩展）。通常 PHP 拓展的版本可以是不一致的，将它们的版本约束为 `*` 是一个不错的主意。一个 PHP 扩展包的例子：包名可以写成 `ext-gd`。
|
||||
|
||||
* `lib-<name>` 允许对 PHP 库的版本进行限制。
|
||||
以下是可供使用的名称：`curl`、`iconv`、`icu`、`libxml`、`openssl`、`pcre`、`uuid`、`xsl`。
|
||||
|
||||
你可以使用 `composer show --platform` 命令来获取可用的平台软件包的列表。
|
||||
|
||||
<a name="Specifying-the-version"></a>
|
||||
## 指明版本
|
||||
|
||||
你需要一些方法来指明自己开发的包的版本，当你在 Packagist 上发布自己的包，它能够从 VCS (git, svn,
|
||||
hg) 的信息推断出包的版本，因此你不必手动指明版本号，并且也不建议这样做。请查看 [标签](#Tags) 和 [分支](#Branches) 来了解版本号是如何被提取的。
|
||||
|
||||
如果你想要手动创建并且真的要明确指定它，你只需要添加一个 `version` 字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
> **注意：** 你应该尽量避免手动设置版本号，因为标签的值必须与标签名相匹配。
|
||||
|
||||
<a name="Tags"></a>
|
||||
### 标签
|
||||
|
||||
对于每一个看起来像版本号的标签，都会相应的创建一个包的版本。它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式，`-patch`、`-alpha`、`-beta` 或 `-RC` 这些后缀是可选的。在后缀之后也可以再跟上一个数字。
|
||||
|
||||
下面是有效的标签名称的几个例子：
|
||||
|
||||
- 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)时是不允许这种前缀的，
|
||||
> 因此 `v` 将被省略（例如标签 `V1.0.0` 将创建 `1.0.0` 版本）。
|
||||
|
||||
<a name="Branches"></a>
|
||||
### 分支
|
||||
|
||||
对于每一个分支，都会相应的创建一个包的开发版本。如果分支名看起来像一个版本号，那么将创建一个如同 `{分支名}-dev` 的包版本号。例如一个分支 `2.0` 将产生一个 `2.0.x-dev` 包版本（加入了 `.x` 是出于技术的原因，以确保它被识别为一个分支，而 `2.0.x` 的分支名称也是允许的，它同样会被转换为 `2.0.x-dev`）。如果分支名看起来不像一个版本号，它将会创建 `dev-{分支名}` 形式的版本号。例如 `master` 将产生一个 `dev-master` 的版本号。
|
||||
|
||||
下面是版本分支名称的一些示例：
|
||||
|
||||
- 1.x
|
||||
- 1.0 (equals 1.0.x)
|
||||
- 1.1.x
|
||||
|
||||
> **注意：** 当你安装一个新的版本时，将会自动从它 `source` 中拉取。
|
||||
> 详细请查看 [`install`](03-cli.md#install) 命令。
|
||||
|
||||
<a name="Aliases"></a>
|
||||
### 别名
|
||||
|
||||
它表示一个包版本的别名。例如，你可以为 `dev-master` 设置别名 `1.0.x-dev`，这样就可以通过 require `1.0.x-dev` 来得到 `dev-master` 版本的包。
|
||||
|
||||
详细请查看[“别名”](articles/aliases.md)。
|
||||
|
||||
<a name="Lock-file"></a>
|
||||
## 锁文件
|
||||
|
||||
如果你愿意，可以在你的项目中提交 `composer.lock` 文件。他将帮助你的团队始终针对同一个依赖版本进行测试。任何时候，这个锁文件都只对于你的项目产生影响。
|
||||
|
||||
如果你不想提交锁文件，并且你正在使用 Git，那么请将它添加到 `.gitignore` 文件中。
|
||||
|
||||
<a name="Publishing-to-a-VCS"></a>
|
||||
## 发布到 VCS（线上版本控制系统）
|
||||
|
||||
一旦你有一个包含 `composer.json` 文件的库存储在线上版本控制系统（例如：Git），你的库就可以被 Composer 所安装。在这个例子中，我们将 `acme/hello-world` 库发布在 GitHub 上的 `github.com/username/hello-world` 中。
|
||||
|
||||
现在测试这个 `acme/hello-world` 包，我们在本地创建一个新的项目。我们将它命名为 `acme/blog`。此博客将依赖 `acme/hello-world`，而后者又依赖 `monolog/monolog`。我们可以在某处创建一个新的 `blog` 文件夹来完成它，并且需要包含 `composer.json` 文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "acme/blog",
|
||||
"require": {
|
||||
"acme/hello-world": "dev-master"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在这个例子中 `name` 不是必须的，因为我们并不想将它发布为一个库。在这里为 `composer.json` 文件添加描述。
|
||||
|
||||
现在我们需要告诉我们的应用，在哪里可以找到 `hello-world` 的依赖。为此我们需要在 `composer.json` 中添加 `repositories` 来源申明：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "acme/blog",
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "https://github.com/username/hello-world"
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
"acme/hello-world": "dev-master"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
更多关于包的来源是如何工作的，以及还有什么其他的类型可供选择，请查看[资源库](05-repositories.md)。
|
||||
|
||||
这就是全部了。你现在可以使用 Composer 的 `install` 命令来安装你的依赖包了！
|
||||
|
||||
**小结：** 任何含有 `composer.json` 的 `GIT`、`SVN`、`HG` 存储库，都可以通过 `require` 字段指定“包来源”和“声明依赖”来添加到你的项目中。
|
||||
|
||||
<a name="Publishing-to-packagist"></a>
|
||||
## 发布到 packagist
|
||||
|
||||
好的，你现在可以发布你的包了，但你不会希望你的用户每次都这样繁琐的指定包的来源。
|
||||
|
||||
你可能注意到了另一件事，我们并没有指定 `monolog/monolog` 的来源。它是怎么工作的？答案是 packagist。
|
||||
|
||||
[Packagist](https://packagist.org/) 是 Composer 主要的一个包信息存储库，它默认是启用的。任何在 packagist 上发布的包都可以直接被 Composer 使用。就像 monolog
|
||||
它被 [发布在 packagist 上](https://packagist.org/packages/monolog/monolog)，我们可以直接使用它，而不必指定任何额外的来源信息。
|
||||
|
||||
如果我们想与世界分享我们的 `hello-world`，我们最好将它发布到 packagist 上。这样做是很容易的。
|
||||
|
||||
你只需要点击那个大大的 "Submit Package" 按钮并注册。接着提交你库的来源地址，此时 packagist 就开始了抓取。一旦完成，你的包将可以提供给任何人使用。
|
||||
|
||||
← [基本用法](01-basic-usage.md) | [命令行](03-cli.md) →
|
||||
|
|
@ -0,0 +1,570 @@
|
|||
<a name="Command-line-interface"></a>
|
||||
# 命令行
|
||||
|
||||
你已经学会了如何使用命令行界面做一些事情。本章将向你介绍所有可用的命令。
|
||||
|
||||
为了从命令行获得帮助信息，请运行 `composer` 或者 `composer list` 命令，然后结合 `--help` 命令来获得更多的帮助信息。
|
||||
|
||||
---
|
||||
|
||||
- [命令行](#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_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)
|
||||
|
||||
---
|
||||
<a name="Global-Options"></a>
|
||||
## 全局参数
|
||||
|
||||
下列参数可与每一个命令结合使用：
|
||||
|
||||
* **--verbose (-v):** 增加反馈信息的详细度。
|
||||
* -v 表示正常输出。
|
||||
* -vv 表示更详细的输出。
|
||||
* -vvv 则是为了 debug。
|
||||
* **--help (-h):** 显示帮助信息。
|
||||
* **--quiet (-q):** 禁止输出任何信息。
|
||||
* **--no-interaction (-n):** 不要询问任何交互问题。
|
||||
* **--working-dir (-d):** 如果指定的话，使用给定的目录作为工作目录。
|
||||
* **--profile:** 显示时间和内存使用信息。
|
||||
* **--ansi:** 强制 ANSI 输出。
|
||||
* **--no-ansi:** 关闭 ANSI 输出。
|
||||
* **--version (-V):** 显示当前应用程序的版本信息。
|
||||
|
||||
<a name="Process-Exit-Codes"></a>
|
||||
## 进程退出代码
|
||||
|
||||
* **0:** 正常
|
||||
* **1:** 通用/未知错误
|
||||
* **2:** 依赖关系处理错误
|
||||
|
||||
<a name="init"></a>
|
||||
## 初始化 `init`
|
||||
|
||||
在 [“库”](02-libraries.md) 那一章我们看到了如何手动创建 `composer.json` 文件。实际上还有一个 `init` 命令可以更容易的做到这一点。
|
||||
|
||||
当您运行该命令，它会以交互方式要求您填写一些信息，同时聪明的使用一些默认值。
|
||||
|
||||
```sh
|
||||
php composer.phar init
|
||||
```
|
||||
|
||||
<a name="init-Options"></a>
|
||||
### 初始化-参数
|
||||
|
||||
* **--name:** 包的名称。
|
||||
* **--description:** 包的描述。
|
||||
* **--author:** 包的作者。
|
||||
* **--homepage:** 包的主页。
|
||||
* **--require:** 需要依赖的其它包，必须要有一个版本约束。并且应该遵循 `foo/bar:1.0.0` 这样的格式。
|
||||
* **--require-dev:** 开发版的依赖包，内容格式与 **--require** 相同。
|
||||
* **--stability (-s):** `minimum-stability` 字段的值。
|
||||
|
||||
<a name="install"></a>
|
||||
## 安装 `install`
|
||||
|
||||
`install` 命令从当前目录读取 `composer.json` 文件，处理了依赖关系，并把其安装到 `vendor` 目录下。
|
||||
|
||||
```sh
|
||||
php composer.phar install
|
||||
```
|
||||
|
||||
如果当前目录存在 `composer.lock` 文件，它会从此文件读取依赖版本，而不是根据 `composer.json` 文件去获取依赖。这确保了该库的每个使用者都能得到相同的依赖版本。
|
||||
|
||||
如果没有 `composer.lock` 文件，composer 将在处理完依赖关系后创建它。
|
||||
|
||||
<a name="install-Options"></a>
|
||||
### 安装-参数
|
||||
|
||||
* **--prefer-source:** 下载包的方式有两种： `source`
|
||||
和 `dist`。对于稳定版本 composer 将默认使用 `dist` 方式。而 `source` 表示版本控制源 。如果 `--prefer-source` 是被启用的，composer 将从 `source` 安装（如果有的话）。如果想要使用一个 bugfix 到你的项目，这是非常有用的。并且可以直接从本地的版本库直接获取依赖关系。
|
||||
* **--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/4 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。
|
||||
|
||||
<a name="update"></a>
|
||||
## 更新 `update`
|
||||
|
||||
为了获取依赖的最新版本，并且升级 `composer.lock` 文件，你应该使用 `update` 命令。
|
||||
|
||||
```sh
|
||||
php composer.phar update
|
||||
```
|
||||
|
||||
这将解决项目的所有依赖，并将确切的版本号写入 `composer.lock`。
|
||||
|
||||
如果你只是想更新几个包，你可以像这样分别列出它们：
|
||||
|
||||
```sh
|
||||
php composer.phar update vendor/package vendor/package2
|
||||
```
|
||||
|
||||
你还可以使用通配符进行批量更新：
|
||||
|
||||
```sh
|
||||
php composer.phar update vendor/*
|
||||
```
|
||||
|
||||
<a name="update-Options"></a>
|
||||
### 更新-参数
|
||||
|
||||
* **--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/4 autoloading 到 classmap 可以获得更快的加载支持。特别是在生产环境下建议这么做，但由于运行需要一些时间，因此并没有作为默认值。
|
||||
* **--lock:** 仅更新 lock 文件的 hash，取消有关 lock 文件过时的警告。
|
||||
* **--with-dependencies** 同时更新白名单内包的依赖关系，这将进行递归更新。
|
||||
|
||||
<a name="require"></a>
|
||||
## 申明依赖 `require`
|
||||
|
||||
`require` 命令增加新的依赖包到当前目录的 `composer.json` 文件中。
|
||||
|
||||
```sh
|
||||
php composer.phar require
|
||||
```
|
||||
|
||||
在添加或改变依赖时， 修改后的依赖关系将被安装或者更新。
|
||||
|
||||
如果你不希望通过交互来指定依赖包，你可以在这条令中直接指明依赖包。
|
||||
|
||||
```sh
|
||||
php composer.phar require vendor/package:2.* vendor/package2:dev-master
|
||||
```
|
||||
|
||||
<a name="require-Options"></a>
|
||||
### 申明依赖-参数
|
||||
|
||||
* **--prefer-source:** 当有可用的包时，从 `source` 安装。
|
||||
* **--prefer-dist:** 当有可用的包时，从 `dist` 安装。
|
||||
* **--dev:** 安装 `require-dev` 字段中列出的包。
|
||||
* **--no-update:** 禁用依赖关系的自动更新。
|
||||
* **--no-progress:** 移除进度信息，这可以避免一些不处理换行的终端或脚本出现混乱的显示。
|
||||
* **--update-with-dependencies** 一并更新新装包的依赖。
|
||||
|
||||
<a name="global"></a>
|
||||
## 全局执行 `global`
|
||||
|
||||
`global` 命令允许你在 [COMPOSER_HOME](#COMPOSER_HOME) 目录下执行其它命令，像 `install`、`require` 或 `update`。
|
||||
|
||||
并且如果你将 `$COMPOSER_HOME/vendor/bin` 加入到了 `$PATH` 环境变量中，你就可以用它在命令行中安装全局应用，下面是一个例子：
|
||||
|
||||
```sh
|
||||
php composer.phar global require fabpot/php-cs-fixer:dev-master
|
||||
```
|
||||
|
||||
现在 `php-cs-fixer` 就可以在全局范围使用了（假设你已经设置了你的 PATH）。如果稍后你想更新它，你只需要运行 `global update`：
|
||||
|
||||
```sh
|
||||
php composer.phar global update
|
||||
```
|
||||
|
||||
<a name="search"></a>
|
||||
## 搜索 `search`
|
||||
|
||||
`search` 命令允许你为当前项目搜索依赖包，通常它只搜索 packagist.org 上的包，你可以简单的输入你的搜索条件。
|
||||
|
||||
```sh
|
||||
php composer.phar search monolog
|
||||
```
|
||||
|
||||
您也可以通过传递多个参数来进行多条件搜索。
|
||||
|
||||
<a name="search-Options"></a>
|
||||
### 搜索-参数
|
||||
|
||||
* **--only-name (-N):** 仅针对指定的名称搜索（完全匹配）。
|
||||
|
||||
<a name="show"></a>
|
||||
## 展示 `show`
|
||||
|
||||
列出所有可用的软件包，你可以使用 `show` 命令。
|
||||
|
||||
```sh
|
||||
php composer.phar show
|
||||
```
|
||||
|
||||
如果你想看到一个包的详细信息，你可以输入一个包名称。
|
||||
|
||||
```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
|
||||
|
||||
autoload
|
||||
psr-0
|
||||
Monolog : src/
|
||||
|
||||
requires
|
||||
php >=5.3.0
|
||||
```
|
||||
|
||||
你甚至可以输入一个软件包的版本号，来显示该版本的详细信息。
|
||||
|
||||
```sh
|
||||
php composer.phar show monolog/monolog 1.0.2
|
||||
```
|
||||
|
||||
<a name="show-Options"></a>
|
||||
### 展示-参数
|
||||
|
||||
* **--installed (-i):** 列出已安装的依赖包。
|
||||
* **--platform (-p):** 仅列出平台软件包（PHP 与它的扩展）。
|
||||
* **--self (-s):** 仅列出当前项目信息。
|
||||
|
||||
<a name="depends"></a>
|
||||
## 依赖性检测 `depends`
|
||||
|
||||
`depends` 命令可以查出已安装在你项目中的某个包，是否正在被其它的包所依赖，并列出他们。
|
||||
|
||||
```sh
|
||||
php composer.phar depends --link-type=require monolog/monolog
|
||||
|
||||
nrk/monolog-fluent
|
||||
poc/poc
|
||||
propel/propel
|
||||
symfony/monolog-bridge
|
||||
symfony/symfony
|
||||
```
|
||||
|
||||
<a name="depends-Options"></a>
|
||||
### 依赖性检测-参数
|
||||
|
||||
* **--link-type:** 检测的类型，默认为 `require` 也可以是 `require-dev`。
|
||||
|
||||
<a name="validate"></a>
|
||||
## 有效性检测 `validate`
|
||||
|
||||
在提交 `composer.json` 文件，和创建 tag 前，你应该始终运行 `validate` 命令。它将检测你的 `composer.json` 文件是否是有效的
|
||||
|
||||
```sh
|
||||
php composer.phar validate
|
||||
```
|
||||
|
||||
### 有效性检测参数
|
||||
|
||||
* **--no-check-all:** Composer 是否进行完整的校验。
|
||||
|
||||
<a name="status"></a>
|
||||
## 依赖包状态检测 `status`
|
||||
|
||||
如果你经常修改依赖包里的代码，并且它们是从 source（自定义源）进行安装的，那么 `status` 命令允许你进行检查，如果你有任何本地的更改它将会给予提示。
|
||||
|
||||
```sh
|
||||
php composer.phar status
|
||||
```
|
||||
|
||||
你可以使用 `--verbose` 系列参数（-v|vv|vvv）来获取更详细的详细：
|
||||
|
||||
```sh
|
||||
php composer.phar status -v
|
||||
|
||||
You have changes in the following dependencies:
|
||||
vendor/seld/jsonlint:
|
||||
M README.mdown
|
||||
```
|
||||
|
||||
<a name="self-update"></a>
|
||||
## 自我更新 `self-update`
|
||||
|
||||
将 Composer 自身升级到最新版本，只需要运行 `self-update` 命令。它将替换你的 `composer.phar` 文件到最新版本。
|
||||
|
||||
```sh
|
||||
php composer.phar self-update
|
||||
```
|
||||
|
||||
如果你想要升级到一个特定的版本，可以这样简单的指定它：
|
||||
|
||||
```sh
|
||||
php composer.phar self-update 1.0.0-alpha7
|
||||
```
|
||||
|
||||
如果你已经为整个系统安装 Composer（参见 [全局安装](00-intro.md#全局安装)），你可能需要在 `root` 权限下运行它：
|
||||
|
||||
```sh
|
||||
sudo composer self-update
|
||||
```
|
||||
|
||||
<a name="self-update-Options"></a>
|
||||
### 自我更新-参数
|
||||
|
||||
* **--rollback (-r):** 回滚到你已经安装的最后一个版本。
|
||||
* **--clean-backups:** 在更新过程中删除旧的备份，这使得更新过后的当前版本是唯一可用的备份。
|
||||
|
||||
<a name="config"></a>
|
||||
## 更改配置 `config`
|
||||
|
||||
`config` 命令允许你编辑 Composer 的一些基本设置，无论是本地的 `composer.json` 或者全局的 `config.json` 文件。
|
||||
|
||||
```sh
|
||||
php composer.phar config --list
|
||||
```
|
||||
|
||||
<a name="config-Usage"></a>
|
||||
### 更改配置-使用方法
|
||||
|
||||
`config [options] [setting-key] [setting-value1] ... [setting-valueN]`
|
||||
|
||||
`setting-key` 是一个配置选项的名称，`setting-value1` 是一个配置的值。可以使用数组作为配置的值（像 `github-protocols`），多个 `setting-value` 是允许的。
|
||||
|
||||
有效的配置选项，请查看“架构”章节的 [config](04-schema.md#config) 。
|
||||
|
||||
<a name="config-Options"></a>
|
||||
### 更改配置-参数
|
||||
|
||||
* **--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` 参数一起使用。
|
||||
|
||||
<a name="Modifying-Repositories"></a>
|
||||
### 修改包来源
|
||||
|
||||
除了修改配置选项， `config` 命令还支持通过以下方法修改来源信息：
|
||||
|
||||
```sh
|
||||
php composer.phar config repositories.foo vcs http://github.com/foo/bar
|
||||
```
|
||||
|
||||
<a name="create-project"></a>
|
||||
## 创建项目 `create-project`
|
||||
|
||||
你可以使用 Composer 从现有的包中创建一个新的项目。这相当于执行了一个 `git clone` 或 `svn checkout` 命令后将这个包的依赖安装到它自己的 vendor 目录。
|
||||
|
||||
此命令有几个常见的用途：
|
||||
|
||||
1. 你可以快速的部署你的应用。
|
||||
2. 你可以检出任何资源包，并开发它的补丁。
|
||||
3. 多人开发项目，可以用它来加快应用的初始化。
|
||||
|
||||
要创建基于 Composer 的新项目，你可以使用 "create-project" 命令。传递一个包名，它会为你创建项目的目录。你也可以在第三个参数中指定版本号，否则将获取最新的版本。
|
||||
|
||||
如果该目录目前不存在，则会在安装过程中自动创建。
|
||||
|
||||
```sh
|
||||
php composer.phar create-project doctrine/orm path 2.2.*
|
||||
```
|
||||
|
||||
此外，你也可以无需使用这个命令，而是通过现有的 `composer.json` 文件来启动这个项目。
|
||||
|
||||
默认情况下，这个命令会在 packagist.org 上查找你指定的包。
|
||||
|
||||
<a name="create-project-Options"></a>
|
||||
### 创建项目-参数
|
||||
|
||||
* **--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 。如果你在非交互模式下运行创建命令，这将是非常有用的。
|
||||
|
||||
<a name="dump-autoload"></a>
|
||||
## 打印自动加载索引 `dump-autoload`
|
||||
|
||||
某些情况下你需要更新 autoloader，例如在你的包中加入了一个新的类。你可以使用 `dump-autoload` 来完成，而不必执行 `install` 或 `update` 命令。
|
||||
|
||||
此外，它可以打印一个优化过的，符合 PSR-0/4 规范的类的索引，这也是出于对性能的可考虑。在大型的应用中会有许多类文件，而 autoloader 会占用每个请求的很大一部分时间，使用 classmaps 或许在开发时不太方便，但它在保证性能的前提下，仍然可以获得 PSR-0/4 规范带来的便利。
|
||||
|
||||
<a name="dump-autoload-Options"></a>
|
||||
### 打印自动加载索引-参数
|
||||
|
||||
* **--optimize (-o):** 转换 PSR-0/4 autoloading 到 classmap 获得更快的载入速度。这特别适用于生产环境，但可能需要一些时间来运行，因此它目前不是默认设置。
|
||||
* **--no-dev:** 禁用 autoload-dev 规则。
|
||||
|
||||
<a name="licenses"></a>
|
||||
## 查看许可协议 `licenses`
|
||||
|
||||
列出已安装的每个包的名称、版本、许可协议。可以使用 `--format=json` 参数来获取 JSON 格式的输出。
|
||||
|
||||
<a name="run-script"></a>
|
||||
## 执行脚本 `run-script`
|
||||
|
||||
你可以运行此命令来手动执行 [脚本](articles/scripts.md)，只需要指定脚本的名称，可选的 `--no-dev` 参数允许你禁用开发者模式。
|
||||
|
||||
<a name="diagnose"></a>
|
||||
## 诊断 `diagnose`
|
||||
|
||||
如果你觉得发现了一个 bug 或是程序行为变得怪异，你可能需要运行 `diagnose` 命令，来帮助你检测一些常见的问题。
|
||||
|
||||
```sh
|
||||
php composer.phar diagnose
|
||||
```
|
||||
|
||||
<a name="archive"></a>
|
||||
## 归档 `archive`
|
||||
|
||||
此命令用来对指定包的指定版本进行 zip/tar 归档。它也可以用来归档你的整个项目，不包括 excluded/ignored（排除/忽略）的文件。
|
||||
|
||||
```sh
|
||||
php composer.phar archive vendor/package 2.0.21 --format=zip
|
||||
```
|
||||
|
||||
<a name="archive-Options"></a>
|
||||
### 归档-参数
|
||||
|
||||
* **--format (-f):** 指定归档格式：tar 或 zip（默认为 tar）。
|
||||
* **--dir:** 指定归档存放的目录（默认为当前目录）。
|
||||
|
||||
<a name="help"></a>
|
||||
## 获取帮助信息 `help`
|
||||
|
||||
使用 `help` 可以获取指定命令的帮助信息。
|
||||
|
||||
```sh
|
||||
php composer.phar help install
|
||||
```
|
||||
|
||||
<a name="Environment-variables"></a>
|
||||
## 环境变量
|
||||
|
||||
你可以设置一些环境变量来覆盖默认的配置。建议尽可能的在 `composer.json` 的 `config` 字段中设置这些值，而不是通过命令行设置环境变量。值得注意的是环境变量中的值，将始终优先于 `composer.json` 中所指定的值。
|
||||
|
||||
<a name="COMPOSER"></a>
|
||||
### COMPOSER
|
||||
|
||||
环境变量 `COMPOSER` 可以为 `composer.json` 文件指定其它的文件名。
|
||||
|
||||
例如：
|
||||
|
||||
```sh
|
||||
COMPOSER=composer-other.json php composer.phar install
|
||||
```
|
||||
|
||||
<a name="COMPOSER_ROOT_VERSION"></a>
|
||||
### COMPOSER_ROOT_VERSION
|
||||
|
||||
通过设置这个环境变量，你可以指定 root 包的版本，如果程序不能从 VCS 上猜测出版本号，并且未在 `composer.json` 文件中申明。
|
||||
|
||||
<a name="COMPOSER_VENDOR_DIR"></a>
|
||||
### COMPOSER_VENDOR_DIR
|
||||
|
||||
通过设置这个环境变量，你可以指定 composer 将依赖安装在 `vendor` 以外的其它目录中。
|
||||
|
||||
<a name="COMPOSER_BIN_DIR"></a>
|
||||
### COMPOSER_BIN_DIR
|
||||
|
||||
通过设置这个环境变量，你可以指定 `bin`（[Vendor Binaries](articles/vendor-binaries.md)）目录到 `vendor/bin` 以外的其它目录。
|
||||
|
||||
<a name="http_proxy-or-HTTP_PROXY"></a>
|
||||
### http_proxy or HTTP_PROXY
|
||||
|
||||
如果你是通过 HTTP 代理来使用 Composer，你可以使用 `http_proxy` 或 `HTTP_PROXY` 环境变量。只要简单的将它设置为代理服务器的 URL。许多操作系统已经为你的服务设置了此变量。
|
||||
|
||||
建议使用 `http_proxy`（小写）或者两者都进行定义。因为某些工具，像 git 或 curl 将使用 `http_proxy` 小写的版本。另外，你还可以使用 `git config --global http.proxy <proxy url>` 来单独设置 git 的代理。
|
||||
|
||||
<a name="no_proxy"></a>
|
||||
### no_proxy
|
||||
|
||||
如果你是使用代理服务器，并且想要对某些域名禁用代理，就可以使用 `no_proxy` 环境变量。只需要输入一个逗号相隔的域名 *排除* 列表。
|
||||
|
||||
此环境变量接受域名、IP 以及 CIDR地址块。你可以将它限制到一个端口（例如：`:80`）。你还可以把它设置为 `*` 来忽略所有的 HTTP 代理请求。
|
||||
|
||||
<a name="HTTP_PROXY_REQUEST_FULLURI"></a>
|
||||
### HTTP_PROXY_REQUEST_FULLURI
|
||||
|
||||
如果你使用了 HTTP 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。
|
||||
|
||||
<a name="HTTPS_PROXY_REQUEST_FULLURI"></a>
|
||||
### HTTPS_PROXY_REQUEST_FULLURI
|
||||
|
||||
如果你使用了 HTTPS 代理，但它不支持 `request_fulluri` 标签，那么你应该设置这个环境变量为 `false` 或 `0` ，来防止 composer 从 `request_fulluri` 读取配置。
|
||||
|
||||
<a name="COMPOSER_HOME"></a>
|
||||
### COMPOSER_HOME
|
||||
|
||||
`COMPOSER_HOME` 环境变量允许你改变 Composer 的主目录。这是一个隐藏的、所有项目共享的全局目录（对本机的所有用户都可用）。
|
||||
|
||||
它在各个系统上的默认值分别为：
|
||||
- \*nix `/home/<user>/.composer`。
|
||||
- OSX `/Users/<user>/.composer`。
|
||||
- Windows `C:\Users\<user>\AppData\Roaming\Composer`。
|
||||
|
||||
<a name="COMPOSER_HOME-config.json"></a>
|
||||
#### COMPOSER_HOME/config.json
|
||||
|
||||
你可以在 `COMPOSER_HOME` 目录中放置一个 `config.json` 文件。在你执行 `install` 和 `update` 命令时，Composer 会将它与你项目中的 `composer.json` 文件进行合并。
|
||||
|
||||
该文件允许你为用户的项目设置 [配置信息](04-schema.md#config) 和 [资源库](05-repositories.md)。
|
||||
|
||||
若 _全局_ 和 _项目_ 存在相同配置项，那么项目中的 `composer.json` 文件拥有更高的优先级。
|
||||
|
||||
<a name="COMPOSER_CACHE_DIR"></a>
|
||||
### COMPOSER_CACHE_DIR
|
||||
|
||||
`COMPOSER_CACHE_DIR` 环境变量允许你设置 Composer 的缓存目录，这也可以通过 [`cache-dir`](04-schema.md#config) 进行配置。
|
||||
|
||||
它在各个系统上的默认值分别为：
|
||||
- \*nix and OSX `$COMPOSER_HOME/cache`。
|
||||
- Windows `C:\Users\<user>\AppData\Local\Composer` 或 `%LOCALAPPDATA%/Composer`。
|
||||
|
||||
<a name="COMPOSER_PROCESS_TIMEOUT"></a>
|
||||
### COMPOSER_PROCESS_TIMEOUT
|
||||
|
||||
这个环境变量控制着 Composer 执行命令的等待时间（例如：git 命令）。默认值为300秒（5分钟）。
|
||||
|
||||
<a name="COMPOSER_DISCARD_CHANGES"></a>
|
||||
### COMPOSER_DISCARD_CHANGES
|
||||
|
||||
这个环境变量控制着 discard-changes [config option](04-schema.md#config)。
|
||||
|
||||
<a name="COMPOSER_NO_INTERACTION"></a>
|
||||
### COMPOSER_NO_INTERACTION
|
||||
|
||||
如果设置为1，这个环境变量将使 Composer 在执行每一个命令时都放弃交互，相当于对所有命令都使用了 `--no-interaction`。可以在搭建 *虚拟机/持续集成服务器* 时这样设置。
|
||||
|
||||
← [库（资源包）](02-libraries.md) | [架构](04-schema.md) →
|
||||
|
|
@ -0,0 +1,777 @@
|
|||
<a name="composer.json"></a>
|
||||
# composer.json 架构
|
||||
|
||||
本章将解释所有在 `composer.json` 中可用的字段。
|
||||
|
||||
---
|
||||
|
||||
- [composer.json](#composer.json)
|
||||
- [JSON schema](#JSON-schema)
|
||||
- [Root 包](#Root-Package)
|
||||
- [属性](#Properties)
|
||||
- [包名 `name`](#package-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 <span>(root-only)</span>](#require-dev)
|
||||
- [conflict](#conflict)
|
||||
- [replace](#replace)
|
||||
- [provide](#provide)
|
||||
- [suggest](#suggest)
|
||||
- [autoload](#autoload)
|
||||
- [PSR-0](#PSR-0)
|
||||
- [Classmap](#Classmap)
|
||||
- [Files](#Files)
|
||||
- [include-path](#include-path)
|
||||
- [target-dir](#target-dir)
|
||||
- [minimum-stability <span>(root-only)</span>](#minimum-stability)
|
||||
- [prefer-stable <span>(root-only)</span>](#prefer-stable)
|
||||
- [repositories <span>(root-only)</span>](#repositories)
|
||||
- [config <span>(root-only)</span>](#config)
|
||||
- [scripts <span>(root-only)</span>](#scripts)
|
||||
- [extra](#extra)
|
||||
- [bin](#bin)
|
||||
- [archive](#archive)
|
||||
|
||||
---
|
||||
|
||||
<a name="JSON-schema"></a>
|
||||
## 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).
|
||||
|
||||
<a name="Root-Package"></a>
|
||||
## Root 包
|
||||
|
||||
“root 包”是指由 `composer.json` 定义的在你项目根目录的包。这是 `composer.json` 定义你项目所需的主要条件。（简单的说，你自己的项目就是一个 root 包）
|
||||
|
||||
某些字段仅适用于“root 包”上下文。 `config` 字段就是其中一个例子。只有“root 包”可以定义。在依赖包中定义的 `config` 字段将被忽略，这使得 `config` 字段只有“root 包”可用（`root-only`）。
|
||||
|
||||
如果你克隆了其中的一个依赖包，直接在其上开始工作，那么它就变成了“root 包”。与作为他人的依赖包时使用相同的 `composer.json` 文件，但上下文发生了变化。
|
||||
|
||||
> **注意：** 一个资源包是不是“root 包”，取决于它的上下文。
|
||||
> 例：如果你的项目依赖 `monolog` 库，那么你的项目就是“root 包”。
|
||||
> 但是，如果你从 GitHub 上克隆了 `monolog` 为它修复 bug，
|
||||
> 那么此时 `monolog` 就是“root 包”。
|
||||
|
||||
<a name="Properties"></a>
|
||||
## 属性
|
||||
|
||||
<a name="package-name"></a>
|
||||
### 包名 `name`
|
||||
|
||||
包的名称，它包括供应商名称和项目名称，使用 `/` 分隔。
|
||||
|
||||
例：
|
||||
|
||||
* monolog/monolog
|
||||
* igorw/event-source
|
||||
|
||||
对于需要发布的包（库），这是必须填写的。
|
||||
|
||||
<a name="description"></a>
|
||||
### 描述 `description`
|
||||
|
||||
一个包的简短描述。通常这个最长只有一行。
|
||||
|
||||
对于需要发布的包（库），这是必须填写的。
|
||||
|
||||
<a name="version"></a>
|
||||
### 版本 `version`
|
||||
|
||||
`version` 不是必须的，并且建议忽略（见下文）。
|
||||
|
||||
它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式， `-dev`、`-patch`、`-alpha`、`-beta` 或 `-RC` 这些后缀是可选的。在后缀之后也可以再跟上一个数字。
|
||||
|
||||
例：
|
||||
|
||||
- 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`。
|
||||
|
||||
> **注意：** Packagist 使用 VCS 仓库，
|
||||
> 因此 `version` 定义的版本号必须是真实准确的。
|
||||
> 自己手动指定的 `version`，最终有可能在某个时候因为人为错误造成问题。
|
||||
|
||||
<a name="type"></a>
|
||||
### 安装类型 `type`
|
||||
|
||||
包的安装类型，默认为 `library`。
|
||||
|
||||
包的安装类型，用来定义安装逻辑。如果你有一个包需要一个特殊的逻辑，你可以设定一个自定义的类型。这可以是一个 `symfony-bundle`，一个 `wordpress-plugin` 或者一个 `typo3-module`。这些类型都将是具体到某一个项目，而对应的项目将要提供一种能够安装该类型包的安装程序。
|
||||
|
||||
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:** 一个安装类型为 `composer-plugin` 的包，它有一个自定义安装类型，可以为其它包提供一个 installler。详细请查看 [自定义安装类型](articles/custom-installers.md)。
|
||||
|
||||
仅在你需要一个自定义的安装逻辑时才使用它。建议忽略这个属性，采用默认的 `library`。
|
||||
|
||||
<a name="keywords"></a>
|
||||
### 关键字 `keywords`
|
||||
|
||||
该包相关的关键词的数组。这些可用于搜索和过滤。
|
||||
|
||||
实例：
|
||||
|
||||
- logging
|
||||
- events
|
||||
- database
|
||||
- redis
|
||||
- templating
|
||||
|
||||
可选。
|
||||
|
||||
<a name="homepage"></a>
|
||||
### 项目主页 `homepage`
|
||||
|
||||
该项目网站的 URL 地址。
|
||||
|
||||
可选。
|
||||
|
||||
<a name="time"></a>
|
||||
### 版本发布时间 `time`
|
||||
|
||||
版本发布时间。
|
||||
|
||||
必须符合 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM:SS` 格式。
|
||||
|
||||
可选。
|
||||
|
||||
<a name="license"></a>
|
||||
### 许可协议 `license`
|
||||
|
||||
包的许可协议，它可以是一个字符串或者字符串数组。
|
||||
|
||||
最常见的许可协议的推荐写法（按字母排序）：
|
||||
|
||||
- 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/)。
|
||||
|
||||
对于闭源软件，你必须使用 `"proprietary"` 协议标识符。
|
||||
|
||||
一个例：
|
||||
|
||||
```json
|
||||
{
|
||||
"license": "MIT"
|
||||
}
|
||||
```
|
||||
|
||||
对于一个包，当允许在多个许可协议间进行选择时（"disjunctive license"），这些协议标识符可以被指定为数组。
|
||||
|
||||
多协议的一个例：
|
||||
|
||||
```json
|
||||
{
|
||||
"license": [
|
||||
"LGPL-2.1",
|
||||
"GPL-3.0+"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
另外它们也可以由 "or" 分隔，并写在括号中：
|
||||
|
||||
```json
|
||||
{
|
||||
"license": "(LGPL-2.1 or GPL-3.0+)"
|
||||
}
|
||||
```
|
||||
|
||||
同样，当有多个许可协议需要结合使用时（"conjunctive license"），它们应该被 "and" 分隔，并写在括号中。
|
||||
|
||||
<a name="authors"></a>
|
||||
### 作者 `authors`
|
||||
|
||||
包的作者。这是一个对象数组。
|
||||
|
||||
这个对象必须包含以下属性：
|
||||
|
||||
* **name:** 作者的姓名，通常使用真名。
|
||||
* **email:** 作者的 email 地址。
|
||||
* **homepage:** 作者主页的 URL 地址。
|
||||
* **role:** 该作者在此项目中担任的角色（例：开发人员 或 翻译）。
|
||||
|
||||
一个实例：
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
可选，但强烈建议提供此内容。
|
||||
|
||||
<a name="support"></a>
|
||||
### 支持 `support`
|
||||
|
||||
获取项目支持的向相关信息对象。
|
||||
|
||||
这个对象必须包含以下属性：
|
||||
|
||||
* **email:** 项目支持 email 地址。
|
||||
* **issues:** 跟踪问题的 URL 地址。
|
||||
* **forum:** 论坛地址。
|
||||
* **wiki:** Wiki 地址。
|
||||
* **irc:** IRC 聊天频道地址，类似于 irc://server/channel。
|
||||
* **source:** 网址浏览或下载源。
|
||||
|
||||
一个实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"support": {
|
||||
"email": "support@example.org",
|
||||
"irc": "irc://irc.freenode.org/composer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
可选。
|
||||
|
||||
<a name="Package-links"></a>
|
||||
### Package links
|
||||
|
||||
下面提到的所有对象，都应该是 包名 到 [版本](01-basic-usage.md#Package-Versions) 的映射对象。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "1.0.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
所有的这些都是可选的。
|
||||
|
||||
`require` 和 `require-dev` 还支持稳定性标签（@，仅针对“root 包”）。这允许你在 [minimum-stability](#minimum-stability) 设定的范围外做进一步的限制或扩展。例：如果你想允许依赖一个不稳定的包，你可以在一个包的版本约束后使用它，或者是一个空的版本约束内使用它。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "1.0.*@beta",
|
||||
"acme/foo": "@dev"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你的依赖之一，有对另一个不稳定包的依赖，你最好在 require 中显示的定义它，并带上足够详细的稳定性标识。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"doctrine/doctrine-fixtures-bundle": "dev-master",
|
||||
"doctrine/data-fixtures": "@dev"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`require` 和 `require-dev` 还支持对 dev（开发）版本的明确引用（即：版本控制系统中的提交编号 commit），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 `#<ref>` 的标识。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7",
|
||||
"acme/foo": "1.0.x-dev#abc123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **注意：** 虽然这有时很方便，但不应该长期在你的包中使用，因为它有一个技术上的限制。
|
||||
> composer.json 将仍然在哈希值之前指定的分支名称读取元数据，
|
||||
> 正因为如此，在某些情况下，它不会是一个实用的解决方法，
|
||||
> 如果可能，你应该总是尝试切换到拥有标签的版本。
|
||||
|
||||
它也可以应用于行内别名，这样它将匹配一个约束，否则不会。更多信息请参考 [别名](articles/aliases.md)。
|
||||
|
||||
<a name="require"></a>
|
||||
#### require
|
||||
|
||||
必须的软件包列表，除非这些依赖被满足，否则不会完成安装。
|
||||
|
||||
<a name="require-dev"></a>
|
||||
#### require-dev <span>(root-only)</span>
|
||||
|
||||
这个列表是为开发或测试等目的，额外列出的依赖。“root 包”的 require-dev 默认是会被安装的。然而 `install` 或 `update` 支持使用 `--no-dev` 参数来跳过 `require-dev` 字段中列出的包。
|
||||
|
||||
<a name="conflict"></a>
|
||||
#### conflict
|
||||
|
||||
此列表中的包与当前包的这个版本冲突。它们将不允许同时被安装。
|
||||
|
||||
请注意，在 `conflict` 中指定类似于 `<1.0, >= 1.1` 的版本范围时，这表示它与小于1.0 *并且* 同时大等于1.1的版本冲突，这很可能不是你想要的。在这种情况下你可能想要表达的是 `<1.0 | >= 1.1` 。
|
||||
|
||||
<a name="replace"></a>
|
||||
#### replace
|
||||
|
||||
这个列表中的包将被当前包取代。这使你可以 fork 一个包，以不同的名称和版本号发布，同时要求依赖于原包的其它包，在这之后依赖于你 fork 的这个包，因为它取代了原来的包。
|
||||
|
||||
这对于创建一个内部包含子包的主包也非常的有用。例如 symfony/symfony 这个主包，包含了所有 Symfony 的组件，而这些组件又可以作为单独的包进行发布。如果你 require 了主包，那么它就会自动完成其下各个组件的任务，因为主包取代了子包。
|
||||
|
||||
注意，在使用上述方法取代子包时，通常你应该只对子包使用 `self.version` 这一个版本约束，以确保主包仅替换掉子包的准确版本，而不是任何其他版本。
|
||||
|
||||
<a name="provide"></a>
|
||||
#### 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`.
|
||||
|
||||
<a name="suggest"></a>
|
||||
### suggest
|
||||
|
||||
建议安装的包，它们增强或能够与当前包良好的工作。这些只是信息，并显示在依赖包安装完成之后，给你的用户一个建议，他们可以添加更多的包。
|
||||
|
||||
格式如下，版本约束变成了描述信息。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"suggest": {
|
||||
"monolog/monolog": "Allows more advanced logging of the application flow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="autoload"></a>
|
||||
### autoload
|
||||
|
||||
PHP autoloader 的自动加载映射。
|
||||
|
||||
Currently [`PSR-0`](http://www.php-fig.org/psr/psr-0/) autoloading,
|
||||
[`PSR-4`](http://www.php-fig.org/psr/psr-4/) autoloading, `classmap` generation and
|
||||
`files` includes are supported. PSR-4 is the recommended way though since it offers
|
||||
greater ease of use (no need to regenerate the autoloader when you add classes).
|
||||
|
||||
#### PSR-4
|
||||
|
||||
Under the `psr-4` key you define a mapping from namespaces to paths, relative to the
|
||||
package root. When autoloading a class like `Foo\\Bar\\Baz` a namespace prefix
|
||||
`Foo\\` pointing to a directory `src/` means that the autoloader will look for a
|
||||
file named `src/Bar/Baz.php` and include it if present. Note that as opposed to
|
||||
the older PSR-0 style, the prefix (`Foo\\`) is **not** present in the file path.
|
||||
|
||||
Namespace prefixes must end in `\\` to avoid conflicts between similar prefixes.
|
||||
For example `Foo` would match classes in the `FooBar` namespace so the trailing
|
||||
backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct.
|
||||
|
||||
The PSR-4 references are all combined, during install/update, into a single
|
||||
key => value array which may be found in the generated file
|
||||
`vendor/composer/autoload_psr4.php`.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-4": {
|
||||
"Monolog\\": "src/",
|
||||
"Vendor\\Namespace\\": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you need to search for a same prefix in multiple directories,
|
||||
you can specify them as an array as such:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-4": { "Monolog\\": ["src/", "lib/"] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you want to have a fallback directory where any namespace will be looked for,
|
||||
you can use an empty prefix like:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-4": { "": "src/" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="PSR-0"></a>
|
||||
#### PSR-0
|
||||
|
||||
在 `psr-0` key 下你定义了一个命名空间到实际路径的映射（相对于包的根目录）。注意，这里同样支持 PEAR-style 方式的约定（与命名空间不同，PEAR 类库在类名上采用了下划线分隔）。
|
||||
|
||||
请注意，命名空间的申明应该以 `\\` 结束，以确保 autoloader 能够准确响应。例： `Foo` 将会与 `FooBar` 匹配，然而以反斜杠结束就可以解决这样的问题， `Foo\\` 和 `FooBar\\` 将会被区分开来。
|
||||
|
||||
在 install/update 过程中，PSR-0 引用都将被结合为一个单一的键值对数组，存储至 `vendor/composer/autoload_namespaces.php` 文件中。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-0": {
|
||||
"Monolog\\": "src/",
|
||||
"Vendor\\Namespace\\": "src/",
|
||||
"Vendor_Namespace_": "src/"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你需要搜索多个目录中一个相同的前缀，你可以将它们指定为一个数组，例：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-0": { "Monolog\\": ["src/", "lib/"] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
PSR-0 方式并不仅限于申明命名空间，也可以是精确到类级别的指定。这对于只有一个类在全局命名空间的类库是非常有用的（如果 php 源文件也位于包的根目录）。例如，可以这样申明：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-0": { "UniqueGlobalClass": "" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你想设置一个目录作为任何命名空间的备用目录，你可以使用空的前缀，像这样：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-0": { "": "src/" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="Classmap"></a>
|
||||
#### Classmap
|
||||
|
||||
`classmap` 引用的所有组合，都会在 install/update 过程中生成，并存储到 `vendor/composer/autoload_classmap.php` 文件中。这个 map 是经过扫描指定目录（同样支持直接精确到文件）中所有的 `.php` 和 `.inc` 文件里内置的类而得到的。
|
||||
|
||||
你可以用 classmap 生成支持支持自定义加载的不遵循 PSR-0/4 规范的类库。要配置它指向需要的目录，以便能够准确搜索到类文件。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"classmap": ["src/", "lib/", "Something.php"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="Files"></a>
|
||||
#### Files
|
||||
|
||||
如果你想要明确的指定，在每次请求时都要载入某些文件，那么你可以使用 'files' autoloading。通常作为函数库的载入方式（而非类库）。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"files": ["src/MyLibrary/functions.php"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### autoload-dev <span>(root-only)</span>
|
||||
|
||||
This section allows to define autoload rules for development purposes.
|
||||
|
||||
Classes needed to run the test suite should not be included in the main autoload
|
||||
rules to avoid polluting the autoloader in production and when other people use
|
||||
your package as a dependency.
|
||||
|
||||
Therefore, it is a good idea to rely on a dedicated path for your unit tests
|
||||
and to add it within the autoload-dev section.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-4": { "MyLibrary\\": "src/" }
|
||||
},
|
||||
"autoload-dev": {
|
||||
"psr-4": { "MyLibrary\\Tests\\": "tests/" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="include-path"></a>
|
||||
### include-path
|
||||
|
||||
> **不建议**：这是目前唯一支持传统项目的做法，所有新的代码都建议使用自动加载。
|
||||
> 这是一个过时的做法，但 Composer 将仍然保留这个功能。
|
||||
|
||||
一个追加到 PHP `include_path` 中的列表。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"include-path": ["lib/"]
|
||||
}
|
||||
```
|
||||
|
||||
可选。
|
||||
|
||||
<a name="target-dir"></a>
|
||||
### target-dir
|
||||
|
||||
> **DEPRECATED**: This is only present to support legacy PSR-0 style autoloading,
|
||||
> and all new code should preferably use PSR-4 without target-dir and projects
|
||||
> using PSR-0 with PHP namespaces are encouraged to migrate to PSR-4 instead.
|
||||
|
||||
定义当前包安装的目标文件夹。
|
||||
|
||||
若某个包的根目录，在它申明的命名空间之下，将不能正确的使用自动加载。而 `target-dir` 解决了这个问题。
|
||||
|
||||
Symfony 就是一个例子。它有一些独立的包作为组件。Yaml 组件就放在 `Symfony\Component\Yaml` 目录下，然而这个包的根目录实际上是 `Yaml`。为了使自动加载成为可能，我们需要确保它不会被安装到 `vendor/symfony/yaml`，而是安装到 `vendor/symfony/yaml/Symfony/Component/Yaml`，从而使 Symfony 定义的 autoloader 可以从 `vendor/symfony/yaml` 加载它。
|
||||
|
||||
要做到这一点 `autoload` 和 `target-dir` 应该定义如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-0": { "Symfony\\Component\\Yaml\\": "" }
|
||||
},
|
||||
"target-dir": "Symfony/Component/Yaml"
|
||||
}
|
||||
```
|
||||
|
||||
可选。
|
||||
|
||||
<a name="minimum-stability"></a>
|
||||
### minimum-stability <span>(root-only)</span>
|
||||
|
||||
这定义了通过稳定性过滤包的默认行为。默认为 `stable`（稳定）。因此如果你依赖于一个 `dev`（开发）包，你应该明确的进行定义。
|
||||
|
||||
对每个包的所有版本都会进行稳定性检查，而低于 `minimum-stability` 所设定的最低稳定性的版本，将在解决依赖关系时被忽略。对于个别包的特殊稳定性要求，可以在 `require` 或 `require-dev` 中设定（请参考 [Package links](#Package-links)）。
|
||||
|
||||
可用的稳定性标识（按字母排序）：`dev`、`alpha`、`beta`、`RC`、`stable`。
|
||||
|
||||
<a name="prefer-stable"></a>
|
||||
### prefer-stable <span>(root-only)</span>
|
||||
|
||||
当此选项被激活时，Composer 将优先使用更稳定的包版本。
|
||||
|
||||
使用 `"prefer-stable": true` 来激活它。
|
||||
|
||||
<a name="repositories"></a>
|
||||
### repositories <span>(root-only)</span>
|
||||
|
||||
使用自定义的包资源库。
|
||||
|
||||
默认情况下 composer 只使用 packagist 作为包的资源库。通过指定资源库，你可以从其他地方获取资源包。
|
||||
|
||||
Repositories 并不是递归调用的，只能在“Root包”的 `composer.json` 中定义。附属包中的 `composer.json` 将被忽略。
|
||||
|
||||
支持以下类型的包资源库：
|
||||
|
||||
* **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)。
|
||||
|
||||
实例：
|
||||
|
||||
```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 上的包。
|
||||
|
||||
<a name="config"></a>
|
||||
### config <span>(root-only)</span>
|
||||
|
||||
下面的这一组选项，仅用于项目。
|
||||
|
||||
支持以下选项：
|
||||
|
||||
* **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", "ssh"]`。从 github.com 克隆时使用的协议优先级清单，因此默认情况下将优先使用 git 协议进行克隆。你可以重新排列它们的次序，例如，如果你的网络有代理服务器或 git 协议的效率很低，你就可以提升 https 协议的优先级。
|
||||
* **github-oauth:** 一个域名和 oauth keys 的列表。
|
||||
例如：使用 `{"github.com": "oauthtoken"}` 作为此选项的值，
|
||||
将使用 `oauthtoken` 来访问 github 上的私人仓库，并绕过 low IP-based rate 的 API 限制。
|
||||
[关联知识](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
|
||||
关于如何获取 GitHub 的 OAuth token。
|
||||
* **vendor-dir:** 默认为 `vendor`。通过设置你可以安装依赖到不同的目录。
|
||||
* **bin-dir:** 默认为 `vendor/bin`。如果一个项目包含二进制文件，它们将被连接到这个目录。
|
||||
* **cache-dir:** unix 下默认为 `$home/cache`，Windows 下默认为 `C:\Users\<user>\AppData\Local\Composer`。用于存储 composer 所有的缓存文件。相关信息请查看 [COMPOSER_HOME](03-cli.md#composer-home)。
|
||||
* **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 的后缀，当设置为空时将会产生一个随机的字符串。
|
||||
* **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.
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"bin-dir": "bin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="scripts"></a>
|
||||
### scripts <span>(root-only)</span>
|
||||
|
||||
Composer 允许你在安装过程中的各个阶段挂接脚本。
|
||||
|
||||
更多细节和案例请查看 [脚本](articles/scripts.md)。
|
||||
|
||||
<a name="extra"></a>
|
||||
### extra
|
||||
|
||||
任意的，供 `scripts` 使用的额外数据。.
|
||||
|
||||
这可以是几乎任何东西。若要从脚本事件访问处理程序，你可以这样做：
|
||||
|
||||
```php
|
||||
$extra = $event->getComposer()->getPackage()->getExtra();
|
||||
```
|
||||
|
||||
可选。
|
||||
|
||||
<a name="bin"></a>
|
||||
### bin
|
||||
|
||||
该属性用于标注一组应被视为二进制脚本的文件，他们会被软链接到（config 对象中的）`bin-dir` 属性所标注的目录，以供其他依赖包调用。
|
||||
|
||||
详细请查看 [Vendor Binaries](articles/vendor-binaries.md)。
|
||||
|
||||
可选。
|
||||
|
||||
<a name="archive"></a>
|
||||
### archive
|
||||
|
||||
这些选项在创建包存档时使用。
|
||||
|
||||
支持以下选项：
|
||||
|
||||
* **exclude:** 允许设置一个需要被排除的路径的列表。使用与 .gitignore 文件相同的语法。一个前导的（!）将会使其变成白名单而无视之前相同目录的排除设定。前导斜杠只会在项目的相对路径的开头匹配。星号为通配符。
|
||||
|
||||
实例：
|
||||
|
||||
```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`。
|
||||
|
||||
可选。
|
||||
|
||||
← [命令行](03-cli.md) | [资源库](05-repositories.md) →
|
||||
|
|
@ -0,0 +1,509 @@
|
|||
<a name="Repositories"></a>
|
||||
# 资源库
|
||||
|
||||
本章将解释包和库的概念，什么样的存储库是可用的，以及它们如何工作。
|
||||
|
||||
---
|
||||
|
||||
- [资源库](#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)
|
||||
|
||||
---
|
||||
|
||||
<a name="Concepts"></a>
|
||||
## 概述
|
||||
|
||||
在此之前，我们看到存在不同类型的资源库，我们需要了解一些基本概念，以理解 Composer 是如何构建于其上的。
|
||||
|
||||
<a name="Package"></a>
|
||||
### 包
|
||||
|
||||
Composer 是一个依赖管理工具。它在本地安装一些资源包。一个包本质上就是一个包含东西的目录。通常情况下它存储 PHP 代码，但在理论上它可以是任何东西。并且它包含一个描述，其中有一个名称和一个版本号，这个名称和版本号用于识别该包。
|
||||
|
||||
事实上，在 composer 内部将每一个版本都视为一个单独的包。尽管在你使用 composer 时这种区别无关紧要，但当你想改变它时，这就显得至关重要。
|
||||
|
||||
除了名称和版本号，还存放了有用的元数据。与安装关系最密切的是 source 信息，它申明了在哪里可以获得资源包的内容。包数据指向包内容，并有两种指向方式：dist 和 source。
|
||||
|
||||
**Dist:** dist 指向一个存档，该存档是对一个资源包的某个版本的数据进行的打包。通常是已经发行的稳定版本。
|
||||
|
||||
**Source:** source 指向一个开发中的源。这通常是一个源代码仓库，例如 git。当你想要对下载下来的资源包进行修改时，可以这样获取。
|
||||
|
||||
你可以使用其中任意一个，或者同时使用。这取决于其它的一些因素，比如“user-supplied 选项”和“包的稳定性”，前者将会被优先考虑。
|
||||
|
||||
<a name="Repository"></a>
|
||||
### 资源库
|
||||
|
||||
一个资源库是一个包的来源。它是一个 packages/versions 的列表。Composer 将查看所有你定义的 repositories 以找到你项目需要的资源包。
|
||||
|
||||
默认情况下已经将 Packagist.org 注册到 Composer。你可以在 `composer.json` 中申明更多的资源库，把它们加入你的项目中。
|
||||
|
||||
资源库的定义仅可用于“root 包”，而在你依赖的包中定义的资源库将不会被加载。如果你想了解其中的原因，请阅读 [FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md)。
|
||||
|
||||
<a name="Types"></a>
|
||||
## Types
|
||||
|
||||
<a name="Composer"></a>
|
||||
### Composer
|
||||
|
||||
主资源库的类型为 `composer`。它使用一个单一的 `packages.json` 文件，包含了所有的资源包元数据。
|
||||
|
||||
这也是 packagist.org 所使用的资源类型。要引用一个 `composer` 资源库，只需要提供一个存放 `packages.json` 文件的 **目录路径**。比如要引用 `packagist.org` 下的 `/packages.json`，它的 URL 就应该是 `packagist.org`。而 `example.org/packages.json` 的 URL 应该是 `example.org`。
|
||||
|
||||
<a name="packages"></a>
|
||||
#### packages
|
||||
|
||||
唯一必须的字段是 `packages`。它的 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` 的内容，其内至少应包含以下信息：
|
||||
|
||||
* name
|
||||
* version
|
||||
* dist or source
|
||||
|
||||
这是一个最简单的包定义：
|
||||
|
||||
```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) 中介绍的字段。
|
||||
|
||||
<a name="notify-batch"></a>
|
||||
#### notify-batch
|
||||
|
||||
`notify-batch` 字段允许你指定一个 URL，它将会在用户安装每一个包时被调用。该 URL 可以是（与其资源库相同域名的）绝对路径或者一个完整的 URL 地址。
|
||||
|
||||
例如使用下面的值：
|
||||
|
||||
```json
|
||||
{
|
||||
"notify-batch": "/downloads/"
|
||||
}
|
||||
```
|
||||
|
||||
对于 `example.org/packages.json` 包含的 `monolog/monolog` 包，它将会发送一个 `POST` 请求到 `example.org/downloads/`，使用下面的 JSON request body：
|
||||
|
||||
```json
|
||||
{
|
||||
"downloads": [
|
||||
{"name": "monolog/monolog", "version": "1.2.1.0"},
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`version` 字段将包含标准化的版本号。
|
||||
|
||||
`notify-batch` 字段是可选的。
|
||||
|
||||
<a name="includes"></a>
|
||||
#### includes
|
||||
|
||||
对于较大的资源库，可以拆分 `packages.json` 为多个文件。`includes` 字段允许你引用这些额外的文件。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"includes": {
|
||||
"packages-2011.json": {
|
||||
"sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17"
|
||||
},
|
||||
"packages-2012-01.json": {
|
||||
"sha1": "897cde726f8a3918faf27c803b336da223d400dd"
|
||||
},
|
||||
"packages-2012-02.json": {
|
||||
"sha1": "26f911ad717da26bbcac3f8f435280d13917efa5"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
文件的 SHA-1 码允许它被缓存，仅在 hash 值改变时重新请求。
|
||||
|
||||
此字段是可选的。你也许并不需要它来自定义存储库。
|
||||
|
||||
<a name="provider-includes"></a>
|
||||
#### provider-includes and providers-url
|
||||
|
||||
的对于非常大的资源库，像 packagist.org 使用 so-called provider 文件是首选方法。`provider-includes` 字段允许你设置一个列表，来申明这个资源库提供的包名称。在这种情况下文件的哈希算法必须使用 sha256。
|
||||
|
||||
`providers-url` 描述了如何在服务器上找到这些 provider 文件。它是以资源库的根目录为起点的绝对路径。
|
||||
|
||||
实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"provider-includes": {
|
||||
"providers-a.json": {
|
||||
"sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c"
|
||||
},
|
||||
"providers-b.json": {
|
||||
"sha256": "b38372163fac0573053536f5b8ef11b86f804ea8b016d239e706191203f6efac"
|
||||
}
|
||||
},
|
||||
"providers-url": "/p/%package%$%hash%.json"
|
||||
}
|
||||
```
|
||||
|
||||
这些文件包含资源包的名称以及哈希值，以验证文件的完整性，例如：
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"acme/foo": {
|
||||
"sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82"
|
||||
},
|
||||
"acme/bar": {
|
||||
"sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
上述文件申明了 `acme/foo` 和 `acme/bar` 可以在这个资源库找到，通过加载由 `providers-url` 引用的文件，替换 `%package%` 为包名并且替换 `%hash%` 为 sha256 的值。这些文件本身只包含上文提到的 [packages](#packages) 的定义。
|
||||
|
||||
这些字段是可选的。你也许并不需要它们来自定义存储库。
|
||||
|
||||
<a name="stream-options"></a>
|
||||
#### stream options
|
||||
|
||||
`packages.json` 文件是用一个 PHP 流加载的。你可以使用 `options` 参数来设定额外的流信息。你可以设置任何有效的PHP 流上下文选项。更多相关信息请查看 [Context options and parameters](http://php.net/manual/en/context.php)。
|
||||
|
||||
<a name="VCS"></a>
|
||||
### VCS
|
||||
|
||||
VCS 表示版本控制系统。这包括像 git、svn 或 hg 这样的版本管理系统。Composer 有一个资源类型可以从这些系统安装软件包。
|
||||
|
||||
<a name="from-a-VCS"></a>
|
||||
#### 从 VCS 资源库加载一个包
|
||||
|
||||
这里有几个用例。最常见的是维护自己 fork 的第三方库。如果你在项目中使用某些库，并且你决定改变这些库内的某些东西，你会希望你项目中使用的是你自己的修正版本。如果这个库是在 GitHub 上（这种情况经常出现），你可以简单的 fork 它并 push 你的变更到这个 fork 里。在这之后你更新项目的 `composer.json` 文件，添加你的 fork 作为一个资源库，变更版本约束来指向你的自定义分支。关于版本约束的命名约定请查看 [库（资源包）](02-libraries.md)。
|
||||
|
||||
例如，假设你 fork 了 monolog，在 `bugfix` 分支修复了一个 bug：
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "https://github.com/igorw/monolog"
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
"monolog/monolog": "dev-bugfix"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
当你运行 `php composer.phar update` 时，你应该得到你修改的版本，而不是 packagist.org 上的 `monolog/monolog`。
|
||||
|
||||
注意，你不应该对包进行重命名，除非你真的打算摆脱原来的包，并长期的使用你自己的 fork。这样 Composer 就会正确获取你的包了。如果你确定要重命名这个包，你应该在默认分支（通常是 master 分支）上操作，而不是特性分支，因为包的名字取自默认分支。
|
||||
|
||||
如果其它包依赖你 fork 的这个分支，可能要对它做版本号的行内别名设置，才能够准确的识别版本约束。更多相关信息请查看 [别名](articles/aliases.md)。
|
||||
|
||||
<a name="Using-private"></a>
|
||||
#### 使用私有资源库
|
||||
|
||||
完全相同的解决方案，也可以让你使用你 GitHub 和 BitBucket 上的私人代码库进行工作：
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"vendor/my-private-repo": "dev-master"
|
||||
},
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "git@bitbucket.org:vendor/my-private-repo.git"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
唯一的要求是为一个 git 客户端安装 SSH 秘钥。
|
||||
|
||||
<a name="Git-alternatives"></a>
|
||||
#### Git 的备选方案
|
||||
|
||||
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)
|
||||
|
||||
为了从这些系统获取资源包，你必须安装对应的客户端，这可能是不方便的。基于这个原因，这里提供了 GitHub 和 BitBucket 的 API 的特殊支持，以便在无需安装版本控制系统的情况下获取资源包。在 VCS 资源库提供的 `dist` 中获取 zip 存档。
|
||||
|
||||
* **GitHub:** [github.com](https://github.com) (Git)
|
||||
* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)
|
||||
|
||||
VCS 驱动将基于 URL 自动检测版本库类型。但如果可能，你需要明确的指定一个 `git`、`svn` 或 `hg` 作为资源库类型，而不是 `vcs`。
|
||||
|
||||
If you set the `no-api` key to `true` on a github repository it will clone the
|
||||
repository as it would with any other git repository instead of using the
|
||||
GitHub API. But unlike using the `git` driver directly, composer will still
|
||||
attempt to use github's zip files.
|
||||
|
||||
<a name="Subversion-Options"></a>
|
||||
#### Subversion 选项
|
||||
|
||||
由于 Subversion 没有原生的分支和标签的概念，Composer 假设在默认情况下该代码位于 `$url/trunk`、`$url/branches` 和 `$url/tags` 内。如果你的存储库使用了不同的布局，你可以更改这些值。例如，如果你使用大写的名称，你可以像这样配置资源库：
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "http://svn.example.org/projectA/",
|
||||
"trunk-path": "Trunk",
|
||||
"branches-path": "Branches",
|
||||
"tags-path": "Tags"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
如果你的存储库目录中没有任何分支或标签文件夹，你可以将 `branches-path` 或 `tags-path` 设置为 `false`。
|
||||
|
||||
如果是一个位于子目录的包，例如， `/trunk/foo/bar/composer.json` 和 `/tags/1.0/foo/bar/composer.json`，那么你可以让 composer 通过 `"package-path"` 选项设置的子目录进行访问，在这个例子中可以将其设置为 `"package-path": "foo/bar/"`。
|
||||
|
||||
<a name="PEAR"></a>
|
||||
### PEAR
|
||||
|
||||
`pear` 类型资源库，使得从任何 PEAR 渠道安装资源包成为可能。Composer 将为所有此类型的包增加前缀（类似于 `pear-{渠道名称}/`）以避免冲突。而在之后使用别名时也增加前缀（如 `pear-{渠道别名}/`）。
|
||||
|
||||
例如使用 `pear2.php.net`：
|
||||
|
||||
```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`。
|
||||
|
||||
> **注意：** `pear` 类型的资源库对每个 requires 都要做完整的请求，因此可能大大降低安装速度。
|
||||
|
||||
<a name="Custom-vendor-alias"></a>
|
||||
#### 自定义供应商别名
|
||||
|
||||
通过自定义供应商名称，对 PEAR 渠道包进行别名是允许的。
|
||||
|
||||
例：
|
||||
|
||||
假设你有一个私人 PEAR 库，并希望使用 Composer 从 VCS 集成依赖。你的 PEAR 库包含以下资源包：
|
||||
|
||||
* `BasePackage`。
|
||||
* `IntermediatePackage` 依赖于 `BasePackage`。
|
||||
* `TopLevelPackage1` 和 `TopLevelPackage2` 都依赖于 `IntermediatePackage`。
|
||||
|
||||
如果没有一个供应商别名，Composer 将使用 PEAR 渠道名称作为包名的一部分：
|
||||
|
||||
* `pear-pear.foobar.repo/BasePackage`
|
||||
* `pear-pear.foobar.repo/IntermediatePackage`
|
||||
* `pear-pear.foobar.repo/TopLevelPackage1`
|
||||
* `pear-pear.foobar.repo/TopLevelPackage2`
|
||||
|
||||
假设之后的某个时间，你希望将你的 PEAR 包迁移，使用 Composer 资源库和命名方案，并且采用 `foobar` 作为供应商名称。这样之前使用 PEAR 包的项目将不会看到更新的资源包，因为它们有不同的供应商名称（`foobar/IntermediatePackage` 与 `pear-pear.foobar.repo/IntermediatePackage`）。
|
||||
|
||||
你可以通过从一开始就为 PEAR 资源库指定 `vendor-alias` 来避免这种情况的发生，以得到一个不会过时的包名。
|
||||
|
||||
为了说明这一点，下面的例子会从你的 PEAR 资源库中得到 `BasePackage`、`TopLevelPackage1` 和 `TopLevelPackage2` 资源包，并从 Github 资源库中获取 `IntermediatePackage` 资源包：
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{
|
||||
"type": "git",
|
||||
"url": "https://github.com/foobar/intermediate.git"
|
||||
},
|
||||
{
|
||||
"type": "pear",
|
||||
"url": "http://pear.foobar.repo",
|
||||
"vendor-alias": "foobar"
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
"foobar/TopLevelPackage1": "*",
|
||||
"foobar/TopLevelPackage2": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="Package"></a>
|
||||
### Package
|
||||
|
||||
如果你想使用一个项目，它无法通过上述任何一种方式支持 composer，你仍然可以使用 `package` 类型定义资源库。
|
||||
|
||||
基本上，你可以定义与 `packages.json` 中 `composer` 类型资源库相同的信息，但需要为每个这样的资源包分别定义。同样，至少应该包含以下信息：`name`、`version`、（`dist` 或 `source`）。
|
||||
|
||||
这是一个 smarty 模板引擎的例子：
|
||||
|
||||
```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.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
通常你不需要去定义 `source`，因为你并不是真的需要它。
|
||||
|
||||
> **注意：** 该资源库类型存在以下限制，因此应尽可能避免使用：
|
||||
>
|
||||
> - Composer 将不会更新资源包，除非你修改了 `version` 字段。
|
||||
> - Composer 将不会更新 commit references，因此如果你使用 `master` reference，将不得不删除该程序包以强制更新，并且将不得不面对一个不稳定的 lock 文件。
|
||||
|
||||
<a name="Hosting-your-own"></a>
|
||||
## Hosting your own
|
||||
|
||||
尽管大部分的时间，你大概都会把资源包放在 packagist.org 上，但这里还将告诉你一些用例，以便你可以自行托管资源库。
|
||||
|
||||
* **Private company packages:** 如果你是一个公司的职员，对公司内部的资源包使用 composer，你可能会想让这些包保持私有的状态。
|
||||
|
||||
* **Separate ecosystem:** 如果你的项目有自己的生态系统，并且自己的资源包不需要被其它项目所复用，你可能会想将它们从 packagist.org 上分离出来。其中一个例子就是 wordpress 的插件。
|
||||
|
||||
对于自行托管的软件包，建议使用 `composer` 类型资源库设置，它将提供最佳的性能。
|
||||
|
||||
这里有一些工具，可以帮助你创建 `composer` 类型的资源库。
|
||||
|
||||
<a name="Packagist"></a>
|
||||
### Packagist
|
||||
|
||||
packagist 的底层是开源的。这意味着你可以只安装你自己拷贝的 packagist，改造并使用它。这真的是很直接简单的事情。然而，由于其规模和复杂性，对于大多数中小型企业还是建议使用 Satis。
|
||||
|
||||
Packagist 是一个 Symfony2 应用程序，并且托管在 GitHub 上 [github.com/composer/packagist](https://github.com/composer/packagist)。它内部使用了 composer 并作为 VCS 资源库与 composer 用户之间的代理。它拥有所有 VCS 资源包的列表，定期重新抓取它们，并将其作为一个 composer 资源库。
|
||||
|
||||
要设置你的副本，只需要按照 [github.com/composer/packagist](https://github.com/composer/packagist) 的说明进行操作。
|
||||
|
||||
<a name="Satis"></a>
|
||||
### Satis
|
||||
|
||||
Satis 是一个静态的 `composer` 资源库生成器。它像是一个超轻量级的、基于静态文件的 packagist 版本。
|
||||
|
||||
你给它一个包含 `composer.json` 的存储库，定义好 VCS 和 资源库。它会获取所有你列出的包，并打印 `packages.json` 文件，作为 `composer` 类型的资源库。
|
||||
|
||||
更多详细信息请查看 [github.com/composer/satis](https://github.com/composer/satis) 和 [Satis article](articles/handling-private-packages-with-satis.md)。
|
||||
|
||||
<a name="Artifact"></a>
|
||||
### Artifact
|
||||
|
||||
在某些情况下，或许没有能力拥有之前提到的任何一种线上资源库。Typical example could be cross-organisation library exchange through built artifacts。当然大部分的时间他们都是私有的。为了简化维护，可以简单的使用 `artifact` 资源库类型，来引用一个包含那些私有包的 ZIP 存档的文件夹：
|
||||
|
||||
```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` 所在的根目录：
|
||||
|
||||
```sh
|
||||
unzip -l acme-corp-parser-10.3.5.zip
|
||||
|
||||
composer.json
|
||||
...
|
||||
```
|
||||
|
||||
如果有两个不同版本的资源包，它们都会被导入。当有一个新版本的存档被添加到 artifact 文件夹，并且你运行了 `update` 命令，该版本就会被导入，并且 Composer 将更新到最新版本。
|
||||
|
||||
<a name="Disabling-Packagist"></a>
|
||||
## 禁用 Packagist
|
||||
|
||||
你可以在 `composer.json` 中禁用默认的 Packagist 资源库。
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{
|
||||
"packagist": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
← [架构](04-schema.md) | [社区](06-community.md) →
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
# 社区
|
||||
|
||||
已经有很多人在使用 composer，也有很多人为它做出了贡献。
|
||||
|
||||
## 贡献
|
||||
|
||||
如果你想为 composer 做出自己的贡献，请阅读 [README](https://github.com/composer/composer)。
|
||||
|
||||
最重要的原则介绍如下：
|
||||
|
||||
> 所有贡献的代码 - 包括那些具有提交权限的人 - 必须通过一个 pull request 提交，并在合并前由核心开发人员的核准。
|
||||
>
|
||||
> Fork 这个项目，创建一个特性分支，并给我们发送 pull request。
|
||||
>
|
||||
> 为了与基础代码保持一致，你应该确保代码遵循 [编码规范](http://symfony.com/doc/2.0/contributing/code/standards.html)。
|
||||
|
||||
## IRC频道 / 邮件列表
|
||||
|
||||
邮件列表：[用户支持](http://groups.google.com/group/composer-users) / [开发者](http://groups.google.com/group/composer-dev)。
|
||||
|
||||
irc.freenode.org 上的 IRC 频道：[#composer](irc://irc.freenode.org/composer) （用户）/ [#composer-dev](irc://irc.freenode.org/composer-dev)（开发者）。
|
||||
|
||||
Stack Overflow 上有越来越多 [Composer 相关问题](http://stackoverflow.com/questions/tagged/composer-php)的收藏。
|
||||
|
||||
← [资源库](05-repositories.md)
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
<!--
|
||||
tagline: Alias branch names to versions
|
||||
-->
|
||||
|
||||
# 别名
|
||||
|
||||
## 为什么使用别名？
|
||||
|
||||
当你使用 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.*` 这个版本约束。
|
||||
|
||||
如果有人想要最新的 `dev-master` 版本，他们将会碰到一个问题：另一些依赖它的包可能使用了 `1.0.*` 这个版本约束，因此在 require 这个开发版本时将会产生冲突，因为 `dev-master` 不符合 `1.0.*` 的约束。
|
||||
|
||||
这时，就可以使用别名。
|
||||
|
||||
## 分支别名
|
||||
|
||||
`dev-master` 指向一个在你 VCS 项目上的主分支。有些用户会想要使用最新的开发版本，这是相当常见的情况。因此，Composer 允许你别名你的 `dev-master` 版本为一个 `1.0.x-dev` 的版本号。这是通过在 `composer.json` 文件中的 `extra` 下指定 `branch-alias` 字段来完成的：
|
||||
|
||||
```json
|
||||
{
|
||||
"extra": {
|
||||
"branch-alias": {
|
||||
"dev-master": "1.0.x-dev"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
此处的分支版本必须以 `dev-` 开头（不可比较的版本名称），对应的别名必须是可比较的开发版本名称（即，以数字开头，并以 `.x-dev` 结束）。`branch-alias` 所引用的分支必须是存在的。对于 `dev-master` 你需要在 `master` 分支上提交它。
|
||||
|
||||
其结果是，任何人都可以使用 `1.0.*` 版本约束来得到 `dev-master` 版本。
|
||||
|
||||
为了定义分支别名，你必须是需要别名的包的所有者。如果你想别名一个第三方包，而又不想 fork 它到自己的版本库，可以使用行内别名，我们在接下来就会提到它。
|
||||
|
||||
## 使用行内别名
|
||||
|
||||
分支别名是非常适合用于主开发分支的。但为了使用它们，你需要拥有对源码的控制权，并且你需要提交别名修改到你控制的版本库。
|
||||
|
||||
当你只想在本地项目中尝试一些依赖包的 bug 修正时，这并不是最好的方式。
|
||||
|
||||
出于这个原因，你可以在 `require` 和 `require-dev` 字段中直接别名你需要的包。比方说那你找到了 `monolog/monolog` 的一个 bug。你在 GitHub 上克隆了 [Monolog](https://github.com/Seldaek/monolog) 并在名为 `bugfix` 的分支上修正了一个问题。现在你想安装这个版本到你的本地项目。
|
||||
|
||||
你所使用的 `symfony/monolog-bundle` require 了 `monolog/monolog` 并约束了版本 `1.*`. 因此你需要让你的 `dev-bugfix` 满足该版本约束。
|
||||
|
||||
只要在你项目根目录的 `composer.json` 文件中加入以下内容：
|
||||
|
||||
```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`。
|
||||
|
||||
> **注意：** 如果要对一个资源包使用行内别名，这个别名（`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，请尝试将你的修复合并到上游分支。这将避免使用你资源包的用户出现问题。
|
||||
|
||||
|
|
@ -0,0 +1,165 @@
|
|||
<!--
|
||||
tagline: Modify the way certain types of packages are installed
|
||||
-->
|
||||
|
||||
# 设置和使用自定义安装类型
|
||||
|
||||
## 概要
|
||||
|
||||
有时需要在包的安装过程中执行其它的动作，例如：将它安装在默认的 `vendor` 以外的其它目录。
|
||||
|
||||
在这些情况下，你可以考虑创建一个自定义安装程序来处理特定的逻辑。
|
||||
|
||||
## 调用自定义安装程序
|
||||
|
||||
假设你的项目已经有了一个自定义的安装模块，那么如何根据 [安装类型][1] 正确调用你包文件中的安装程序就成为了一个问题。
|
||||
|
||||
> _参见见下一章，如何通过指令创建自定义安装程序。_
|
||||
|
||||
任何自定义安装程序都要通过 [type][1] 属性来识别。一旦被确认，它将完全覆盖默认的安装程序，并执行自己的安装逻辑。
|
||||
|
||||
一个实际用例：
|
||||
|
||||
> phpDocumentor 的特殊模板需要安装在 /vendor 以外的其它目录中。
|
||||
> 因此他们选择 `phpdocumentor-template` [安装类型][1] 并为此类型创建了一个插件，以便将他们的模板发送到正确的目录中。
|
||||
|
||||
在这样一个模板包的例子中 composer.json 将使用以下设置：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "phpdocumentor/template-responsive",
|
||||
"type": "phpdocumentor-template",
|
||||
"require": {
|
||||
"phpdocumentor/template-installer-plugin": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **重要提示：** 为了确保这个模板安装程序在安装模板包之前就已存在，模板包必须写入对此安装程序包的依赖。
|
||||
|
||||
## 创建一个安装程序
|
||||
|
||||
一个自定义安装程序通常是以 Composer 插件的形式存在，并包含有一个类，它实现了 [`Composer\Installer\InstallerInterface`][3] 这个接口。
|
||||
|
||||
一个基本的安装程序插件必须由3个文件组成：
|
||||
|
||||
1. 包文件：composer.json
|
||||
2. 插件类，例如：`My\Project\Composer\Plugin.php`，其中的类必须实现 `Composer\Plugin\PluginInterface` 接口。
|
||||
3. 安装程序类，例如：`My\Project\Composer\Installer.php`，其中的类必须实现 `Composer\Installer\InstallerInterface` 接口。
|
||||
|
||||
### composer.json
|
||||
|
||||
此处的包文件和普通资源包是相同的，但需要满足以下条件：
|
||||
|
||||
1. [type][1] 属性必须是 `composer-plugin`。
|
||||
2. [extra][2] 属性必须包含 `class` 元素，它定义了插件类的名称（包含命名空间）。如果这个包有多个插件类，可以使用数组的形式进行定义。
|
||||
|
||||
实例：
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 插件类
|
||||
|
||||
这个类定义了 Composer 的插件，它必须实现 [`Composer\Plugin\PluginInterface`][3] 这个接口。它可以在 `activate()` 方法中注册自定义安装程序。
|
||||
|
||||
这个类可以被放在任何位置、使用任何名字，只要能够根据 `extra.class` 中的定义被自动加载即可。
|
||||
|
||||
实例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义安装程序类
|
||||
|
||||
这个类用于执行自定义的安装过程，它必须实现 [`Composer\Installer\InstallerInterface`][4] 这个接口（或者继承了另一个实现此接口的安装程序类）。它将会对 [安装类型][1] 中定义的字符串执行 `supports()` 方法验证，一旦通过就采用对应的安装程序。
|
||||
|
||||
> **注意：** _请慎重选择你的 [安装类型][1] 名称，建议遵循这样的格式：`vendor-type`_。例如：`phpdocumentor-template`。
|
||||
|
||||
InstallerInterface 类定义了以下方法（请查阅源码以获得更详细的信息）：
|
||||
|
||||
* **supports()** 在这里测试你发布的这个安装程序名称是否通过 [安装类型][1] 匹配（参见示例）。只有正确匹配的资源包才会使用此安装程序进行安装。
|
||||
* **isInstalled()** 确定支持的资源包是否已安装。
|
||||
* **install()** 这里你可以定义在安装时需要执行的动作。
|
||||
* **update()** 这里你可以定义在更新时需要执行的动作。当 Composer 调用更新参数时这是必须的。
|
||||
* **uninstall()** 这里你可以定义在移除一个包时需要执行的动作。
|
||||
* **getInstallPath()** 这个方法需要返回一个资源包将要安装的位置。_相对于 composer.json 文件的位置。_
|
||||
|
||||
实例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这个例子演示了，简单的继承 [`Composer\Installer\LibraryInstaller`][5] 类来剥离 `phpdocumentor/template-` 前缀，并用剩余的部分重新组装了一个完全不同的安装路径。
|
||||
|
||||
> _并非安装在 `/vendor` 目录，任何使用这个安装程序的资源包，将被放置在 `/data/templates/<stripped name>` 目录中。_
|
||||
|
||||
[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
|
||||
|
|
@ -0,0 +1,202 @@
|
|||
<!--
|
||||
tagline: Host your own composer repository
|
||||
-->
|
||||
|
||||
# 用 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`.
|
||||
|
||||
Satis 是一个静态的 `composer` 代码库生成器。
|
||||
|
||||
## 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.
|
||||
|
||||
```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.
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
|
||||
{ "type": "vcs", "url": "http://svn.example.org/private/repo" },
|
||||
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
|
||||
],
|
||||
"require": {
|
||||
"company/package": "*",
|
||||
"company/package2": "*",
|
||||
"company/package3": "2.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Once you did this, you just run `php bin/satis build <configuration file> <build dir>`.
|
||||
For example `php bin/satis build config.json web/` would read the `config.json`
|
||||
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.
|
||||
|
||||
```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
|
||||
|
||||
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):
|
||||
|
||||
```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:
|
||||
|
||||
```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.
|
||||
|
||||
### 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`:
|
||||
|
||||
```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`:
|
||||
|
||||
```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`.
|
||||
|
|
@ -0,0 +1,133 @@
|
|||
<!--
|
||||
tagline: Modify and extend Composer's functionality
|
||||
-->
|
||||
|
||||
# 设置和使用插件
|
||||
|
||||
## 概述
|
||||
|
||||
你可能需要改变和扩展 Composer 加入自定义的功能。例如：如果你的环境对 Composer 的行为有特殊要求，而这并不适用于普通用户。又或者，你想使用 Composer 完成某些事情，而又不希望对普通用户造成影响。
|
||||
|
||||
在这些情况下，你可以考虑创建一个插件来处理特定的逻辑。
|
||||
|
||||
## 创建一个插件
|
||||
|
||||
一个插件就是一个普通的 Composer 资源包，插件的主要代码都位于这个包中，并且还可以依赖更多其它的资源包。
|
||||
|
||||
### 插件包
|
||||
|
||||
插件包内的文件和普通资源包相同，但必须满足下列要求：
|
||||
|
||||
1. [type][1] 属性必须是 `composer-plugin`。
|
||||
2. [extra][2] 属性必须包含一个元素 `class`，它定义了插件类的名称（包含命名空间）。如果一个包中含有多个插件，则可以使用数组来定义类名。
|
||||
|
||||
此外，你必须 require 一个特殊的资源包 `composer-plugin-api`，定义与你的插件相兼容的 composer plugin API 版本。目前 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]。使用这两个对象可以读取所有的配置，操作所有的内部对象和状态。
|
||||
|
||||
实例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 事件处理程序
|
||||
|
||||
此外，插件还可以实现 [`Composer\EventDispatcher\EventSubscriberInterface`][6] 接口，为了在插件载入后自动注册事件处理程序到 `EventDispatcher`。
|
||||
|
||||
插件可用事件如下：
|
||||
|
||||
* **COMMAND** 在载入插件的所有命令前被调用。它为你提供了访问程序输入输出的对象。
|
||||
* **PRE_FILE_DOWNLOAD** 在文件下载前被触发，它允许你在下载前根据目标 URL 操作 `RemoteFilesystem` 对象。
|
||||
|
||||
> 一个插件也可以订阅 [脚本事件][7]。
|
||||
|
||||
实例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用插件
|
||||
|
||||
插件包是优先被安装和加载的，在 Composer 启动时，如果在已安装资源包的当前项目列表中被找到，它们将被自动加载。此外，所有的插件包将被安装在 `COMPOSER_HOME` 目录，以便在 Composer 全局命令前载入，在操作本地项目前插件就已经被载入。
|
||||
|
||||
> 你可以通过 `--no-plugins` 选项让 composer 的命令禁用所有已经安装的插件。这或许是特别有用的，如果任何插件会导致错误，而你想要升级或卸载它。
|
||||
|
||||
[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
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
<!--
|
||||
tagline: Script are callbacks that are called before/after installing packages
|
||||
-->
|
||||
|
||||
# 脚本
|
||||
|
||||
## 什么是脚本？
|
||||
|
||||
一个脚本，在 Composer 中，可以是一个 PHP 回调（定义为静态方法）或任何命令行可执行的命令。脚本对于在 Composer 运行过程中，执行一个资源包的自定义代码或包专用命令是非常有用的。
|
||||
|
||||
> **注意：**只有在根包的 `composer.json` 中定义的脚本才会被执行。即便根包的外部依赖定义了其自身的脚本，Composer 也不会去执行这些额外的脚本。
|
||||
|
||||
<a name="event-names"></a>
|
||||
## 事件名称
|
||||
|
||||
Composer 在运行过程中将会触发以下事件：
|
||||
|
||||
|事件名称|详细说明
|
||||
|---|---
|
||||
| **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` 命令执行后触发。
|
||||
- **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` 命令前使用脚本，请确保它们已被定义在根包中。
|
||||
|
||||
## 定义脚本
|
||||
|
||||
在 `composer.json` 的根 JSON 对象中应该有一个名为 `"scripts"` 的属性，它包含有一系列的事件名称，以及对应的事件脚本。一个事件的脚本可以被定义为一个字符串（仅适用于单个脚本）或数组（单个或多个脚本）。
|
||||
|
||||
对于任何给定的事件：
|
||||
|
||||
- 脚本将按照事件和定义的顺序触发。
|
||||
- 一个脚本数组可以包含 PHP 回调和命令行可执行命令。
|
||||
- 由 PHP 类文件包含的回调，其存放的位置必须确保 Composer 能够正确的载入。
|
||||
|
||||
脚本定义实例：
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"post-update-cmd": "MyVendor\\MyClass::postUpdate",
|
||||
"post-package-install": [
|
||||
"MyVendor\\MyClass::postPackageInstall"
|
||||
],
|
||||
"post-install-cmd": [
|
||||
"MyVendor\\MyClass::warmCache",
|
||||
"phpunit -c app/"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
使用前面定义的例子，这里的 `MyVendor\MyClass` 类，就可以被使用来执行 PHP 的回调：
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace MyVendor;
|
||||
|
||||
use Composer\Script\Event;
|
||||
|
||||
class MyClass
|
||||
{
|
||||
public static function postUpdate(Event $event)
|
||||
{
|
||||
$composer = $event->getComposer();
|
||||
// do stuff
|
||||
}
|
||||
|
||||
public static function postPackageInstall(Event $event)
|
||||
{
|
||||
$installedPackage = $event->getOperation()->getPackage();
|
||||
// do stuff
|
||||
}
|
||||
|
||||
public static function warmCache(Event $event)
|
||||
{
|
||||
// make cache toasty
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
当一个事件被触发，Composer 的内部事件处理程序将接收一个 `Composer\Script\Event` 对象，这是传递给您的 PHP 回调的第一个参数。这个 `Event` 对象拥有一些 getter 方法来帮助你取得当前事件的上下文：
|
||||
|
||||
- `getComposer()`: 返回当前的 `Composer\Composer` 对象实例。
|
||||
- `getName()`: 返回事件名称的字符串。
|
||||
- `getIO()`: 返回当前的 输入\输出 流，它实现了 `Composer\IO\IOInterface` 接口，以便在控制台中使用。
|
||||
|
||||
## 手动运行脚本
|
||||
|
||||
如果你想手动运行事件脚本，可以使用下面的语法结构：
|
||||
|
||||
```sh
|
||||
composer run-script [--dev] [--no-dev] script
|
||||
```
|
||||
|
||||
例如 `composer run-script post-install-cmd` 将会运行所有 **post-install-cmd** 事件下定义的脚本。
|
||||
|
|
@ -0,0 +1,153 @@
|
|||
<!--
|
||||
tagline: Solving problems
|
||||
-->
|
||||
# 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:
|
||||
|
||||
```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:
|
||||
|
||||
```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):
|
||||
|
||||
```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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
## API rate limit and OAuth tokens
|
||||
|
||||
Because of GitHub's rate limits on their API it can happen that Composer prompts
|
||||
for authentication asking your username and password so it can go ahead with its work.
|
||||
|
||||
If you would prefer not to provide your GitHub credentials to Composer you can
|
||||
manually create a token using the following procedure:
|
||||
|
||||
1. [Create](https://github.com/settings/applications) an OAuth token on GitHub.
|
||||
[Read more](https://github.com/blog/1509-personal-api-tokens) on this.
|
||||
|
||||
2. Add it to the configuration running `composer config -g github-oauth.github.com <oauthtoken>`
|
||||
|
||||
Now Composer should install/update without asking for authentication.
|
||||
|
||||
## proc_open(): fork failed errors
|
||||
If composer shows proc_open() fork failed on some commands:
|
||||
|
||||
`PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar`
|
||||
|
||||
This could be happening because the VPS runs out of memory and has no Swap space enabled.
|
||||
|
||||
```sh
|
||||
free -m
|
||||
|
||||
total used free shared buffers cached
|
||||
Mem: 2048 357 1690 0 0 237
|
||||
-/+ buffers/cache: 119 1928
|
||||
Swap: 0 0 0
|
||||
```
|
||||
|
||||
To enable the swap you can use for example:
|
||||
|
||||
```sh
|
||||
/bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024
|
||||
/sbin/mkswap /var/swap.1
|
||||
/sbin/swapon /var/swap.1
|
||||
```
|
||||
|
|
@ -0,0 +1,110 @@
|
|||
<!--
|
||||
tagline: Expose command-line scripts from packages
|
||||
-->
|
||||
|
||||
# 二进制供应库和 `vendor/bin` 目录
|
||||
|
||||
## 什么是二进制供应库？
|
||||
|
||||
一个 Composer 资源包，想要传递给安装它的用户的任何命令行脚本，
|
||||
都应该被列入 `二进制供应库`。
|
||||
|
||||
如果一个资源包，含有不被用户所需要的其他脚本（比如构建或编译脚本）
|
||||
那么这些代码不应该被列入二进制供应库。
|
||||
|
||||
|
||||
## 如何定义？
|
||||
|
||||
它是通过在项目的 `composer.json` 里添加一个 `bin` 键定义的。
|
||||
它是以一种文件的数组的形式定义的，这样任何给定的项目
|
||||
都可以添加多个二进制文件。
|
||||
|
||||
```json
|
||||
{
|
||||
"bin": ["bin/my-script", "bin/my-other-script"]
|
||||
}
|
||||
```
|
||||
|
||||
## 在 composer.json 里定义二进制供应库的作用是？
|
||||
|
||||
对于任何 **依赖于** 该资源包的项目，
|
||||
它将引导 Composer 安装资源包里的二进制文件到 `vendor/bin` 目录。
|
||||
|
||||
这是一个便捷的途径来暴露有用的脚本，
|
||||
否则它们将会被隐藏在 `vendor/` 目录的深处。
|
||||
|
||||
|
||||
## 当 Composer 运行到定义了二进制供应库的 composer.json 文件时发生了什么？
|
||||
|
||||
对于被某个资源包直接定义的二进制供应库，什么也不会发生。
|
||||
|
||||
|
||||
## 当 Composer 运行到，列出了二进制供应库依赖关系的 composer.json 文件时发生了什么？
|
||||
|
||||
Composer 会检查所有依赖包里定义的二进制文件。
|
||||
并为每一个依赖的二进制库设立一个指向 `vendor/bin` 的软连接。
|
||||
|
||||
比如 `my-vendor/project-a` 资源包的二进制库就是这样安装的：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-vendor/project-a",
|
||||
"bin": ["bin/project-a-bin"]
|
||||
}
|
||||
```
|
||||
|
||||
在该 `composer.json` 上执行 `composer install` 命令，
|
||||
不会对 `bin/project-a-bin` 造成任何影响。
|
||||
|
||||
再比如项目 `my-vendor/project-b` 有这样的 require 定义：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-vendor/project-b",
|
||||
"require": {
|
||||
"my-vendor/project-a": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在该 `composer.json` 上执行 `composer install` 命令时，
|
||||
将会检查 project-b 的所有依赖包，并安装它们的二进制库到 `vendor/bin` 目录。
|
||||
|
||||
这种情况下，Composer 将使 `vendor/bin/project-a-bin` 可以作为
|
||||
`vendor/my-vendor/project-a/bin/project-a-bin` 的访问路径。在类 Unix 平台上，
|
||||
这是通过创建软链接实现的。
|
||||
|
||||
|
||||
## 对于 Windows 环境和 .bat 文件呢？
|
||||
|
||||
完全由 Composer 管理的包并不 *需要* 包含任何用以兼容 Windows 的
|
||||
`.bat` 文件。在 Windows 环境下运行时，Composer 会用一种特殊的方式处理
|
||||
二进制文件的安装：
|
||||
|
||||
* 一个用以引用此二进制文件的 `.bat` 文件会自动生成
|
||||
* 一个与该二进制文件同名的 Unix 风格的代理文件也会自动生成
|
||||
（方便 Cygwin 或 Git Bash 使用）
|
||||
|
||||
有时资源包需要维护自定义的 `.bat` 文件来支持工作流，它可以不包含在 Composer 中。
|
||||
这种情况下，该资源包 **不** 应该把它们作为二进制文件列出，因为 Composer 不需要知道它们。
|
||||
|
||||
|
||||
## 二进制供应库可以安装在 vendor/bin 以外的其它地方么？
|
||||
|
||||
当然，这里有两种指定二进制供应库的其他可选位置的方法：
|
||||
|
||||
1. 在 `composer.json` 文件中的 `bin-dir` 配置属性处设置
|
||||
2. 设置环境变量 `COMPOSER_BIN_DIR`
|
||||
|
||||
前者的实例如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"bin-dir": "scripts"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在这个 `composer.json` 上运行 `composer install` 会把所有的二进制供应库
|
||||
都安装在 `scripts/` 目录，而不是缺省的 `vendor/bin/` 目录。
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
# 如何为我的框架自定义一个资源包安装目录？
|
||||
|
||||
每个框架都可能有一个或多个不同的依赖包安装目录。Composer 可以通过使用 [composer/installers](https://github.com/composer/installers) 来配置，安装依赖到其它的目录，而不是默认的 `vendor` 目录。
|
||||
|
||||
如果你是一个 **包作者** 并且希望自己的资源包被安装到自定义的目录中，简单的 require `composer/installers` 依赖，并设置适当的 `type` 属性。这是常见的方式，如果你的资源包专门用于一个框架，如 CakePHP、Drupal 或 WordPress。这是一个 WordPress 主题的 composer.json 文件的例子：
|
||||
|
||||
```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 来覆盖安装路径：
|
||||
|
||||
```json
|
||||
{
|
||||
"extra": {
|
||||
"installer-paths": {
|
||||
"sites/example.com/modules/{$name}": ["vendor/package"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
现在该资源包将被安装到你指定的目录，并替换 `$name` 变量，而不是默认目录。
|
||||
|
||||
> **注意：** 你不能通过它改变所有包的安装目录。这仅适用于引入 `composer/installers` 依赖，自定义了 type 属性的资源包。
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
# 我应该提交 vendor 目录中的依赖包吗？
|
||||
|
||||
一般情况下 **不建议**。vendor 目录（或者你安装依赖的其它目录）都应该被添加进 `.gitignore`/`svn:ignore`/等等。
|
||||
|
||||
最好这么做，然后让所有开发人员使用 Composer 来安装依赖包。同样，build server、CI、deployment tools 等等，应进行修改，使运行 Composer 成为其项目引导的一部分。
|
||||
|
||||
虽然在某些环境下提交它是很让人心动的，但它将导致一些问题：
|
||||
|
||||
- 当你更新代码时，将极大的增加 VCS 仓库的体积和差异。
|
||||
- 在你自己的 VCS 中将产生与你依赖的资源包重复的历史记录。
|
||||
- 通过 git 的一个 git 仓库安装添加依赖，将把它们视作子模块。这是有问题的，因为它们并不是真正的子模块，并且你将会遇到这些问题。
|
||||
|
||||
如果你真的觉得你必须这样做，你有几个选择：
|
||||
|
||||
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 命令前删除你磁盘中的依赖文件。
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
# 为什么说“比较符”和“通配符”相结合的版本约束是坏主意？
|
||||
|
||||
这是人们常犯的一个错误，定义了类似 `>=2.*` 或 `>=1.1.*` 的版本约束。
|
||||
|
||||
通过思考它所表示的真正含义，你很快就会发现，它并没有多大意义。如果我们分解 `>=2.*`，你会得到两个部分：
|
||||
|
||||
- `>=2` 表示资源包应该是 2.0.0 或以上版本。
|
||||
- `2.*` 表示资源包版本应该介于 2.0.0 （含）和 3.0.0（不含）之间。
|
||||
|
||||
正如你所看到的，要同时满足这两个规则包版本必须 >=2.0.0，但它是无法判断的，因为当你这么写的时候，你究竟是想要包含 3.0.0 版本还是不包含？它应该进行匹配吗？因为你定义了 `>=2`，但同时你又限制它为 `2.*`。
|
||||
|
||||
出于这个原因，Composer 将抛出一个错误，并告诉你这是无效的。想要确切的表达你意思，最简单的方法就是仅使用“比较符”和“通配符”其中的一种来定义约束。
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
# 为什么 Composer 不递归加载储存库？
|
||||
|
||||
当你使用自定义库时，你可能会碰到问题，因为 Composer 不会递归加载你要求的储存库，所以你必须修改这些储存库中所有的 `composer.json` 文件。
|
||||
|
||||
在详细说明为什么是这样之前，你需要明白：使用自定义 VCS & 包储存库去尝试某些事情，或者使用你 fork 的一个分支，直到你的 pull request 被合并，等等。你不应该使用它们来跟踪你的私人资源包，关于这点你应该看看 [setting up Satis](../articles/handling-private-packages-with-satis.md) 来为你的公司甚至自己处理私人资源包。
|
||||
|
||||
这里有三个途径可以使依赖解析器使用你自定义的储存库：
|
||||
|
||||
- 读取根包的存储库，从定义的存储库得到所有的软件包，解析依赖需求。这是目前的状态，它工作得很好，除了有“无法递归的加载储存库”这个限制。
|
||||
|
||||
- 读取根包的存储库，同时从定义的 repos 初始化资源包，递归的初始化，根据所有依赖包中定义的 repos，以及这些依赖包所依赖的其它包中定义的 repos，等等，然后再解析依赖需求。这可能可以工作，但会严重影响初始化的速度，因为每读取一个 VCS repos 都需要几秒钟。它可能最终执行失败，因为一个包的不同版本，可能来自一个包资源库中一个相同的包，但来至不同的 dist/source 。这样有太多的可能会出错。
|
||||
|
||||
- 读取根包的存储库，然后读取第一级依赖，接着读取这些依赖包所依赖的其它包，等等，然后再解析依赖需求。这样听起来更有效率，但仍然存在第二种解决方案中的问题。因为加载依赖的储存库并不像听起来那么容易。你需要加载所有可能匹配的依赖包的 repos，而这些包的定义又可能是互相冲突的。
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<module type="WEB_MODULE" version="4">
|
||||
<component name="NewModuleRootManager" inherit-compiler-output="true">
|
||||
<exclude-output />
|
||||
<content url="file://$MODULE_DIR$" />
|
||||
<orderEntry type="inheritedJdk" />
|
||||
<orderEntry type="sourceFolder" forTests="false" />
|
||||
</component>
|
||||
</module>
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
# 中文翻译贡献者名单
|
||||
|
||||
> 项目持续至今，从一个人苦撑，到渐渐有了朋友的加入，感谢大家的辛劳与付出，同时也期待结识更多的新朋友。
|
||||
|
||||
- [王赛](#wangsai)
|
||||
- [东方孤思子](#dongfanggusizi)
|
||||
|
||||
|
||||
<a name="wangsai"></a>
|
||||
## 王赛
|
||||
- 邮箱：wangsai@bootcss.com
|
||||
- 网址： [Bootstrap中文网](http://www.bootcss.com) & [Laravel中文网](http://www.golaravel.com)
|
||||
- Github: [https://github.com/wangsai/](https://github.com/wangsai/)
|
||||
|
||||
|
||||
<a name="dongfanggusizi"></a>
|
||||
## 东方孤思子
|
||||
- 邮箱：qiansen1386@gmail.com
|
||||
- Github: [https://github.com/qiansen1386](https://github.com/qiansen1386)
|
||||
|
|
@ -0,0 +1,171 @@
|
|||
# Introduction
|
||||
|
||||
Composer is a tool for dependency management in PHP. It allows you to declare
|
||||
the libraries your project depends on and it will manage (install/update) them
|
||||
for you.
|
||||
|
||||
## Dependency management
|
||||
|
||||
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](https://npmjs.org/) and ruby's [bundler](http://bundler.io/).
|
||||
|
||||
Suppose:
|
||||
|
||||
a) You have a project that depends on a number of libraries.
|
||||
|
||||
b) Some of those libraries depend on other libraries.
|
||||
|
||||
Composer:
|
||||
|
||||
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).
|
||||
|
||||
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 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.
|
||||
|
||||
Composer is multi-platform and we strive to make it run equally well on Windows,
|
||||
Linux and OSX.
|
||||
|
||||
## 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
|
||||
|
||||
Installing Composer locally is a matter of just running the installer in your
|
||||
project directory:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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 additionally (re)name it as well using the `--filename` option:
|
||||
|
||||
```sh
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
A quick copy-paste version including sudo:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
> **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`:
|
||||
|
||||
```sh
|
||||
C:\Users\username>cd C:\bin
|
||||
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
|
||||
```
|
||||
|
||||
> **Note:** If the above fails due to readfile, use the `http` url or enable
|
||||
> php_openssl.dll in php.ini
|
||||
|
||||
Create a new `composer.bat` file alongside `composer.phar`:
|
||||
|
||||
```sh
|
||||
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
|
||||
C:\Users\username>composer -V
|
||||
Composer version 27d8904
|
||||
```
|
||||
|
||||
## Using Composer
|
||||
|
||||
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.
|
||||
|
||||
[Basic usage](01-basic-usage.md) →
|
||||
|
|
@ -0,0 +1,207 @@
|
|||
# Basic usage
|
||||
|
||||
## Introduction
|
||||
|
||||
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.
|
||||
|
||||
> **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
|
||||
|
||||
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 `require` Key
|
||||
|
||||
The first (and often only) thing you specify in `composer.json` is the
|
||||
[`require`](04-schema.md#require) key. You're simply telling Composer which
|
||||
packages your project depends on.
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "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`.
|
||||
|
||||
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.*`](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 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
|
||||
[minimum-stability](04-schema.md#minimum-stability) setting.
|
||||
|
||||
## Installing Dependencies
|
||||
|
||||
To install the defined dependencies for your project, just run the
|
||||
[`install`](03-cli.md#install) command.
|
||||
|
||||
```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.
|
||||
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` in your `.gitignore`. You really don't want to add all of that
|
||||
> code to your repository.
|
||||
|
||||
You will notice the [`install`](03-cli.md#install) command also created a
|
||||
`composer.lock` file.
|
||||
|
||||
## `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`](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.
|
||||
|
||||
If no `composer.lock` file exists, Composer will read the dependencies and
|
||||
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 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:
|
||||
|
||||
```sh
|
||||
php composer.phar update monolog/monolog [...]
|
||||
```
|
||||
|
||||
> **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.
|
||||
|
||||
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 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.
|
||||
|
||||
```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.
|
||||
|
||||
```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`](04-schema.md#autoload) field to `composer.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-4": {"Acme\\": "src/"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Composer will register a [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader
|
||||
for the `Acme` namespace.
|
||||
|
||||
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`](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 __DIR__ . '/vendor/autoload.php';
|
||||
$loader->add('Acme\\Test\\', __DIR__);
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
← [Intro](00-intro.md) | [Libraries](02-libraries.md) →
|
||||
|
|
@ -0,0 +1,212 @@
|
|||
# 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`](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 the [`name`](04-schema.md#name) property in `composer.json`:
|
||||
|
||||
```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.
|
||||
|
||||
* `hhvm` represents the version of the HHVM runtime (aka HipHop Virtual
|
||||
Machine) and allows you to apply a constraint, e.g., '>=2.3.3'.
|
||||
|
||||
* `ext-<name>` allows you to require PHP extensions (includes core
|
||||
extensions). Versioning can be quite inconsistent here, so it's often
|
||||
a good idea to just set the constraint to `*`. An example of an extension
|
||||
package name is `ext-gd`.
|
||||
|
||||
* `lib-<name>` allows constraints to be made on versions of libraries used by
|
||||
PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
|
||||
`openssl`, `pcre`, `uuid`, `xsl`.
|
||||
|
||||
You can use [`show --platform`](03-cli.md#show) to get a list of your locally
|
||||
available platform packages.
|
||||
|
||||
## Specifying the version
|
||||
|
||||
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,
|
||||
you can just add a `version` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"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` (`-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.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`).
|
||||
|
||||
### 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,
|
||||
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:
|
||||
|
||||
- 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`:
|
||||
|
||||
```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`:
|
||||
|
||||
```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`](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`](04-schema.md#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 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) →
|
||||
|
|
@ -0,0 +1,701 @@
|
|||
# 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.
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
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`.
|
||||
|
||||
```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
|
||||
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.
|
||||
* **--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`. 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
|
||||
terminals or scripts which don't handle backspace characters.
|
||||
* **--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
|
||||
|
||||
In order to get the latest versions of the dependencies and to update the
|
||||
`composer.lock` file, you should use the `update` command.
|
||||
|
||||
```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:
|
||||
|
||||
```sh
|
||||
php composer.phar update vendor/package vendor/package2
|
||||
```
|
||||
|
||||
You can also use wildcards to update a bunch of packages at once:
|
||||
|
||||
```sh
|
||||
php composer.phar update vendor/*
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
* **--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`. 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
|
||||
terminals or scripts which don't handle backspace characters.
|
||||
* **--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.
|
||||
* **--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. If no file exists one will be created on the fly.
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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.
|
||||
* **--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-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
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
php composer.phar show
|
||||
```
|
||||
|
||||
If you want to see the details of a certain package, you can pass the package
|
||||
name.
|
||||
|
||||
```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] https://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da
|
||||
dist : [zip] https://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.
|
||||
|
||||
```sh
|
||||
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.
|
||||
* **--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
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
php composer.phar depends --link-type=require monolog/monolog
|
||||
|
||||
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
|
||||
|
||||
* **--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.
|
||||
|
||||
```sh
|
||||
php composer.phar validate
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
* **--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
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
php composer.phar status
|
||||
```
|
||||
|
||||
With the `--verbose` option you get some more information about what was
|
||||
changed:
|
||||
|
||||
```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.
|
||||
|
||||
```sh
|
||||
php composer.phar self-update
|
||||
```
|
||||
|
||||
If you would like to instead update to a specific release simply specify it:
|
||||
|
||||
```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
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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](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`.
|
||||
* **--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.
|
||||
* **--absolute:** Returns absolute paths when fetching *-dir config values
|
||||
instead of relative.
|
||||
|
||||
### 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:
|
||||
|
||||
```sh
|
||||
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"
|
||||
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.
|
||||
|
||||
```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.
|
||||
|
||||
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.
|
||||
* **--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
|
||||
|
||||
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/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/4 for convenience and classmaps for
|
||||
performance.
|
||||
|
||||
### Options
|
||||
|
||||
* **--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 any required arguments.
|
||||
|
||||
## 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.
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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`.
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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
|
||||
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 <proxy url>`.
|
||||
|
||||
### 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/<user>/.composer` on \*nix,
|
||||
`/Users/<user>/.composer` on OSX and
|
||||
`C:\Users\<user>\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 [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`](06-config.md#cache-dir) option.
|
||||
|
||||
By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and
|
||||
`C:\Users\<user>\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows.
|
||||
|
||||
### COMPOSER_PROCESS_TIMEOUT
|
||||
|
||||
This env var controls the time Composer waits for commands (such as git
|
||||
commands) to finish executing. The default value is 300 seconds (5 minutes).
|
||||
|
||||
### COMPOSER_DISCARD_CHANGES
|
||||
|
||||
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
|
||||
`--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) →
|
||||
|
|
@ -0,0 +1,861 @@
|
|||
# The composer.json Schema
|
||||
|
||||
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`.
|
||||
|
||||
> **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` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) 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
|
||||
- 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
|
||||
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](https://www.spdx.org/licenses/).
|
||||
|
||||
For closed-source software, you may use `"proprietary"` as the license identifier.
|
||||
|
||||
An Example:
|
||||
|
||||
```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:
|
||||
|
||||
```json
|
||||
{
|
||||
"license": [
|
||||
"LGPL-2.1",
|
||||
"GPL-3.0+"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively they can be separated with "or" and enclosed in parenthesis;
|
||||
|
||||
```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.
|
||||
|
||||
### 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:
|
||||
|
||||
```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.
|
||||
|
||||
### 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.
|
||||
* **docs:** URL to the documentation.
|
||||
|
||||
An example:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "1.0.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
All links are optional fields.
|
||||
|
||||
`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
|
||||
allow unstable packages of a dependency for example.
|
||||
|
||||
Example:
|
||||
|
||||
```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:
|
||||
|
||||
```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
|
||||
when you run update. These only work if you explicitly require a dev version
|
||||
and append the reference with `#<ref>`.
|
||||
|
||||
Example:
|
||||
|
||||
```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
|
||||
> 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` and `require-dev` also support references to specific PHP versions
|
||||
and PHP extensions your project needs to run successfully.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"require" : {
|
||||
"php" : "^5.5 || ^7.0",
|
||||
"ext-mbstring": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### require
|
||||
|
||||
Lists packages required by this package. The package will not be installed
|
||||
unless those requirements can be met.
|
||||
|
||||
#### require-dev <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
Lists packages required for developing this package, or running
|
||||
tests, etc. The dev requirements of the root package are installed by default.
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"suggest": {
|
||||
"monolog/monolog": "Allows more advanced logging of the application flow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### autoload
|
||||
|
||||
Autoload mapping for a PHP 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
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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:
|
||||
|
||||
```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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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/4. To configure this you specify all directories or files
|
||||
to search for classes.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"files": ["src/MyLibrary/functions.php"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Exclude files from classmaps
|
||||
|
||||
If you want to exclude some files or folders from the classmap you can use the 'exclude-from-classmap' property.
|
||||
This might be useful to exclude test classes in your live environment, for example, as those will be skipped
|
||||
from the classmap even when building an optimized autoloader.
|
||||
|
||||
The classmap generator will ignore all files in the paths configured here. The paths are absolute from the package
|
||||
root directory (i.e. composer.json location), and support `*` to match anything but a slash, and `**` to
|
||||
match anything. `**` is implicitly added to the end of the paths.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"exclude-from-classmap": ["/Tests/", "/test/", "/tests/"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### autoload-dev <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
This section allows to define autoload rules for development purposes.
|
||||
|
||||
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
|
||||
|
||||
> **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:
|
||||
|
||||
```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
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"psr-0": { "Symfony\\Component\\Yaml\\": "" }
|
||||
},
|
||||
"target-dir": "Symfony/Component/Yaml"
|
||||
}
|
||||
```
|
||||
|
||||
Optional.
|
||||
|
||||
### minimum-stability <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
This defines the default behavior for filtering packages by stability. This
|
||||
defaults to `stable`, so if you rely on a `dev` package, you should specify
|
||||
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 <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
When this is enabled, Composer will prefer more stable packages over unstable
|
||||
ones when finding compatible stable packages is possible. If you require a
|
||||
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 <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
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:
|
||||
|
||||
```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": "https://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": "https://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 <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
A set of configuration options. It is only used for projects. See
|
||||
[Config](06-config.md) for a description of each individual option.
|
||||
|
||||
### scripts <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
Composer allows you to hook into various parts of the installation process
|
||||
through the use of scripts.
|
||||
|
||||
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:
|
||||
|
||||
```php
|
||||
$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:
|
||||
|
||||
```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`.
|
||||
|
||||
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) →
|
||||
|
|
@ -0,0 +1,667 @@
|
|||
# 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:
|
||||
|
||||
```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:
|
||||
|
||||
* name
|
||||
* version
|
||||
* dist or source
|
||||
|
||||
Here is a minimal package definition:
|
||||
|
||||
```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).
|
||||
|
||||
#### notify-batch
|
||||
|
||||
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.
|
||||
|
||||
An example value:
|
||||
|
||||
```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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```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.
|
||||
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```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
|
||||
`%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
|
||||
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](https://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. 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:
|
||||
|
||||
```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.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
#### Using private repositories
|
||||
|
||||
Exactly the same solution allows you to work with your private repositories at
|
||||
GitHub and BitBucket:
|
||||
|
||||
```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.
|
||||
|
||||
#### Git alternatives
|
||||
|
||||
Git is not the only version control system supported by the VCS repository.
|
||||
The following are supported:
|
||||
|
||||
* **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
|
||||
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`.
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
```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`.
|
||||
|
||||
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/"`.
|
||||
|
||||
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`
|
||||
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`:
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{
|
||||
"type": "pear",
|
||||
"url": "https://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:
|
||||
|
||||
```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
|
||||
|
||||
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:
|
||||
|
||||
```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.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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 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
|
||||
repository.
|
||||
|
||||
### 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
|
||||
|
||||
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:
|
||||
|
||||
```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:
|
||||
|
||||
```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
|
||||
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
|
||||
`composer.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{
|
||||
"packagist": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
← [Schema](04-schema.md) | [Config](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\<user>\AppData\Local\Composer` on Windows. Stores all the caches used
|
||||
by Composer. See also [COMPOSER_HOME](03-cli.md#composer-home).
|
||||
|
||||
## cache-files-dir
|
||||
|
||||
Defaults to `$cache-dir/files`. Stores the zip archives of packages.
|
||||
|
||||
## cache-repo-dir
|
||||
|
||||
Defaults to `$cache-dir/repo`. Stores repository metadata for the `composer`
|
||||
type and the VCS repos of type `svn`, `github` and `bitbucket`.
|
||||
|
||||
## cache-vcs-dir
|
||||
|
||||
Defaults to `$cache-dir/vcs`. Stores VCS clones for loading VCS repository
|
||||
metadata for the `git`/`hg` types and to speed up installs.
|
||||
|
||||
## cache-files-ttl
|
||||
|
||||
Defaults to `15552000` (6 months). Composer caches all dist (zip, tar, ..)
|
||||
packages that it downloads. Those are purged after six months of being unused by
|
||||
default. This option allows you to tweak this duration (in seconds) or disable
|
||||
it completely by setting it to 0.
|
||||
|
||||
## cache-files-maxsize
|
||||
|
||||
Defaults to `300MiB`. Composer caches all dist (zip, tar, ..) packages that it
|
||||
downloads. When the garbage collection is periodically ran, this is the maximum
|
||||
size the cache will be able to use. Older (less used) files will be removed
|
||||
first until the cache fits.
|
||||
|
||||
## bin-compat
|
||||
|
||||
Defaults to `auto`. Determines the compatibility of the binaries to be installed.
|
||||
If it is `auto` then Composer only installs .bat proxy files when on Windows. If
|
||||
set to `full` then both .bat files for Windows and scripts for Unix-based
|
||||
operating systems will be installed for each binary. This is mainly useful if you
|
||||
run Composer inside a linux VM but still want the .bat proxies available for use
|
||||
in the Windows host OS.
|
||||
|
||||
## prepend-autoloader
|
||||
|
||||
Defaults to `true`. If `false`, the Composer autoloader will not be prepended to
|
||||
existing autoloaders. This is sometimes required to fix interoperability issues
|
||||
with other autoloaders.
|
||||
|
||||
## autoloader-suffix
|
||||
|
||||
Defaults to `null`. String to be used as a suffix for the generated Composer
|
||||
autoloader. When null a random one will be generated.
|
||||
|
||||
## optimize-autoloader
|
||||
|
||||
Defaults to `false`. If `true`, always optimize when dumping the autoloader.
|
||||
|
||||
## sort-packages
|
||||
|
||||
Defaults to `false`. If `true`, the `require` command keeps packages sorted
|
||||
by name in `composer.json` when adding a new package.
|
||||
|
||||
## classmap-authoritative
|
||||
|
||||
Defaults to `false`. If `true`, the Composer autoloader will only load classes
|
||||
from the classmap. Implies `optimize-autoloader`.
|
||||
|
||||
## github-domains
|
||||
|
||||
Defaults to `["github.com"]`. A list of domains to use in github mode. This is
|
||||
used for GitHub Enterprise setups.
|
||||
|
||||
## github-expose-hostname
|
||||
|
||||
Defaults to `true`. If `false`, the OAuth tokens created to access the
|
||||
github API will have a date instead of the machine hostname.
|
||||
|
||||
## gitlab-domains
|
||||
|
||||
Defaults to `["gitlab.com"]`. A list of domains of GitLab servers.
|
||||
This is used if you use the `gitlab` repository type.
|
||||
|
||||
## notify-on-install
|
||||
|
||||
Defaults to `true`. Composer allows repositories to define a notification URL,
|
||||
so that they get notified whenever a package from that repository is installed.
|
||||
This option allows you to disable that behaviour.
|
||||
|
||||
## discard-changes
|
||||
|
||||
Defaults to `false` and can be any of `true`, `false` or `"stash"`. This option
|
||||
allows you to set the default style of handling dirty updates when in
|
||||
non-interactive mode. `true` will always discard changes in vendors, while
|
||||
`"stash"` will try to stash and reapply. Use this for CI servers or deploy
|
||||
scripts if you tend to have modified vendors.
|
||||
|
||||
## archive-format
|
||||
|
||||
Defaults to `tar`. Composer allows you to add a default archive format when the
|
||||
workflow needs to create a dedicated archiving format.
|
||||
|
||||
## archive-dir
|
||||
|
||||
Defaults to `.`. Composer allows you to add a default archive directory when the
|
||||
workflow needs to create a dedicated archiving format. Or for easier development
|
||||
between modules.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"archive-dir": "/home/user/.composer/repo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
← [Repositories](05-repositories.md) | [Community](07-community.md) →
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
# 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) and
|
||||
[CONTRIBUTING](https://github.com//composer/composer/blob/master/CONTRIBUTING.md)
|
||||
documents.
|
||||
|
||||
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 [PSR-2 Coding Standards](http://www.php-fig.org/psr/psr-2/).
|
||||
|
||||
## IRC / mailing list
|
||||
|
||||
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](https://stackoverflow.com/questions/tagged/composer-php).
|
||||
|
||||
← [Config](06-config.md)
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
<!--
|
||||
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` 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.
|
||||
|
||||
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`:
|
||||
|
||||
```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`:
|
||||
|
||||
```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.
|
||||
|
|
@ -0,0 +1,198 @@
|
|||
<!--
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```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
|
||||
> 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:
|
||||
|
||||
```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
|
||||
|
||||
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:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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/<stripped name>` 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
|
||||
|
|
@ -0,0 +1,200 @@
|
|||
<!--
|
||||
tagline: Host your own composer repository
|
||||
-->
|
||||
|
||||
# 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.
|
||||
|
||||
```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.
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
|
||||
{ "type": "vcs", "url": "http://svn.example.org/private/repo" },
|
||||
{ "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
|
||||
],
|
||||
"require": {
|
||||
"company/package": "*",
|
||||
"company/package2": "*",
|
||||
"company/package3": "2.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Once you did this, you just run `php bin/satis build <configuration file> <build dir>`.
|
||||
For example `php bin/satis build config.json web/` would read the `config.json`
|
||||
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.
|
||||
|
||||
```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
|
||||
|
||||
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):
|
||||
|
||||
```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:
|
||||
|
||||
```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.
|
||||
|
||||
### 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`:
|
||||
|
||||
```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`:
|
||||
|
||||
```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`.
|
||||
|
|
@ -0,0 +1,160 @@
|
|||
<!--
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
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
|
||||
|
|
@ -0,0 +1,133 @@
|
|||
<!--
|
||||
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.
|
||||
|
||||
**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.
|
||||
- **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
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"post-update-cmd": "MyVendor\\MyClass::postUpdate",
|
||||
"post-package-install": [
|
||||
"MyVendor\\MyClass::postPackageInstall"
|
||||
],
|
||||
"post-install-cmd": [
|
||||
"MyVendor\\MyClass::warmCache",
|
||||
"phpunit -c app/"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Using the previous definition example, here's the class `MyVendor\MyClass`
|
||||
that might be used to execute the PHP callbacks:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace MyVendor;
|
||||
|
||||
use Composer\Script\Event;
|
||||
|
||||
class MyClass
|
||||
{
|
||||
public static function postUpdate(Event $event)
|
||||
{
|
||||
$composer = $event->getComposer();
|
||||
// do stuff
|
||||
}
|
||||
|
||||
public static function postPackageInstall(Event $event)
|
||||
{
|
||||
$installedPackage = $event->getOperation()->getPackage();
|
||||
// do stuff
|
||||
}
|
||||
|
||||
public static function warmCache(Event $event)
|
||||
{
|
||||
// make cache toasty
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
|
@ -0,0 +1,153 @@
|
|||
<!--
|
||||
tagline: Solving problems
|
||||
-->
|
||||
# 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:
|
||||
|
||||
```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:
|
||||
|
||||
```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):
|
||||
|
||||
```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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
## API rate limit and OAuth tokens
|
||||
|
||||
Because of GitHub's rate limits on their API it can happen that Composer prompts
|
||||
for authentication asking your username and password so it can go ahead with its work.
|
||||
|
||||
If you would prefer not to provide your GitHub credentials to Composer you can
|
||||
manually create a token using the following procedure:
|
||||
|
||||
1. [Create](https://github.com/settings/applications) an OAuth token on GitHub.
|
||||
[Read more](https://github.com/blog/1509-personal-api-tokens) on this.
|
||||
|
||||
2. Add it to the configuration running `composer config -g github-oauth.github.com <oauthtoken>`
|
||||
|
||||
Now Composer should install/update without asking for authentication.
|
||||
|
||||
## proc_open(): fork failed errors
|
||||
If composer shows proc_open() fork failed on some commands:
|
||||
|
||||
`PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar`
|
||||
|
||||
This could be happening because the VPS runs out of memory and has no Swap space enabled.
|
||||
|
||||
```sh
|
||||
free -m
|
||||
|
||||
total used free shared buffers cached
|
||||
Mem: 2048 357 1690 0 0 237
|
||||
-/+ buffers/cache: 119 1928
|
||||
Swap: 0 0 0
|
||||
```
|
||||
|
||||
To enable the swap you can use for example:
|
||||
|
||||
```sh
|
||||
/bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024
|
||||
/sbin/mkswap /var/swap.1
|
||||
/sbin/swapon /var/swap.1
|
||||
```
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
<!--
|
||||
tagline: Expose command-line scripts from packages
|
||||
-->
|
||||
|
||||
# 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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```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:
|
||||
|
||||
```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`.
|
||||
|
||||
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:
|
||||
|
||||
```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
|
||||
`vendor/bin/`.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
# 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:
|
||||
|
||||
```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
|
||||
[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:
|
||||
|
||||
```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.
|
||||
|
||||
> **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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
翻译术语对照表
|
||||
===============
|
||||
|
||||
> [D](#d) || [P](#p) || [S](#s) || [V](#v)
|
||||
|
||||
## D
|
||||
|
||||
### dependencies 依赖包、依赖关系
|
||||
|
||||
## P
|
||||
|
||||
### Package 资源包
|
||||
|
||||
## S
|
||||
|
||||
### symlink 软链接
|
||||
|
||||
## V
|
||||
|
||||
### Vendor 供应商
|
||||
|
||||
### Vendor Binary 二进制供应库
|
||||
|
||||
Loading…
Reference in New Issue