⚙️ cli_configuration — 配置管理

本示例演示如何用 SDK 程序化操作 composer.json、composer config、认证令牌与仓库源——四大配置场景一网打尽。

🎯 示例定位

examples/cli_configuration 把「配置类」操作拆成四个函数，对应 Composer 的四套配置体系：📄 composer.json 文件操作（依赖/脚本/自动加载/config/顶级属性，不调用二进制）、⚙️ composer config 命令（读写项目级与全局级配置、查主目录、清缓存）、🔑 认证管理（GitHub/GitLab/Bearer/HTTP Basic 凭证）、🗂️ 仓库管理（VCS/Composer/Path/Artifact 源、启停 Packagist、稳定性策略）。学完即掌握脚手架、CI、私有镜像场景的全部配置 API。

📜 完整代码

package cli_configuration

import (
	"fmt"
	"log"

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

// Example01ComposerJson 操作 composer.json（纯文件，不调用 composer）
func Example01ComposerJson() {
	c, err := composer.New(composer.DefaultOptions())
	if err != nil {
		log.Fatalf("无法创建Composer实例: %v", err)
	}
	c.SetWorkingDir("/path/to/project")

	// 1. 读取 composer.json
	if cj, err := c.ReadComposerJSON(); err != nil {
		log.Printf("读取失败: %v", err)
	} else {
		fmt.Printf("项目: %s / %s / %s\n", cj.Name, cj.Description, cj.Type)
	}

	// 2. 设置顶级属性（仅支持 name/description/type/keywords 等）
	c.SetProperty("name", "myvendor/mypackage")
	c.SetProperty("description", "一个很棒的PHP库")
	c.SetProperty("keywords", []string{"php", "library"})

	// 3. 添加/移除依赖（只改文件，不执行安装）
	c.AddRequire("symfony/console", "^6.0", false) // require
	c.AddRequire("phpunit/phpunit", "^10.0", true) // require-dev
	c.RemoveRequire("old/package", false)

	// 4. 添加/移除脚本
	c.AddScript("test", "phpunit", "运行测试")
	c.AddScript("post-install-cmd", []string{"php artisan optimize:clear"}, "安装后清理缓存")
	c.RemoveScript("old-script")

	// 5. 自动加载（psr-4 / psr-0 / classmap / files）
	c.AddAutoload("psr-4", "App\\", "src/", false)
	c.AddAutoload("psr-4", "Tests\\", "tests/", true)

	// 6. 读写 composer.json 的 config 字段
	c.SetConfig("process-timeout", 500)
	timeout, _ := c.GetConfig("process-timeout")
	fmt.Printf("进程超时: %v\n", timeout)
}

// Example02Config 走 composer config 命令（项目级/全局级）
func Example02Config() {
	c, _ := composer.New(composer.DefaultOptions())
	c.SetWorkingDir("/path/to/project")

	v, _ := c.GetConfigWithGlobal("vendor-dir", false) // false=项目级
	fmt.Printf("vendor-dir: %s\n", v)
	c.SetConfigWithGlobal("vendor-dir", "vendor", false)

	g, _ := c.GetConfigWithGlobal("bin-dir", true) // true=全局
	fmt.Printf("全局 bin-dir: %s\n", g)

	home, _ := c.GetComposerHome()
	fmt.Printf("Composer主目录: %s\n", home)
	c.ClearCache()
}

// Example03Auth 管理认证配置（auth.json）
func Example03Auth() {
	c, _ := composer.New(composer.DefaultOptions())

	auth, _ := c.GetAuthConfig()
	fmt.Printf("GitHub令牌数: %d, GitLab令牌数: %d\n", len(auth.GitHub), len(auth.GitLab))

	c.AddGitHubToken("github.com", "your-github-token")
	c.AddGitLabToken("gitlab.com", "your-gitlab-token")
	c.AddBearerToken("example.com", "your-bearer-token")
	c.AddHTTPBasicAuth("example.com", "username", "password")

	// authType ∈ github-oauth / gitlab-oauth / bearer / http-basic
	token, _ := c.GetToken("github-oauth", "github.com")
	fmt.Printf("GitHub令牌: %s\n", token)
	c.RemoveToken("github-oauth", "github.com")
}

// Example04Repository 管理仓库源
func Example04Repository() {
	c, _ := composer.New(composer.DefaultOptions())
	c.SetWorkingDir("/path/to/project")

	output, _ := c.ListRepositories()
	fmt.Println(output)

	c.AddVcsRepository("my-vcs", "https://github.com/myorg/myrepo")
	c.AddComposerRepository("private-repo", "https://packages.example.com")
	c.AddPathRepository("local-lib", "../my-lib", nil)
	c.AddArtifactRepository("my-artifacts", "/path/to/artifacts")
	c.RemoveRepository("my-vcs")

	c.DisablePackagistRepository()
	c.EnablePackagistRepository()

	c.SetMinimumStability("stable")
	c.SetPreferStable(true)
}

🔍 代码讲解

• 🚀 创建实例：composer.New(composer.DefaultOptions()) 拿到 *Composer，SetWorkingDir 指定要操作的 PHP 项目目录。本机若无 composer，AutoInstall=true 会自动拉取。
• 📄 读 → 改 → 写模式：ReadComposerJSON 返回结构化 *ComposerJSON，随后的 SetProperty / AddRequire / AddScript / AddAutoload / SetConfig 都在内存中改文件并原子写回，全程不调用 composer 二进制。
• ⚙️ 两条 config 路线分清：SetConfig / GetConfig（composer_json.go）只改 JSON 文件的 config 字段，值可为任意类型；GetConfigWithGlobal / SetConfigWithGlobal（config.go）走 composer config 命令，值必须为字符串，第三参 global bool 控制全局/项目级。
• 🔑 认证按类型分桶：四类 Add* 方法分别写入 auth.json 的不同字段；GetToken / RemoveToken 的 authType 必须是 github-oauth / gitlab-oauth / bearer / http-basic 之一。
• 🗂️ 仓库四件套：VCS（Git 仓库）、Composer（私有镜像）、Path（本地路径，第三参可传 options）、Artifact（打包目录）覆盖几乎所有私有源场景；DisablePackagistRepository 适合纯内网环境。
• 🧯 错误处理：示例用 log.Printf 记录失败但继续执行，便于一次跑完所有步骤；生产环境建议遇错即返回。

▶️ 运行方式

git clone https://github.com/scagogogo/composer-skills.git
cd composer-skills/examples/cli_configuration

# 需本机已装 PHP 7.4+ 与 Composer 2.0+，否则 SDK 会自动安装
go run 01_composer_json_config_auth_repo.go

会真实改文件

示例中的 /path/to/project 是占位路径，运行前请改成你本机真实 PHP 项目目录。认证与仓库写入会真实修改该项目的 composer.json 与 auth.json，建议在测试项目里跑。

📚 涉及的 SDK 方法

方法	文档链接
New / DefaultOptions / SetWorkingDir	new · set-working-dir
ReadComposerJSON / SetProperty / AddRequire / RemoveRequire / AddScript / RemoveScript / AddAutoload	read-composer-json · set-property · add-require · remove-require · add-script · remove-script · add-autoload
SetConfig / GetConfig	composer.json 操作
GetConfigWithGlobal / SetConfigWithGlobal / GetComposerHome / ClearCache	get-config-with-global · set-config-with-global · get-composer-home · clear-cache
GetAuthConfig / AddGitHubToken / AddGitLabToken / AddBearerToken / AddHTTPBasicAuth / GetToken / RemoveToken	get-auth-config · add-github-token · add-gitlab-token · add-bearer-token · add-http-basic-auth · 认证管理
ListRepositories / AddVcsRepository / AddComposerRepository / AddPathRepository / AddArtifactRepository / RemoveRepository / DisablePackagistRepository / EnablePackagistRepository	list-repositories · add-vcs-repository · add-composer-repository · add-path-repository · remove-repository · 仓库管理
SetMinimumStability / SetPreferStable	set-minimum-stability · set-prefer-stable

所有方法均属于 pkg/composer。

🚀 进阶

• 🏗️ 脚手架组合拳：WriteComposerJSON（写空模板）+ SetProperty + AddRequire + AddAutoload 串起来即可程序化生成全新项目的 composer.json，无需 composer init 交互。
• 🔐 CI 安全注入：流水线里用 AddBearerToken / AddHTTPBasicAuth 临时注入私有源凭证，跑完用 RemoveToken 清理，避免凭据落盘。
• 🪞 镜像加速：AddComposerRepository 加国内镜像，再 DisablePackagistRepository 关停官方源，依赖拉取全程走镜像。
• 🧪 Mock 测试：SetMockComposerJSON 让 ReadComposerJSON 返回注入数据，单测无需真实项目目录（注意便捷版 ReadComposerJson 不受此 mock 影响）。
• 🔄 文件 vs 命令：只改文件用 composer_json.go 系（快、不依赖二进制、值类型自由）；需触发 composer 真正生效（重算 lock、刷新元数据）则用 config.go 系走命令。