Installing and setting up a Magento 2 extension
This is a guide for Magento 2. For Magento 1 extensions and guides, please refer to Magento 1 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.
General Installation Guide
Our Magento 2 extensions can also be installed via composer. See: https://www.xtento.com/composer/customer/ (Described below is the non-composer method - if you use composer, after running "composer require", start with step 4 in the guide below)
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
- It is recommended to ENABLE the cache at System > Cache Management before installing any extension.
- Open the extension ZIP file you downloaded from the 'My Downloads' 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", "bin", "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.
- Connect via SSH and run the following commands (make sure to run them as the user who owns the Magento files! See output of "ls -la"):
- php bin/magento module:enable --clear-static-content Xtento_XtCore
- php bin/magento module:enable --clear-static-content Xtento_MODULENAME (replace with what you purchased, see ZIP filename, WITHOUT the version. For example: Xtento_OrderExport)
- php bin/magento maintenance:enable ; php bin/magento setup:upgrade ; php bin/magento setup:static-content:deploy ; php bin/magento setup:di:compile ; php bin/magento maintenance:disable
- 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.
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. (In case you installed the module via composer, update via "composer update xtento/modulename --with-all-dependencies" instead) No need to run the module:enable commands, however it is very important you run setup:upgrade (php bin/magento setup:upgrade) after updating any Magento extension. Then, after updating, clear the contents inside the /var/cache/, /var/di/ and /var/generation/ (Magento 2.2+: generated/code) directories (located in the Magento root directory). Sometimes it is also required to deploy static content using the "bin/magento setup:static-content:deploy" command.
Installing a Magento Marketplace extension
If you purchased an extension on Magento Marketplace, there are three ways to install your extension:
1) Easy Method: Use the "official Marketplace method" and install via composer. Easy, as it fetches components/dependencies automatically. Just be sure to select the "Install dependencies" option when installing via the Web Setup Wizard.
3) Manual ZIP Method: You can also go the ZIP route. You can download the extension ZIP file from the "My Purchases" section on marketplace.magento.com. Be sure to download the "Xtento_XtCore" package as well, it's located in the "Packages" tab at "My Purchases" (Screenshot where to find the Xtento_XtCore package Important, as of October 2017 there's a bug on Marketplace that won't let you download the XtCore module. Click here to download it. (This only applies if you purchased the module on Marketplace and do a manual ZIP installation)).
First, upload the contents of the XtCore package. Then, create another folder called app/code/Xtento/MODULENAME/ where MODULENAME must be replaced by the modules internal identifier. You can find it in the "composer.json" file in the extension ZIP file you downloaded, look at the node "psr-4". For example, it could say "Xtento\\ProductExport\\" or "Xtento\\GridActions\\" there, then the MODULENAME is the part after \\ and before \\, so in our examples ProductExport" or "GridActions". This is what you call the folder, then, for example app/code/Xtento/ProductExport, and you put the contents of the extension ZIP file in there.
Then, install the extensions as stated above in our normal install guide: First install and enable Xtento_XtCore, then the extension you purchased.
Any questions, please do not hesitate to contact us.
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/ and /var/generation/ (Magento 2.2+: generated/code) directories (located in the Magento root directory) and also in Magento at "System > Cache Management" using the "Flush Magento Cache" and "Flush Cache Storage" buttons.
- 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.
- Module STILL doesn't show up: Try restarting your webserver (Apache/Nginx) and also if using PHP-FPM, restart it: sudo service php-fpm restart
- 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.
- Blank page / Error 500/503 / "Exception printing is disabled"? Probably an error. Please enable "developer mode" in Magento, for example via .htaccess or the command line using bin/magento, to see the real error message. Or, if that doesn't work, force display_errors/error_reporting by adding this at the beginning of index.php in the Magento root directory (REMOVE THIS AFTER TESTING):
<?php ini_set('display_errors', 1); ini_set('error_reporting', E_ALL);
- Module does not appear in backend? You are using redis as the cache backend? Try running FLUSHDB and FLUSHALL (attention on production systems) to fully flush the cache backend. We've seen this being the problem before, where "Flush Cache Storage" button didn't fully do the trick.
Still got problems? A fatal error you can't solve yourself? Please get in touch with us.
Error "Notice: Undefined index: id in Iterator.php"
If you get the following error message:
Notice: Undefined index: id in [...]/Model/Config/Structure/Element/Iterator.php on line 59
This means you forgot to install the "Xtento_XtCore" module. Install this base module first, and make sure it is enabled. It is included with the ZIP file. If you purchased the extension on Magento Marketplace, and installed the extension via Component Manager, you forgot to select "Install dependencies" when installing the extension.
Missing design / CSS in admin after setup:upgrade
This is usually due to wrong file permissions. You can deploy the static view files of Magento as described here: http://devdocs.magento.com/guides/v2.1/config-guide/cli/config-cli-subcommands-static-view.html
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 > 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
Uncaught TypeError: Argument 1 ... instance of Magento\Framework\ObjectManager\ObjectManager given
Alternate error message: "Uncaught Error: Cannot instantiate interface ..."
If you get this error with any of our extensions, please empty the var/di (Magento 2.2+: generated/metadata), var/cache and var/generation (Magento 2.2+: generated/code) folders of Magento.
If you use Redis flush it as well: redis-cli flushall
Autoload error: Module 'Xtento_XtCore' from '/some/path/app/code/Xtento/XtCore' has been already defined
That's because you installed Xtento_XtCore twice, once via composer, once via uploading it directly into app/code/Xtento. Remove the app/code/Xtento/XtCore folder.
[ReflectionException] Class Xtento\XtCore\... does not exist
This means you forgot to install the Xtento_XtCore module. You probably did not upload the files of the XtCore extension. If you cannot find the XtCore extension and you purchased this extension on Magento Marketplace, please see the "Installing a Magento Marketplace extension" section here on this page, it has a link where you can download the XtCore extension.
Composer: Could not find package for minimum stability
You either forgot to add the repository (see below) or you need to add the authentication keys to auth.json manually (see article below).
Run this in the Magento root directory to add our composer repository:
composer config repositories.xtento composer https://repo.xtento.com
The authentication keys can be found/generated at "Composer Authentication" on xtento.com.
Composer: The file could not be downloaded (HTTP/1.1 404 Not Found)
Error: The "https://repo.xtento.com/composer/download/file/..." file could not be downloaded (HTTP/1.1 404 Not Found)
Solution: Flush the composer cache using composer clear-cache
Composer update: Invalid credentials for ‘https://repo.xtento.com/packages.json’, aborting
If you're trying to run composer update or install and are getting the following error about the XTENTO repository (repo.xtento.com):
Invalid credentials for ‘https://repo.xtento.com/packages.json’, aborting
You either entered the wrong credentials (you can get them at "Composer Keys" at My Downloads on xtento.com) or something else went wrong.
To fix this, open the "auth.json" file (located either in the Magento root directory or the composer home directory, usually var/composer_home/) and update it like this (the bold part must be added, including the comma!):
{
"http-basic": {
"repo.magento.com": {
"username": "<your public key>",
"password": "<your private key>"
},
"repo.xtento.com": {
"username": "<your public key>",
"password": "<your private key>"
}
}
}
If nothing helps, copy the auth.json file from var/composer_home/ into the root directory of Magento.
Composer / Web Setup Wizard: Cannot upgrade the Magento core due to version requirements
Trying to upgrade Magento, for example to Magento 2.3 and cannot do so as composer/Web Setup Wizard complains that our extensions have dependencies that conflict with the upgrade?
Errors such as "xtento/xyz 1.2.3 requires magento/framework ^100.0||^101.0"? Or: "xtento/... requires php ~5.5.22|~5.6.0|7.0.2|7.0.4|~7.0.6|~7.1.0 -> your PHP version (7.3.xx) does not satisfy that requirement."
Step 1: Go to the Main Page of our wiki and see if we support the Magento version you are upgrading to. For example, support for Magento 2.3 was added on Dec 4th, 2018.
Step 2: If we indeed support the Magento version you are upgrading too, but composer does not offer you "our" updated versions which are compatible with for example Magento 2.3, that means your support and update period has ended.
Step 3: Go to "My Downloads" on xtento.com and renew your support and update period, you will then get access to the latest module versions (also via composer) so you have access to the module version that is compatible with, for example, Magento 2.3, and can now upgrade the Magento core.
Web Setup Wizard: Command "show" failed
If you get the following error in the Magento "Extension Manager" after installing one of our extensions via composer:
Command "show" failed: [Composer\Downloader\TransportException] The 'https://repo.xtento.com/packages.json' URL required authentication. You must be using the interactive console to authenticate show [--all] [-i|--installed] [-p|--platform] [-a|--available] [-s|--self] [-N|--name-only] [-P|--path] [-t|--tree] [-l|--latest] [-o|--outdated] [-m|--minor-only] [-D|--direct] [--strict] [-f|--format FORMAT] [--] [<package>] [<version>]
You will need to do the following:
1) Make sure auth.json (see above - Composer update: Invalid credentials for... article) is set up properly, including XTENTO authentication keys
2) Make sure auth.json has appropriate file permissions so the Magento webserver can read the file
3) If nothing helps, copy auth.json into the Magento root directory
404 error: Page not found.
If you get an error page saying "404 error: Page not found." when, for example, trying to save one of our import/export profiles or other data, this is usually caused by a firewall/webserver security rule. Check your webservers error.log, it will probably contain something like this or a similar error that means a rule must be whitelisted:
[Thu Aug 23 08:51:49 2018] [-:error] [pid 1234:tid 123456789123456789] [client 123.123.123.123:30711] [client 123.123.123.123] ModSecurity: Access denied with code 403 (phase 2). String match "on" at TX:sql_injection_score_blocking. [file "/etc/httpd/modsecurity.d/modsecurity_crs_49_inbound_blocking.conf"] [line "69"] [id "4049002"] [msg "Anomaly Score Summary (General: 0/5, Nexcess_Custom: 0/5, SQLi=16/15, XSS=5/30)"] [severity "CRITICAL"] [hostname "staging.xyz.com"] [uri "/xyz_admin/xtento_productexport/profile/save/key/bef92da72d53689f993b812fa05ca46ee5294469013073c46c14a8fabc0fd95f/back/edit/active_tab/destination/"] [unique_id "W36t5M8oRapedVe4alhlQg13245"], referer https://staging.xyz.com/xyz_admin/xtento_productexport/profile/edit/id/1/active_tab/general/key/b737227c69f92205dd363e7ae8000969f571793b22e921561d99440259227b5d/
Your server admin/webhoster will need to whitelist it.
Error: SQLSTATE[HY000]: General Error: 2006 MySQL server has gone away
You are using one of our import / export modules and got the above error? Please increase the variable "max_allowed_packet" on your MySQL Server, usually the variable can be found in the "/etc/my.cnf" file. If the settings is too low please increase it, for example max_allowed_packet=100MB. MySQL Server restart might be required.
Error: Missing required argument $name of Logger
If you get the following error:
There has been an error processing your request
Missing required argument $name of Xtento\SomeModule\Logger\Logger.
The solution is to clear the contents of the var/di and generation/ folders.
Cannot save license key / enable module
You are sure you entered the correct license key, however, when clicking "Save" in the modules configuration, the license key is gone or the module is disabled again? This could be a cache issue/bug in Magento 2. Try going to System > Cache Management, disable all caches, go back into our modules configuration, enter the license key and enable the module - it should work now. Now, enable all caches again and flush the cache storage. Modules are disabled again after enabling the cache again? There are issues with your cache in Magento - try checking folder permissions of var/cache, try clearing var/cache manually or also check if data is maybe being cached in your cache backend such as redis.
Installing an extension on Magento Cloud via composer
Using Magento cloud? Following is a short guide how to add one of our extensions to your project via composer.
- Set up an environment variable with your composer credentials. See here ("Add Magento authentication keys", replace repo.magento.com with repo.xtento.com) for more details. Attention, if you already have auth.json in your root directory, put it there, otherwise, it's much better to use an environment variable.
- On the command line, run magento-cloud project:get -p <environment> to get the projects code. For example, the staging branch.
- Cd into the source code directory shown on your screen after running the above command
- Add our repository: composer config repositories.xtento composer https://repo.xtento.com
- Require/install whatever module you need/purchased: composer require xtento/orderexport --no-update
- Run composer update to update composer.lock for just that package: composer --ignore-platform-reqs update xtento/orderexport
- Add your changes to git: git add -A
- Commit your changes: git commit -m "Added xtento/orderexport to composer.json/lock"
- Push changes to branch, rebuild project: git push magento <environment>
- Once confirmed to be working, push changes to production
Magento Cloud: Error 503 / Maintenance Page
Getting HTTP error 503 or seeing a maintenance page when using Magento Cloud? Be sure to check out the var/report/ folder of Magento for more details.
Segmentation Fault
Getting a segmentation fault running imports/exports? Be sure to check out "ulimit -s" on your server and make sure it's set to a high enough value (for example to 65535). Also, take a look at the php.ini setting "pcre.recursion_limit" which shouldn't be set to a too high value. If nothing helps, debug the issue using "strace" and "gdb".
Exception #0 (OutOfRangeException): Specified invalid parent id (Xtento_XtCore::extensions)
You probably forgot to install & enable our base module, the Xtento_XtCore module. See above for installation instructions.
Type Error occurred when creating object ...
You probably updated one of our modules and forgot to clear all caches. Especially make sure to clear the contents of the generated/code/* folder.
Uncaught TypeError: Argument ...
You probably updated one of our modules and forgot to clear all caches. Especially make sure to clear the contents of the generated/code/* folder.
Warning: Unsupported declare 'strict_types'
You are running an outdated PHP version of the "php"-binary on your server is linked to an older PHP version. Make sure to execute bin/magento or composer or whatever using the correct PHP version for your system, for example, php7.2
The following modules are outdated: ...
Error: "Please update your modules: Run "composer install" from the Magento root directory... The following modules are outdated: ..."
Reason: You forgot to run the bin/magento setup:upgrade command after installing or updating an extension.