🌐 Repository

The Composer SDK's repository module handles CRUD operations on the repositories configuration in composer.json, as well as repository-related installation preferences (preferred-install), minimum stability (minimum-stability), prefer-stable (prefer-stable) and other global switches, and supports global repository management. All methods are attached to the core type Composer and defined in pkg/composer/repository.go.

Package path: github.com/scagogogo/composer-skills/pkg/composer

Capability Overview 🌐

Method	Purpose	Return Value
AddRepository	Add a repository of any type to composer.json	error
RemoveRepository	Remove a repository from composer.json	error
ListRepositories	List all repositories configured for the current project	(string, error)
AddPackagistRepository	Add the Packagist.org repository or a mirror	error
DisablePackagistRepository	Disable the official Packagist repository	error
EnablePackagistRepository	Enable the official Packagist repository	error
AddVcsRepository	Add a VCS (Git/SVN) repository	error
AddPathRepository	Add a local path repository	error
AddComposerRepository	Add a Composer type repository	error
AddArtifactRepository	Add a local artifact repository	error
GetPreferredInstall	Read the preferred-install config	(string, error)
SetPreferredInstall	Set the preferred-install config	error
GetMinimumStability	Read the minimum-stability config	(string, error)
SetMinimumStability	Set the minimum-stability config	error
GetPreferStable	Read the prefer-stable config	(string, error)
SetPreferStable	Set the prefer-stable config	error
AddGlobalRepository	Add a global repository (effective for all projects)	error
RemoveGlobalRepository	Remove a global repository	error
ListGlobalRepositories	List all global repositories	(string, error)

Related Methods

repository.go also provides generic config read/write: SetConfigParameter, GetConfigParameter, UnsetConfig, equivalent to composer config key [value] [--unset].

---

🌐 RepositoryType / Repository Types

The core data structures of the repository module, defined in 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"
)

Constant	Value	Description
VcsRepository	vcs	Version control system repository (Git/HG/SVN/Fossil)
ComposerRepository	composer	Composer type repository (contains packages.json)
PackagistRepository	packagist	Packagist repository
PathRepository	path	Local path repository
ArtifactRepository	artifact	Local artifact directory (contains zip/tar)
PearRepository	pear	PEAR repository

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"`
}

Field	Type	Description
Type	RepositoryType	Repository type
URL	string	Repository URL or path
Name	string	Repository name (kept only for serialization)
Options	map[string]interface{}	Additional options (e.g., symlink, canonical)

Serialization

AddRepository serializes the Repository to JSON and writes it via composer config repositories.name '<json>'.

---

🌐 AddRepository

Add a repository to composer.json, equivalent to composer config repositories.name '{"type":"...","url":"..."}'.

When to Use

Use to add a custom repository of any type (Composer, VCS, Path, Artifact, PEAR). This is the low-level generic method; the other AddXxxRepository methods are all built on top of it.

Signature

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

Parameters

Parameter	Type	Description
name	string	Repository name (written to repositories.<name>)
repo	Repository	Repository struct, containing type, URL, options

Return Values

• error: Error returned when adding fails or JSON serialization fails.

Example

package main

import (
	"log"

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

func main() {
	comp, err := composer.New(composer.DefaultOptions())
	if err != nil {
		log.Fatalf("Failed to initialize Composer: %v", err)
	}

	// Add a private Composer repository
	repo := composer.Repository{
		Type: composer.ComposerRepository,
		URL:  "https://composer.example.org",
	}
	if err := comp.AddRepository("private", repo); err != nil {
		log.Fatalf("Failed to add repository: %v", err)
	}
}

---

🌐 RemoveRepository

Remove a repository from composer.json, equivalent to composer config --unset repositories.name.

When to Use

Use when a repository is no longer in use, or when replacing it with another config.

Signature

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

Parameters

Parameter	Type	Description
name	string	Name of the repository to remove

Return Values

• error: Error returned when removal fails.

Example

if err := comp.RemoveRepository("private"); err != nil {
	log.Fatalf("Failed to remove repository: %v", err)
}

---

🌐 ListRepositories

List all repositories configured in the current project, equivalent to composer config repositories.

When to Use

Use to see which package sources the current project is hooked into — commonly used to diagnose "why a certain package won't install".

Signature

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

Return Values

• string: Raw output of the repository list.
• error: Error returned when listing fails.

Example

output, err := comp.ListRepositories()
if err != nil {
	log.Fatalf("Failed to list repositories: %v", err)
}
fmt.Println("Configured repositories:")
fmt.Println(output)

---

🌐 AddPackagistRepository

Add the Packagist.org repository (or a mirror). Internally constructs a Repository with type=packagist and writes it to repositories.packagist.org.

When to Use

Use to switch the Packagist mirror (e.g., the Alibaba mirror in China) or re-enable the official source.

Signature

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

Parameters

Parameter	Type	Description
url	string	Packagist repository URL

Return Values

• error: Error returned when adding fails.

Example

// Add the official Packagist repository
if err := comp.AddPackagistRepository("https://repo.packagist.org"); err != nil {
	log.Fatalf("Failed to add Packagist repository: %v", err)
}

// Add the Alibaba mirror
if err := comp.AddPackagistRepository("https://mirrors.aliyun.com/composer"); err != nil {
	log.Fatalf("Failed to add Packagist mirror: %v", err)
}

Fixed Write Location

The repository name written by this method is fixed to packagist.org. If you need a custom name, use AddRepository instead.

---

🌐 DisablePackagistRepository

Disable the official Packagist.org repository, equivalent to composer config repositories.packagist.org.url false.

When to Use

Use when you only want to use private repositories and don't want Composer to fall back to Packagist.

Signature

func (c *Composer) DisablePackagistRepository() error

Return Values

• error: Error returned when disabling fails.

Example

if err := comp.DisablePackagistRepository(); err != nil {
	log.Fatalf("Failed to disable Packagist repository: %v", err)
}

---

🌐 EnablePackagistRepository

Enable the official Packagist.org repository, equivalent to composer config repositories.packagist.org.url https://repo.packagist.org.

When to Use

Use to restore from a disabled state, or to switch back to the official source after a mirror fails.

Signature

func (c *Composer) EnablePackagistRepository() error

Return Values

• error: Error returned when enabling fails.

Example

if err := comp.EnablePackagistRepository(); err != nil {
	log.Fatalf("Failed to enable Packagist repository: %v", err)
}

---

🌐 AddVcsRepository

Add a version control system (Git/SVN/HG/Fossil) repository; internally constructs a Repository with type=vcs.

When to Use

Use to pull packages from code hosting platforms like GitHub/GitLab/Gitee that have not been published to Packagist.

Signature

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

Parameters

Parameter	Type	Description
name	string	Repository name
url	string	VCS repository URL

Return Values

• error: Error returned when adding fails.

Example

if err := comp.AddVcsRepository("my-lib", "https://github.com/vendor/package"); err != nil {
	log.Fatalf("Failed to add VCS repository: %v", err)
}

---

🌐 AddPathRepository

Add a local path repository; internally constructs a Repository with type=path and carries Options.

When to Use

Use when developing multiple interdependent packages locally (monorepo or symlink development mode) to avoid repeatedly publishing to remote repositories.

Signature

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

Parameters

Parameter	Type	Description
name	string	Repository name
path	string	Local path (relative or absolute)
options	map[string]interface{}	Repository options, e.g., {"symlink": true}

Return Values

• error: Error returned when adding fails.

Example

options := map[string]interface{}{
	"symlink": true,
}
if err := comp.AddPathRepository("local", "../my-package", options); err != nil {
	log.Fatalf("Failed to add path repository: %v", err)
}

Common Options

• symlink (bool): install via symlink instead of copy.
• canonical (bool): whether to prioritize this repository.
• versions (map): manually specify available versions.

---

🌐 AddComposerRepository

Add a Composer type repository (a repository service containing packages.json); internally constructs a Repository with type=composer.

When to Use

Use to hook into a private Composer repository service (e.g., Satis, Private Packagist, self-hosted mirror).

Signature

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

Parameters

Parameter	Type	Description
name	string	Repository name
url	string	Composer repository URL

Return Values

• error: Error returned when adding fails.

Example

if err := comp.AddComposerRepository("private", "https://composer.example.org"); err != nil {
	log.Fatalf("Failed to add Composer repository: %v", err)
}

---

🌐 AddArtifactRepository

Add a local artifact repository. The directory should contain .zip / .tar archive files of packages; internally constructs a Repository with type=artifact.

When to Use

Use for offline environments or intranet distribution of pre-packaged packages — no VCS or Packagist needed.

Signature

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

Parameters

Parameter	Type	Description
name	string	Repository name
path	string	Artifact directory path

Return Values

• error: Error returned when adding fails.

Example

if err := comp.AddArtifactRepository("artifacts", "./packages"); err != nil {
	log.Fatalf("Failed to add artifact repository: %v", err)
}

---

🌐 GetPreferredInstall

Get the preferred-install config, equivalent to composer config preferred-install.

When to Use

Use to confirm whether the current project prefers dist or source for installation.

Signature

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

Return Values

• string: Current preferred-install value (dist / source / auto).
• error: Error returned when retrieval fails.

Example

value, err := comp.GetPreferredInstall()
if err != nil {
	log.Fatalf("Failed to get preferred-install: %v", err)
}
fmt.Printf("Current preferred-install: %s\n", value)

---

🌐 SetPreferredInstall

Set the preferred-install config, equivalent to composer config preferred-install value.

When to Use

Use to switch the installation method — CI prefers dist (fast, saves bandwidth), use source when debugging source code.

Signature

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

Parameters

Parameter	Type	Description
value	string	Must be one of dist, source, or auto

Return Values

• error: Error returned when the value is invalid or setting fails.

Example

// Prefer packaged releases
if err := comp.SetPreferredInstall("dist"); err != nil {
	log.Fatalf("Failed to set preferred-install: %v", err)
}

Value Validation

value only accepts dist, source, auto; other values directly return an invalid preferred-install value error and will not be written.

---

🌐 GetMinimumStability

Get the minimum stability config, equivalent to composer config minimum-stability.

When to Use

Use to know how unstable a package the current project allows to install.

Signature

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

Return Values

• string: Current minimum stability (stable / RC / beta / alpha / dev).
• error: Error returned when retrieval fails.

Example

stability, err := comp.GetMinimumStability()
if err != nil {
	log.Fatalf("Failed to get minimum stability: %v", err)
}
fmt.Printf("Current minimum stability: %s\n", stability)

---

🌐 SetMinimumStability

Set the minimum stability config, equivalent to composer config minimum-stability stability.

When to Use

Use to relax or tighten the stability threshold for installable packages — e.g., allow beta versions to try out new features.

Signature

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

Parameters

Parameter	Type	Description
stability	string	Stability level, e.g., stable, RC, beta, alpha, dev

Return Values

• error: Error returned when setting fails.

Example

// Allow installing beta versions of packages
if err := comp.SetMinimumStability("beta"); err != nil {
	log.Fatalf("Failed to set minimum stability: %v", err)
}

Pair with prefer-stable

Relaxing minimum-stability alone may pull in many unstable packages. Pair with SetPreferStable(true) to prefer stable versions while still allowing unstable ones.

---

🌐 GetPreferStable

Get the config for whether to prefer stable versions, equivalent to composer config prefer-stable.

When to Use

Use to confirm the state of the prefer-stable switch.

Signature

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

Return Values

• string: "1" means enabled, "0" means disabled.
• error: Error returned when retrieval fails.

Example

value, err := comp.GetPreferStable()
if err != nil {
	log.Fatalf("Failed to get prefer-stable: %v", err)
}
preferStable := value == "1"
fmt.Printf("Currently preferring stable versions: %v\n", preferStable)

Returns String, Not Bool

This method returns "0" / "1" strings; you need to convert to bool yourself via value == "1".

---

🌐 SetPreferStable

Set whether to prefer stable version packages, equivalent to composer config prefer-stable <0|1>.

When to Use

Use when you want to still prefer resolving stable versions after relaxing minimum-stability.

Signature

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

Parameters

Parameter	Type	Description
preferStable	bool	true prefers stable versions (writes "1"), false writes "0"

Return Values

• error: Error returned when setting fails.

Example

// Set to prefer stable versions
if err := comp.SetPreferStable(true); err != nil {
	log.Fatalf("Failed to set prefer-stable: %v", err)
}

---

🌐 AddGlobalRepository

Add a global repository, effective for all projects, equivalent to composer config --global repositories.name '<json>'.

When to Use

Use to hook into a private repository or mirror across all projects — avoiding per-project configuration.

Signature

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

Parameters

Parameter	Type	Description
name	string	Repository name
repo	Repository	Repository struct

Return Values

• error: Error returned when adding fails or JSON serialization fails.

Example

repo := composer.Repository{
	Type: composer.ComposerRepository,
	URL:  "https://composer.example.org",
}
if err := comp.AddGlobalRepository("global-private", repo); err != nil {
	log.Fatalf("Failed to add global repository: %v", err)
}

Difference from AddRepository

AddRepository writes to the project-level composer.json's repositories; AddGlobalRepository writes to the global ~/.composer/config.json's repositories, affecting all projects.

---

🌐 RemoveGlobalRepository

Remove a global repository, equivalent to composer config --global --unset repositories.name.

When to Use

Use to clean up global repositories that are no longer in use, preventing Composer from resolving to invalid addresses.

Signature

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

Parameters

Parameter	Type	Description
name	string	Name of the global repository to remove

Return Values

• error: Error returned when removal fails.

Example

if err := comp.RemoveGlobalRepository("global-private"); err != nil {
	log.Fatalf("Failed to remove global repository: %v", err)
}

---

🌐 ListGlobalRepositories

List all configured global repositories, equivalent to composer config --global repositories.

When to Use

Use to troubleshoot "why is there an extra global repository" or to audit global config.

Signature

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

Return Values

• string: Raw output of the global repository list.
• error: Error returned when listing fails.

Example

output, err := comp.ListGlobalRepositories()
if err != nil {
	log.Fatalf("Failed to list global repositories: %v", err)
}
fmt.Println("Global repository list:")
fmt.Println(output)

---

🌐 Generic Config Read/Write

repository.go also provides three generic methods to directly manipulate any config key:

Method	Signature	Purpose
SetConfigParameter	func (c *Composer) SetConfigParameter(key string, value string) error	Set a config key, equivalent to composer config key value
GetConfigParameter	func (c *Composer) GetConfigParameter(key string) (string, error)	Get a config key, equivalent to composer config key
UnsetConfig	func (c *Composer) UnsetConfig(key string) error	Remove a config key, equivalent to composer config --unset key

Example

// Set project description
_ = comp.SetConfigParameter("description", "My PHP project")

// Set author info (array index syntax)
_ = comp.SetConfigParameter("authors.0.name", "John Doe")
_ = comp.SetConfigParameter("authors.0.email", "john@example.com")

// Read project name
name, _ := comp.GetConfigParameter("name")
fmt.Printf("Project name: %s\n", name)

// Remove a repository that is no longer needed
_ = comp.UnsetConfig("repositories.old-repo")

Relationship with the Config Module

GetConfigWithGlobal / SetConfigWithGlobal (from the Config module) take an extra global bool parameter to read/write global config; the three methods on this page only operate on the current project-level config. When you need to modify complex configs beyond repositories.*, prefer SetConfig from composer.json File Operations.

---

Advanced and Related

• 🧩 Satis module: use the SDK to build a private Composer repository service (CreateSatisConfig, BuildSatis).
• 📄 composer.json Operations: AddRepository goes through the composer config command; if you need to directly manipulate the repositories field of composer.json, use ReadComposerJSON / WriteComposerJSON.
• 🌍 Global Operations module: require / update / remove / install / list etc. under the global subcommand.