🌍 cli_global — 全局操作

该示例演示如何通过 SDK 对 Composer 的全局环境执行包的安装、列出、更新、移除，以及获取全局目录、执行全局二进制、查看状态、生成自动加载等一整套全局运维能力。

📌 示例定位

• 学习目标：掌握 composer 包下所有 Global* 系列方法，理解全局操作与项目级操作的区别——全局命令作用于 COMPOSER_HOME，而非当前项目的 vendor/。
• 对应场景：全局安装 CLI 工具（如 phpstan、php-cs-fixer）、统一升级全局工具链、在 CI 镜像中预装常用二进制、查询全局环境状态。
• 对应 SDK 方法：composer 包下的 GlobalRequire、GlobalList、GlobalUpdate、GlobalRemove、GlobalHome、GlobalExecute、GlobalStatus、GlobalInstall、GlobalDumpAutoload，以及构造用的 New 与 DefaultOptions。
• 前置条件：本机已安装 PHP 7.4+ 与 Composer 2.0+。全局操作会修改 COMPOSER_HOME，建议在可重置的环境（容器/虚拟机）中运行。

📜 完整代码

package cli_global

import (
	"fmt"
	"log"

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

// Example01GlobalOperations 演示如何使用全局Composer操作
func Example01GlobalOperations() {
	c, err := composer.New(composer.DefaultOptions())
	if err != nil {
		log.Fatalf("无法创建Composer实例: %v", err)
	}

	// 示例1：全局安装包
	fmt.Println("1. 全局安装包...")
	err = c.GlobalRequire("phpstan/phpstan", "^1.0")
	if err != nil {
		log.Printf("全局安装包失败: %v", err)
	} else {
		fmt.Println("全局安装成功")
	}

	// 示例2：列出全局安装的包
	fmt.Println("\n2. 列出全局安装的包...")
	output, err := c.GlobalList()
	if err != nil {
		log.Printf("获取全局包列表失败: %v", err)
	} else {
		fmt.Println(output)
	}

	// 示例3：全局更新包
	fmt.Println("\n3. 全局更新包...")
	err = c.GlobalUpdate([]string{"phpstan/phpstan"})
	if err != nil {
		log.Printf("全局更新失败: %v", err)
	} else {
		fmt.Println("全局更新成功")
	}

	// 示例4：全局移除包
	fmt.Println("\n4. 全局移除包...")
	err = c.GlobalRemove("phpstan/phpstan")
	if err != nil {
		log.Printf("全局移除失败: %v", err)
	} else {
		fmt.Println("全局移除成功")
	}

	// 示例5：获取全局目录路径
	fmt.Println("\n5. 获取全局目录路径...")
	output, err = c.GlobalHome()
	if err != nil {
		log.Printf("获取全局目录失败: %v", err)
	} else {
		fmt.Printf("全局目录: %s\n", output)
	}

	// 示例6：执行全局安装的二进制文件
	fmt.Println("\n6. 执行全局安装的二进制文件...")
	output, err = c.GlobalExecute("phpstan", "analyse", "--no-progress")
	if err != nil {
		log.Printf("执行全局命令失败: %v", err)
	} else {
		fmt.Println(output)
	}

	// 示例7：查看全局包状态
	fmt.Println("\n7. 查看全局包状态...")
	output, err = c.GlobalStatus()
	if err != nil {
		log.Printf("获取全局状态失败: %v", err)
	} else {
		fmt.Println(output)
	}

	// 示例8：全局安装依赖
	fmt.Println("\n8. 全局安装依赖...")
	err = c.GlobalInstall()
	if err != nil {
		log.Printf("全局安装依赖失败: %v", err)
	} else {
		fmt.Println("全局依赖安装成功")
	}

	// 示例9：全局生成自动加载文件
	fmt.Println("\n9. 全局生成自动加载文件...")
	err = c.GlobalDumpAutoload(true)
	if err != nil {
		log.Printf("全局生成自动加载失败: %v", err)
	} else {
		fmt.Println("全局自动加载文件已生成")
	}
}

🧠 代码讲解

创建实例

🔧 用 composer.New(composer.DefaultOptions()) 创建实例。全局操作不依赖 WorkingDir——它们作用于 COMPOSER_HOME，因此无需像项目级示例那样调用 SetWorkingDir。

全局增删改（示例 1/3/4）

📥 GlobalRequire("phpstan/phpstan", "^1.0") 等价于 composer global require，把包写入全局 composer.json 并安装，第二个参数是版本约束。

🔄 GlobalUpdate([]string{"phpstan/phpstan"}) 只更新指定包；传空切片则更新全部全局包，等价于 composer global update。

🗑️ GlobalRemove("phpstan/phpstan") 从全局环境移除包并清理其依赖，等价于 composer global remove。

全局查询（示例 2/5/7）

📋 GlobalList() 返回全局已安装包的文本清单（composer global list 的原始输出），适合直接打印或日志归档。

🏠 GlobalHome() 返回 COMPOSER_HOME 路径，定位全局 vendor/、composer.json 等文件位置，是后续自定义脚本常需要的入口。

📊 GlobalStatus() 显示全局包的本地修改情况（composer global status），用于检测全局环境是否被手动改动过。

执行与维护（示例 6/8/9）

⚡ GlobalExecute("phpstan", "analyse", "--no-progress") 直接调用全局安装的二进制文件，等价于 composer global exec phpstan -- analyse --no-progress。这是把 Composer 全局工具链纳入自动化脚本的关键入口。

📦 GlobalInstall() 基于全局 composer.json 执行 composer global install，常用于在新机器上还原全局工具集。

🧩 GlobalDumpAutoload(true) 重新生成全局自动加载文件，true 表示启用优化（optimized classmap），等价于 composer global dump-autoload --optimize。

错误处理风格

⚠️ 注意本示例对每个调用都采用「失败仅 log.Printf 记录、继续执行下一步」的策略，便于一次性演示全部方法。生产环境中，安装/移除等关键步骤失败通常应短路返回，避免后续命令在异常状态下执行。

▶️ 运行方式

# 在仓库根目录执行
cd /home/cc11001100/github/scagogogo/composer-skills

# 运行 cli_global 示例（需要本机已安装 PHP 与 Composer）
go run examples/cli_global/01_global_operations.go

💡 全局操作会真实修改本机的 COMPOSER_HOME。若担心污染本地环境，建议在容器中运行；若本机未安装 Composer，SDK 会触发自动安装流程。

⚠️ 示例 1 会全局安装 phpstan/phpstan，示例 4 又会将其移除——若中途中断，可能残留全局包，可手动执行 composer global remove phpstan/phpstan 清理。

📚 涉及的 SDK 方法

方法名	所属包	文档链接
New	composer	/sdk/composer/methods/default-options
DefaultOptions	composer	/sdk/composer/methods/default-options
GlobalRequire	composer	/sdk/composer/methods/global-require
GlobalList	composer	/sdk/composer/methods/global-list
GlobalUpdate	composer	/sdk/composer/methods/global-update
GlobalRemove	composer	/sdk/composer/methods/global-remove
GlobalHome	composer	/sdk/composer/methods/get-composer-home
GlobalExecute	composer	/sdk/composer/methods/exec
GlobalStatus	composer	/sdk/composer/methods/status
GlobalInstall	composer	/sdk/composer/methods/global-install
GlobalDumpAutoload	composer	/sdk/composer/methods/dump-autoload

关于链接

GlobalHome、GlobalExecute、GlobalStatus、GlobalDumpAutoload 暂无独立方法页，上表链接指向其项目级对应方法的文档（GetComposerHome、Exec、Status、DumpAutoload），参数语义一致，仅作用域从项目目录切换为全局 COMPOSER_HOME。

🚀 进阶

• 🧰 全局工具链即代码：把团队约定的全局工具（phpstan、php-cs-fixer、psalm 等）及版本约束写成一个 Go 程序，新成员一键 GlobalRequire 全部装好，告别「环境配不平」。
• 🔄 带选项的变体：GlobalRequire/GlobalUpdate/GlobalRemove 各有对应的 *WithOptions 版本，可传入 --no-dev、--optimize-autoloader 等参数，适合在 CI 中精细控制全局安装行为。
• 📦 批量操作：搭配 GlobalRequireMultiple 与 GlobalRemoveMultiple 一次性安装/移除多个包，减少重复调用 composer 二进制的开销。
• 🗂️ 全局状态巡检：周期性调用 GlobalStatus 与 GlobalList，对比基线快照，发现全局环境被意外篡改的情况。
• 🐳 镜像层缓存：在 Dockerfile 中先用 GlobalRequire 预装工具，再 GlobalDumpAutoload(true) 优化自动加载，把全局工具链固化进镜像层，提升后续容器启动速度。