viv

Getting started

For a PHP developer who has not used viv before: what it is, your first install, and where to go next.

What viv is

viv is a Rust reimplementation of Composer that installs from composer.lock and writes the vendor/ directory Composer would write, byte for byte, faster than Composer itself. It covers the Composer commands you run every day; anything else — plugins outside its native adapters, and Composer's longer tail of commands — stays with Composer, and the composer shim passes those straight through.

Install

cargo binstall vivace

See Install and upgrade for prebuilt binaries, the .deb package, and how to upgrade.

Your first viv install

In a project that already has a composer.json and composer.lock, run:

viv install

If there's no vendor/ yet, viv resolves the lock and writes one. If Composer already wrote vendor/, viv adopts it automatically, no flag needed: it relinks every installed package from its own store in place, so the result matches what a fresh viv install would have written.

Only one path asks first: running composer install through the composer shim on a terminal prompts before it touches a Composer-written vendor/, since typing composer install didn't opt into viv rewriting your tree —

This will relink every installed package from the store, overwriting vendor/ in place. Continue? [y/N]

— answer y to continue, anything else (including a bare Enter) aborts. A plain viv install, or a script that already runs through the shim, proceeds without asking. If a package can't be downloaded — a private package behind a licence key, for example — viv keeps Composer's copy of that package, prints a warning, and adopts the rest.

Starting from nothing

No composer.json yet? viv init writes one and stops, with no prompts: the package name is guessed from git config user.name and the directory, type is project, license is MIT, and autoload.psr-4 points at src/ when that directory exists. Pass --name, --license or --type to override a default, or --require/--require-dev to add dependencies in the same command:

mkdir demo && cd demo && viv init --require psr/log

That resolves psr/log, writes composer.lock, and installs vendor/, the same as viv add would on an existing project (--no-install opts out). Run it again with --force to start over.

viv init is for the directory you're already in; viv new is for one that doesn't exist yet. A bare name creates it and runs init's own defaults inside:

viv new demo

vendor/package[:constraint] downloads that package's dist as a project skeleton (constraint defaults to the newest stable version), drops its own VCS metadata, and installs it, running the post-root-package-install/ post-create-project-cmd scripts a skeleton like Laravel's relies on (--no-scripts opts out):

viv new laravel/laravel:^11 my-app

create-project is Composer's own name for this, kept as an alias.