🌐 仓库

Composer SDK 的仓库模块负责 composer.json 中 repositories 配置的增删查改，以及与仓库相关的安装偏好（preferred-install）、最小稳定性（minimum-stability）、稳定优先（prefer-stable）等全局开关，并支持全局仓库管理。所有方法都挂在核心类型 Composer 上，定义在 pkg/composer/repository.go。

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

能力一览 🌐

方法	作用	返回值
AddRepository	添加任意类型仓库到 composer.json	error
RemoveRepository	从 composer.json 移除仓库	error
ListRepositories	列出当前项目配置的所有仓库	(string, error)
AddPackagistRepository	添加 Packagist.org 仓库或镜像	error
DisablePackagistRepository	禁用官方 Packagist 仓库	error
EnablePackagistRepository	启用官方 Packagist 仓库	error
AddVcsRepository	添加 VCS（Git/SVN）仓库	error
AddPathRepository	添加本地路径仓库	error
AddComposerRepository	添加 Composer 类型仓库	error
AddArtifactRepository	添加本地制品仓库	error
GetPreferredInstall	读取 preferred-install 配置	(string, error)
SetPreferredInstall	设置 preferred-install 配置	error
GetMinimumStability	读取 minimum-stability 配置	(string, error)
SetMinimumStability	设置 minimum-stability 配置	error
GetPreferStable	读取 prefer-stable 配置	(string, error)
SetPreferStable	设置 prefer-stable 配置	error
AddGlobalRepository	添加全局仓库（对所有项目生效）	error
RemoveGlobalRepository	移除全局仓库	error
ListGlobalRepositories	列出所有全局仓库	(string, error)

相关方法

repository.go 还提供通用配置项读写：SetConfigParameter、GetConfigParameter、UnsetConfig，等价于 composer config key [value] [--unset]。

---

🌐 RepositoryType / Repository 类型

仓库模块的核心数据结构，定义在 repository.go。

RepositoryType

type RepositoryType string

const (
	VcsRepository      RepositoryType = "vcs"
	ComposerRepository RepositoryType = "composer"
	PackagistRepository RepositoryType = "packagist"
	PathRepository     RepositoryType = "path"
	ArtifactRepository RepositoryType = "artifact"
	PearRepository     RepositoryType = "pear"
)

常量	值	说明
VcsRepository	vcs	版本控制系统仓库（Git/HG/SVN/Fossil）
ComposerRepository	composer	Composer 类型仓库（含 packages.json）
PackagistRepository	packagist	Packagist 仓库
PathRepository	path	本地路径仓库
ArtifactRepository	artifact	本地制品目录（含 zip/tar）
PearRepository	pear	PEAR 仓库

Repository

type Repository struct {
	Type    RepositoryType         `json:"type"`
	URL     string                 `json:"url,omitempty"`
	Name    string                 `json:"name,omitempty"`
	Options map[string]interface{} `json:"options,omitempty"`
}

字段	类型	说明
Type	RepositoryType	仓库类型
URL	string	仓库 URL 或路径
Name	string	仓库名称（仅序列化保留）
Options	map[string]interface{}	额外选项（如 symlink、canonical 等）

序列化

AddRepository 会把 Repository 序列化成 JSON 后通过 composer config repositories.name '<json>' 写入。

---

🌐 AddRepository

添加一个仓库到 composer.json，等价于 composer config repositories.name '{"type":"...","url":"..."}'。

何时使用

需要添加任意类型的自定义仓库（Composer、VCS、Path、Artifact、PEAR）时使用。这是底层通用方法，其它 AddXxxRepository 都基于它实现。

签名

func (c *Composer) AddRepository(name string, repo Repository) error

参数

参数	类型	说明
name	string	仓库名称（写入 repositories.<name>）
repo	Repository	仓库结构体，包含类型、URL、选项

返回值

• error：添加失败或 JSON 序列化失败时返回的错误。

示例

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

	// 添加一个私有的 Composer 仓库
	repo := composer.Repository{
		Type: composer.ComposerRepository,
		URL:  "https://composer.example.org",
	}
	if err := comp.AddRepository("private", repo); err != nil {
		log.Fatalf("添加仓库失败: %v", err)
	}
}

---

🌐 RemoveRepository

从 composer.json 中移除仓库，等价于 composer config --unset repositories.name。

何时使用

仓库不再使用、或要替换为另一个配置时使用。

签名

func (c *Composer) RemoveRepository(name string) error

参数

参数	类型	说明
name	string	要移除的仓库名称

返回值

• error：移除失败时返回的错误。

示例

if err := comp.RemoveRepository("private"); err != nil {
	log.Fatalf("移除仓库失败: %v", err)
}

---

🌐 ListRepositories

列出当前项目中配置的所有仓库，等价于 composer config repositories。

何时使用

需要查看当前项目接入了哪些包源时使用——常用于诊断"为什么某个包装不上"。

签名

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

返回值

• string：仓库列表的原始输出。
• error：列出失败时返回的错误。

示例

output, err := comp.ListRepositories()
if err != nil {
	log.Fatalf("列出仓库失败: %v", err)
}
fmt.Println("已配置的仓库:")
fmt.Println(output)

---

🌐 AddPackagistRepository

添加 Packagist.org 仓库（或镜像）。内部构造 type=packagist 的 Repository 并写入 repositories.packagist.org。

何时使用

切换 Packagist 镜像（如国内阿里云镜像）或重新启用官方源时使用。

签名

func (c *Composer) AddPackagistRepository(url string) error

参数

参数	类型	说明
url	string	Packagist 仓库 URL

返回值

• error：添加失败时返回的错误。

示例

// 添加官方 Packagist 仓库
if err := comp.AddPackagistRepository("https://repo.packagist.org"); err != nil {
	log.Fatalf("添加 Packagist 仓库失败: %v", err)
}

// 添加阿里云镜像
if err := comp.AddPackagistRepository("https://mirrors.aliyun.com/composer"); err != nil {
	log.Fatalf("添加 Packagist 镜像失败: %v", err)
}

写入位置固定

此方法写入的仓库名固定为 packagist.org。若需自定义名称，请改用 AddRepository。

---

🌐 DisablePackagistRepository

禁用官方 Packagist.org 仓库，等价于 composer config repositories.packagist.org.url false。

何时使用

只使用私有仓库、且不希望 Composer 回退到 Packagist 时使用。

签名

func (c *Composer) DisablePackagistRepository() error

返回值

• error：禁用失败时返回的错误。

示例

if err := comp.DisablePackagistRepository(); err != nil {
	log.Fatalf("禁用 Packagist 仓库失败: %v", err)
}

---

🌐 EnablePackagistRepository

启用官方 Packagist.org 仓库，等价于 composer config repositories.packagist.org.url https://repo.packagist.org。

何时使用

从禁用状态恢复、或镜像失效后切回官方源时使用。

签名

func (c *Composer) EnablePackagistRepository() error

返回值

• error：启用失败时返回的错误。

示例

if err := comp.EnablePackagistRepository(); err != nil {
	log.Fatalf("启用 Packagist 仓库失败: %v", err)
}

---

🌐 AddVcsRepository

添加版本控制系统（Git/SVN/HG/Fossil）仓库，内部构造 type=vcs 的 Repository。

何时使用

从 GitHub/GitLab/Gitee 等代码托管平台拉取尚未发布到 Packagist 的包时使用。

签名

func (c *Composer) AddVcsRepository(name string, url string) error

参数

参数	类型	说明
name	string	仓库名称
url	string	VCS 仓库 URL

返回值

• error：添加失败时返回的错误。

示例

if err := comp.AddVcsRepository("my-lib", "https://github.com/vendor/package"); err != nil {
	log.Fatalf("添加 VCS 仓库失败: %v", err)
}

---

🌐 AddPathRepository

添加本地路径仓库，内部构造 type=path 的 Repository 并携带 Options。

何时使用

本地同时开发多个相互依赖的包（monorepo 或软链接开发模式）时使用，可避免反复发布到远程仓库。

签名

func (c *Composer) AddPathRepository(name string, path string, options map[string]interface{}) error

参数

参数	类型	说明
name	string	仓库名称
path	string	本地路径（相对或绝对）
options	map[string]interface{}	仓库选项，如 {"symlink": true}

返回值

• error：添加失败时返回的错误。

示例

options := map[string]interface{}{
	"symlink": true,
}
if err := comp.AddPathRepository("local", "../my-package", options); err != nil {
	log.Fatalf("添加路径仓库失败: %v", err)
}

常用选项

• symlink（bool）：用软链接而非复制安装。
• canonical（bool）：是否优先于此仓库。
• versions（map）：手动指定可用版本。

---

🌐 AddComposerRepository

添加 Composer 类型仓库（含 packages.json 的仓库服务），内部构造 type=composer 的 Repository。

何时使用

接入私有 Composer 仓库服务（如 Satis、Private Packagist、自建镜像）时使用。

签名

func (c *Composer) AddComposerRepository(name string, url string) error

参数

参数	类型	说明
name	string	仓库名称
url	string	Composer 仓库 URL

返回值

• error：添加失败时返回的错误。

示例

if err := comp.AddComposerRepository("private", "https://composer.example.org"); err != nil {
	log.Fatalf("添加 Composer 仓库失败: %v", err)
}

---

🌐 AddArtifactRepository

添加本地制品仓库。该目录下应包含包的 .zip / .tar 压缩文件，内部构造 type=artifact 的 Repository。

何时使用

离线环境或内网分发已打包的包时使用——无需 VCS 与 Packagist。

签名

func (c *Composer) AddArtifactRepository(name string, path string) error

参数

参数	类型	说明
name	string	仓库名称
path	string	制品目录路径

返回值

• error：添加失败时返回的错误。

示例

if err := comp.AddArtifactRepository("artifacts", "./packages"); err != nil {
	log.Fatalf("添加制品仓库失败: %v", err)
}

---

🌐 GetPreferredInstall

获取 preferred-install 配置，等价于 composer config preferred-install。

何时使用

需要确认当前项目优先使用 dist 还是 source 安装时使用。

签名

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

返回值

• string：当前的 preferred-install 值（dist / source / auto）。
• error：获取失败时返回的错误。

示例

value, err := comp.GetPreferredInstall()
if err != nil {
	log.Fatalf("获取 preferred-install 失败: %v", err)
}
fmt.Printf("当前的 preferred-install: %s\n", value)

---

🌐 SetPreferredInstall

设置 preferred-install 配置，等价于 composer config preferred-install value。

何时使用

需要切换安装方式时使用——CI 优先 dist（快、省流量），调试源码时用 source。

签名

func (c *Composer) SetPreferredInstall(value string) error

参数

参数	类型	说明
value	string	必须是 dist、source 或 auto 之一

返回值

• error：值非法或设置失败时返回的错误。

示例

// 优先使用打包版本
if err := comp.SetPreferredInstall("dist"); err != nil {
	log.Fatalf("设置 preferred-install 失败: %v", err)
}

值校验

value 只接受 dist、source、auto，其它值会直接返回 invalid preferred-install value 错误，不会写入。

---

🌐 GetMinimumStability

获取最小稳定性配置，等价于 composer config minimum-stability。

何时使用

需要知道当前项目允许安装多不稳定的包时使用。

签名

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

返回值

• string：当前的最小稳定性（stable / RC / beta / alpha / dev）。
• error：获取失败时返回的错误。

示例

stability, err := comp.GetMinimumStability()
if err != nil {
	log.Fatalf("获取最小稳定性失败: %v", err)
}
fmt.Printf("当前的最小稳定性: %s\n", stability)

---

🌐 SetMinimumStability

设置最小稳定性配置，等价于 composer config minimum-stability stability。

何时使用

需要放宽或收紧可安装包的稳定性门槛时使用——例如允许安装 beta 版本尝鲜。

签名

func (c *Composer) SetMinimumStability(stability string) error

参数

参数	类型	说明
stability	string	稳定性级别，如 stable、RC、beta、alpha、dev

返回值

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

示例

// 允许安装 beta 版本的包
if err := comp.SetMinimumStability("beta"); err != nil {
	log.Fatalf("设置最小稳定性失败: %v", err)
}

与 prefer-stable 配合

单独放开 minimum-stability 可能引入大量不稳定包。配合 SetPreferStable(true) 可在允许不稳定的同时优先选择稳定版本。

---

🌐 GetPreferStable

获取是否优先使用稳定版本的配置，等价于 composer config prefer-stable。

何时使用

需要确认 prefer-stable 开关状态时使用。

签名

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

返回值

• string："1" 表示启用，"0" 表示禁用。
• error：获取失败时返回的错误。

示例

value, err := comp.GetPreferStable()
if err != nil {
	log.Fatalf("获取 prefer-stable 失败: %v", err)
}
preferStable := value == "1"
fmt.Printf("当前是否优先使用稳定版本: %v\n", preferStable)

返回字符串而非布尔

此方法返回 "0" / "1" 字符串，需要自行 value == "1" 转换为布尔。

---

🌐 SetPreferStable

设置是否优先使用稳定版本包，等价于 composer config prefer-stable <0|1>。

何时使用

放开 minimum-stability 后希望仍优先解析稳定版本时使用。

签名

func (c *Composer) SetPreferStable(preferStable bool) error

参数

参数	类型	说明
preferStable	bool	true 优先稳定版本（写入 "1"），false 写入 "0"

返回值

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

示例

// 设置优先使用稳定版本
if err := comp.SetPreferStable(true); err != nil {
	log.Fatalf("设置 prefer-stable 失败: %v", err)
}

---

🌐 AddGlobalRepository

添加全局仓库，对所有项目生效，等价于 composer config --global repositories.name '<json>'。

何时使用

需要在所有项目中接入某个私有仓库或镜像时使用——避免每个项目单独配置。

签名

func (c *Composer) AddGlobalRepository(name string, repo Repository) error

参数

参数	类型	说明
name	string	仓库名称
repo	Repository	仓库结构体

返回值

• error：添加失败或 JSON 序列化失败时返回的错误。

示例

repo := composer.Repository{
	Type: composer.ComposerRepository,
	URL:  "https://composer.example.org",
}
if err := comp.AddGlobalRepository("global-private", repo); err != nil {
	log.Fatalf("添加全局仓库失败: %v", err)
}

与 AddRepository 的区别

AddRepository 写入项目级 composer.json 的 repositories；AddGlobalRepository 写入全局 ~/.composer/config.json 的 repositories，影响所有项目。

---

🌐 RemoveGlobalRepository

删除全局仓库，等价于 composer config --global --unset repositories.name。

何时使用

全局仓库不再使用时清理，避免 Composer 解析失效地址。

签名

func (c *Composer) RemoveGlobalRepository(name string) error

参数

参数	类型	说明
name	string	要删除的全局仓库名称

返回值

• error：删除失败时返回的错误。

示例

if err := comp.RemoveGlobalRepository("global-private"); err != nil {
	log.Fatalf("删除全局仓库失败: %v", err)
}

---

🌐 ListGlobalRepositories

列出所有已配置的全局仓库，等价于 composer config --global repositories。

何时使用

排查"为什么全局多了一个仓库"或核对全局配置时使用。

签名

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

返回值

• string：全局仓库列表的原始输出。
• error：列出失败时返回的错误。

示例

output, err := comp.ListGlobalRepositories()
if err != nil {
	log.Fatalf("列出全局仓库失败: %v", err)
}
fmt.Println("全局仓库列表:")
fmt.Println(output)

---

🌐 通用配置项读写

repository.go 还提供三个直接操作任意配置项的通用方法：

方法	签名	作用
SetConfigParameter	func (c *Composer) SetConfigParameter(key string, value string) error	设置配置项，等价于 composer config key value
GetConfigParameter	func (c *Composer) GetConfigParameter(key string) (string, error)	获取配置项，等价于 composer config key
UnsetConfig	func (c *Composer) UnsetConfig(key string) error	删除配置项，等价于 composer config --unset key

示例

// 设置项目描述
_ = comp.SetConfigParameter("description", "我的PHP项目")

// 设置作者信息（数组下标语法）
_ = comp.SetConfigParameter("authors.0.name", "张三")
_ = comp.SetConfigParameter("authors.0.email", "zhangsan@example.com")

// 读取项目名称
name, _ := comp.GetConfigParameter("name")
fmt.Printf("项目名称: %s\n", name)

// 删除一个不再需要的仓库
_ = comp.UnsetConfig("repositories.old-repo")

与配置模块的关系

GetConfigWithGlobal / SetConfigWithGlobal（配置模块）多一个 global bool 参数，可读写全局配置；而本页这三个方法只操作当前项目级配置。若需修改 repositories.* 之外的复杂配置，可优先使用 composer.json 文件操作 中的 SetConfig。

---

进阶与相关

• 🧩 Satis 模块：用 SDK 搭建私有 Composer 仓库服务（CreateSatisConfig、BuildSatis）。
• 📄 composer.json 操作：AddRepository 走的是 composer config 命令；若需直接操作 composer.json 的 repositories 字段，可用 ReadComposerJSON / WriteComposerJSON。
• 🌍 全局操作模块：global 子命令下的 require / update / remove / install / list 等。