Installing and setting up a Magento extension
This is a guide for Magento 1. For Magento 2 extensions and guides, please refer to Magento 2 Guides.
Disclaimer: We recommend to install ANY extension you purchase/download in a testing environment before deploying it to your production environment. Please also backup your Magento installation (files and database) before installing any extension and make sure no conflicting extensions are installed. All XTENTO extensions were tested in clean Magento installations without third party extensions and we can't guarantee for compatibility with third party extensions.
Contents |
General Installation Guide
The following steps are required to set up a XTENTO extension. Please follow them carefully as if you're missing one of the steps, the installation of the extension could fail which could lead to issues in your Magento installation. If the installation fails, or if you're seeing any error message, please try to re-install the module by starting from the first step again.
Warning for Mac OS users: If you are installing the extension in a local environment by copying the extensions files using Finder into a local directory, make sure to *merge* and not to *replace* the existing folders contents, as otherwise your app folder will be gone. Read more. Use a file manager that merges folders or a FTP client instead.
Installation procedure
- If you're using the Magento compiler - or if you are not sure if you're doing so - please log into the Magento backend and go to System > Tools > Compilation and turn it off. If you don't do so there's a good chance you'll temporarily break your Magento installation, see the troubleshooting section at the bottom of this site for fixes. Also, it is recommended to ENABLE the cache at System > Cache Management before installing any extension.
Folder structure matching
- Open the extension ZIP file you downloaded from the 'My Downloadable Products' section on www.xtento.com and extract it to a directory on your computer using a tool like WinRar, WinZIP or similar.
- Upload the extracted folders and files into the root directory of your Magento installation. The root directory of Magento is the folder that contains the directories "app", "js", "skin", "lib" and more. All folders should match the existing folder structure. If one of our extensions is already installed and you're updating it, make sure to overwrite the existing files of the extension.
- Go to System > Cache Management and click both the 'Flush Magento Cache' as well as the 'Flush Cache Storage' button. This is required to activate the extension.
Cache Management - Log out of the Magento admin and log back in - you'll see a 404 Error when trying to open the configuration section if you don't log out / log in once.
- If you're using the Magento compiler and had it enabled before installing this extension, go to System > Tools > Compilation and click on 'Run Compilation Process' to re-compile Magento and enable it again by clicking on 'Enable'.
Please follow the extension specific setup steps (if any) now. Otherwise you're done with the installation.
Update Guide
Updating a XTENTO extension is easy: Simply follow the installation guide (see above) and overwrite any existing files.
Troubleshooting: Problems after installation
- Module doesn't show up in the backend / doesn't work: Try to manually refresh the cache by deleting the contents inside the /var/cache/ directory (located in the Magento root directory).
- Module STILL doesn't show up in the backend / doesn't work: Make sure you have uploaded all files to the CORRECT location. This is very important - please do not forget to upload one or more files and make sure you upload it to the right location (Magento root directory)
- Module STILL doesn't show up: Make sure the file permissions for all the files uploaded are right. Files must be readable by the webserver.
- I get an error saying 'Class X' could not be found: Please go to through the installation process once again and make sure you have uploaded all files. This is very important - please do not forget to upload one or more files.
- Error 503 Service unavailable: You tried to install the extension using the Magento Downloader. That's the WRONG way to do it. Delete the file "maintenance.flag" located in the Magento root directory and install the extension as explained above using (S)FTP.
- I only get a blank screen / 500 Internal Server Error / Mage registry key "_singleton/.../..." already exists when opening the Magento backend: You had the Magento compiler enabled and forgot to disable it before installing this extension. Please open the file includes/config.php located in the root directory of Magento and make sure both lines saying define are commented out. To comment code, simply add a # (hash character) in front of that line, making it the very first character of that line. The backend should work again then and you should be able to recompile Magento at System > Tools > Compiler.
- Getting Mage registry key "_singleton/xtento_..." already exists and you are sure the compiler is fine/disabled? This can be caused by missing files. Make sure to re-upload all extension files.
- Blank page / Error 500/503 / "Exception printing is disabled"? Probably an error. Please do the following and email us the error message, if it's not an error explained above: See this.
- Getting "SQLSTATE[42S02]: Base table or view not found: 1146 Table '...' doesn't exist"? Please see here
Still got problems? A fatal error you can't solve yourself? Please get in touch with us and temporarily disable the extension by navigating to the root directory of Magento, folder /app/etc/modules/ and find the XML file for the just installed extension. Simply rename the file to ORIGINALFILENAME.xml.disabled and refresh the Magento cache.
Troubleshooting: PHP Memory Limit
For Magento to properly work, the PHP memory_limit should be set to at least 256M (or even better 512M) as required by Magento: Magento System Requirements
You can check the set PHP memory_limit in phpinfo() or at System > Configuration > Section: "XTENTO Extensions" > General Configuration > Tab "Debug Information".
If you get an error saying: "Fatal error: Allowed memory size of 123456789 bytes exhausted (tried to allocate xy bytes)" your PHP memory_limit must be increased.
If you get an error saying: "Fatal error: Out of memory (allocated 1234567) (tried to allocate 123456 bytes)" this is a different problem not caused by the PHP memory_limit. The following system memory limits may need to be increased:
- Test if you have any RLimitMEM in your Apache settings that may limit memory usage for Apache processes. You can use cd /etc/apache2/ && grep -irn 'RLimitMEM' to search for this configuration value.
- See if you have any security limits for the Apache user in /etc/security/limits.conf, or generally for users using ulimit -v
Cronjob issues with our import/export modules?
Are you sure your Magento cronjob has been set up properly but automatic imports/exports don't work anyways? See here on how to move them into a separate cron group.
