A composer install helper for private packages

Fund package maintenance!

Installs: 122 156

Dependents: 2

Suggesters: 0

Security: 0

Stars: 125

Watchers: 4

Forks: 7

Open Issues: 6


v4.0.0 2020-02-20 18:46 UTC

This package is auto-updated.

Last update: 2020-07-13 15:36:58 UTC


Packagist version MIT license Build Status Coverage Status Packagist downloads

This is a Composer plugin offering a way to reference private package URLs within composer.json and composer.lock. It outsources sensitive dist URL parts (license keys, tokens) into environment variables or a .env file typically ignored by version control. This repository is inspired by acf-pro-installer.

Quick overview

  • When installing or updating a package, the dist URL {%VERSION} placeholder gets replaced by the version set in the package. The versioned dist URL is added to composer.lock.
  • Before downloading the package, {%VARIABLE} formatted placeholders get replaced by their corresponding env variables in the dist URL. Env vars will never be stored inside composer.lock.
  • If an env variable is not set for the given placeholder the plugin trys to read it from the .env file using vlucas/phpdotenv. If it can't be resolved a MissingEnvException gets thrown.
  • Package dist URLs with no {%VARIABLE} formatted placeholders get ignored by this plugin.


Arbitrary private package

Add the desired private package to the repositories field inside composer.json. In this example the entire dist URL of the package will be replaced by an environment variable. Find more about composer repositories in the composer documentation.

  "type": "package",
  "package": {
    "name": "package-name/package-name",
    "version": "1.0.0",
    "dist": {
      "type": "zip",
      "url": "https://example.com/package-name.zip?key={%PACKAGE_KEY}&version={%VERSION}"
    "require": {
      "ffraenz/private-composer-installer": "^4.0"

Provide the private package dist URL inside the .env file:


Let composer require the private package:

composer require "package-name/package-name:*"

WordPress plugins

WordPress plugins can be installed using the package type wordpress-plugin in conjunction with the composer/installers installer. In this example we are installing the ACF Pro plugin. Add following entry to the repositories field inside composer.json and set the desired ACF Pro version.

  "type": "package",
  "package": {
    "name": "advanced-custom-fields/advanced-custom-fields-pro",
    "version": "1.2.3",
    "type": "wordpress-plugin",
    "dist": {
      "type": "zip",
      "url": "https://connect.advancedcustomfields.com/index.php?a=download&p=pro&k={%PLUGIN_ACF_KEY}&t={%VERSION}"
    "require": {
      "composer/installers": "^1.4",
      "ffraenz/private-composer-installer": "^4.0"

Provide the ACF Pro key inside the .env file. To get this key, login to your ACF account and scroll down to 'Licenses & Downloads'.


Let Composer require ACF Pro:

composer require "advanced-custom-fields/advanced-custom-fields-pro:*"


This package heavily depends on vlucas/phpdotenv to load environment variables "automagically". This may cause version conflicts if your project already depends on it. Refer to this table to set the version of private-composer-installer accordingly or consider upgrading.

vlucas/phpdotenv private-composer-installer
^4.0 ^4.0
^3.0 ^3.0, ^2.0
^2.2 ^1.0


Install composer dependencies:

docker-compose run --rm composer composer install

Before pushing changes to the repository run tests and check coding standards using following command:

docker-compose run --rm composer composer check

This is a project by Fränz Friederes and contributors