Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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 is especially useful when you can't use Private Packagist or Basic HTTP Auth because the source of a package is not in your control. This repository is inspired by acf-pro-installer.

Quick overview

  • This plugin is compatible with both Composer 2.x (latest) and 1.x.
  • When installing or updating a package, the dist URL {%VERSION} placeholder gets replaced by the version set in the package. In Composer 1 the dist URL version gets fulfilled before it is added to composer.lock.
  • Before downloading the package, {%VARIABLE} formatted placeholders get replaced by their corresponding environment variables in the dist URL. Env vars will never be stored inside composer.lock.
  • If an environment variable is not available for the given placeholder the plugin trys to read it from the .env file in the working directory or in one of the parent directories. The .env file gets parsed by vlucas/phpdotenv.
  • If an environment variable can't be resolved a MissingEnvException gets thrown.
  • Package dist URLs with no {%VARIABLE} formatted placeholders get ignored by this plugin.


Arbitrary private packages

Add the desired private package to the repositories field inside composer.json. Find more about Composer repositories in the Composer documentation. Specify the exact version to install, and use {%VARIABLE} placeholders to specify any sensitive tokens in your .env file.

  "type": "package",
  "package": {
    "name": "package-name/package-name",
    "dist": {
      "type": "zip",
      "url": "{%PACKAGE_KEY}&version={%VERSION}"
    "require": {
      "ffraenz/private-composer-installer": "^5.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",
    "type": "wordpress-plugin",
    "dist": {
      "type": "zip",
      "url": "{%PLUGIN_ACF_KEY}&t={%VERSION}"
    "require": {
      "composer/installers": "^1.4",
      "ffraenz/private-composer-installer": "^5.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:*"


The configuration options listed below may be added to the root configuration in composer.json like so:

  "name": "...",
  "description": "...",
  "require": {
  "extra": {
    "private-composer-installer": {
      "dotenv-path": ".",
      "dotenv-name": ".env"


Dotenv file directory relative to the root package (where composer.json is located). By default dotenv files are expected to be in the root package folder or in any of the parent folders.


Dotenv file name. Defaults to .env.


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.1, ^5.2 ^5.0
^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 test

This is a project by Fränz Friederes and contributors