README

The Composer Platform Package Installer is a powerful plugin for platform-aware distribution URL resolution.

The core behavior is simple:

Your package declares platform-specific artifact URLs or URL templates in composer.json
At install time, the plugin picks the best URL for the current OS/architecture
It resolves placeholders (built-in {version} plus optional custom variables)
It tells Composer to download and install the package from that resolved URL

Requirements

PHP 8.1+
Composer 2+

Installation

Install the plugin using Composer:

composer require codewithkyrian/platform-package-installer

Then change your package type to platform-package in composer.json:

{
  "name": "org/your-platform-package",
  "type": "platform-package",
  "require": {
    "codewithkyrian/platform-package-installer": "^2.0"
  }
}

Core Configuration

All core behavior is configured in composer.json under extra.artifacts.

Legacy extra.platform-urls is still supported for backward compatibility, but is deprecated.

Format A: Simple (no custom variables)

Use this when:

you are using direct artifact URLs with no placeholders, or
{version} is the only placeholder you need.

{
  "extra": {
    "artifacts": {
      "darwin-arm64": "https://cdn.example.com/pkg/{version}/darwin-arm64.zip",
      "linux-x86_64": "https://cdn.example.com/pkg/{version}/linux-x86_64.tar.gz",
      "all": "https://cdn.example.com/pkg/{version}/universal.zip"
    }
  }
}

Format B: Extended (custom variables + defaults)

Use this when templates include additional placeholders beyond {version}.

{
  "extra": {
    "artifacts": {
      "urls": {
        "darwin-arm64": "https://cdn.example.com/pkg/{version}/variant-{runtime}/darwin-arm64.zip",
        "linux-x86_64": "https://cdn.example.com/pkg/{version}/variant-{runtime}/linux-x86_64.tar.gz"
      },
      "vars": {
        "runtime": "gpu"
      }
    }
  }
}

Application-Level Variable Overrides

Consumers of your platform package can override variables from their root project:

{
  "extra": {
    "platform-packages": {
      "org/your-platform-package": {
        "runtime": "cpu"
      }
    }
  }
}

Variable precedence:

Root app override (extra.platform-packages.<package-name>)
Package default (extra.artifacts.vars)
Built-in {version} (always provided by plugin)

Placeholder Behavior

{version} is built in and always available
Any {name} placeholder can be used
Unresolved placeholders cause artifact URL resolution to fail for that package
If override variables resolve to a URL that does not exist, the plugin retries with package default variables
On failure, Composer falls back to the package's original dist configuration

Platform Matching

The plugin matches the current machine against keys in artifacts:

OS-only keys: linux, darwin, windows, raspberrypi
OS + architecture keys: darwin-arm64, linux-x86_64, windows-32, windows-64, etc.
all as final fallback

More specific matches are preferred over generic ones.

Optional Helper: Generate URLs Command

platform:generate-urls is a helper to generate artifact URL entries from a template.

composer platform:generate-urls --dist-type=github --repo-path=vendor/repo --platforms=linux-x86_64 --platforms=darwin-arm64

You can also provide platforms as a comma-separated list:

composer platform:generate-urls --dist-type=github --repo-path=vendor/repo --platforms=linux-x86_64,darwin-arm64,windows-x86_64

Or with a custom URL template:

composer platform:generate-urls --dist-type=https://cdn.example.com/vendor/repo/release-{version}-{platform}.{ext} --platforms=linux-x86_64,darwin-arm64

Command options:

--platforms platform identifiers (repeat the flag or use comma-separated values)
--dist-type github, gitlab, huggingface, or custom template
--repo-path repository path for built-in templates
--extension force archive extension

The command writes generated URLs into extra.artifacts.

Testing

Run tests with:

composer test

The test suite includes:

unit tests for matching, templating, and generation logic
integration tests that run real composer install flows

License

MIT. See LICENSE.

codewithkyrian / platform-package-installer

Maintainers

Package info

Statistics

Security