In a composer.json, how do the vcs, path and composer repository types differ, and when would you choose each?

## What a repository is to Composer A **repository** is a source of package metadata: a list of package names, versions and where to download each one. By default Composer knows exactly one, **Packagist.org**. Every other source is declared in the root `composer.json` under `repositories`, and only the **root** package's list counts. Repositories that a dependency declares in its own `composer.json` are ignored, so a private package that itself depends on another private package forces the root project to declare both. ## The three types that matter | Type | Points at | Versions come from | Typical use | |---|---|---|---| | `composer` | a URL serving `packages.json` | the registry's metadata | Packagist, a self-hosted or private registry | | `vcs` | a Git, Mercurial, Subversion or Fossil repository | tags (releases) and branches (`dev-<branch>`) | a patched fork, a private repository without a registry | | `path` | a local directory, absolute or relative, globs allowed | the checked-out branch or tag, the package's `version` key, else `dev-master` | packages developed inside the same monorepo | ### composer The `composer` type is the registry protocol. You give the base URL, and Composer fetches the `packages.json` index and the per-package metadata files it points to. It is fast because the registry has already read every package's `composer.json`, and Composer usually downloads zip dists rather than cloning. ### vcs The `vcs` type makes Composer clone or query the repository itself and read `composer.json` on each tag and branch. The classic use is a **fork with a fix**: 1. Push the fix to a branch named `bugfix` on your fork. 2. Add the fork as a `vcs` repository. 3. Require the package under its **original** name with the constraint `dev-bugfix`. The package's `name` in the fork must stay the same as the original, or the override does not apply. If other dependencies require a tagged range of the same package, an inline alias such as `dev-bugfix as 1.0.x-dev` lets the branch stand in for that version line. The cost is speed: each VCS repository has to be scanned when Composer builds its package pool, which is why many teams move private packages behind a `composer` registry once there are more than a handful. ### path The `path` type turns a local directory into a package. Composer **symlinks** it into `vendor/` when it can (the console prints `Symlinking from ...`) and **mirrors** (copies) it otherwise. `"options": {"symlink": false}` forces a copy, which is what you want when building a deployable artifact from a monorepo, since a symlink pointing outside the build directory breaks once the artifact moves. `"options": {"versions": {"my/package": "4.2-dev"}}` sets the version when it cannot be inferred. ## Priority: canonical repositories and filters Composer searches repositories **top to bottom**, with Packagist added implicitly **last**. In Composer 2 every repository is **canonical** by default: once a package name is found in a repository, lower repositories are not searched for that name, even if they carry a higher version. Composer 1 did the opposite. This is why a fork declared as a `vcs` repository overrides the Packagist original, and why an internal package name cannot be replaced by a higher version published on Packagist. Three settings adjust this: - `"canonical": false` lets Composer keep looking in lower repositories and pick the best version across them. - `"only": ["acme/*"]` restricts a repository to matching package names. - `"exclude": ["toy/package"]` stops it supplying the named packages. `{"packagist.org": false}` in the list, or `composer config -g repo.packagist.org false`, removes Packagist entirely for projects that must install only from an internal registry. ## Settings that keep repositories honest - `secure-http` defaults to `true`, so Composer refuses plain `http://` URLs for downloads; turning it off to reach an internal server is almost always the wrong fix compared with giving that server a certificate. - Credentials for private `composer` and `vcs` repositories belong in `auth.json` or environment variables, never inside the `url` in `composer.json`, which is committed. - A `path` repository only works where the directory exists, so a project that ships to a server needs the path packages inside the build context, mirrored rather than symlinked. ## Choosing - Private code shared by several projects: a `composer` registry, restricted with `only` to your vendor prefix. - A temporary patch to an open-source library: a `vcs` repository pointing at your fork, and a plan to go back upstream. - Several packages developed in one repository: `path` repositories with a glob, mirrored for release builds.