packagist

Documentation

Overview

Package packagist provides an HTTP client for the Packagist API.

Overview

This package fetches package metadata from Packagist (https://packagist.org), the main Composer repository for PHP packages.

Usage

client, err := packagist.NewClient(24 * time.Hour)
if err != nil {
    log.Fatal(err)
}

pkg, err := client.FetchPackage(ctx, "symfony/console", false)
if err != nil {
    log.Fatal(err)
}

fmt.Println(pkg.Name, pkg.Version)
fmt.Println("Dependencies:", pkg.Dependencies)

PackageInfo

[FetchPackage] returns a PackageInfo containing:

• Name, Version: Package identity (latest stable version)
• Dependencies: Composer "require" dependencies (filtered)
• Description: Package description
• License, Author: Package metadata
• Repository, HomePage: URLs for enrichment

Caching

Responses are cached to reduce load on Packagist. The cache TTL is set when creating the client. Pass refresh=true to bypass the cache.

Dependency Filtering

The following are filtered from dependencies:

• php, composer-plugin-api, composer-runtime-api
• ext-* (PHP extensions)
• lib-* (system libraries)
• Packages without a "/" (non-Composer packages)

Version Selection

The client selects the latest stable version, skipping dev versions. If no stable version exists, the first version is used.

Index

• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client
  • func (c *Client) FetchPackage(ctx context.Context, pkg string, refresh bool) (*PackageInfo, error)
  • func (c *Client) FetchPackageVersion(ctx context.Context, pkg, version string, refresh bool) (*PackageInfo, error)
  • func (c *Client) ListVersions(ctx context.Context, pkg string, refresh bool) ([]string, error)
  • func (c *Client) ListVersionsWithConstraints(ctx context.Context, pkg string, refresh bool) (map[string]string, error)
• type Dependency
• type PackageInfo

Types

type Client

type Client struct {
	*integrations.Client
	// contains filtered or unexported fields
}

Client provides access to the Packagist package registry API. It handles HTTP requests with caching and automatic retries.

All methods are safe for concurrent use by multiple goroutines.

func NewClient

func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client

NewClient creates a Packagist client with the given cache backend.

Parameters:

• backend: Cache backend for HTTP response caching (use storage.NullBackend{} for no caching)
• cacheTTL: How long responses are cached (typical: 1-24 hours)

The returned Client is safe for concurrent use.

func (*Client) FetchPackage

func (c *Client) FetchPackage(ctx context.Context, pkg string, refresh bool) (*PackageInfo, error)

FetchPackage retrieves metadata for a PHP package from Packagist (latest version).

The pkg parameter must be in "vendor/package" format (e.g., "symfony/console"). Package name is normalized to lowercase with whitespace trimmed. Package name cannot be empty; an empty string will result in an API error.

If refresh is true, the cache is bypassed and a fresh API call is made. If refresh is false, cached data is returned if available and not expired.

Version selection: The latest stable version is selected, skipping dev versions. If no stable version exists, the first version in the list is used.

Returns:

• PackageInfo populated with metadata on success
• integrations.ErrNotFound if the package doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)
• Other errors for JSON decoding failures or missing version data

The returned PackageInfo pointer is never nil if err is nil. This method is safe for concurrent use.

func (*Client) FetchPackageVersion

func (c *Client) FetchPackageVersion(ctx context.Context, pkg, version string, refresh bool) (*PackageInfo, error)

FetchPackageVersion retrieves metadata for a specific version of a PHP package.

The pkg parameter must be in "vendor/package" format. The version must be an exact version string (e.g., "6.3.0").

If refresh is true, the cache is bypassed and a fresh API call is made.

Returns:

• PackageInfo populated with metadata on success
• integrations.ErrNotFound if the package or version doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)

This method is safe for concurrent use.

func (*Client) ListVersions

func (c *Client) ListVersions(ctx context.Context, pkg string, refresh bool) ([]string, error)

ListVersions returns all available versions for a package, sorted from oldest to newest.

func (*Client) ListVersionsWithConstraints

func (c *Client) ListVersionsWithConstraints(ctx context.Context, pkg string, refresh bool) (map[string]string, error)

ListVersionsWithConstraints returns all versions and their PHP runtime constraints. Returns a map of version -> require.php (empty string if not specified).

Uses the full Packagist API (packagist.org/packages/) instead of the P2 API because P2 returns minimal stubs (no require field) for most versions.

type Dependency

type Dependency struct {
	Name       string // Package name (vendor/package)
	Constraint string // Version constraint (e.g., "^6.0", ">=2.0,<3.0")
}

Dependency represents a Composer package dependency with version constraint.

type PackageInfo

type PackageInfo struct {
	Name         string       // Package name (e.g., "symfony/console", never empty in valid info)
	Version      string       // Latest stable version (e.g., "6.3.0", never empty in valid info)
	Dependencies []Dependency // Composer require dependencies with constraints (nil or empty if none)
	Repository   string       // Normalized repository URL (empty if not provided)
	HomePage     string       // Homepage URL (may be empty)
	Description  string       // Package description (may be empty)
	License      string       // License identifier (may be empty, only first license if multiple)
	Author       string       // First author name (may be empty)
	RequiredPHP  string       // PHP version constraint from require.php (e.g., ">=8.1", may be empty)
}

PackageInfo holds metadata for a PHP package from Packagist.

Package names follow Composer conventions (vendor/package format). Version is the latest stable version; dev versions are skipped. Dependencies exclude PHP, extensions (ext-*), libraries (lib-*), and Composer platform packages.

Zero values: All string fields are empty, Dependencies is nil. This struct is safe for concurrent reads after construction.