How do I make my module installable via Composer?

[teppo]

I'm posting this as an update to an earlier post created by @Hari KT: https://processwire.com/talk/topic/4958-composer-support-for-processwire/. Though that approach still (kind of) works (as does the one detailed in https://github.com/wireframe-framework/processwire-composer-installer), thanks to @d'Hinnisdaël there's now a better alternative: the official composer/installers project ?

An example repository implementing the things detailed in this post:

• GitHub repository: https://github.com/teppokoivula/HelloWorld
• Packagist entry: https://packagist.org/packages/teppokoivula/hello-world

As a module author, how do I make my module installable via Composer?

1) Add a composer.json file to your module's directory. Here's an example:

{
    "name": "vendor-name/module-name",
    "type": "processwire-module",
    "license": "MIT",
    "extra": {
        "installer-name": "ModuleName"
    },
    "require": {
        "composer/installers": "~1.0"
    }
}

The composer.json file explained:

• "name" consists of two parts: your vendor (author) name, and the name of the package (module). These can (but don't have to) be the same as your GitHub or BitBucket user and repository names.
  • Please note that this value should be all lowercase! That's the syntax expected by both Packagist and Composer.
• "type" should be "processwire-module". You may have seen "pw-module" used by other packages; that's the value used by third party installers, you don't need to worry about that now.
• "license" should specify the license your module is published under. See Composer help for expected syntax. It's technically fine to leave this out, but it's always a good idea to let users know how they're allowed to use your code.
• "installer-name" under "extra" should specify the expected directory name for your module. Usually this is the same as your module's name. If you leave this out, the package part of the "name" value will be used instead (which may be just fine, though I'd recommend always filling in this value).
• "require" includes Composer dependencies of your module. The key part here is "composer/installers" — without this Composer won't know that your module requires said installer, and it may not be installable at all, so be sure to add this row.

2) Submit your project to Packagist: https://packagist.org/packages/submit.

You will need an account for this step. It's free and very easy to register, and you can automatically connect it with your GitHub account. Connecting with GitHub also makes it easier to auto-update package versions from GitHub repository.

3) Recommended but not absolutely necessary: add tags to your module's Git repository.

It's recommended that when you push a new version of your module to GitHub or BitBucket, you also add a matching tag: if you push version 0.0.3 (or version "3", following the old school ProcessWire version number format), you should also add tag 0.0.3 (or "v0.0.3" if you want to be verbose) to GitHub/BitBucket.

(This step is not strictly speaking necessary, but it does make things easier for users installing your module, and makes much easier to track which version of the module is currently installed via Composer. It requires additional step when publishing a new version of the module, but please consider doing it anyway!)

4) Also recommended but not absolutely necessary: configure Packagist to auto-update based on GitHub/BitBucket.

Follow the instructions here: https://packagist.org/about#how-to-update-packages. This step ensures that once you push a new version of your module, Packagist automatically updates stored information without you logging in and hitting the "update" button manually.

(This step may not be necessary if you've already allowed Packagist access to your GitHub account.)

... and that's it. Congratulations, your module is now installable via Composer!

As a module user, how do install a module via Composer?

Go to your site's root directory and type on the command-line "composer install vendor-name/module-name". You can look up the correct details from Packagist, or the module author may have included them in the support forum thread.

Obviously this only works for those modules that have implemented Composer installer support as outlined in this tutorial.

Note: if you're using a "non-standard" directory structure for ProcessWire — you've moved the root of the project outside the public web root, or something along those lines — check out the custom install paths part of the composer/installers README. The "installer-paths" setting allows you to manually specify a custom install path for the "processwire-module" package type.