🪞 Mirrors

Packagist officially maintains geographic mirror sources, used to accelerate package metadata download in regions where packagist.org cannot be accessed stably. This page explains mirror concepts, official mirror list, and how to switch to mirrors in SDK.

Source Code Location

This page is based on pkg/repository/mirrors.go. This file currently only contains official mirror reference comments, does not provide mirror constants or mirror list methods — mirror switching is implemented via WithBaseURL / WithRepoURL or Options.ServerUrl configuration.

Why Mirrors Are Needed

• 🌐 Regional network: Developers in some regions have high latency, unstable direct connection to packagist.org.
• ⚡ Acceleration: Mirrors are closer to local network, fetching package metadata and indexes is faster.
• 🔄 Reliability: Mirrors can serve as fallback when main site fluctuates.
• 🏢 Enterprise internal: Self-hosted Packagist / Satis instances as unified entry for private + public packages.

Official Mirrors

Packagist official recommended mirror list see https://packagist.org/mirrors. Common community mirrors include:

Mirror	Region	Notes
packagist.org	Global	Official main site
Regional community mirrors	Varies	See official mirrors page for latest list

Mirror List Changes

pkg/repository/mirrors.go clearly notes "official recommended mirror sources" reference from https://packagist.org/mirrors, this list changes over time. Before use, please verify with official page, SDK does not embed mirror URL constants.

Switching Mirrors in SDK

All ComposerClient read methods prepend baseURL (business API) or repoURL (V2 metadata), so switching mirrors only requires overriding these two values.

Method 1: High-level Facade (Recommended)

package main

import (
    "fmt"
    "log"
    "time"

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

func main() {
    c := client.NewComposerClient(
        30*time.Second,
        // Business API endpoint points to mirror
        client.WithBaseURL("https://packagist.mirror.example.com"),
        // V2 metadata endpoint points to mirror's repo subdomain
        client.WithRepoURL("https://repo.packagist.mirror.example.com"),
    )

    stats, err := c.GetStatistics()
    if err != nil {
        log.Fatalf("Failed to access mirror: %v", err)
    }
    fmt.Printf("Mirror total packages: %d\n", stats.Totals.Packages)
}

Mirror URL Structure

Different mirrors may have different URL structures: some mirrors put /packages/list.json, /statistics.json etc. under same domain; others put p2/... V2 metadata on separate subdomain. Before configuration, please consult chosen mirror's documentation, fill WithBaseURL and WithRepoURL respectively.

Method 2: Lower-level Repository + Proxy

If mirror itself needs to be accessed via proxy (e.g., enterprise intranet proxy), or you want to specify both server URL and proxy, use lower-level Repository layer:

repo := repository.NewRepository(repository.Options{
    ServerUrl: "https://packagist.mirror.example.com",
    Proxy:     "http://127.0.0.1:7890",
})
stats, err := repo.Statistics(ctx)

See Options for details.

Self-hosted Mirrors / Satis

If you use Satis or private Packagist instance as internal mirror, configuration is the same — point baseURL / ServerUrl to your instance address. SDK request paths (/packages/list.json, /api/security-advisories/ etc.) follow Packagist API conventions, as long as your instance is compatible with these paths it will work directly.

Private Package Authentication

Self-hosted instances requiring authentication: current ComposerClient only carries username / apiToken in three write operations (Create/Edit/UpdatePackage) (as URL query parameters). Read methods don't carry authentication. If your private mirror reads also need authentication, we recommend:

• Use lower-level Repository + Proxy (add authentication header at proxy layer), or
• Self-fork extend ComposerClient to add Authorization header.

Advanced Topics

Mirror Sync Delay

Mirrors are not real-time synced, usually have minute-level to hour-level delay. Therefore:

• 🛠️ Just published packages may temporarily not be visible on mirrors — at this time use UpdatePackage to trigger main site fetch, then wait for mirror sync.
• 🔒 Security advisory mirror sync may have delay, when doing vulnerability alerts should use main site as reference or confirm mirror sync policy.

Mirror Selection Trade-offs

Dimension	Main Site	Mirror
Real-time	Latest	Has delay
Speed	Varies by region	Usually faster
Data completeness	Authoritative	Depends on mirror sync policy
Advisories	Most timely	May lag

Production environment security monitoring: recommend advisories go to main site (don't override baseURL for GetSecurityAdvisories*), large lists go to mirror (point ListPackages etc. to mirror for acceleration).

🔗 Related

• 🔌 Client configuration see ComposerClient.
• ⚙️ Proxy and ServerUrl see Options.
• 🏗️ Lower-level HTTP see Repository.