🌍 Global Operations

The Composer SDK's global operations module wraps all capabilities of the composer global subcommand — installing, updating, removing, listing, and executing dependencies in Composer's global directory (~/.composer), as well as generating global autoload, initializing global projects, and viewing status. All methods are attached to the core type Composer.

Main methods are defined in pkg/composer/global.go; WithOptions variants and batch variants (GlobalInit, GlobalRequireMultiple, GlobalRemoveMultiple) are defined in pkg/composer/global.go and pkg/composer/additional_methods.go.

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

Capability Overview 🌍

Method	Purpose	Return Value
`GlobalRequire`	Globally install a single package	`error`
`GlobalRequireWithOptions`	Globally install a single package with options	`error`
`GlobalRequireMultiple`	Globally install multiple packages at once	`error`
`GlobalUpdate`	Globally update packages	`error`
`GlobalUpdateWithOptions`	Globally update packages with options	`error`
`GlobalRemove`	Globally remove a single package	`error`
`GlobalRemoveWithOptions`	Globally remove a single package with options	`error`
`GlobalRemoveMultiple`	Globally remove multiple packages at once	`error`
`GlobalInstall`	Globally install dependencies	`error`
`GlobalList`	List globally installed packages	`(string, error)`
`GlobalHome`	Get global directory path	`(string, error)`
`GlobalExecute`	Execute globally installed binaries	`(string, error)`
`GlobalStatus`	Show status of globally installed packages	`(string, error)`
`GlobalDumpAutoload`	Generate autoload for global installs	`error`
`GlobalInit`	Initialize project in global directory	`error`

Global Directory

All global subcommands work under ~/.composer (determined by COMPOSER_HOME). Use GetComposerHome from the Config module to get the actual path.

🌍 GlobalRequire

Globally install a package, equivalent to composer global require package[:version].

When to Use

Use when installing globally available CLI tools (e.g., phpunit/phpunit, friendsofphp/php-cs-fixer, laravel/installer).

Signature

func (c *Composer) GlobalRequire(packageName string, version string) error

Parameters

Parameter	Type	Description
`packageName`	`string`	Package name, e.g., `symfony/console`
`version`	`string`	Version constraint, e.g., `^5.0`; empty string means latest version

Return Values

error: Error that occurred during global installation.

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

	// Globally install latest Laravel installer
	if err := comp.GlobalRequire("laravel/installer", ""); err != nil {
		log.Fatalf("Global install failed: %v", err)
	}

	// Globally install specified version
	if err := comp.GlobalRequire("symfony/console", "^6.0"); err != nil {
		log.Fatalf("Global install failed: %v", err)
	}
}

Advanced

Use GlobalRequireWithOptions when additional flags like --prefer-dist, --no-progress, --no-suggest are needed; use GlobalRequireMultiple to install multiple packages at once.

🌍 GlobalRequireWithOptions

Globally install a package with custom options, equivalent to composer global require [options] package[:version].

When to Use

Use when you need to control the installation method (prefer dist/source, disable progress bar, skip suggestions, etc.).

Signature

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

Parameters

Parameter	Type	Description
`packageName`	`string`	Package name to globally install
`version`	`string`	Version constraint, empty string means latest version
`options`	`map[string]string`	Additional options; keys are option names, values are option values

Option Construction Rule

options is processed by internal buildOptionsArgs: keys are sorted alphabetically, then values that are empty generate --key, otherwise --key=value, ensuring deterministic command construction.

Return Values

error: Error that occurred during global installation.

Example

options := map[string]string{
	"prefer-dist": "",
	"no-progress": "",
	"no-suggest":  "",
}
if err := comp.GlobalRequireWithOptions("symfony/console", "^5.0", options); err != nil {
	log.Fatalf("Global package install failed: %v", err)
}

🌍 GlobalRequireMultiple

Globally install multiple packages at once, equivalent to composer global require pkg1[:v1] pkg2[:v2] ....

When to Use

Use when you need to batch install a set of global tools — more efficient than looping GlobalRequire (triggers only one resolution and write).

Signature

func (c *Composer) GlobalRequireMultiple(packages map[string]string) error

Parameters

Parameter	Type	Description
`packages`	`map[string]string`	Mapping of package name to version constraint; empty string value means latest version

Return Values

error: Error that occurred during global installation.

Example

packages := map[string]string{
	"laravel/installer":         "",      // Latest version
	"friendsofphp/php-cs-fixer": "^3.0",
	"phpunit/phpunit":           "^10.0",
}
if err := comp.GlobalRequireMultiple(packages); err != nil {
	log.Fatalf("Batch global install failed: %v", err)
}

Iteration Order

map iteration order is non-deterministic in Go, so the final command-line argument order is also non-deterministic. Composer is insensitive to argument order, so results are consistent; if you need deterministic output (e.g., audit logs), use GlobalRequireWithOptions to install one by one.

🌍 GlobalUpdate

Globally update packages, equivalent to composer global update [packages...].

When to Use

Use to update global tools to new versions matching constraints. Pass empty slice to update all global packages.

Signature

func (c *Composer) GlobalUpdate(packages []string) error

Parameters

Parameter	Type	Description
`packages`	`[]string`	List of package names to update; empty updates all packages

Return Values

error: Error that occurred during global update.

Example

// Update specified global packages
if err := comp.GlobalUpdate([]string{"symfony/console"}); err != nil {
	log.Fatalf("Global update failed: %v", err)
}

// Update all global packages
if err := comp.GlobalUpdate(nil); err != nil {
	log.Fatalf("Global update failed: %v", err)
}

Advanced

Use GlobalUpdateWithOptions when options like --prefer-dist, --no-dev, --no-progress are needed.

🌍 GlobalUpdateWithOptions

Globally update packages with custom options, equivalent to composer global update [options] [packages...].

When to Use

Use for silent updates in CI, or to control whether dev dependencies are included.

Signature

func (c *Composer) GlobalUpdateWithOptions(packages []string, options map[string]string) error

Parameters

Parameter	Type	Description
`packages`	`[]string`	List of package names to update; empty updates all packages
`options`	`map[string]string`	Additional options

Return Values

error: Error that occurred during global update.

Example

options := map[string]string{
	"prefer-dist": "",
	"no-dev":      "",
	"no-progress": "",
}
if err := comp.GlobalUpdateWithOptions([]string{"symfony/console"}, options); err != nil {
	log.Fatalf("Global package update failed: %v", err)
}

🌍 GlobalRemove

Globally remove a package, equivalent to composer global remove package.

When to Use

Use when a global tool is no longer needed, or to clean up conflicting global packages.

Signature

func (c *Composer) GlobalRemove(packageName string) error

Parameters

Parameter	Type	Description
`packageName`	`string`	Package name to globally remove

Return Values

error: Error that occurred during global removal.

Example

if err := comp.GlobalRemove("symfony/console"); err != nil {
	log.Fatalf("Global remove failed: %v", err)
}

Advanced

Use GlobalRemoveWithOptions when options like --no-progress, --no-update are needed; use GlobalRemoveMultiple to remove multiple packages at once.

🌍 GlobalRemoveWithOptions

Globally remove a package with custom options, equivalent to composer global remove [options] package.

When to Use

Use to disable progress bar, or to prevent dependency updates from being triggered immediately on removal.

Signature

func (c *Composer) GlobalRemoveWithOptions(packageName string, options map[string]string) error

Parameters

Parameter	Type	Description
`packageName`	`string`	Package name to globally remove
`options`	`map[string]string`	Additional options

Return Values

error: Error that occurred during global removal.

Example

options := map[string]string{
	"no-progress": "",
	"no-update":   "",
}
if err := comp.GlobalRemoveWithOptions("symfony/console", options); err != nil {
	log.Fatalf("Global package remove failed: %v", err)
}

🌍 GlobalRemoveMultiple

Globally remove multiple packages at once, equivalent to composer global remove pkg1 pkg2 ....

When to Use

Use to batch clean up a set of no-longer-used global tools — more efficient than looping GlobalRemove.

Signature

func (c *Composer) GlobalRemoveMultiple(packages []string) error

Parameters

Parameter	Type	Description
`packages`	`[]string`	List of package names to globally remove

Return Values

error: Error that occurred during global removal.

Example

packages := []string{
	"laravel/installer",
	"friendsofphp/php-cs-fixer",
	"phpunit/phpunit",
}
if err := comp.GlobalRemoveMultiple(packages); err != nil {
	log.Fatalf("Batch global remove failed: %v", err)
}

🌍 GlobalInstall

Globally install dependencies, equivalent to composer global install.

When to Use

Use when global composer.json already exists and dependencies need to be installed from composer.lock — commonly used to restore the global toolset on a new machine.

Signature

func (c *Composer) GlobalInstall() error

Return Values

error: Error that occurred during global installation.

Example

if err := comp.GlobalInstall(); err != nil {
	log.Fatalf("Global install failed: %v", err)
}

Install vs Require

GlobalInstall installs from composer.lock (doesn't modify dependency manifest); GlobalRequire appends dependencies to composer.json and resolves versions.

🌍 GlobalList

List globally installed packages, equivalent to composer global show.

When to Use

Use to see what global tools are currently installed and their versions.

Signature

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

Return Values

string: Raw output of globally installed package list.
error: Error returned when listing fails.

Example

output, err := comp.GlobalList()
if err != nil {
	log.Fatalf("Failed to list global packages: %v", err)
}
fmt.Println("Globally installed packages:")
fmt.Println(output)

Command Mapping

This method actually executes composer global show (Composer uses show to list packages; there's no standalone global list subcommand).

🌍 GlobalHome

Get the global directory path, equivalent to composer global home.

When to Use

Use to locate global vendor/bin, global composer.json, or global auth.json.

Signature

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

Return Values

string: Global directory path.
error: Error returned on failure.

Example

home, err := comp.GlobalHome()
if err != nil {
	log.Fatalf("Failed to get global directory: %v", err)
}
fmt.Printf("Composer global directory: %s\n", home)

More Reliable Alternative

GetComposerHome from the Config module gets it via composer config --global home, with clearer semantics; recommended to use first.

🌍 GlobalExecute

Execute binaries from globally installed packages, equivalent to composer global exec command [args...].

When to Use

Use to invoke a globally installed CLI tool (e.g., php-cs-fixer, laravel) in your program.

Signature

func (c *Composer) GlobalExecute(command string, args ...string) (string, error)

Parameters

Parameter	Type	Description
`command`	`string`	Binary name to execute
`args`	`...string`	Arguments passed through to the binary

Return Values

string: Command execution output.
error: Error that occurred during execution.

Example

// Invoke globally installed php-cs-fixer
output, err := comp.GlobalExecute("php-cs-fixer", "fix", "src/", "--dry-run")
if err != nil {
	log.Fatalf("Execution failed: %v", err)
}
fmt.Println(output)

Difference from Exec Module

Exec from the Script Execution module executes binaries in the project's vendor/bin; GlobalExecute executes binaries in the global vendor/bin.

🌍 GlobalStatus

Show status of globally installed packages, equivalent to composer global status.

When to Use

Use to see whether global packages have uncommitted local modifications or are behind remote.

Signature

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

Return Values

string: Raw status output.
error: Error returned on failure.

Example

status, err := comp.GlobalStatus()
if err != nil {
	log.Fatalf("Failed to get global status: %v", err)
}
fmt.Println("Global package status:")
fmt.Println(status)

🌍 GlobalDumpAutoload

Generate autoload files for global installs, equivalent to composer global dump-autoload [--optimize].

When to Use

Use when you've manually modified global package source code, or want to optimize global tool startup performance.

Signature

func (c *Composer) GlobalDumpAutoload(optimize bool) error

Parameters

Parameter	Type	Description
`optimize`	`bool`	`true` enables `--optimize` to optimize autoload (recommended for production)

Return Values

error: Error that occurred during autoload generation.

Example

// Generate optimized autoload
if err := comp.GlobalDumpAutoload(true); err != nil {
	log.Fatalf("Failed to generate global autoload: %v", err)
}

🌍 GlobalInit

Initialize a project in the global directory, equivalent to composer global init --name=<name> --no-interaction.

When to Use

Use to create a global composer.json from scratch (e.g., initializing a global toolset manifest).

Signature

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

Parameters

Parameter	Type	Description
`name`	`string`	Project name, format `vendor/name`

Return Values

error: Error that occurred during initialization.

Example

if err := comp.GlobalInit("myvendor/global-tools"); err != nil {
	log.Fatalf("Global initialization failed: %v", err)
}

Non-interactive

This method always includes --no-interaction, suitable for CI, container, and other TTY-less environments. If a global composer.json already exists, init may refuse to overwrite.

⚙️ Config module: GetComposerHome gets global directory path, ClearCache clears global cache.
🌐 Repository module: AddGlobalRepository / RemoveGlobalRepository / ListGlobalRepositories manage global repository sources.
💻 Script Execution module: Project-level vendor/bin binary execution (Exec, ExecPHP, ExecAll).
📦 Dependencies module: Project-level Install / Update / DumpAutoload.

🌍 Global Operations ​

Capability Overview 🌍 ​

🌍 GlobalRequire ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

Advanced ​

🌍 GlobalRequireWithOptions ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

🌍 GlobalRequireMultiple ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

🌍 GlobalUpdate ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

Advanced ​

🌍 GlobalUpdateWithOptions ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

🌍 GlobalRemove ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

Advanced ​

🌍 GlobalRemoveWithOptions ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

🌍 GlobalRemoveMultiple ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

🌍 GlobalInstall ​

When to Use ​

Signature ​

Return Values ​

Example ​

🌍 GlobalList ​

When to Use ​

Signature ​

Return Values ​

Example ​

🌍 GlobalHome ​

When to Use ​

Signature ​

Return Values ​

Example ​

🌍 GlobalExecute ​

When to Use ​

Signature ​

Parameters ​

Return Values ​

Example ​

🌍 GlobalStatus ​

When to Use ​

Signature ​

Return Values ​

Example ​

🌍 GlobalDumpAutoload ​

🌍 Global Operations

Capability Overview 🌍

🌍 GlobalRequire

When to Use

Signature

Parameters

Return Values

Example

Advanced

🌍 GlobalRequireWithOptions

When to Use

Signature

Parameters

Return Values

Example

🌍 GlobalRequireMultiple

When to Use

Signature

Parameters

Return Values

Example

🌍 GlobalUpdate

When to Use

Signature

Parameters

Return Values

Example

Advanced

🌍 GlobalUpdateWithOptions

When to Use

Signature

Parameters

Return Values

Example

🌍 GlobalRemove

When to Use

Signature

Parameters

Return Values

Example

Advanced

🌍 GlobalRemoveWithOptions

When to Use

Signature

Parameters

Return Values

Example

🌍 GlobalRemoveMultiple

When to Use

Signature

Parameters

Return Values

Example

🌍 GlobalInstall

When to Use

Signature

Return Values

Example

🌍 GlobalList

When to Use

Signature

Return Values

Example

🌍 GlobalHome

When to Use

Signature

Return Values

Example

🌍 GlobalExecute

When to Use

Signature

Parameters

Return Values

Example

🌍 GlobalStatus

When to Use

Signature

Return Values

Example

🌍 GlobalDumpAutoload