⚙️ 配置

Composer SDK 的配置模块负责 composer config 子命令的全部能力——校验、缓存、配置项读写、来源追踪、平台要求检查，以及结构化的 config --list 解析。所有方法都挂在核心类型 Composer 上，定义在 pkg/composer/config.go。

与 composer.json 文件操作的区别

本页方法走的是 composer config 子命令（会真正调用 composer 二进制并影响全局/项目配置）。如果你只想纯文件读写 composer.json 中的 config 字段或顶级属性，请看 composer.json 操作（ReadComposerJSON、SetConfig、SetProperty、AddRequire 等）。

包路径：github.com/scagogogo/composer-skills/pkg/composer

能力一览 ⚙️

方法	作用	返回值
Validate	验证 composer.json 是否有效	error
GetComposerHome	获取 Composer 主目录	(string, error)
ClearCache	清除 Composer 缓存	error
GetConfigWithGlobal	读取指定配置项，可选全局	(string, error)
SetConfigWithGlobal	设置指定配置项，可选全局	error
ListConfig	列出所有配置值	(string, error)
ListConfigWithGlobal	列出全局或项目配置	(string, error)
GetConfigSource	查询配置项的来源文件	(string, error)
CheckPlatformReqs	检查平台要求	(string, error)
ValidateComposerJson	带选项校验 composer.json	error
GetConfigStructured	列出配置并以结构化结果返回	(*ConfigResult, error)

---

⚙️ Validate

验证 composer.json 是否有效，等价于 composer validate。

何时使用

在写入或修改 composer.json 后、提交代码前，确认文件结构与字段合法时使用。

签名

func (c *Composer) Validate() error

返回值

• error：校验失败时返回的错误。

示例

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)
	}

	if err := comp.Validate(); err != nil {
		log.Fatalf("composer.json 无效: %v", err)
	}
	fmt.Println("composer.json 校验通过")
}

进阶

需要更细粒度校验时使用 ValidateComposerJson(strict, withDependencies)，或参考 校验模块 中的 ValidateStrict、ValidateSchema、ValidateQuiet 等变体。

---

⚙️ GetComposerHome

获取 Composer 主目录，等价于 composer config --global home。

何时使用

需要定位 Composer 全局配置文件、全局 vendor 目录或 auth.json 时使用。

签名

func (c *Composer) GetComposerHome() (string, error)

返回值

• string：Composer 主目录路径（已去除首尾空白）。
• error：获取失败时返回的错误。

示例

home, err := comp.GetComposerHome()
if err != nil {
	log.Fatalf("获取 Composer 主目录失败: %v", err)
}
fmt.Printf("Composer 主目录: %s\n", home)

便捷别名

便捷查询模块 中的 GetComposerHomeDir 提供相同能力，并额外提供 GetCacheDir、GetVendorDir、GetBinDir 等目录定位方法。

---

⚙️ ClearCache

清除 Composer 缓存，等价于 composer clear-cache。

何时使用

遇到包下载损坏、镜像同步滞后、磁盘空间紧张时使用。

签名

func (c *Composer) ClearCache() error

返回值

• error：清除过程中发生的错误。

示例

if err := comp.ClearCache(); err != nil {
	log.Fatalf("清除缓存失败: %v", err)
}
fmt.Println("缓存已清空")

---

⚙️ GetConfigWithGlobal

获取 Composer 配置项的值，可选择读取全局配置，等价于 composer config [--global] setting。

何时使用

需要在程序里读取某个配置项（如 process-timeout、preferred-install、bin-dir）时使用。

签名

func (c *Composer) GetConfigWithGlobal(setting string, global bool) (string, error)

参数

参数	类型	说明
setting	string	配置项名称，如 process-timeout
global	bool	true 读取全局配置，false 读取项目配置

返回值

• string：配置项的值（已去除首尾空白）。
• error：获取失败时返回的错误。

示例

// 读取项目级 process-timeout
timeout, err := comp.GetConfigWithGlobal("process-timeout", false)
if err != nil {
	log.Fatalf("读取配置失败: %v", err)
}
fmt.Printf("process-timeout = %s\n", timeout)

// 读取全局 bin-dir
binDir, err := comp.GetConfigWithGlobal("bin-dir", true)
if err != nil {
	log.Fatalf("读取全局配置失败: %v", err)
}
fmt.Printf("全局 bin-dir = %s\n", binDir)

---

⚙️ SetConfigWithGlobal

设置 Composer 配置项的值，可选择写入全局配置，等价于 composer config [--global] setting value。

何时使用

需要程序化调整某个配置项时使用——例如 CI 里把 preferred-install 切成 dist，或初始化容器时设置全局 bin-dir。

签名

func (c *Composer) SetConfigWithGlobal(setting string, value string, global bool) error

参数

参数	类型	说明
setting	string	配置项名称
value	string	要设置的值
global	bool	true 写入全局配置，false 写入项目配置

返回值

• error：设置失败时返回的错误。

示例

// 全局设置 preferred-install 为 dist
if err := comp.SetConfigWithGlobal("preferred-install", "dist", true); err != nil {
	log.Fatalf("设置全局配置失败: %v", err)
}

// 项目级设置 process-timeout
if err := comp.SetConfigWithGlobal("process-timeout", "300", false); err != nil {
	log.Fatalf("设置项目配置失败: %v", err)
}

写入位置

global=false 时值写入当前项目的 composer.json 的 config 字段；global=true 时写入全局 config.json。请确认 Composer 的工作目录正确。

---

⚙️ ListConfig

列出所有配置值，等价于 composer config --list。

何时使用

需要一次性查看当前项目所有 Composer 配置项及其值时使用，常用于调试与诊断。

签名

func (c *Composer) ListConfig() (string, error)

返回值

• string：所有配置值的列表（原始输出）。
• error：列出配置失败时返回的错误（已包裹为"列出配置失败"）。

示例

output, err := comp.ListConfig()
if err != nil {
	log.Fatalf("列出配置失败: %v", err)
}
fmt.Println("配置列表:")
fmt.Println(output)

进阶

需要结构化结果（按 Key/Value/Source 拆分）时使用 GetConfigStructured；需要区分全局/项目时使用 ListConfigWithGlobal。

---

⚙️ ListConfigWithGlobal

列出所有配置值，可选择列出全局配置或项目配置，等价于 composer config --list [--global]。

何时使用

需要分别查看全局与项目级配置时使用——例如排查某个配置项被哪一层覆盖。

签名

func (c *Composer) ListConfigWithGlobal(global bool) (string, error)

参数

参数	类型	说明
global	bool	true 列出全局配置，false 列出项目配置

返回值

• string：配置值列表。
• error：列出配置失败时返回的错误。

示例

// 列出全局配置
globalCfg, err := comp.ListConfigWithGlobal(true)
if err != nil {
	log.Fatalf("列出全局配置失败: %v", err)
}
fmt.Println("全局配置:")
fmt.Println(globalCfg)

// 列出项目配置
projectCfg, err := comp.ListConfigWithGlobal(false)
if err != nil {
	log.Fatalf("列出项目配置失败: %v", err)
}
fmt.Println("项目配置:")
fmt.Println(projectCfg)

---

⚙️ GetConfigSource

获取指定配置项的来源信息，等价于 composer config key --source。

何时使用

调试配置问题时使用——它能告诉你某个值是从项目 composer.json、全局 config.json 还是默认值加载的。

签名

func (c *Composer) GetConfigSource(key string) (string, error)

参数

参数	类型	说明
key	string	要查询来源的配置项名称

返回值

• string：配置项的来源信息（已去除首尾空白）。
• error：获取失败时返回的错误（已包裹为"获取配置来源失败"）。

示例

source, err := comp.GetConfigSource("preferred-install")
if err != nil {
	log.Fatalf("获取配置来源失败: %v", err)
}
fmt.Printf("preferred-install 的来源: %s\n", source)

---

⚙️ CheckPlatformReqs

检查平台要求，等价于 composer check-platform-reqs。

何时使用

部署前确认当前 PHP 版本与扩展满足项目（含依赖）的平台要求时使用。

签名

func (c *Composer) CheckPlatformReqs() (string, error)

返回值

• string：平台要求检查的原始输出。
• error：检查失败时返回的错误。

示例

output, err := comp.CheckPlatformReqs()
if err != nil {
	log.Fatalf("平台要求检查失败: %v", err)
}
fmt.Println(output)

进阶

需要结构化结果（每条要求的 Package/Version/Status/Required）时使用 CheckPlatformReqsStructured（定义在 result_types.go，返回 *PlatformCheckResult）；如需带格式输出可参考 CheckPlatformReqsWithFormat（additional_methods.go）。

---

⚙️ ValidateComposerJson

带选项校验 composer.json，等价于 composer validate [--strict] [--with-dependencies]。

何时使用

需要严格模式校验、或连带检查依赖的 composer.json 合法性时使用。

签名

func (c *Composer) ValidateComposerJson(strict bool, withDependencies bool) error

参数

参数	类型	说明
strict	bool	true 启用 --strict 严格模式
withDependencies	bool	true 连带检查依赖包的 composer.json

返回值

• error：校验失败时返回的错误。

示例

// 严格模式 + 连带检查依赖
if err := comp.ValidateComposerJson(true, true); err != nil {
	log.Fatalf("校验失败: %v", err)
}
fmt.Println("composer.json 及其依赖均校验通过")

---

⚙️ GetConfigStructured

列出配置并以结构化结果返回。内部执行 composer config --list 后用 ParseConfigList 解析。

何时使用

需要在程序里遍历配置项并按 Key/Value/Source 处理时使用——例如生成配置报告、对比两套环境差异。

签名

func (c *Composer) GetConfigStructured() (*ConfigResult, error)

返回值

• *ConfigResult：结构化配置结果，Items 为 []ConfigItem。
• error：执行或解析错误。

示例

result, err := comp.GetConfigStructured()
if err != nil {
	log.Fatalf("获取结构化配置失败: %v", err)
}
for _, item := range result.Items {
	fmt.Printf("%s = %s\n", item.Key, item.Value)
}

---

⚙️ ConfigItem / ConfigResult 类型

GetConfigStructured 返回的结构体，定义在 pkg/composer/result_types.go。

type ConfigItem struct {
	Key    string `json:"key"`
	Value  string `json:"value"`
	Source string `json:"source,omitempty"`
}

type ConfigResult struct {
	Items []ConfigItem `json:"items,omitempty"`
}

类型	字段	说明
ConfigItem	Key	配置项名称
ConfigItem	Value	配置项值
ConfigItem	Source	来源信息（可能为空）
ConfigResult	Items	全部配置项列表

解析逻辑

ParseConfigList 按行分割 composer config --list 的输出，每行按首个空格切成 Key 与 Value 两段。空行会被跳过。

---

📄 与 composer.json 文件操作的联动

配置模块走 composer config 子命令，而下面这些方法（来自 composer_json.go）走纯文件读写，二者互补：

方法	签名	作用
ReadComposerJSON	func (c *Composer) ReadComposerJSON() (*ComposerJSON, error)	读取并解析整个 composer.json
WriteComposerJSON	func (c *Composer) WriteComposerJSON(composerJSON *ComposerJSON) error	把结构体写回 composer.json
AddRequire	func (c *Composer) AddRequire(packageName, version string, isDev bool) error	追加依赖到 require/require-dev
AddScript	func (c *Composer) AddScript(name string, script interface{}, description string) error	添加脚本及可选描述
AddAutoload	func (c *Composer) AddAutoload(type_ string, namespace string, paths interface{}, isDev bool) error	添加自动加载规则
SetConfig	func (c *Composer) SetConfig(key string, value interface{}) error	设置 composer.json 的 config 字段
GetConfig	func (c *Composer) GetConfig(key string) (interface{}, error)	读取 composer.json 的 config 字段
SetProperty	func (c *Composer) SetProperty(property string, value interface{}) error	设置顶级属性（name/description/type 等）

SetConfig vs SetConfigWithGlobal

• SetConfig(key, value)（composer_json.go）：直接改 composer.json 文件的 config 字段，不调用 composer，值可以是任意 interface{}（数字、布尔、对象）。
• SetConfigWithGlobal(setting, value, global)（config.go，本页）：走 composer config 命令，值只能是 string，可写全局。

按需选择：批量结构化写入用前者，单条命令式写入用后者。

以上方法的完整签名、参数、示例与注意事项请见 composer.json 操作。

---

进阶与相关

• 📄 composer.json 操作：纯文件读写 composer.json 的全部方法。
• ✅ 校验模块：ValidateStrict、ValidateSchema、ValidateComposerLock 等更细粒度的校验变体。
• 🧱 平台模块：CheckPlatform、GetPHPVersion、HasExtension 等平台检查能力。
• 🏗️ 仓库模块：SetPreferredInstall、SetMinimumStability、SetPreferStable 等通过 composer config 修改仓库与稳定性相关配置的方法。