Skip to content
PHP Ecosystem
Explore

NpmRegistry

API reference › Foxy › Native › NpmRegistry

final readonly classFoxy\Native\NpmRegistry
ImplementsNpmRegistryInterface
Sourcesrc/Native/NpmRegistry.php

Provides the npm registry access of the native manager: abbreviated metadata, integrity-verified tarballs, and bulk security advisories.

Requests answered with HTTP 429 are retried up to three times, waiting the Retry-After seconds (capped at 60) or 1, 2, and 4 seconds. Tarballs are cached and verified against their Subresource Integrity value on every cache hit and every download; a prefetch fills the cache with parallel downloads and no retry. Every metadata request, tarball download, prefetch, and cache hit is written at very verbose level (-vv).

URLs written to the output or put in an exception message are masked with Url::sanitize(): an access_token query value and a userinfo password become ***, and a long or token-like user name keeps its first three characters.

MethodDescriptionDefined by
__construct()Creates an npm registry client with cache and retry support.NpmRegistry
fetchTarball()Returns the path of a verified .tgz written inside the directory, from the cache when possible.NpmRegistry
getAdvisories()Returns the registry’s bulk advisories document for the given versions, as the registry wrote it.NpmRegistry
getMetadata()Returns the abbreviated metadata of a package.NpmRegistry
prefetchTarballs()Downloads the tarballs missing from the cache in parallel, verifying each before it is cached.NpmRegistry
ConstantValueDescriptionDefined by
DEFAULT_URL'https://registry.npmjs.org'NpmRegistry
public function __construct(Composer\Util\HttpDownloader $httpDownloader, Composer\Cache $cache, Composer\IO\IOInterface $io, string $url = \self::DEFAULT_URL, Closure(int): void|null $delay = null)

Creates an npm registry client with cache and retry support.

Parameters

ParameterTypeDescription
$httpDownloaderComposer\Util\HttpDownloaderDownloader that performs the requests; prefetchTarballs() needs the async-enabled instance returned by Composer::getLoop()->getHttpDownloader().
$cacheComposer\CacheTarball cache.
$ioComposer\IO\IOInterfaceOutput for the retry and failed prefetch notices and the very verbose registry traffic.
$urlstringRegistry base URL; a trailing slash is ignored.
$delayClosure(int): void|nullReplacement for sleep() during the 429 back-off, or null to sleep.
public function fetchTarball(Foxy\Native\ResolvedPackage $package, string $directory): string

Returns the path of a verified .tgz written inside the directory, from the cache when possible.

A cached tarball that fails its integrity check is removed and downloaded again.

Parameters

ParameterTypeDescription
$packageResolvedPackageRegistry package; its resolved and integrity values must be set.
$directorystringExisting directory that receives the tarball.

Returns

string

Throws

public function getAdvisories(array<string, non-empty-list<string>> $versions): string

Returns the registry’s bulk advisories document for the given versions, as the registry wrote it.

Sends one POST to npm’s bulk advisories endpoint with a JSON object body; an empty response body is returned as an empty string.

Parameters

ParameterTypeDescription
$versionsarray<string, non-empty-list<string>>Locked versions keyed by package name.

Returns

string

Throws

public function getMetadata(string $name): Foxy\Native\PackageMetadata

Returns the abbreviated metadata of a package.

Parameters

ParameterTypeDescription
$namestringPackage name, scoped names included (@scope/name).

Returns

PackageMetadata

Throws

public function prefetchTarballs(list<Foxy\Native\ResolvedPackage> $packages, string $directory): void

Downloads the tarballs missing from the cache in parallel, verifying each before it is cached.

Nothing is downloaded when the cache is disabled or read-only, since the downloads could not be kept. A package without a tarball URL is skipped. A download that fails, does not match its integrity value, or cannot be cached is discarded with a verbose notice; fetchTarball() downloads it again and reports the error. Each download is written into the given directory, as fetchTarball() does, and removed before the method returns.

Parameters

ParameterTypeDescription
$packageslist<ResolvedPackage>Registry packages whose tarballs are wanted.
$directorystringExisting directory that holds each tarball while it is verified.