🛠️ Composer CLI SDK 概览

pkg/composer 是 Composer Skills 项目中最核心的模块。它把本地 composer 二进制封装成一套类型安全、可测试、可自动安装的 Go SDK，对外提供 234 个方法，覆盖依赖管理、包操作、项目创建、配置、仓库、审计、诊断、平台检查、版本约束等几乎所有 Composer CLI 能力。

如果你只想记住一个入口，那就是 核心运行：通过 composer.New(composer.DefaultOptions()) 拿到一个 *Composer，之后所有方法都挂在它上面。

📦 模块定位

• 📦 包路径：github.com/scagogogo/composer-skills/pkg/composer
• 🛠️ 核心类型：Composer（结构体，非接口，方法集合都在 *Composer 上）
• 🌐 底层机制：通过 os/exec 调用本地 composer 可执行文件，所有命令的输出经 CombinedOutput 合并 stdout/stderr 后以 string 返回
• 🔒 可测试性：内置 SetupMockOutput 机制，可在不真正执行 composer 的情况下注入任意命令的预期输出与错误
• ⚡ 自动安装：未检测到 composer 时，Options.AutoInstall=true 会触发内置安装器自动拉取并安装 composer

🚀 创建一个 Composer 实例

最小可用示例——检测/自动安装 composer 并在当前目录工作：

package main

import (
    "log"

    "github.com/scagogogo/composer-skills/pkg/composer"
)

func main() {
    comp, err := composer.New(composer.DefaultOptions())
    if err != nil {
        log.Fatalf("初始化 Composer 失败: %v", err)
    }
    // comp 现在可以执行任意 composer 子命令
    if err := comp.Install(false, false); err != nil {
        log.Fatalf("安装依赖失败: %v", err)
    }
}

想更省事？

直接用 composer.QuickSetup(workingDir, true)（位于 auto_install.go），一步完成检测、安装与实例创建。

想完全控制实例的行为，自定义 Options：

options := composer.Options{
    WorkingDir:     "/srv/my-app",
    AutoInstall:    true,
    DefaultTimeout: 30 * time.Minute,
    Env:            []string{"COMPOSER_HOME=/tmp/composer"},
}
comp, err := composer.New(options)

DefaultOptions() 返回的默认配置是：WorkingDir=""（当前目录）、AutoInstall=true、DefaultTimeout=10*time.Minute。

🗂️ 20 个分类总览

下表把 pkg/composer 的全部方法按职责归类，方便你按场景跳转到对应子文档。方法数为近似值（含主方法与 WithOptions/WithFormat 等变体）。

分类	方法数	重点方法	子文档
🛠️ 核心运行	11	New、Run、RunWithContext、IsInstalled、SelfUpdate	core
📦 依赖管理	18	Install、Update、DumpAutoload、InstallWithOptions、UpdateWithLock	dependencies
🔍 包操作	28	RequirePackage、Remove、ShowPackage、Search、OutdatedPackages、BumpPackages、WhyNotPackage	packages
➕ 扩展方法	25	OutdatedWithOptions、InstallDryRun、RequireMultiple、WhyWithOptions	—
🗜️ 归档	5	Archive、ArchivePackage、ArchiveWithFormat	—
🔒 安全审计	10	Audit、AuditWithJSON、HasVulnerabilities、GetAbandonedPackages	audit
✅ 自动安装	6	EnsureInstalled、QuickSetup、SelfUpdateWithProgress	—
⌨️ 命令补全	4	GenerateCompletion、ListCommands、GetCommandHelp	—
📋 composer.json 操作	11	ReadComposerJSON、AddRequire、AddScript、SetConfig	—
⚙️ 配置	10	ListConfig、GetConfigWithGlobal、SetConfigWithGlobal、CheckPlatformReqs	—
🧩 便捷查询	27	IsProject、HasComposerLock、GetDirectDependencyNames、IsPackageInstalled	—
🩺 诊断	8	Diagnose、Status、Check、LocalExec	diagnosis
🌐 环境变量	18	SetEnvVariable、SetProcessTimeout、EnableSuperuser、DisableInteraction	—
▶️ 脚本执行	6	Exec、ExecPHP、ExecAll、ExecWithWorkingDir	exec
💰 资助	6	Fund、FundWithJSON、HasFunding、GetFundingURLs	fund
🌍 全局	12	GlobalRequire、GlobalUpdate、GlobalList、GlobalDumpAutoload	—
❤️ 健康检查	9	HealthCheck、BatchRequire、BatchRemove、StatusStructured	—
📜 许可证	4	Licenses、CheckLicenses	licenses
🔑 OAuth/认证	9	GetAuthConfig、AddGitHubToken、AddGitLabToken、AddBearerToken	auth
🏗️ 平台	6	CheckPlatform、GetPHPVersion、HasExtension、IsPlatformAvailable	platform

此外还有若干独立分类（验证 validate、版本约束、版本 version、项目 project、仓库、Satis satis、archive、environment、completion、home、about、composer-json、convenience、输出解析 parsing 等），详见左侧导航。

说明：上表中「核心运行」「依赖管理」「包操作」三类的全部方法签名、参数、返回值与示例分别在 core、dependencies、packages 中详细展开。

⚡ 快速示例

1. 安装并锁定生产依赖

comp, _ := composer.New(composer.DefaultOptions())
comp.SetWorkingDir("/srv/my-app")

// 生产环境：跳过开发依赖 + 优化自动加载
if err := comp.Install(true, true); err != nil {
    log.Fatal(err)
}
// 仅刷新 composer.lock 哈希，不改变任何包版本
_ = comp.UpdateWithLock()

2. 添加/移除包并查看过时依赖

_ = comp.RequirePackage("symfony/console", "^6.0", false)
_ = comp.Remove("old/dep", true) // 从 require-dev 移除

outdated, _ := comp.GetOutdatedInfo() // 结构化结果
for _, p := range outdated.Installed {
    fmt.Printf("%s: %s -> %s (%s)\n", p.Name, p.Installed, p.Latest, p.LatestStatus)
}

3. 用结构化方式查包信息与搜索

info, _ := comp.ShowPackageInfo("monolog/monolog")
fmt.Printf("%s %s — %s\n", info.Name, info.Version, info.Description)

res, _ := comp.SearchInfo("logger")
for _, r := range res.Results {
    fmt.Println(r.Name, r.Description)
}

4. 带超时与取消的命令执行

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
out, err := comp.RunWithContext(ctx, "update", "--prefer-dist")
if errors.Is(err, context.DeadlineExceeded) {
    log.Println("更新超时")
}

🎯 设计约定

• 🎯 返回值统一：所有命令方法要么返回 (string, error)（拿到原始输出），要么返回 error（只关心是否成功）；结构化方法在此基础上多返回一个指针类型，如 (*PackageInfo, error)。
• ⚠️ 错误包裹：执行失败时返回的 error 用 fmt.Errorf("%w: ...", ErrCommandExecution, ...) 包裹预定义哨兵错误，便于用 errors.Is 判断类别。
• 🧩 WithOptions 模式：几乎每个命令都有 XxxWithOptions(options map[string]string) 变体，options 的键是 composer 长选项名（不含 --），值为空串表示纯开关选项。
• 🧪 Mock 友好：测试中用 SetupMockOutput("require symfony/console", "ok", nil) 注入预期输出，RunWithContext 会优先命中 mock，不真正调用 composer。

📚 下一步

• 🛠️ 先读 核心运行：搞懂 New、Run 与自动安装/自更新机制。
• 📦 再看 依赖管理：掌握 Install/Update 的全部变体。
• 🔍 最后看 包操作：学会 require/remove/show/search/outdated 等高频操作。
• 🔒 安全相关见 安全审计；校验相关见 校验。