This is a small guide on how to install a Magento module.

Important Note!

Whatever option you choose, please never install a module on a production environment without having it properly tested before and ideally after doing an in-depth code review!
Ideally you have a clean build and deployment process in place that will take care of deploying new modules including all necessary configuration updates to the production server. This will not only ensure a smooth and gapless update process, but might also provide a way to rollback in case something unexpected is happening.

Option 1: Magento Connect

If the module is available on Magento Connect...

  1. Go to Magento Connect, find the module, login to Magento connect and click the big "Install Now" button on the module page to show the module's extension key
  2. Go to System > Magento Connect > Magento Connect Manager, login with your admin credentials, paste the extension key into the input field under "Install New Extensions" and follow the instructions.

I do not recommend using Magento Connect to install modules for many different reasons. Most of the AOE modules are not even available on Magento Connect and the ones that are are terribly outdated. Finding a stable release (check the tags) on GitHub is usually a much better choice. Also checkout GitHub's network diagram (simply append /network to the module's GitHub page) to find out which is the most maintained fork and branch. For AOE that's usually the fork in the AOEpeople account, but for some modules you should also check the aoemedia account and fbrnc's account.)

Instead of using Magento Connect I recommend using one of the methods mentioned below (in order from simplest to most recommended):

Option 2: Extract and copy

Like many other community provided Magento modules all AOE modules internally have a file structure that matches the Magento core. (Watch out for some modules that have an additional src directory). Although it's recommended to use one of the options below that rely on modman (or a different implementation of the same concept) you can download the module from GitHub, extract it and simply copy the files over to the Magento core. Again, please don't do this on production!

wget https://codeload.github.com/AOEpeople/Aoe_Scheduler/tar.gz/v0.4.3 -O /tmp/package.tar.gz
tar -xzvf /tmp/package.tar.gz
cp -Rv Aoe_Scheduler-0.4.3/* /var/www/magento/htdocs/

Option 3: modman

All AOE modules (and many other community provided Magento modules) come with a modman file in the module's root folder. This indicates that this module can be installed using the modman script.

Modman will parse the modman configuration file and will create symlinks (or copies if you prefer) from within the correct location inside the Magento directory structure to your module. This way your modules and the core are still cleanly separated from each other. This has a lot of benefits:

  • You can manage the modules and the core in different VCS locations.
  • This allows you to reuse generic modules across project and/or include Magento modules directly from their original source.
  • This allows you to easily update both the modules and the Magento core to newer versions.
  • Uninstall modules is easy since you only have to delete the directory inside the .modman directory.

Note: If you want to use modman you need to configure Magento to allow rendering templates that are being symlinked. Please go to System > Configuration > Advanced > Developer and enable Allow Symlinks.

For more information modman please read the project's readme file.

This is how to install a module via modman:

  1. Create a directory called .modman inside your Magento root directory (e.g. htdocs). Or even better: create this directory outside the web root, next to your Magento root directory. In this case you also need to create a file .basedir inside your .modman directory containing the relative path to your Magento root directory: In this case this would be htdocs. (Don't get confused with the different things called 'modman': There's the modman script, the modman configuration file inside the module and the .modman directory that will contain all the modules). Resulting directory structure:
    /var/www/magento/
    .modman/
        .basedir (<- contains "htdocs")
        ModuleA/
        ModuleB/
        ...
    htdocs/
        index.php
        app/
        ...
  2. Clone the module's repository
    cd /var/www/magento/.modman 
    git clone https://github.com/AOEpeople/Aoe_Scheduler.git Aoe_Scheduler
  3. Download modman
    wget https://raw.githubusercontent.com/colinmollenhour/modman/master/modman -O /var/www/magento/modman
    chmod +x /var/www/magento/modman
  4. Run the modman script
    cd /var/www/magento
    modman deploy-all

Modman also has some build-in capabilities to deal with some VCS. I don't think this is part of the scope of what modman should be doing. That's why I prefer to handle all git operations outside modman.

If your Magento project itself is also using git and you're familiar/comfortable with git submodules you could include the Magento module like this:

cd /var/www/magento
git submodule add https://github.com/AOEpeople/Aoe_Scheduler.git .modman/Aoe_Scheduler

Option 4: Composer

While modman is a great tool to 'wire' the modules into the Magento core it doesn't help you to manage where the modules are coming from. Using git submodules is one way of doing this, but you might soon run into problems.

The recommended way of 'connecting' your Magento modules to Magento these days is Composer. Check out the instructions in the Composer page on how to install it.

From there you have two more options:

Option 4.a: Using the Magento Hackathon Composer Installer

This is definitely the most popular option. While this installer teaches Composer how to handle Magento modules it also parses the modman files (and offers some other methods) to create the symlinks or copy the files. This is fast and handy, but again: This tool is doing way too much for my taste (while not being 100% compatible with the original modman files).

Check out the project's readme file for more information.

Option 4.b: Using the AOEpeople Magento Composer Installer

The AOEpeople Magento Composer Installer is super lightweight (in fact it's only a few lines of code inspired by Composer's Multi-Framework Composer Library Installer) and only let's it know how to handle Magento modules (and in addition it also introduces another type for the Magento core). This composer installer acts like a replacement for the Hackathon Composer installer. So every Magento module that comes with a composer.json file that contains a reference to the Hackathon installer will work with this lightweight one as well.

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

The AOEpeople installer will not deal with parsing the modman files. You should use the original modman script to do so.

So in order to setup a simple project and pull in a Magento module via composer you need to create a composer.json file in you project root folder. (Again, don't confuse the project's composer.json file with the one that's inside the Magento modules).

Before a composer package can be used it needs to be registered on packagist.org or in a different package repository. A lot of the open source Magento modules are listed in the repository managed by Firegento. You need to add following lines to your project's composer.json to tell Composer to also check out the Firegento repository:

{
   ...
    "repositories": [
        {
            "type": "composer",
            "url": "http://packages.firegento.com"
        }
    ],
    ...
}

Most of the AOE modules are on Packagist or on Firegento. In case a module is in neither of those you can add custom sources to be checked by Composer. Usually we like to be explicit and configure them even if the module is on Packagist or Firegento:

{
    ...
    "require": {
        ...
        "aoepeople/aoe_scheduler": "*",
        ...
    },
    "repositories": [
        ...
        {
            "type": "vcs",
            "url": "https://github.com/AOEpeople/Aoe_Scheduler.git"
        },
        ...
    ],
    ...
}

And here's what you need to add if you want to use the AOEpeople installer instead of the Hackathon one:

{
    ...
    "require": {
        "aoepeople/composer-installers": "*",
        "aoepeople/aoe_scheduler": "...",
        ...
    },
    "repositories": [
        ...
        {
            "type": "vcs",
            "url": "https://github.com/AOEpeople/composer-installers.git"
        },
        {
            "type": "vcs",
            "url": "https://github.com/AOEpeople/Aoe_Scheduler.git"
        },
        ...
    ],
    ...
}

After you created the composer.json file in your project root directory make Composer go find and download them like this:

composer.phar install

You should now see the module showing up in the .modman folder. Assuming that you already have the Magento core in htdocs (either through Composer or manually) you now need to run modman to create the symlinks:

modman deploy-all

Now you should be good to go! :)

Comments

This website uses disqus for the commenting functionality. In order to protect your privacy comments are disabled by default.

Enable Comments