Create a Composer Package Locally

If you’re working on a PHP project that uses several Composer packages, you may find yourself needing to create a Composer package locally without submitting it to Packagist or other hosted repositories.

To save you from having to create an empty Packagist package and constantly having to update the hosted code, you can start developing the package locally until you are ready to submit a first version.

Contrary to popular belief, you do not need to start creating Composer package in your project’s vendor directory.

Instead, specify a path repository in your main project’s composer.json file. Composer will then create a symlink in your project’s vendor directory to the external path of the package you are developing.

Start by adding a path repository within the repositories configuration of your project’s composer.json file.

"repositories": [
        "type": "path",
        "url": "../packages/[vendor_name]/[package_name]"

In this example, a packages directory exists outside of the main project’s directory. This prevents any packages being developed on from being unnecessarily exposed or accidentally being pushed to a VCS such as Git.

Secondly, add your local package to the require section of your project’s composer.json to include the package within your project.

As you may not have committed your project to a VCS or if you have, tagged the commits with a version number, simply include dev-master rather than a version number to fetch the latest updates from your package.

"require": {
    "[vendor_name]/[package_name]": "dev-master"

Finally, create a composer.json in your local package’s directory.

In the example specified in this post, the composer.json file would be created within ../packages/[vendor_name]/[package_name].

The contents of your package’s composer.json does not have to contain a lot of information.

Simply ensure that you specify the correct requirements of your package, followed by including any files needed to be autoloaded in the autoload section of the composer.json file.

  "name": "[vendor_name]/[package_name]",
  "description": "Your Description",
  "require": {
    "php": "7.0.2|7.0.4|~7.0.6|~7.1.0",
  "autoload": {
    "files": [

Head back to your main project’s directory, and run the composer update command. You should notice that your package gets included and Composer has generated a symlink to the directory of your package.

The output from running the Composer update command in command line might look like the below.

  - Installing [vendor_name]/[package_name] (dev-master)
    Symlinked from ../packages/[vendor_name]/[package_name]

When you create a Composer package locally and start your development on it, you could add a Git repository specifically for your package and push changes to it.

To do this, simply run the git init command within your package’s directory and set up the relevant Git configuration.

This means that you can work on a Composer package without needing to expose the package publicly until you are completely happy that you have a working first version of your package to publish.