言午月月鸟 - php composer 常用操作

## 介绍
> Composer 是 PHP 的 一个 项目级别的 依赖管理 工具。

## 安装 composer

```
curl -sS https://getcomposer.org/installer | php
# 或者
php -r "readfile('https://getcomposer.org/installer');" | php
```

总之，就是想办法 下载 https://getcomposer.org/installer 脚本，并用 PHP 运行它；以便在当前目录得到一个 composer.phar 文件。后续 composer 操作都是通过 php composer.phar（或简化为直接用 composer） 去运行。

如果你想更方便地全局使用，你也可以将其设为可执行（linux）或者写一个bat文件（windows)包装一下，并放置到系统目录。

windows 用户还有更简单的方式，直接下载：
[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe) 进行全局安装。

## 创建 composer 包
只要你项目中已经有一个 composer.json 文件，那说明先帮你做好了创建工作。

否则请使用 php composer.phar init 命令，按交互引导创建。

如果你比较熟悉 composer.json 的格式说明，你也可以手动创建该文件。

### 配置依赖

在项目根目录的 composer.json 文件中，添加/编辑 依赖说明。

```
{
    "require": {
        "monolog/monolog": "1.0.*"
    }
}
```
格式为 包名: 版本

常用：

版本格式 | 说明
---|---
1.0.* | 表示 1.0.x 
~1.2 |  表示指定版本而小于下一个大版本，即 >=1.2,<2.0

更多版本格式说明请参考：
[phpcomposer - 基本用法#包版本 章节](https://docs.phpcomposer.com/01-basic-usage.html#Package-Versions)

## 安装依赖
在项目目录，已配置好 composer.json 后，运行：

```
# 如果使用了全局安装，可以直接使用 （ composer.phar install 或 composer install）
php composer.phar install

```

composer 将下载并安装对应依赖包到 vendor 目录（默认）。

安装逻辑：

如果存在 composer.lock 文件，严格按照该文件指定的包版本安装；否则，将读取 composer.json 根据规则下载满足条件的包，并创建一个记录了确定版本的 composer.lock 文件。

对于开发项目，建议提交该文件（composer.lock）到版本库，以确保各环境实际安装的依赖包版本相同。

### 优化国内下载速度：

```
# 可忽略 -g 参数，则配置仅在当前项目生效
# Packagist 
composer config -g repo.packagist composer https://packagist.phpcomposer.com
# 阿里云
# composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
```

更多 命令请参考：
[phpcomposer - 命令行 章节](https://docs.phpcomposer.com/03-cli.html)

## 发布 composer 包
请先按照格式规范配置你项目中的 composer.json 。

关注配置项：
 - name 格式：[供应商]/[库名]，建议 小写字母+短横线命名；
 - license 根据实际选择适合的协议；
 - version 不建议配置该项。

发布的版本可以通过 tag 或者 分支 控制。如：
 - 打个 tag 为 v1.0.1 则表示存在这么一个确定版本；
 - 创建分支 v1.2 则表示存在一个版本 1.2.x-dev；特别的默认存在 dev-master。（如果分支名为一个合法版本，则对应版本 [分支名]-dev；否则对应版本 dev-[分支名]）。

比较主流是将自己的包发布到 packagelist 上，以便全世界都可以使用：

首先请把你的代码放置到公网版本管理系统，如 github, gitee 等；
然后访问 https://packagist.org/ 注册自己的账号，并按引导提交即可。

更多详情请参考： 
[phpcomposer - 库（资源包）章节](https://docs.phpcomposer.com/02-libraries.html)

## 自建composer 仓库
有时公司内部使用，不方便发布到公网，也可以自建 composer 仓库管理。
推荐两种简单的方法：直接使用 git 仓库作为源 或者 使用 satis 统一管理包。

### 直接使用 git 仓库作为源
提交待发布的 composer 包代码到 git，注意名称 和 版本。
在使用包的项目 里 配置 composer.json 参考：

```
    // 添加/编辑 repositories 节点，增加包引用地址，参考如下：
    "repositories":[ 
       { 
           "type":"git", 
           "url":"http://internal.site/pkgs/demo.git"
       }
    ],

// require 节点 添加包引用，参考如下：
    "require": {
        "mypkg/demo": "1.0.0"
    },

// （如果内部 git 未配置 https 支持）↓
    // config 节点 配置取消强制 https 限制，参考如下：
    "config": {
        "secure-http": false
    }
```

### 使用 satis 统一管理包
好处是：避免每个项目使用都去添加 repositories 配置

安装：

```
composer create-project composer/satis:dev-master
php bin/satis build <configuration-file> <output-directory>
```

其中 configuration-file 类似 composer.json，主要包含引用包地址。如：

```
{
    "name": "My Repository",
    "homepage": "http://mysatis.site",
    "repositories": [
        { "type": "git", "url": "http://internal.site/pkgs/demo1.git" },
        { "type": "git", "url": "http://internal.site/pkgs/demo2.git" },
        {"packagist": false}
    ],
    "require-all" : true,
    "archive": {
        "directory": "dist",
        "format": "tar",
        "prefix-url": "http://mysatis.site/",
        "skip-dev": true
    },
    "config":{"secure-http":false}
}

# 说明：
# archive 配置项可选，如果配置则会将包压缩存储到服务器，项目使用 composer update 会更快
# config.secure-http 可选，如果服务器支持了 https 则不需要
```

然后把 output-directory 添加到 nginx server，如 http://mysatis.site

项目引用时，不再需要配置如果 repositories，直接配置 mysatis.site 作为源，然后引用包即可。

```
{
    "repositories": [ { "type": "composer", "url": "http://mysatis.site" } ],
    "require": {
        "mypkg/demo1": "1.0.0",
        "mypkg/demo2": "dev-master"
    },
    "config" :{"secure-http":false}
}
```

## 疑难杂症

### vendor 下载的某些包包含 .git 目录，无法提交到项目代码库

一般情况下，**不建议** 将 vendor 目录（或者你安装依赖的其它目录）添加到代码库。

如果一定要这么做，你有可能会踩到一个坑。对于某些没有发布 release 版本的依赖库，拉取下来的代码里，会包含 .git 目录。

而等你将 vendor 目录提交到自己代码库的时候，要么 git 会报错提示存在子仓库，要么提交上去之后该代码库目录是空的。

解决方案：

1. 把该代码库下的 .git 添加到 .ignore 文件的忽略列表里，如：vendor/xxx/.git；
  2. 如果你是在提交过一次之后才发现需要忽略，则该目录已被git添加到索引。还需要手动清除一下。即： ```git rm --cached vendor/xxx/.git```

## 参考文章
 - [phpcomposer - 很完善的教程 + composer国内镜像源](https://docs.phpcomposer.com/)
 - [composer/satis 项目](https://github.com/composer/satis)
 - [我应该提交 vendor 目录中的依赖包吗](https://docs.phpcomposer.com/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.html)