Composer 文档笔记

Basic usage

https://getcomposer.org/doc/01-basic-usage.md

# get a list of your locally available platform packages.
# php | ext-<name> | lib-<name>
composer show --platform

Libraries

https://getcomposer.org/doc/02-libraries.md

Light-weight distribution packages 轻量级分发包。使用 .gitattributes 来防止不需要的文件使 zip 分发包膨胀。

// .gitattributes
/demo export-ignore
phpunit.xml.dist export-ignore
/.github/ export-ignore

通过检查手动生成的压缩文件进行测试：

git archive branchName --format zip -o file.zip

Command-line interface / Commands

https://getcomposer.org/doc/03-cli.md

As Composer uses symfony/console you can call commands by short name if it’s not ambiguous.

composer dump
# calls
composer dump-autoload

Bash Completions

composer completion bash > completion.bash

Global Options:

--profile 显示计时和内存使用信息

install / i:

php composer.phar install

如果当前目录中有 composer.lock 文件，会使用其中的确切版本而不是重新解析。这确保了每个人使用的依赖版本相同。

如果没有 composer.lock 文件，Composer 会在解析依赖后创建一个。

常用选项：

--prefer-install: 指定安装方式，可选 source 或 dist
--no-dev: 跳过安装 require-dev 中列出的包
--optimize-autoloader (-o): 优化自动加载器，建议在生产环境使用
--classmap-authoritative (-a): 仅从 classmap 自动加载类，隐式启用 --optimize-autoloader

update / u / upgrade:

php composer.phar update

更新所有依赖到最新版本（根据 composer.json 的约束）并更新 composer.lock 文件。

常用选项：

--prefer-stable: 优先使用稳定版本
--prefer-lowest: 尝试回退到最低匹配的版本
--with-dependencies: 同时更新依赖的依赖项

require / r:

php composer.phar require vendor/package:version

添加新的依赖包并更新 composer.json 文件。

remove / rm / uninstall:

php composer.phar remove vendor/package

移除包并更新 composer.json 文件。

dump-autoload / dumpautoload:

php composer.phar dump-autoload

更新自动加载器，不安装或更新任何包。在添加新类时很有用。

选项：

-o, --optimize: 生成优化的 autoloader
--classmap-authoritative (-a): 仅从 classmap 自动加载
--no-dev: 不生成开发环境的 autoloader

global:

php composer.phar global require vendor/package

全局安装包，存储在 COMPOSER_HOME 目录。

search:

php composer.phar search keyword

搜索包。

self-update / selfupdate:

php composer.phar self-update

更新 Composer 到最新版本。

Composer 支持多种环境变量来控制其行为：

COMPOSER_HOME: 指定 Composer 主目录位置
COMPOSER_CACHE_DIR: 更改 Composer 缓存目录
COMPOSER_MEMORY_LIMIT: 设置 PHP 内存限制
COMPOSER_PROCESS_TIMEOUT: 设置命令执行超时时间（默认 300 秒）
COMPOSER_NO_INTERACTION: 禁用交互模式
COMPOSER_NO_DEV: 等同于 --no-dev 选项
COMPOSER_VENDOR_DIR: 更改安装依赖的目录

The composer.json schema

https://getcomposer.org/doc/04-schema.md

composer.json 文件是 Composer 项目的核心配置文件，用于定义包的基本信息和依赖关系。以下是主要字段的说明：

基本字段

name: 包名称，格式为 vendor/project，例如 monolog/monolog。必须小写，可包含短横线、下划线或点号。
description: 包的简短描述，通常为一行。
version: 包的版本号，格式如 1.0.0 或 v1.0.0。一般建议省略，由 VCS 标签推断。
type: 包类型，默认为 library。其他可选值包括 project、metapackage 和 composer-plugin。
keywords: 关键词数组，用于搜索和过滤。
homepage: 项目网站的 URL。
readme: 自述文件的相对路径，默认为 README.md。
time: 版本发布日期，格式为 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS。
license: 包的许可证，可以是字符串或字符串数组。

作者与支持

authors: 包作者数组，每个作者为一个对象，包含 name、email、homepage 和 role 字段。
support: 提供支持的各种信息，如 email、issues、forum、wiki 等。
funding: 用于赞助包作者的 URL 数组。

依赖管理

require: 运行时必需的依赖包映射表（包名到版本约束）。
require-dev: 开发环境需要的依赖包映射表，仅对根包有效。
conflict: 与当前包冲突的包。
replace: 由当前包替换的包。
provide: 当前包提供的包（接口实现等）。
suggest: 推荐安装的包，仅起信息提示作用。

自动加载配置

autoload: 定义项目自动加载规则，支持 psr-4、psr-0、classmap 和 files。
autoload-dev: 开发环境的额外自动加载规则，仅对根包有效。

其他高级配置

repositories: 定义额外的包来源，仅对根包有效。
minimum-stability: 默认包稳定性过滤级别，仅对根包有效。
prefer-stable: 是否优先使用稳定版本，仅对根包有效。
config: 各种配置选项，仅对根包有效。
scripts: 在安装过程中各个阶段执行的脚本钩子，仅对根包有效。
extra: 供脚本使用的任意额外数据。
bin: 应作为二进制文件安装的文件集合。

示例：

{
    "name": "monolog/monolog",
    "description": "Logging library",
    "keywords": ["logging", "psr-3"],
    "homepage": "https://github.com/Seldaek/monolog",
    "license": "MIT",
    "authors": [
        {
            "name": "Jordi Boggiano",
            "email": "j.boggiano@seld.be",
            "homepage": "https://seld.be"
        }
    ],
    "require": {
        "php": ">=5.3.0",
        "psr/log": "~1.0"
    },
    "autoload": {
        "psr-4": {"Monolog\\": "src/Monolog"}
    }
}

Repositories

https://getcomposer.org/doc/05-repositories.md

仓库是包的来源，Composer 会在所有配置的仓库中查找项目所需的包。本节介绍仓库的概念和类型。

仓库类型

1. Composer 仓库

使用单个 packages.json 文件包含所有包元数据的仓库类型，这也是 Packagist 使用的类型。

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://example.org"
        }
    ]
}

2. VCS 仓库

版本控制系统（Version Control System）仓库，支持从 git、svn、fossil 或 hg 仓库安装包。

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/username/repository"
        }
    ],
    "require": {
        "vendor/package": "dev-branch-name"
    }
}

使用 VCS 仓库的主要场景包括：

维护第三方库的自己的分支
使用私有仓库
需要直接从版本控制系统获取代码

3. Package 仓库

针对不支持 Composer 的项目，可以手动定义包的信息。

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "smarty/smarty",
                "version": "3.1.7",
                "dist": {
                    "url": "https://www.smarty.net/files/Smarty-3.1.7.zip",
                    "type": "zip"
                }
            }
        }
    ]
}

自托管仓库选项

当需要保持包私有或为项目创建独立生态系统时，可以选择自托管仓库：

Private Packagist：提供私有包托管和镜像功能的托管或自托管应用。
Satis：轻量级的静态 Composer 仓库生成器，适合小型团队。

Artifact 仓库：使用包含 ZIP 或 TAR 归档文件的文件夹作为包源。

{
    "repositories": [
        {
            "type": "artifact",
            "url": "path/to/directory/with/zips/"
        }
    ]
}

Path 仓库：直接依赖本地目录，对于单体仓库特别有用。

{
    "repositories": [
        {
            "type": "path",
            "url": "../../packages/my-package"
        }
    ]
}

禁用 Packagist.org

默认情况下，Composer 会使用 Packagist.org 作为包源。如需禁用：

{
    "repositories": [
        {
            "packagist.org": false
        }
    ]
}

或通过全局配置：

php composer.phar config -g repo.packagist false

Config

https://getcomposer.org/doc/06-config.md

Composer 配置选项可以通过 composer.json 中的 config 字段设置。以下是一些常用的配置项：

基本配置选项

process-timeout: 进程执行超时时间（秒），默认 300（5分钟）。

{
    "config": {
        "process-timeout": 900
    }
}

allow-plugins: 控制哪些 Composer 插件可以执行代码（Composer 2.2.0+）。

{
    "config": {
        "allow-plugins": {
            "vendor/plugin-name": true,
            "another-vendor/*": true
        }
    }
}

preferred-install: 首选安装方式，可为 source、dist 或 auto。

{
    "config": {
        "preferred-install": {
            "vendor/*": "source",
            "*": "dist"
        }
    }
}

仓库与认证

github-protocols: 克隆 GitHub 仓库使用的协议列表，默认 ["https", "ssh", "git"]。
github-oauth: GitHub OAuth 令牌列表。
gitlab-oauth/gitlab-token: GitLab OAuth 令牌或私有令牌列表。

http-basic: HTTP 基本认证信息。

{
    "config": {
        "http-basic": {
            "example.org": {
                "username": "username",
                "password": "password"
            }
        }
    }
}

目录与缓存

vendor-dir: 安装依赖的目录，默认为 vendor。
bin-dir: 二进制文件链接目录，默认为 vendor/bin。
cache-dir: 缓存目录。
cache-files-ttl: 缓存文件的存活时间（秒），默认 15552000（6个月）。
cache-files-maxsize: 缓存可使用的最大空间，默认 “300MiB”。

自动加载相关

optimize-autoloader: 始终优化自动加载器，默认 false。
prepend-autoloader: 是否将 Composer 自动加载器前置到已存在的自动加载器，默认 true。
classmap-authoritative: 设为 true 时，自动加载器只会从 classmap 加载类，默认 false。
apcu-autoloader: 是否使用 APCu 缓存查找的类，默认 false。

安全与其他

platform-check: 平台检查级别，默认 php-only，可设为 true 或 false。
secure-http: 是否只允许通过 HTTPS 下载包，默认 true。
discard-changes: 处理脏更新的方式，默认 false，可设为 true 或 stash。
sort-packages: 添加新包时是否按名称排序，默认 false。

全局配置

某些配置可通过命令行全局设置：

php composer.phar config -g repo.packagist false
php composer.phar config -g process-timeout 900

Runtime Composer utilities

https://getcomposer.org/doc/07-runtime.md

Composer 除了安装和管理依赖外，还提供了一些运行时实用工具。如果需要依赖特定版本的这些功能，可以通过 composer-runtime-api 包实现。

自动加载

最常用的运行时工具是自动加载器，在所有 Composer 版本中可用。

require __DIR__ . '/vendor/autoload.php';

// 现在可以使用项目的依赖了
$log = new Monolog\Logger('name');

已安装版本信息

Composer 2.0 引入了 Composer\InstalledVersions 类，提供了检查已安装包的静态方法。

检查包是否存在

\Composer\InstalledVersions::isInstalled('vendor/package'); // 返回布尔值
\Composer\InstalledVersions::isInstalled('psr/log-implementation'); // 检查虚拟包

从 Composer 2.1 开始，还可以检查包是否通过 require-dev 安装：

\Composer\InstalledVersions::isInstalled('vendor/package', false); // 仅检查 require 中的包

检查包版本

use Composer\Semver\VersionParser;

// 检查包是否满足版本约束
\Composer\InstalledVersions::satisfies(new VersionParser, 'vendor/package', '2.0.*');

// 获取包的版本号
$version = \Composer\InstalledVersions::getVersion('vendor/package'); // 标准化版本 (如 1.2.3.0)
$prettyVersion = \Composer\InstalledVersions::getPrettyVersion('vendor/package'); // 原始版本 (如 v1.2.3)

获取包的安装路径

// 获取包安装的绝对路径
$path = \Composer\InstalledVersions::getInstallPath('vendor/package');

查找指定类型的已安装包

// 获取所有类型为 'foo-plugin' 的已安装包
$packages = \Composer\InstalledVersions::getInstalledPackagesByType('foo-plugin');

平台检查

Composer 2.0 引入了 vendor/composer/platform_check.php 文件，会在包含自动加载器时自动执行。它会验证当前 PHP 环境是否满足平台要求，如 PHP 版本和扩展。

默认情况下，只检查 PHP 版本（php-only）。可以通过 platform-check 配置选项修改行为：

{
    "config": {
        "platform-check": true  // 也检查 PHP 扩展
    }
}

如果要禁用此安全检查：

{
    "config": {
        "platform-check": false
    }
}

二进制文件中的自动加载器路径

Composer 2.2 引入了全局变量 $_composer_autoload_path，它在运行 Composer 安装的二进制文件时设置。

二进制文件中的 bin-dir 路径

Composer 2.2.2 引入了全局变量 $_composer_bin_dir，它在运行 Composer 安装的二进制文件时设置。

Basic usage#

Libraries#

Command-line interface / Commands#

The composer.json schema#

基本字段#

作者与支持#

依赖管理#

自动加载配置#

其他高级配置#

Repositories#

仓库类型#

1. Composer 仓库#

2. VCS 仓库#

3. Package 仓库#

自托管仓库选项#

禁用 Packagist.org#

Config#

基本配置选项#

仓库与认证#

目录与缓存#

自动加载相关#

安全与其他#

全局配置#

Runtime Composer utilities#

自动加载#

已安装版本信息#

检查包是否存在#

检查包版本#

获取包的安装路径#

查找指定类型的已安装包#

平台检查#

二进制文件中的自动加载器路径#

二进制文件中的 bin-dir 路径#