How to make Magento Extensions work with Composer

This post is about how to make Magento extensions installable wich composer. Please refer to the previous post here on magebase.com on how to do the other part, namely install Magento extensions with composer.

Most packages, which are installable with composer, contain a configuration file named composer.json in the modules root directory. (Well, there are ways around this, but that goes beyond the scope of this post. Check the composer reference if you want more.)

Don’t confuse this composer.json file with the composer.json file in the root directory of the target project, which is called the root composer.json.

Note: If you are providing your extension as a Magento Connect 2.0 package you actually don’t have to create the composer.json file – all required information could already be found in the package archive.

But maybe you don’t want to depend on Magento Connect for distribution, or are hosting your module on github anyway. In those cases it makes a lot of sense to provide a composer.json file with the module.

So generally, when you want to make your Module compatible with composer, your first step would be to create that file. Then you fill in the basic information required for any composer package.

Here for example is the composer.json file of one of my extensions:

{
  "name":"netzarbeiter/groups-catalog2",
  "type":"magento-module",
  "license":"OSL-3.0",
  "homepage":"https://github.com/Vinai/groupscatalog2",
  "description":"Magento extension to hide categories and products from customers depending on their customer group.",
  "authors":[
    {
      "name":"Vinai Kopp",
      "email":"vinai@netzarbeiter.com"
    }
  ],
  "require":{
    "magento-hackathon/magento-composer-installer":"*"
  }
}

You can call composer.phar validate in the directory, and it will tell you if you forgot anything, or if there is a syntax error in the JSON.

If you are familiar with packaging composer files you might have noticed two unusual things. The first on is the type

"type":"magento-module"

This tells the magento-composer-installer that it is responsible to figure out how to install the thing.

And because the magento-composer-installer actually isn’t part of the composer project, each Magento module has to list it as a dependency:

"require":{
  "magento-hackathon/magento-composer-installer":"*"
}

That’s almost everything, except for the…

Mapping from Module to Magento

One difference between any other composer package and Magento modules is that Magento extensions need to be integrated into different parts of the Magento source tree after installation. Module code goes into app/code/codePool/ branch, templates and layout configuration into the app/design/ branch, and so on.

First all the module code is installed into the vendor directory (by composer), and then the step of linking the modules files into the Magento source tree is handled by the magento-composer-installer.

This mapping from the module installation directory into Magento needs to be configured.

Currently the mapping can be specified in three ways:

1. The modules composer.json file
2. A Magento Connect 2.0 package.xml file
3. A modman file

The magento-composer-installer will check for each one in the order specified above, and use the first available option.

composer.json map

To specifying the mapping in the composer.json file, add it to the extra.map list like this:

{
  ...
  "extra":{
    "map":[
      ["app/etc/modules/Aoe_TemplateHints.xml", "app/etc/modules/Aoe_TemplateHints.xml"],
      ["app/code/local/Aoe/TemplateHints/", "app/code/local/Aoe/TemplateHints/"],
      ["skin/frontend/base/default/aoe_templatehints", "skin/frontend/base/default/aoe_templatehints"]
    ]
  }
}

Each file or directory to be mapped is an array with two records. The first record is the file or directory in the modules source tree, and the second record is the location inside of the Magento source tree.

In the example above the first and second record always are the same, but it doesn’t have to be that way. A map entry could look something like this:

["code","app/code/community/My/Module"]

package.xml map

The mapping in a package.xml will be created for you when you build a regular Magento Connect 2.0 extension package through the Magento admin interface (System > Magento Connect > Package Extensions). There is nothing special about it, as all Magento extensions that conform to the Magento Connect 2.0 format can be installed by the magento-composer-installer automatically.

The Magento Connect 2.0 extension format is the one that is used when packages for Magento 1.5 and newer are created. The older format, for Magento instances up to 1.4, are actually PEAR packages. The reason they aren’t supported by the magento-composer-installer, is the assumption, that any Magento instance for which composer manages the modules will be a current version.

modman map

Modman is a script which symlinks module files into a directory tree.

The tool quickly was widely adopted by Magento developers. This actually was the first mapping option the magento-composer-installer supported, because so many modules on github already came bundled with a modman configuration.

Using this method gives you the added benefit that your module can also be installed using the modman script.

The modman configuration file has to be in the root directory of the module package. The basic format is very simple. Each line lists two file system paths. The one on the left is the source directory in the module code base, the one on the right is the target inside of Magento.

(If there are line breaks in the following list between the two items, that’s a formatting bug):

My_Module.xml app/etc/modules/My_Module.xml
code app/code/community/My/Module
locale/de_DE/My_Module.csv app/locale/de_DE/My_Module.csv

Once again, most people prefer to use the same structure in the module directory tree as in Magento, but it doesn’t have to (like in our example).

Globbing wildcards are also supported:

app/locale/de_DE/* app/locale/de_DE/

There are some additional features modman offers, like executing scripts when a module is installed, but these other options aren’t supported by the magento-composer-installer and will be silently ignored.

The only additional modman feature for which there currently are plans to incorporate into the installer is @import, which allows including modman files from module subdirectories.

Distribution

To make your module available to the composer-using world, the next step is to add it to the Magento module repository at packages.firegento.com.
And once again, you are presented with a choice:

a)   Make it available from github
b)   Make it available from Magento Connect

a) github

If your module is available on github, it’s easy to add it to the repository.

1. Clone the magento-hackathon/composer-repository
2. Add your module to the satis.json file.
3. Validate it’s still valid JSON (e.g. no trailing or missing comma)
4. Commit and open a pull request

That’s all.

b) Magento Connect

If your module is available on Magento Connect, it’s even easier to add it to the list: you are already done – no additional step is required.

All installable Magento Connect 2.0 packages are automatically listed on packages.firegento.com.

The packages from Magento Connect have a composer name prefix composer20/ which makes it pretty easy to recognize them.

By the way, you can add your module to the repository hosted on github and from Magento Connect. This can even be useful.

For example, I update my modules often, but only build new Magento Connect packages once in a while. Users who want to get bug fixes quickly, should configure a dependency on the github module (netzarbeiter/customer-activation).

Users who want the code from Magento Connect just use the according package name instead (connect20/customeractivation).

Wrap up

This turned out to be a longer post then I had expected. But I hope you agree that it’s actually no rocket science. In fact, it’s rather easy. I hope to see all your modules on packages.firegento.com soon, if they aren’t there already.

If you have any questions, please post a comment here. If you encounter an issue, please open an issue on github.

I really suggest you read up more on composer, which has very good documentation.

Have a good time using composer to manage your dependencies!

Originally published on magebase.com. Copyright © 2013 Magebase - All Rights Reserved.