Velocita: fast and reliable Composer installs

Introducing Velocita: a Composer plugin that works together with a caching reverse proxy to speed up package downloads and to provide a fallback if the original source (e.g. GitHub or Packagist) is experiencing downtime.


Let’s get right to it:

  1. Run a Velocita Proxy instance
  2. Install the Velocita Composer plugin globally by running:
    composer global config allow-plugins.gmta/composer-velocita true
    composer global require gmta/composer-velocita
  3. Point the plugin to your Velocita Proxy instance:
    composer velocita:enable

Note that the proxy (step 1) can be shared between multiple projects and developers. Installing the plugin (step 2 and 3) is something that you do just once on your development machine, for example.


Velocita already allows you to continue working with Composer when upstream servers are experiencing downtime. Additionally, it achieves a significant performance improvement just by being a webserver in your local network:

Composer2.2s ± 0.1s100%
Composer + Velocita0.5s ± 0.1s23%
↑ Results of composer require phpunit/phpunit:9.5.19

Composer + Symfony Flex4.7s ± 0.7s100%
Composer + Symfony Flex + Velocita1.6s ± 0.2s35%
↑ Results of composer create-project symfony/skeleton:v6.0.99 symfony

You can find more details about these measurements in the README.

How it works

Internally, Velocita Proxy generates a reverse proxy configuration for Nginx and the Velocita Composer plugin redirects all supported URLs to the proxy. Using environment variables, you can configure different mirrors and set caching parameters.

No changes are required to either your composer.json or composer.lock files, which means that your projects stay fully compatible with developers that do not use Velocita.

Why use Velocita?

In one of my development teams, we use Composer for our PHP-based applications and tools to pull in dependencies for development and automated deployments. Although Composer does a good job of resolving dependencies, it can lack in speed and reliability.

These are some of the issues that we experienced during regular PHP development and deployments:

  • The GitHub API rate limited (blocked) our requests, requiring authentication to circumvent;
  • Packagist experienced downtime, preventing us from installing packages;
  • GitHub Codeload downloads were throttled to the point were they became unusable;
  • A 3rd party Composer repository decided to go offline;
  • Our ISP decided that using heavy machinery to dig through our fiber-optic was the best course of action.

I believe that in software development, performance and repeatability are two important aspects in improving developer experience and decreasing the length of development iterations. Velocita speeds up composer install by offering a shared cache and if configured correctly, allows you to build projects even when faced with a total ISP outage.

Didn’t we already have something like this?

You might be thinking of Toran Proxy, which is now phased out in favor of Private Packagist – a paid solution that requires you to change your packages’ distribution URL. I strongly feel that having an open source and free to use solution helps the PHP community as a whole without conflicting with Private Packagist’s main goal: offering a private package repository.

Satis is another solution for hosting private packages and preemptively downloading dependencies to use as a cache of sorts. However, it requires coding to integrate with your projects’ repositories and you need to add a new Composer repository in your project’s composer.json to make it work.

Setting packagist to false in composer.json and adding a new repository location can seem like a good solution which does not require a plugin. However, this will also update the distribution URLs in your composer.lock limiting your ability to share that project with other developers. In contrast, Velocita enables you to enable or disable specific mirrors in the central proxy location without changes required in either the projects or the developers’ machines.


I would love to hear from you if Velocita has helped your projects or teams. Check out the Velocita Proxy and Composer Velocita projects on GitHub and feel free to raise issues or send in pull requests.