Riff

Riff is a fast, standalone Composer-compatible package manager written in Rust. It resolves dependencies, downloads packages, installs them, generates autoload files, and provides the day-to-day commands PHP projects expect from Composer.

Riff is under active development. It targets the common Composer workflow, but it is not yet a drop-in replacement for every Composer project—especially projects that execute arbitrary PHP Composer plugins. See Compatibility before adopting it in an existing project.

Why Riff?

• A native binary for dependency resolution, repository access, installation, inspection, and autoload generation.
• Composer-compatible composer.json, composer.lock, global configuration, authentication, scripts, and familiar commands.
• First-class package patching, including declarative cweagans/composer-patches 1.x and 2.x configuration without requiring the PHP plugin.
• Native Symfony Flex 2.x recipes, aliases, packs, auto-scripts, recipe inspection and three-way recipe updates without loading the PHP plugin.
• Mutation-safe dry runs and newline-delimited JSON output for CI and editor integrations.
• A dedicated Riff cache that never mixes runtime data with Composer's cache.
• A composer executable shim for workflows that hard-code the binary name.

Riff does not embed PHP. It starts PHP only to discover runtime platform facts or execute an @php project script.

Benchmark

These are local wall-clock medians measured using symfony/demo at commit 920d86d (153 packages). Each tool installs into a fresh project tree with install plus --prefer-dist, --no-interaction, --no-progress, --no-plugins, --no-scripts, and --no-ansi; Riff also uses --no-audit because Composer does not audit on install by default. Cold runs retain neither package archives nor repository metadata. Warm runs retain only package archives from an untimed install. Riff's PHP platform facts are primed before timing and retained in both scenarios, while repository metadata is never carried between timed runs. The tools alternate which one runs first on each iteration.

The raw samples, exact versions, and cache policy are recorded in docs/assets/symfony-demo-install.json. Reproduce the benchmark and chart with mise run benchmark. Cold-cache results will vary with machine and network conditions.

Install with Homebrew

Homebrew core already uses the name riff for an unrelated tool, so install Riff's namespaced php-riff formula from the official tap:

brew install shyim/tap/php-riff

The formula installs the executable as riff and generates Bash, Zsh, and Fish completions. PHP is installed as a Homebrew dependency.

Install a Linux package

GitHub Releases include native php-riff packages for Debian-compatible and RPM-based distributions on x86-64 and ARM64. Download the package matching your system, then install it with the distribution package manager:

# Debian or Ubuntu (use arm64 instead of amd64 on ARM64)
sudo apt install ./php-riff_*_amd64.deb

# Fedora, Rocky Linux, or another RPM distribution (use aarch64 on ARM64)
sudo dnf install ./php-riff-*.x86_64.rpm

The packages install the executable as riff, include Bash, Zsh, and Fish completions, and depend on PHP CLI 7.2.5 or newer. Git is a recommended package for source installs and VCS-aware commands.

Install a release binary

Prebuilt binaries are available from GitHub Releases for Linux, macOS, and Windows on x86-64 and ARM64. Download the archive matching your target, verify it with the release's SHA256SUMS, and place riff or riff.exe on your PATH.

Release archives contain only the preferred riff executable. Build from source when you also want the Composer-compatible composer executable.

Install from source

Riff currently requires Rust 1.98.0 and PHP 7.2.5 or newer for platform-dependent operations.

git clone https://github.com/shyim/riff.git
cd riff
cargo install --path crates/riff --locked
riff --version

This installs both riff and the Composer-compatible composer shim. If you already have a composer executable in Cargo's binary directory, build the workspace and copy only target/release/riff, or choose which executable appears first on PATH.

Quick start

Use Riff in an existing Composer project:

riff validate
riff install
riff check-platform-reqs

Manage dependencies with familiar commands:

riff require psr/log:^3
riff update symfony/console --with-dependencies
riff remove vendor/package

Preview a mutation without changing the project:

riff require vendor/package:^2 --dry-run
riff update --dry-run

Run riff --help for the complete command list and riff <command> --help for authoritative option details.

Documentation

• Getting started — installation, first project, migration, and shell completion
• Everyday usage — dependency workflows, scripts, dry runs, output, and CI
• Command reference — the complete command surface, grouped by task
• Configuration — PHP selection, global config, authentication, environment variables, and cache behavior
• Rust library API — inject platform facts and execute commands without PHP detection
• Package patching — native patch authoring and Composer Patches compatibility
• Compatibility — supported Composer behavior, native plugin adapters, and intentional limits
• Troubleshooting — diagnostics and common recovery steps
• Contributing — local setup, focused tests, compatibility fixtures, and pull requests

The documentation index provides suggested reading paths.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, then use TESTING.md for the fastest test command for the area you are changing, including Composer parity and fixture inventory checks.

License

Riff is available under the MIT License.