composer-skills

README

Composer Skills

简体中文 · English

Go module: github.com/scagogogo/composer-skills · License: MIT · Go ≥ 1.23

Typed Go SDK for the PHP Composer ecosystem. One import exposes two independent SDKs plus a foundation layer. No exec.Command output parsing — all results are Go structs.

Packages

Import path	Role	Requires PHP
pkg/client	Packagist REST API client (20 methods)	No
pkg/repository	Low-level Packagist HTTP layer (context-aware)	No
pkg/composer	Composer CLI wrapper (234 methods, 20 categories)	Yes (PHP 7.4+, Composer 2.0+)
pkg/detector	Cross-OS Composer binary detection	No
pkg/installer	Auto-install Composer + PHP (Windows/macOS/Linux)	No
pkg/domain	Data models (Package, Advisory, Statistics, Version, …)	No
pkg/composerutils	Filesystem / HTTP / mock / test helpers	No
cmd/composer-skills	Cobra CLI exposing all SDK capabilities (50+ subcommands)	mixed

Choose a SDK

• Query packagist.org (search, stats, advisories, package info) → pkg/client. Pure Go, no PHP.
• Operate on a local PHP project (install/update/require/audit/validate) → pkg/composer. Needs PHP+Composer on the host.
• Detect whether Composer is installed → pkg/detector. Install if missing → pkg/installer.

Install

go get github.com/scagogogo/composer-skills

Packagist API (no PHP)

package main

import (
	"fmt"
	"time"
	"github.com/scagogogo/composer-skills/pkg/client"
)

func main() {
	c := client.NewComposerClient(30 * time.Second)

	r, _ := c.SearchPackages("logging", 10, 1)
	fmt.Println("matches:", r.Total)

	p, _ := c.GetPackage("monolog/monolog")
	fmt.Println(p.Package.Name, "—", p.Package.Description)

	a, _ := c.GetSecurityAdvisories()
	fmt.Println("advisories:", len(a.Advisories))

	s, _ := c.GetStatistics()
	fmt.Println("total packages:", s.Packages)
}

Composer CLI (needs PHP + Composer)

package main

import (
	"fmt"
	"log"
	"github.com/scagogogo/composer-skills/pkg/composer"
)

func main() {
	comp, err := composer.New(composer.DefaultOptions()) // auto-installs Composer if missing
	if err != nil {
		log.Fatal(err)
	}
	comp.SetWorkingDir("/path/to/php/project")

	_ = comp.Install(false, true)
	_ = comp.RequirePackage("monolog/monolog", "^3.0", false)
	_ = comp.Update([]string{}, false)

	audit, _ := comp.AuditWithJSON() // typed security audit
	fmt.Println("vulns:", audit.Found)

	outdated, _ := comp.GetOutdatedInfo() // typed outdated info
	fmt.Println("outdated:", len(outdated.Outdated))

	_ = comp.ValidateStructured() // validate composer.json

	phpVer, _ := comp.GetPHPVersion()
	hasExt, _ := comp.HasExtension("mbstring")
	fmt.Println(phpVer, hasExt)
}

Auto-install Composer

package main

import (
	"fmt"
	"github.com/scagogogo/composer-skills/pkg/detector"
	"github.com/scagogogo/composer-skills/pkg/installer"
)

func main() {
	d := detector.NewDetector()
	if d.IsInstalled() {
		path, _ := d.Detect()
		fmt.Println("found:", path)
		return
	}
	inst := installer.NewInstaller(installer.SmartConfig())
	fmt.Println(inst.Install()) // downloads Composer (+ PHP if needed), OS-aware
}

Structured result methods

Prefer these over raw-string variants — they parse composer ... --format=json into Go structs.

Method	Returns	Wraps
AuditWithJSON	*AuditResult	composer audit --format=json
GetOutdatedInfo	*OutdatedResult	composer outdated --format=json
GetVersionInfo	*VersionInfo	composer --version
ShowPackageInfo	*PackageInfo	composer show --format=json
SearchInfo	*SearchResult	composer search --format=json
ValidateStructured	*ValidateResult	composer validate
CheckPlatformReqsStructured	*PlatformCheckResult	composer check-platform-reqs
GetLicensesInfo	*LicensesResult	composer licenses
GetConfigStructured	*ConfigResult	composer config
DiagnoseStructured	*DiagnoseResult	composer diagnose

Convenience helpers

IsPackageInstalled, IsPackageDev, HasComposerLock, HasVendorDir, GetInstalledPackageNames, GetDirectDependencyNames, GetProjectDependencies, GetProjectSummary, GetRequireWithVersion, GetAbandonedPackagesFromLock, GetNamespaceMap, GetScripts, GetVendorDir, GetCacheDir, GetComposerHomeDir.

CLI

go install github.com/scagogogo/composer-skills/cmd/composer-skills@latest

composer-skills search query "logging"          # Packagist (no PHP)
composer-skills package info symfony/console --json
composer-skills security advisories
composer-skills repo stats
composer-skills repo popular
composer-skills local install --working-dir /path/to/project   # Composer (needs PHP)
composer-skills local audit --working-dir /path/to/project
composer-skills local outdated --working-dir /path/to/project
composer-skills local why monolog/monolog --working-dir /path/to/project

Global flags: --timeout (default 60s), --base-url, --repo-url, --username, --api-token, --json.

Composer CLI method categories (234 methods)

Core (10) · Dependencies (16) · Packages (20) · Audit (10) · Project (10) · Config (12) · Validation (14) · Platform (8) · Repository (18) · Global (14) · Auth (10) · Fund (7) · Licenses (4) · Diagnosis (8) · Exec (8) · Satis (8) · Version (5) · Environment (12) · composer.json (10) · Archive (6).

Naming convention: each operation has a base method, a WithOptions(map[string]string) variant, and a WithFormat(format) variant where Composer supports --format. Structured variants are named XxxInfo / XxxStructured / XxxWithJSON.

Project layout

cmd/composer-skills/   CLI (Cobra, 50+ subcommands)
pkg/client/            Packagist API client
pkg/repository/        Low-level Packagist HTTP layer
pkg/composer/          Composer CLI wrapper SDK
pkg/detector/          Composer detection (cross-OS)
pkg/installer/         Composer + PHP auto-install
pkg/domain/            Data models
pkg/composerutils/     Filesystem / HTTP / mock / test helpers
examples/              15+ runnable programs
docs/skills/           Progressive guides (12)
website/docs/          VitePress docs site

Test

make test           # all tests
make test-race      # with race detector
make test-coverage  # coverage report

450+ tests, mock-based isolation via pkg/composerutils/mock and composer.SetupMockOutput.

Documentation

• Docs site: https://scagogogo.github.io/composer-skills/ (双语 / bilingual: 中文 + English)
• Go reference: https://pkg.go.dev/github.com/scagogogo/composer-skills
• Examples: examples/ directory
• For AI agents: see SKILLS.md — an agent-oriented entry point that points to the docs and code.

Prompt for AI

Copy the block below into your AI chat (ChatGPT, Claude, Copilot, …) to have it integrate this SDK for you. Replace the bracketed line with your concrete goal.

# Task: Integrate `composer-skills` into a Go project

You are integrating **Composer Skills** — `github.com/scagogogo/composer-skills`, a typed Go SDK for the PHP Composer ecosystem. Go ≥ 1.23, MIT.

## Two independent SDKs

1. `pkg/client` — Packagist REST API. Pure Go, no PHP. Methods: `SearchPackages`, `GetPackage`, `GetSecurityAdvisories`, `GetStatistics`, `ListPackages*`, `GetPackageStats`, `CreatePackage`/`EditPackage`/`UpdatePackage` (need `WithAPICredentials`). Construct: `c := client.NewComposerClient(30*time.Second)`.
2. `pkg/composer` — typed wrapper over the local `composer` binary. Needs PHP 7.4+ + Composer 2.0+. Construct: `comp, err := composer.New(composer.DefaultOptions())` (auto-installs Composer if missing). 234 methods across 20 categories.

Foundation: `pkg/detector` (cross-OS Composer detection, `NewDetector().Detect()`), `pkg/installer` (auto-install Composer+PHP, `installer.NewInstaller(installer.SmartConfig()).Install()`), `pkg/domain` (data models), `pkg/composerutils` (fs/http/mock/test helpers).

## Rules

- Prefer structured methods returning Go structs: `AuditWithJSON`, `GetOutdatedInfo`, `GetVersionInfo`, `ShowPackageInfo`, `SearchInfo`, `ValidateStructured`, `CheckPlatformReqsStructured`, `GetLicensesInfo`, `GetConfigStructured`, `DiagnoseStructured`. Avoid parsing raw string output.
- Each operation has base, `WithOptions(map[string]string)`, and (where Composer supports) `WithFormat(format)` variants.
- Convenience helpers: `IsPackageInstalled`, `GetDirectDependencyNames`, `GetProjectSummary`, `GetAbandonedPackagesFromLock`, `GetNamespaceMap`, `GetScripts`, `HasComposerLock`, `HasVendorDir`.
- CLI: `go install github.com/scagogogo/composer-skills/cmd/composer-skills@latest` — 50+ subcommands (`search`, `package`, `repo`, `security`, `local`, …), `--json` flag, `--working-dir` for local ops.
- Docs: https://scagogogo.github.io/composer-skills/ · Go ref: https://pkg.go.dev/github.com/scagogogo/composer-skills · Examples: `examples/`.

## My goal

[Replace this line with what you want to build, e.g. "a Go service that nightly scans all my PHP projects for vulnerable dependencies and alerts Slack."]

Deliver: (1) which SDK and why, (2) complete runnable Go code with imports + error handling, (3) `go get` command + environment prerequisites, (4) relevant doc links.

Acknowledgments

• Packagist — PHP package repository
• Composer — PHP dependency manager

License

MIT