- 简介
- 依赖管理
- 声明依赖关系
- 系统要求
- 安装 - *nix
- 下载 Composer 的可执行文件
- 局部安装
- 全局安装
- 全局安装 (on OSX via homebrew)
- 安装 - Windows
- 使用安装程序
- 手动安装
- 使用 Composer
- 自动加载
- 使用国内镜像
- 使用国内镜像安装
- 下载 Composer
- 局部安装
- 全局安装
- Mac 或 Linux 系统:
- Windows 系统:
- 最后
- 关于升级 Composer
- FAQ
- 有哪些沟通手段可以求助镜像使用上的问题或者报告故障?
- Packagist 中国全量镜像多长时间更新一次?
- 为什么我向 packagist.org 或 Github 提交了 package 或更新,从镜像却下载不到新版本?
- 为什么基于 Yii2 创建的项目安装依赖包时即便设置了中国镜像依然很慢?
- 为什么不为 Asset Packagist 创建中国镜像?
- Packagist 中国全量镜像是否有收费服务或企业版?
- 替换国内镜像
- Packagist 镜像使用方法
- 镜像用法
- 方法一: 修改 composer 的全局配置文件 (推荐方式)
- 方法二: 修改当前项目的
composer.json
配置文件: - 镜像原理:
- 解除镜象:
简介
Composer 是 PHP 的一个依赖管理工具。它允许你申明项目所依赖的代码库,它会在你的项目中为你安装他们。
依赖管理
Composer 不是一个包管理器。是的,它涉及 “packages” 和
“libraries”,但它在每个项目的基础上进行管理,在你项目的某个目录中(例如vendor
)进行安装。默认情况下它不会在全局安装任何东西。因此,这仅仅是一个依赖管理。
这种想法并不新鲜,Composer 受到了 node’s npm 和 ruby’s
bundler 的强烈启发。而当时 PHP 下并没有类似的工具。
Composer 将这样为你解决问题:
a) 你有一个项目依赖于若干个库。
b) 其中一些库依赖于其他库。
c) 你声明你所依赖的东西。
d) Composer 会找出哪个版本的包需要安装,并安装它们(将它们下载到你的项目中)。
声明依赖关系
比方说,你正在创建一个项目,你需要一个库来做日志记录。你决定使用
monolog。为了将它添加到你的项目中,你所需要做的就是创建一个composer.json
文件,其中描述了项目的依赖关系。
{
"require": {
"monolog/monolog": "1.2.*"
}
}
我们只要指出我们的项目需要一些 monolog/monolog
的包,从 1.2
开始的任何版本。
系统要求
运行 Composer 需要 PHP 5.3.2+ 以上版本。一些敏感的 PHP 设置和编译标志也是必须的,但对于任何不兼容项安装程序都会抛出警告。
我们将从包的来源直接安装,而不是简单的下载 zip 文件,你需要 git 、 svn 或者 hg ,这取决于你载入的包所使用的版本管理系统。
Composer 是多平台的,我们努力使它在 Windows 、 Linux 以及 OSX 平台上运行的同样出色。
安装 - *nix
下载 Composer 的可执行文件
局部安装
要真正获取 Composer,我们需要做两件事。首先安装 Composer (同样的,这意味着它将下载到你的项目中):
curl -sS https://getcomposer.org/installer | php
注意: 如果上述方法由于某些原因失败了,你还可以通过
php
>下载安装器:
php -r "readfile('https://getcomposer.org/installer');" | php
这将检查一些 PHP 的设置,然后下载 composer.phar
到你的工作目录中。这是 Composer 的二进制文件。这是一个 PHAR
包(PHP 的归档),这是 PHP 的归档格式可以帮助用户在命令行中执行一些操作。
你可以通过 --install-dir
选项指定 Composer 的安装目录(它可以是一个绝对或相对路径):
curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
全局安装
你可以将此文件放在任何地方。如果你把它放在系统的 PATH
目录中,你就能在全局访问它。 在类Unix系统中,你甚至可以在使用时不加 php
前缀。
你可以执行这些命令让 composer
在你的系统中进行全局调用:
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
注意: 如果上诉命令因为权限执行失败, 请使用 sudo 再次尝试运行
mv
那行命令。
现在只需要运行 composer
命令就可以使用 Composer 而不需要输入 php composer.phar
。
全局安装 (on OSX via homebrew)
Composer 是 homebrew-php 项目的一部分。
brew update
brew tap josegonzalez/homebrew-php
brew tap homebrew/versions
brew install php55-intl
brew install josegonzalez/php/composer
安装 - Windows
使用安装程序
这是将 Composer 安装在你机器上的最简单的方法。
下载并且运行 [Composer-Setup.exe](https://getcomposer.org/Composer-
Setup.exe),它将安装最新版本的 Composer ,并设置好系统的环境变量,因此你可以在任何目录下直接使用 composer
命令。
手动安装
设置系统的环境变量 PATH
并运行安装命令下载 composer.phar 文件:
C:\Users\username>cd C:\bin
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php
注意: 如果收到 readfile 错误提示,请使用
http
链接或者在 php.ini 中开启 php_openssl.dll 。
在 composer.phar
同级目录下新建文件 composer.bat
:
C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
关闭当前的命令行窗口,打开新的命令行窗口进行测试:
C:\Users\username>composer -V
Composer version 27d8904
使用 Composer
现在我们将使用 Composer 来安装项目的依赖。如果在当前目录下没有一个 composer.json
文件,请查看[基本用法](01-basic-
usage.html)章节。
要解决和下载依赖,请执行 install
命令:
php composer.phar install
如果你进行了全局安装,并且没有 phar 文件在当前目录,请使用下面的命令代替:
composer install
继续 上面的例子,这里将下载 monolog 到 vendor/monolog/monolog
目录。
自动加载
除了库的下载,Composer 还准备了一个自动加载文件,它可以加载 Composer
下载的库中所有的类文件。使用它,你只需要将下面这行代码添加到你项目的引导文件中:
require 'vendor/autoload.php';
现在我们就可以使用 monolog 了!想要学习更多关于 Composer 的知识,请查看“基本用法”章节。
基本用法 →
如果您发现文档中有错误,或者能够帮我们完善文档,请提交到我们的 Github
仓库吧!
使用国内镜像
使用国内镜像安装
下载 Composer
安装前请务必确保已经正确安装了 PHP。打开命令行窗口并执行
php -v
查看是否正确输出版本号。
打开命令行并依次执行下列命令安装最新版本的 Composer:
php -r "copy('https://install.phpcomposer.com/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
执行第一条命令下载下来的 composer-setup.php
脚本将简单地检测 php.ini
中的参数设置,如果某些参数未正确设置则会给出警告;然后下载最新版本的 composer.phar
文件到当前目录。
上述 3 条命令的作用依次是:
- 下载安装脚本 -
composer-setup.php
- 到当前目录。 - 执行安装过程。
- 删除安装脚本。
局部安装
上述下载 Composer 的过程正确执行完毕后,可以将 composer.phar
文件到任意目录(比如项目根目录下),然后通过 php
composer.phar
指令即可使用 Composer 了!
全局安装
全局安装是将 Composer 安装到系统环境变量 PATH
所包含的路径下面,然后就能够在命令行窗口中直接执行 composer
命令了。
Mac 或 Linux 系统:
打开命令行窗口并执行如下命令将前面下载的 composer.phar
文件移动到 /usr/local/bin/
目录下面:
sudo mv composer.phar /usr/local/bin/composer
Windows 系统:
- 找到并进入 PHP 的安装目录(和你在命令行中执行的
php
指令应该是同一套 PHP)。 - 将
composer.phar
到 PHP 的安装目录下面,也就是和php.exe
在同一级目录。 - 在 PHP 安装目录下新建一个
composer.bat
文件,并将下列代码保存到此文件中。
@php "%~dp0composer.phar" %*
最后重新打开一个命令行窗口试一试执行 composer --version
看看是否正确输出版本号。
最后
提示:不要忘了经常执行
composer selfupdate
以保持 Composer 一直是最新版本哦!
关于升级 Composer
Composer 升级时是无法利用我们的镜像加速下载的,而必须连接到 Composer
国外官网的服务器上下载升级文件,某些时候就会导致升级的速度非常慢甚至失败。
这里提供一个简单的办法:
如果你的系统中已经有可以正常使用的 Composer 了,说明系统环境是符合要求的,那么只需要下载新的 Composer 文件并覆盖原来的文件即可。
首先你要确定现有的 Composer 的安装目录,然后通过下面的链接下载 composer.phar
文件(以下地址到浏览器地址栏可直接下载),
https://install.phpcomposer.com/composer.phar
将前面下载的 composer.phar
文件覆盖系统中已经安装的 composer.phar
文件即可。注意,有可能在安装时将composer.phar
改名为 composer
了,注意用同样的名字覆盖即可。
FAQ
有哪些沟通手段可以求助镜像使用上的问题或者报告故障?
最好通过邮箱提问或者报告故障: packagist@bootcss.com
一般我会每天查收邮件的,遇到紧急情况会立即处理。如果你的问题我也需要复现或者测试的话一般两天左右给出答复。
请把遇到的问题说清楚,比如系统环境、软件版本、所在城市(用于定位网络异常的情况)等,并且 务必截图、截图、再截图 ,
多发截图有助于问题快速解决,一图顶千言!
注意: 如果你的问题涉及到执行 composer 命令,请在命令末尾添加 -vvv 参数输出详细日志,例如:
composer install -vvv
composer update -vvv
Packagist 中国全量镜像多长时间更新一次?
经过 [2017 年 2 月底到 3 月初的升级](http://www.phpcomposer.com/what-has-chaged-over-the-
last-two-weeks/), 目前的更新频率是 1
分钟一次,在本页面上部就能看到本镜像的“最后同步时间”。但是,一般有两种情况会影响到上面所展示的“最后同步时间”:
- 一是镜像同步时没有检查到需要更新的内容时,这时我们选择不修改“最后同步时间”
- 二是镜像同步时检查到大量更新,尤其是需要同步大量 zip 安装包到国内时,消耗的时间较多,“最后同步时间”会间隔稍多一些
另外还有“不一般”的情况:例如 packagist.org 或
Github 的服务器出现故障或服务遭遇大量攻击而不能响应时,
我们的镜像只能等待这两个服务完全正常之后才能继续同步。这时咱们都只能一起耐心等待了!
为什么我向 packagist.org 或 Github 提交了 package 或更新,从镜像却下载不到新版本?
根据 packagist.org 关于页面上的 Update Schedule
规则说明:packagist.org 会对新提交的 package 立即抓取一次。已经提交的 package 一般是每周抓取一次更新。如果你的
package 源码托管在 Github 或 Bitbucket 上,可以通过设置 service hook 让 packagist.org 在你每次
commit 后抓取更新。
所以建议同学们为自己维护的 package 设置 service hook,这样你每次向 Github 仓库提交代码时就能快速被 packagist.org
抓取了。
总之,是否能够从我们的镜像上下载到 package 的新版本完全取决于 package 的设置和 packagist.org
的更新频率。我们的镜像目前的更新频率是 1 分钟,所以只要 packagist.org 抓取到了新版本,很快就能同步到我们的镜像上。
为什么基于 Yii2 创建的项目安装依赖包时即便设置了中国镜像依然很慢?
更新:2017 年 4 月份,也就是 yii2 的 2.0.12 版本中将 fxp/composer-asset-plugin 插件替换成了
Asset Packagist 。所以,如果你用的是 yii2 2.0.12
及更新版本则不会遇到此问题,但是你会遇到下一个问题。
yii2 通过 [fxp/composer-asset-plugin](https://github.com/fxpio/composer-asset-
plugin) 插件来安前端开发所用到依赖包,此插件会在安装完 php 依赖包之后再安装前端开发所依赖的 npm 或 bower 包,
但是,此插件默认行为是前往 Github 下载资源,从而绕开了我们中国镜像。
- 参考:http://www.yiiframework.com/doc-2.0/guide-start-installation.html#installing-from-composer
- 参考:https://github.com/fxpio/composer-asset-plugin/blob/master/Resources/doc/index.md
fxp/composer-asset-plugin 插件的用途是解决 php 项目中管理、安装 bower、 npm (Node.js
包管理)包的,如果你采用的是 yii2 (2.0.11 及更低版本)框架,请参考其文档。
为什么不为 Asset Packagist 创建中国镜像?
首先,Asset Packagist 的目的也是为了解决在 php
项目中安装前端模块的问题,其通过转换 npm / bower 模块并创建一个类似 packagist 的服务为前端模块提供依赖解析和下载。
yii2 2.0 版本发布于 2014 年,所以有着历史原因,然而随着 Node.js / npm 生态的完善和普及,Asset Packagist
这种方式显得很笨拙,对前端开发没有任何益处,yii2 采用这种方式也只是为了向后兼容,避免破坏现有框架的工作方式而已。
Asset Packagist 的存在意义已经很弱了,新的框架(例如 Laravel ,比 yii2 更流行)对前端开发的支持直接构建在 npm
上的,因此,Asset Packagist 镜像的存在的意义也很弱,没有必要为其提供镜像。
相信 yii2 将来会从 Asset Packagist 转移到 npm 上的。
Packagist 中国全量镜像是否有收费服务或企业版?
Packagist
中国全量镜像一直是免费的,并且将一直免费下去,直到这个镜像没有存在意义为止。目前没有收费服务或企业版的计划,如果您觉得这个镜像对您有用,请赞助我们。
替换国内镜像
Packagist 镜像使用方法
还没安装 Composer 吗?请往下看如何安装 Composer 。
镜像用法
有两种方式启用本镜像服务:
- 系统全局配置: 即将配置信息添加到 Composer 的全局配置文件
config.json
中。见“方法一” - 单个项目配置: 将配置信息添加到某个项目的
composer.json
文件中。见“方法二”
方法一: 修改 composer 的全局配置文件 (推荐方式)
打开命令行窗口(windows用户)或控制台(Linux、Mac 用户)并执行如下命令:
composer config -g repo.packagist composer https://packagist.phpcomposer.com
方法二: 修改当前项目的 composer.json
配置文件:
打开命令行窗口(windows用户)或控制台(Linux、Mac 用户),进入你的项目的根目录(也就是 composer.json
文件所在目录),执行如下命令:
composer config repo.packagist composer https://packagist.phpcomposer.com
上述命令将会在当前项目中的 composer.json
文件的末尾自动添加镜像的配置信息(你也可以自己手工添加):
"repositories": {
"packagist": {
"type": "composer",
"url": "https://packagist.phpcomposer.com"
}
}
以 laravel 项目的 composer.json
配置文件为例,执行上述命令后如下所示(注意最后几行):
{
"name": "laravel/laravel",
"description": "The Laravel Framework.",
"keywords": ["framework", "laravel"],
"license": "MIT",
"type": "project",
"require": {
"php": ">=5.5.9",
"laravel/framework": "5.2.*"
},
"config": {
"preferred-install": "dist"
},
"repositories": {
"packagist": {
"type": "composer",
"url": "https://packagist.phpcomposer.com"
}
}
}
OK,一切搞定!试一下 composer install
来体验飞一般的速度吧!
镜像原理:
一般情况下,安装包的数据(主要是 zip 文件)一般是从 github.com
上下载的,安装包的元数据是从 packagist.org
上下载的。
然而,由于众所周知的原因,国外的网站连接速度很慢,并且随时可能被“墙”甚至“不存在”。
“Packagist 中国全量镜像”所做的就是缓存所有安装包和元数据到国内的机房并通过国内的 CDN
进行加速,这样就不必再去向国外的网站发起请求,从而达到加速 composer install
以及 composer update
的过程,并且更加快速、稳定。因此,即使 packagist.org
、github.com
发生故障(主要是连接速度太慢和被墙),你仍然可以下载、更新安装包。
解除镜象:
如果需要解除镜像并恢复到 packagist 官方源,请执行以下命令:
composer config -g --unset repos.packagist
执行之后,composer 会利用默认值(也就是官方源)重置源地址。
将来如果还需要使用镜像的话,只需要根据前面的“镜像用法”中介绍的方法再次设置镜像地址即可。