Composer 包的开发与发布

概述

本文整理了 Composer 包从本地开发到将开发的composer包发布到packagist的全流程，适用于 PHP 开发者快速实现 Composer 包的开发与共享。

整体流程

一、本地项目初始化与开发

1. 创建 composer.json 文件

通过命令行交互方式

 composer init

执行后需按提示填写包名称（格式：厂商名/包名，如 haveyb/redis-helper）、描述、版本、作者、依赖等信息，完成后自动生成 composer.json。

也可以不执行这个命令，直接复制一个composer.json文件过来改。

2. 设计目录结构并编写代码

推荐基础目录结构（可根据项目复杂度扩展）：

项目根目录/
├── src/                  # 核心代码目录
│   ├── RedisHelper.php   # 功能类文件
│   └── RedisInstance.php # 实例化/辅助类文件
├── composer.json         # 包配置文件（核心）
├── composer.lock         # 依赖锁定文件（自动生成，勿手动修改）
└── README.md             # 项目说明文档（含安装、使用教程）

编写代码时需遵循 PSR 规范，确保自动加载正常生效。

3. 生成 composer.lock 文件

项目开发完成后，执行以下命令锁定依赖版本（避免后续环境差异）：

composer update

说明：若项目无额外依赖，执行后仍会生成 composer.lock，记录当前包的基础配置与版本信息。

　

二、关联 GitHub 仓库

1. GitHub 端创建仓库

  • 登录 GitHub，创建新仓库（推荐仓库名与 Composer 包名一致）。

  • 仓库类型建议设为「Public」（私有仓库需 Packagist 付费支持），无需初始化 README 或 gitignore（避免与本地冲突）。

2. 本地项目关联 Git 并绑定远程仓库

# 1. 本地初始化 Git 仓库
git init

# 2. 关联 GitHub 远程仓库（替换为你的仓库地址）
git remote add origin https://github.com/你的用户名/仓库名.git

# 3. 拉取远程仓库（确保本地与远程版本一致，首次创建的仓库可忽略此步，若有冲突需先解决）
git pull origin master --allow-unrelated-histories

# 4. 删除 vendor 目录（无需提交依赖目录，Composer 会自动安装）
rm -rf vendor/

　

三、提交代码并打 Tag 版本

1. 提交代码到 GitHub

# 1. 添加所有文件到暂存区
git add .

# 2. 提交代码（备注信息建议含版本号，如 v1.0 初始版本）
git commit -m "v1.0: 初始版本，实现 Redis 辅助功能"

# 3. 推送到 GitHub 主分支（若分支名不是 master，需替换为实际分支名，如 main）
git push origin master

2. 打 Tag 并推送（关键步骤）

Composer 包依赖 Git Tag 识别版本，必须执行此步骤：

# 1. 本地创建 Tag（版本号需遵循语义化版本规范，如 v1.0.0、v1.1.0）
git tag v1.0

# 2. 推送 Tag 到 GitHub（使 Packagist 能识别版本）
git push origin --tags

说明：后续迭代版本时，需更新 Tag（如 v1.0.1）并重新推送。

　

四、发布composer包到 Packagist

1. 准备工作

  • 注册/登录 Packagist（可通过 GitHub 账号快捷登录）。

  • 确保 GitHub 仓库已公开，且 composer.json 配置合法（无语法错误）。

2. 提交包到 Packagist

  • 登录 Packagist 后，点击顶部「Submit」按钮。

  • 输入 GitHub 仓库地址（如 https://github.com/你的用户名/仓库名.git），点击「Check」。

  • 校验通过后，点击「Submit」完成发布。

3. 自动同步配置（可选但推荐）

为避免每次更新代码后手动同步 Packagist，可配置 GitHub WebHook：

  • 进入 GitHub 仓库 → 「Settings」→ 「Webhooks」→ 「Add webhook」。

  • Payload URL 填写：https://packagist.org/api/github。

  • Content type 选择：application/json。

  • Secret 填写：从 Packagist 个人设置（「Profile」→「API Tokens」）中生成的 Token。

  • 触发事件选择：「Just the push event」，点击「Add webhook」完成配置。

注意事项

1. composer.json 配置规范

  • 必须包含 name（厂商名/包名，全局唯一）、type（默认 library）、autoload（自动加载规则）字段。

  • 示例基础配置：

    {
"name": "xxx/redis-helper",
"description": "Redis 操作辅助包",
"type": "library",
"version": "1.0",
"autoload": {
 "psr-4": {
   "Xxx\\RedisHelper\\": "src/"
 }
},
"require": {
 "php": ">=7.2" // 最低 PHP 版本要求
}
}

2. 版本号规范

遵循语义化版本（Semantic Versioning）：主版本号（重大变更）.次版本号（功能新增）.修订号（Bug 修复），如 v1.0.0、v1.1.0、v1.0.1。

3. 后续维护

  • 迭代版本时，需先更新 composer.json 中的 version 字段，再提交代码并创建新 Tag（如 v1.0.1）。

  • 若修改依赖，需重新执行 composer update 更新 composer.lock 后再提交。

验证发布结果

1. 在 Packagist 搜索包名（如 haveyb/redis-helper），查看是否显示正常。

2. 本地新建测试项目，执行 composer require haveyb/redis-helper:v1.0，检查是否能成功安装并使用。

相关文章