PluginDownloaderInterface

Where a plugin's source code comes from. The installer needs four things from a source of plugins: read a coordinate, pick a version, put the files somewhere on disk, and clean up after itself. It does not need to know that any of it happens over GitHub — and once that is true, an installer can be driven by a catalog, a private mirror, or a test double without any of them pretending to be a GitHub client. {@see \Milpa\Plugin\GitHubDownloader} is the implementation that ships with the framework.

abstract public function parseSource(string $source): array

Reads a coordinate into its parts: `owner/repo`, `owner/repo:^2.0`, or a full URL. Pure — no network, no disk.

Parameters

Throws

\InvalidArgumentException when the coordinate cannot be read

abstract public function resolveVersion(string $owner, string $repo, ?string $constraint = null): Milpa\ValueObjects\SemanticVersion

The highest published version satisfying the constraint, or the latest one when no constraint is given.

Parameters

Throws

\RuntimeException when no version satisfies the constraint

abstract public function download(string $owner, string $repo, Milpa\ValueObjects\SemanticVersion $version): string

Places that version's files on disk and returns the directory holding them. The returned directory MUST be nested inside a scratch directory this downloader owns and nothing else uses — never a path whose parent holds anything else. The installer cleans up by removing the returned path's PARENT, so an implementation that returns, say, `/tmp/plugin` hands `/tmp` to a recursive delete. It is the one invariant a third-party source of plugins has to get right.

Parameters

Throws

\RuntimeException when the download or the extraction fails

abstract public function cleanup(string $path): void

Recursively removes a directory: either one produced by {@see self::download()} (or its owned parent), or a plugin directory the installer is replacing. Never throws — cleanup runs on failure paths, where a second exception would bury the first.

Parameters