# NpmRegistry

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

[API reference](/docs/api/index.md) › [Foxy](/docs/extensions/foxy/reference/index.md) › [Native](/docs/extensions/foxy/reference/native/index.md) › NpmRegistry

| final readonly class | `Foxy\Native\NpmRegistry` |
| --- | --- |
| Implements | [`NpmRegistryInterface`](/docs/extensions/foxy/reference/native/npmregistryinterface/index.md) |
| Source | [`src/Native/NpmRegistry.php`](https://github.com/php-forge/foxy/blob/main/src/Native/NpmRegistry.php#L49) |

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()`](https://github.com/composer/composer/blob/f0de0bf90226853b841672f086d8b58b02332504/src/Composer/Util/Url.php#L130): an
`access_token` query value and a userinfo password become `***`, and a long or token-like user name keeps its first
three characters.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`__construct()`](#method-__construct) | Creates an npm registry client with cache and retry support. | `NpmRegistry` |
| [`fetchTarball()`](#method-fetchTarball) | Returns the path of a verified `.tgz` written inside the directory, from the cache when possible. | `NpmRegistry` |
| [`getAdvisories()`](#method-getAdvisories) | Returns the registry's bulk advisories document for the given versions, as the registry wrote it. | `NpmRegistry` |
| [`getMetadata()`](#method-getMetadata) | Returns the abbreviated metadata of a package. | `NpmRegistry` |
| [`prefetchTarballs()`](#method-prefetchTarballs) | Downloads the tarballs missing from the cache in parallel, verifying each before it is cached. | `NpmRegistry` |

## Constants

| Constant | Value | Description | Defined by |
| --- | --- | --- | --- |
| <span id="const-DEFAULT_URL"></span>`DEFAULT_URL` | `'https://registry.npmjs.org'` |  | `NpmRegistry` |

## Method details

### __construct() <span id="method-__construct"></span>

```php
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**

| Parameter | Type | Description |
| --- | --- | --- |
| `$httpDownloader` | `Composer\Util\HttpDownloader` | Downloader that performs the requests; [`prefetchTarballs()`](/docs/extensions/foxy/reference/native/npmregistry/index.md#method-prefetchTarballs) needs the async-enabled instance returned by `Composer::getLoop()->getHttpDownloader()`. |
| `$cache` | `Composer\Cache` | Tarball cache. |
| `$io` | `Composer\IO\IOInterface` | Output for the retry and failed prefetch notices and the very verbose registry traffic. |
| `$url` | `string` | Registry base URL; a trailing slash is ignored. |
| `$delay` | [`Closure`](https://www.php.net/manual/en/class.closure.php)`(int): void\|null` | Replacement for `sleep()` during the 429 back-off, or `null` to sleep. |

### fetchTarball() <span id="method-fetchTarball"></span>

```php
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**

| Parameter | Type | Description |
| --- | --- | --- |
| `$package` | [`ResolvedPackage`](/docs/extensions/foxy/reference/native/resolvedpackage/index.md) | Registry package; its `resolved` and `integrity` values must be set. |
| `$directory` | `string` | Existing directory that receives the tarball. |

**Returns**

`string`

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if the request fails or the tarball does not match its integrity value.

### getAdvisories() <span id="method-getAdvisories"></span>

```php
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**

| Parameter | Type | Description |
| --- | --- | --- |
| `$versions` | `array<string, non-empty-list<string>>` | Locked versions keyed by package name. |

**Returns**

`string`

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if the request fails, including a registry that does not implement the endpoint.

### getMetadata() <span id="method-getMetadata"></span>

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

Returns the abbreviated metadata of a package.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$name` | `string` | Package name, scoped names included (`@scope/name`). |

**Returns**

[`PackageMetadata`](/docs/extensions/foxy/reference/native/packagemetadata/index.md)

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if the package is unknown, the request fails, or the metadata is malformed.

### prefetchTarballs() <span id="method-prefetchTarballs"></span>

```php
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()`](/docs/extensions/foxy/reference/native/npmregistry/index.md#method-fetchTarball) downloads it again and reports the error.
Each download is written into the given directory, as [`fetchTarball()`](/docs/extensions/foxy/reference/native/npmregistry/index.md#method-fetchTarball) does, and removed before the
method returns.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$packages` | `list<`[`ResolvedPackage`](/docs/extensions/foxy/reference/native/resolvedpackage/index.md)`>` | Registry packages whose tarballs are wanted. |
| `$directory` | `string` | Existing directory that holds each tarball while it is verified. |