🏗️ 项目管理

Composer SDK 的项目管理模块覆盖项目从创建、初始化、脚本执行到打包归档的完整生命周期。所有方法都挂在核心类型 Composer 上，定义在 pkg/composer/project.go。

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

能力一览 🏗️

方法	作用	返回值
CreateProject	基于骨架包创建新项目	error
CreateProjectWithOptions	创建项目并附带额外选项	error
InitProject	交互式初始化 composer.json	error
InitProjectWithOptions	非交互式初始化并指定名称/描述/作者	error
RunScript	执行 composer.json 中定义的脚本，可传参	(string, error)
ExecuteScript	用 composer run 执行自定义脚本	(string, error)
ArchiveProject	把当前项目打包成 zip/tar 归档	error
GetProjectInfo	解析当前项目基本信息（名称、描述、类型、依赖）	(*ComposerJsonInfo, error)
ListScripts	列出 composer.json 中定义的全部脚本	(string, error)

关键类型

ComposerJsonInfo 是 GetProjectInfo 的结构化返回，定义在本文件中，仅包含项目最常被读取的几个字段。

---

🏗️ CreateProject

基于指定包名创建一个新项目，等价于 composer create-project package/name directory version。

何时使用

需要从某个骨架包（如 laravel/laravel、symfony/website-skeleton）拉起一个全新工程时使用。

签名

func (c *Composer) CreateProject(packageName string, directory string, version string) error

参数

参数	类型	说明
packageName	string	包名，例如 laravel/laravel
directory	string	项目落地目录
version	string	版本约束，空字符串表示最新版本

返回值

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

	// 创建最新版本的 Laravel 项目
	if err := comp.CreateProject("laravel/laravel", "my-project", ""); err != nil {
		log.Fatalf("创建项目失败: %v", err)
	}

	// 创建指定版本的 Symfony 项目
	if err := comp.CreateProject("symfony/website-skeleton", "symfony-project", "^5.0"); err != nil {
		log.Fatalf("创建项目失败: %v", err)
	}
}

进阶

需要 --no-dev、--prefer-dist、自定义仓库等额外参数时，使用 CreateProjectWithOptions。

---

🏗️ CreateProjectWithOptions

带额外选项创建项目，等价于 composer create-project [options] package/name[:version] directory。

何时使用

默认 CreateProject 不够用、需要控制安装方式（无开发依赖、镜像源、稳定性等）时使用。

签名

func (c *Composer) CreateProjectWithOptions(packageName string, directory string, version string, options map[string]string) error

参数

参数	类型	说明
packageName	string	包名
directory	string	项目落地目录
version	string	版本约束，空字符串表示最新版本
options	map[string]string	额外选项，键为选项名，值为选项值（值空字符串表示开关型选项）

选项构造规则

options 经内部 buildOptionsArgs 处理：键按字典序排序后，值为空则生成 --key，否则生成 --key=value，保证命令构造确定性。

返回值

• error：创建过程中发生的错误。

示例

// 创建无开发依赖的 Laravel 项目
options := map[string]string{
	"no-dev":      "",
	"prefer-dist": "",
}
if err := comp.CreateProjectWithOptions("laravel/laravel", "my-project", "", options); err != nil {
	log.Fatalf("创建项目失败: %v", err)
}

// 从私有仓库创建指定稳定性的 Symfony 项目
options = map[string]string{
	"stability":   "dev",
	"repository":  "https://example.org/private-repo",
}
if err := comp.CreateProjectWithOptions("symfony/website-skeleton", "symfony-project", "^5.0", options); err != nil {
	log.Fatalf("创建项目失败: %v", err)
}

---

🏗️ InitProject

交互式初始化一个新项目，等价于 composer init。

何时使用

在空目录里手搓一个 composer.json 时使用。命令会以交互方式询问项目信息。

签名

func (c *Composer) InitProject() error

返回值

• error：初始化过程中发生的错误。

示例

if err := comp.InitProject(); err != nil {
	log.Fatalf("初始化项目失败: %v", err)
}

进阶

在自动化脚本/CI 中无法交互时，改用 InitProjectWithOptions 一次性传入项目元信息。

---

🏗️ InitProjectWithOptions

非交互式初始化项目，等价于 composer init --name=... --description=... --author=... [options]。

何时使用

需要在 CI、脚手架、容器等无 TTY 的环境里生成 composer.json 时使用。

签名

func (c *Composer) InitProjectWithOptions(name string, description string, author string, options map[string]string) error

参数

参数	类型	说明
name	string	项目名称，格式 vendor/name
description	string	项目描述
author	string	作者信息，格式 Name <email>
options	map[string]string	额外选项，如 type、license、no-interaction

返回值

• error：初始化过程中发生的错误。

示例

options := map[string]string{
	"type":           "library",
	"license":        "MIT",
	"no-interaction": "",
}
if err := comp.InitProjectWithOptions(
	"myvendor/awesome-lib",
	"一个很棒的PHP库",
	"张三 <zhangsan@example.com>",
	options,
); err != nil {
	log.Fatalf("初始化项目失败: %v", err)
}

---

🏗️ RunScript

执行 composer.json 中定义的脚本并传参，等价于 composer run-script script-name -- arg1 arg2。

何时使用

在程序里触发 test、build、deploy 等已定义脚本，且需要向脚本透传额外参数时使用。

签名

func (c *Composer) RunScript(scriptName string, args ...string) (string, error)

参数

参数	类型	说明
scriptName	string	要执行的脚本名称
args	...string	透传给脚本的额外参数

返回值

• string：命令执行的输出结果。
• error：执行过程中发生的错误。

示例

output, err := comp.RunScript("test", "--filter=UserTest")
if err != nil {
	log.Fatalf("执行脚本失败: %v", err)
}
fmt.Println(output)

---

🏗️ ExecuteScript

用 composer run 执行 composer.json 中定义的自定义脚本，等价于 composer run script-name。

何时使用

执行自定义脚本（非 Composer 内置脚本事件）时使用。与 RunScript 的区别在于它走 composer run 命令，且不接受透传参数。

签名

func (c *Composer) ExecuteScript(scriptName string) (string, error)

参数

参数	类型	说明
scriptName	string	要执行的脚本名称

返回值

• string：命令执行的输出结果。
• error：执行过程中发生的错误。

示例

output, err := comp.ExecuteScript("deploy")
if err != nil {
	log.Fatalf("执行脚本失败: %v", err)
}
fmt.Println(output)

---

🏗️ ArchiveProject

把当前项目打包成归档文件，等价于 composer archive --dir=directory --format=format。

何时使用

需要把项目分发给离线环境或归档备份时使用。

签名

func (c *Composer) ArchiveProject(directory string, format string) error

参数

参数	类型	说明
directory	string	归档输出目录，空字符串则使用默认目录
format	string	归档格式，如 zip 或 tar，空字符串则使用默认格式

返回值

• error：创建存档过程中发生的错误。

示例

// 创建 ZIP 格式的存档
if err := comp.ArchiveProject("./dist", "zip"); err != nil {
	log.Fatalf("创建存档失败: %v", err)
}

进阶

archive.go 中还有更细粒度的归档方法：Archive、ArchiveWithFormat、ArchiveWithOptions、ArchivePackage、ArchivePackageWithOptions，可对任意包/版本单独归档。

---

🏗️ ComposerJsonInfo 类型

GetProjectInfo 返回的结构体，表示 composer.json 的部分信息。

type ComposerJsonInfo struct {
	Name        string            `json:"name"`
	Description string            `json:"description"`
	Type        string            `json:"type"`
	Require     map[string]string `json:"require"`
	RequireDev  map[string]string `json:"require-dev"`
}

字段	类型	说明
Name	string	项目名称
Description	string	项目描述
Type	string	项目类型
Require	map[string]string	生产依赖
RequireDev	map[string]string	开发依赖

字段范围

ComposerJsonInfo 只覆盖最常被读取的字段。需要完整 composer.json 结构时，请使用 配置模块 中的 ReadComposerJSON（返回完整的 ComposerJSON 结构）。

---

🏗️ GetProjectInfo

获取当前项目基本信息，等价于执行 composer config --list --json 并解析结果。

何时使用

需要在程序里读取项目名称、描述、类型和依赖清单时使用。

签名

func (c *Composer) GetProjectInfo() (*ComposerJsonInfo, error)

返回值

• *ComposerJsonInfo：包含项目基本信息的结构体指针。
• error：获取或解析过程中发生的错误。

示例

info, err := comp.GetProjectInfo()
if err != nil {
	log.Fatalf("获取项目信息失败: %v", err)
}
fmt.Printf("项目名称: %s\n", info.Name)
fmt.Printf("项目描述: %s\n", info.Description)
fmt.Printf("依赖数量: %d\n", len(info.Require))

---

🏗️ ListScripts

列出 composer.json 中定义的所有脚本，等价于 composer run-script --list。

何时使用

需要枚举当前项目可用的脚本清单（常用于脚手架、CLI 提示）时使用。

签名

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

返回值

• string：包含所有脚本列表的输出结果。
• error：列出脚本过程中发生的错误。

示例

output, err := comp.ListScripts()
if err != nil {
	log.Fatalf("列出脚本失败: %v", err)
}
fmt.Println("可用脚本:")
fmt.Println(output)

进阶

需要以结构化方式读取脚本时，可使用 便捷方法模块 中的 GetScripts，返回 map[string]interface{}。