# DependencyResolver

> Resolves npm requirements into one version per package (flat node_modules) against an npm registry.

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

| final readonly class | `Foxy\Native\DependencyResolver` |
| --- | --- |
| Source | [`src/Native/DependencyResolver.php`](https://github.com/php-forge/foxy/blob/main/src/Native/DependencyResolver.php#L47) |

Resolves npm requirements into one version per package (flat `node_modules`) against an npm registry.

Each constraint is recorded with the requirement that declared it. The highest version satisfying every constraint
of a name is selected; a later constraint the selection violates triggers a re-pick, which abandons the previous
version and retracts the constraints it declared, cascading to every selection left without constraints, which is
dropped until something requires it again. A selection is never upgraded because its constraints loosened. An
abandoned version satisfying every current constraint may be selected again once; abandoning it a second time is
final, and selecting it again is reported as a version conflict, so resolution always ends. Local packages,
selected by root `file:` requirements, are fixed selections that are never fetched; an optional one is an optional
subtree like any other, also dropped when a mandatory requirement rejects its version.

Dependencies, non-optional peer dependencies, and optional dependencies are followed. An optional constraint never
blocks a mandatory one: it is dropped with a warning instead, and an optional dependency that is unsatisfiable or
rejects the current selection is skipped with a warning. The packages selected through an optional dependency form
its subtree: a failure inside the subtree, or a mandatory requirement blocked by a constraint from it, drops the
whole subtree with a warning unless the optional package is also required by a mandatory constraint. Packages no
longer reachable from the requirements are dropped from the result.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`__construct()`](#method-__construct) | Creates a resolver backed by the npm registry. | `DependencyResolver` |
| [`resolve()`](#method-resolve) | Resolves the requirements and their transitive dependencies. | `DependencyResolver` |

## Method details

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

```php
public function __construct(Foxy\Native\NpmRegistryInterface $registry, Composer\IO\IOInterface $io)
```

Creates a resolver backed by the npm registry.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$registry` | [`NpmRegistryInterface`](/docs/extensions/foxy/reference/native/npmregistryinterface/index.md) | Registry that provides the package metadata. |
| `$io` | `Composer\IO\IOInterface` | Output that receives the deprecation and skipped-dependency warnings. |

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

```php
public function resolve(list<Foxy\Native\Requirement> $requirements, array<string, Foxy\Native\LocalPackage> $locals = []): array<string, Foxy\Native\ResolvedPackage>
```

Resolves the requirements and their transitive dependencies.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$requirements` | `list<`[`Requirement`](/docs/extensions/foxy/reference/native/requirement/index.md)`>` | Root requirements; a root `file:` requirement selects the local package of the same name. |
| `$locals` | `array<string,` [`LocalPackage`](/docs/extensions/foxy/reference/native/localpackage/index.md)`>` | Local (`file:`) packages keyed by name. A selected local package is never fetched: later requirements are checked against its version, and an optional one is dropped, with its subtree, when a mandatory requirement rejects its version. |

**Returns**

`array<string,` [`ResolvedPackage`](/docs/extensions/foxy/reference/native/resolvedpackage/index.md)`>`: Selected registry and local packages keyed and sorted by name.

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if a mandatory requirement uses an unsupported protocol, an invalid range, has no version satisfying its mandatory constraints, would return to a version abandoned twice, rejects the version of a local package, or the registry fails.