Basic instructions

The instructions are simple in basic: Extract files from the ZIP-file and upload them to your Magento site, and you're done. There are a couple of caveats - like the Magento cache - which we will discuss later on. But first, we will see what is contained in the ZIP-file.

Note that - in most cases - the developer of the Magento extension will tell you how to install things. If there is a procedure provided by the developer, use it instead. But make sure to pay attention to steps 4 till 5 of our tutorial.

Step 0) Create a backup

Changes to your Magento site should never be taken lightly. Make sure to create a backup of all files, but also include a full backup of the database. If the backup becomes very large, like numerous Gigabytes, do not use that as an excuse to not create a backup. Always a backup in place. Also make sure you know how to restore from that backup.

Step 1) Extract the ZIP-file locally and inspect the contents

Let's say we have an example ZIP-file called Yireo_Example.zip which contains a module name Example. The first step is to extract all files contained within the ZIP-file to your local computer. The extracted folder-structure could look a bit like this:

• app/etc/modules/Yireo_Example.xml
• app/code/community/Yireo/Example

If you cross-match these folders with the folders of the Magento filesystem, you can notice that Magento already contains these folders. We can copy all the files and folders recursively to Magento, so that for instance the new file Yireo_Example.xml is copied to the existing folder app/etc/modules.

When the folder-structure also contains a file called package.xml, there is chance that you can skip the procedure in this tutorial alltogether. Instead, login to your MagentoConnect Manager (within the Magento backend) and try to upload the ZIP-file as a package. 

• app/etc/modules/Yireo_Example.xml
• app/code/community/Yireo/Example
• package.xml

Some files might be contained in the ZIP-file but actually have little usage within the Magento filesystem. For instance, the file package.xml might be used by the MagentoConnect Manager, but it should not end up in the Magento root-folder. The same counts for files like installation.txt or README.txt or similar files.

Step 2) Disable the Magento Compiler

Magento has introduces a new feature called the Compiler, which allows you to merge all PHP-files into a single folder, which speeds up some of the PHP-functions that Magento uses. If you have enabled the Magento Compiler, make sure to disable it before making any changes. You can disable the Compiler through the Magento backend.

If you have not enabled the Compiler yet, do not just enable it to see what happens. It is a dangerous tool which could bring down your shop easily. Make sure you read all documentation concerning Magento performance before enabling the Compiler.

Step 3) Uploading all files to the Magento filesystem

Now you're ready to upload all files to the Magento root-filesystem. When you have SSH or SFTP available, it is best to use that - it gives you a secure encrypted connection to your Magento server. Alternatively use FTP, or control panels like CPanel or DirectAdmin.

Step 4) Refresh the Magento cache

The next step is to refresh the Magento cache. This can be done through the Magento backend. Instead of refreshing the Magento cache gently, we recommend you use the button Flush Cache to make sure all left-over files are gone.

Sometimes that's not even enough: If you are using Magento caching with default configuration-settings - meaning, the cache is stored in files - you can also try removing all the files from the Magento folder var/cache.

Step 5) Logout from the Magento backend

This step is important. Logout from the Magento backend. This makes you loose your PHP-session. Next, login again.

Step 6) Re-enable the Magento Compiler

If you had the Magento Compiler enabled before, and you disabled it in step 2, you can try to enable the Compiler again through the Magento backend. Make sure to rebuild the Compiler Cache, otherwise the new extension (or modified files) will not be included. Take note of all our warnings under step 2.

If things go wrong here, remove the file includes/config.php. This effectively disables the Compiler as well.

Success

If all went well, the extension should now be available. If things go wrong, make sure to contact the developer of the Magento extension for assistence.