Magento is one of the most complete e-commerce platforms on the open source market. With a default Magento installation, all the common e-commerce features, such as catalog navigation, promotion rules, tax settings, online payments, and so on are available.
The first version of Magento was released in 2008 after one year of development. Magento was initially designed as an e-commerce system that could be used for a wide range of uses. In later years, Magento became very popular as an out-of-the-box e-commerce system and a lot of minor versions of the 1.x series have been released in the last few years.
To be future proof, Magento started the development of a major upgrade of the system, also known as Magento 2. Magento 2 is a big improvement on every part of Magento. Every aspect is analyzed and rewritten with up-to-date technologies to be ready for the future. Everything, including the developer experience, maintainability, performance, and technologies will be improved.
In this chapter, we will upgrade the data of a Magento 1 installation to a Magento 2 installation. We will also prepare some tools that we can use in the following chapters of this book.
To install a Magento 1 website, we need the following stuff:
A web server (Linux, Apache2, PHP, or MySQL)
The Magento 1.9 codebase
The Magento 1.9 sample data
The Magento 1.9 codebase and sample data can be downloaded from the Magento site at http://www.magentocommerce.com/download.
The following stuff is recommended for the installation:
A virtual host (domain name) that is going to be your web root
api.php app cron.php cron.sh downloader errors favicon.ico get.php includes index.php index.php.sample install.php js lib LICENSE_AFL.txt LICENSE.html LICENSE.txt mage media php.ini.sample pkginfo RELEASE_NOTES.txt shell skin var
Extract the sample data archive to a different folder from the webroot. Copy the contents of the
skinfolders to the
skinfolders in your webroot. We can do this by using the following
cp –R <path_to_sampledata_folder>/media/* <path_to_magento_folder>/media/ cp –R <path_to_sampledata_folder/skin/* <path_to_magento_folder>/skin/
Create a database for the Magento 1 installation and name it
magento1. We can do this by running the following commands:
mysql -u <username> -p create database magento1; exit;
mysql -u <username> -p magento1< "path_to_sample_data.sql"
To avoid permission problems, ensure that all files and folders have the right permissions. For security reasons, it is recommended that all files have just enough permissions so that only the right users can access the right files. When you give all the rights (777), you don't have permission problems because each user can read, write and, execute each file of your application. More information about file permissions can be found at http://devdocs.magento.com/guides/m1x/install/installer-privileges_after.html.
When the files are in the right place and the database is imported, we can run the Magento installer. Open your browser and go to the domain that is configured for your website. You should see the installer as in the following screenshot:
Continue with the installation process by accepting the terms and conditions.
On the next screen, choose the correct language, locale, and currency for your store.
Database Type: MySQL.
Host: Enter the hostname or IP address of your database server (
localhostif it is on the same machine).
Database name: Enter
magento1in this field (or another name if you have a different name for your database).
User name: Enter your database username.
User password: Enter your database password.
Tables prefix: Leave this field empty (the string in this field will be used to prefix all tables of your database).
Base URL: Enter the URL of your website in this field.
Admin path: Enter
adminin this field. This will be the path of the backend.
Enable charts: For development, it is recommended that this be unchecked.
Skip Base URL Validation Before the Next Step: When checked, the wizard will check for a valid URL when processing this form.
Use Web Server (Apache) rewrites: Check this when the apache module
Use Secure URL's (SSL): This checkbox must be unchecked if you don't use HTTPS.
Submit this form and we will be forwarded to the next step. In this step, you can configure the administrator account. Fill in the right data and remember the username and password because this is required to manage the store. Leave the encryption key field empty.
After submitting this form, the installation is complete. Optionally, you can submit the Magento survey. At the bottom of the page, there are buttons to navigate to the frontend and backend. When going to the frontend, you can see a demo shop with sample data as in the following screenshot:
The layout is responsive. When scaling your browser to a smaller width, the website will switch to the mobile layout like in the following screenshot:
We have just created a fully functional Magento 1 store. The webshop is fully configured and filled with data about products, customers, and orders, just the data we need to migrate to Magento 2 (in the upcoming recipes).
When installing a new shop, you have to follow the installer. This interface creates a configuration file
app/etc/local.xml. If the file doesn't exist, Magento will launch the installer wizard. If the file is there, Magento will run the shop.
With a valid
local.xml file, it is technically possible to install a new Magento shop, but this is not recommended because some settings such as a backend user, time zone, and currency are not set. These are actions that you have to do manually when choosing for this method.
In the previous recipe, we created a Magento 1 website with sample data that we will use for an upgrade. In this recipe, we will do the same, but we will create a Magento 2 website with the sample data for Magento 2.
To install Magento 2, we need the newest tools to run that application. Make sure your webserver has the following stuff installed:
PHP 5.5 or higher
MySQL 5.6 or higher
Apache 2.2 or higher
Command line access
We can install Magento 2 in different ways. In this recipe, we will install Magento 2 using Composer. The advantage of this is that we can use GIT to add version control to our custom development.
We will install Magento 2 with Composer. For this, we need authentication keys. With an account on the magento.com site, go to Developers | Secure keys in the My Account section. On this page, you can generate public and private keys that will be your username and password in the next step.
To install Magento 2 with composer, we have to run the following command:
composer create-project --repository-url=https://repo.magento.com magento/project-community-edition <installation_dir>
You will be prompted for a username and password. The username is the public key and the password is the private key that we generated in the previous step. When the command has run, the installation directory will have the following structure:
app bin CHANGELOG.md composer.json composer.lock CONTRIBUTING.md CONTRIBUTOR_LICENSE_AGREEMENT.html COPYING.txt dev .gitignore Gruntfile.js .htaccess .htaccess.sample index.php lib LICENSE_AFL.txt LICENSE.txt nginx.conf.sample package.json .php_cs php.ini.sample pub README.md setup .travis.yml update var vendor
We have installed the codebase with composer. Now we can run the installation wizard. Open your browser and enter the URL of your site. You should see the following welcome screen:
Hit the Agree and Setup Magento button and start the environment check.
Database Server Host: The hostname or IP address of the database server
Database Server Username: The username of the database account
Database Server Password: The password for the account
Database Name: The name of the database
Table Prefix: Optionally, you can give a prefix for each table
Go to the next step and check if the right information is filled for the URL part. In the advanced section, you can optionally configure HTTPS, apache rewrites, and your encryption key. For our test environment, we can leave these settings as they are configured.
In the next step, you can configure your time zone, currency, and default language.
In the last step, you can configure your administration account. After clicking on the Next button, you are ready to install. Click on the Install Now button and the installer will start. This will take some time because the installer will add the sample data during the installation. You can open the Console Log to see what is currently happening.
Run the following commands in your Magento installation directory to configure the sample data:
php bin/magento sampledata:deploy composer update php bin/magento setup:upgrade
The preceding commands will download and install the sample data packages. Because they contain a lot of images, this could take some time. The
setup:upgradecommand will install the sample data, and this also takes some time.
The installation of the webshop is now complete. You now have an up-and-running Magento 2 webshop. When you navigate to the category Gear | Bags, you should see something like in the following screenshot:
We have now installed a Magento 2 website. Like we did in the previous recipe for Magento 1.9, we downloaded the codebase (using composer), created a database, and installed Magento.
For Magento 2, we used composer to download the codebase. Composer is a PHP dependency manager. All the dependencies are set in the
composer.json file. For this recipe, there are the
Magento and the
magento-sample-data dependencies in the
composer.json file. There is also a
composer.lock file generated. In that file, the versions of the installed dependencies are stored.
When working with GIT, we only have to commit the
.gitignore files for a working Magento 2 project. When another person does a Git clone of the repository and runs the composer's
install command, Magento 2 will be installed with the version that is in the
The sample data for Magento 2 is now a script that will be executed after the installation of Magento. That script will add products, customers, orders, CMS data, and more configurations to populate the shop.
The shop is installed and the configuration settings (database, encryption key, and so on) are now stored in
app/etc/env.php instead of in the
app/etc/local.xml file in Magento 1.
When installing Magento 2, here are some common issues that can occur and their fixes:
When you don't see CSS in your browser, you have to check the following things:
Make sure the
pub/folder is writable
Run the command
php bin/magento setup:static-content:deployto generate the static content
You forget to install the sample data:
You can install the sample data after the installation of Magento with the command
php bin/magento sampledata:deploy
The installation is not responding anymore:
This could be caused by an Apache timeout. If this occurs, you can maybe try the command-line installation. This works as follows:
To run the Magento installer from the command line, we can use the command
php bin/magento setup:install. We have to add the following required parameters to the command to configure the installation:
base-url: The base URL, for example http://magento2.local/
db-host: The database host or IP address
db-user: The database username
db-name: The database name
db-password: The database password
admin-firstname: The first name of the administrator user
admin-lastname: The last name of the admin user
admin-email: The e-mail address of the admin user
admin-user: The username (login name) of the admin user
admin-password: The password for the admin user
language: The language of the shop
currency: The currency code of the shop
timezone: The time zone of the shop
use-rewrites: Whether to use the apache rewrites or not
use-sample-data: Install the sample data (optional)
php bin/magento setup:install --base-url=http://magento2.local/ --db-host=localhost --db-user=magento2 --db-name=magento2 --db-password=yourpassword --admin-firstname=John --admin-lastname=Doe --email@example.com --admin-user=admin --language=en_US --currency=USD --timezone=UTC --use-rewrites=1
The differences between Magento 1 and Magento 2 are huge. The code has a whole new structure with a lot of improvements but there is one big disadvantage. What do I do if I want to upgrade my Magento 1 shop to a Magento 2 shop?
Magento created an upgrade tool that migrates the data from a Magento 1 database to the right structure for a Magento 2 database.
The custom modules in your Magento 1 shop will not work in Magento 2. It is possible that some of your modules will have a Magento 2 version, and depending on the module, the module author will have a migration tool to migrate the data that is in the module.
In your Magento 2 version (with the same version as the migration tool), run the following commands:
composer config repositories.data-migration-tool git https://github.com/magento/data-migration-tool-ce composer require magento/data-migration-tool:2.0.0
Install Magento 2 with an empty database by running the installer. Make sure you configure it with the right time zone and currencies.
php bin/magento migrate:data --help
The next thing is creating the configuration files. Examples of the configuration files are in
vendor/magento/data-migration-tool/etc/<version>. We can create a copy of this folder where we can set our custom configuration values. For a Magento 1.9 installation, we have to run the following
cp –R vendor/magento/data-migration-tool/etc/ce-to-ce/18.104.22.168/ vendor/magento/data-migration-tool/etc/ce-to-ce/packt-migration
vendor/magento/data-migration-tool/etc/ce-to-ce/packt-migration/config.xml.distfile and search for the
destination/databasetags. Change the values of these database settings to your database settings like in the following code:
<source> <database host="localhost" name="magento1" user="root"/> </source> <destination> <database host="localhost" name="magento2_migration" user="root"/> </destination>
Rename that file to
config.xmlwith the following command:
mv vendor/magento/data-migration-tool/etc/ce-to-ce/packt-migration/config.xml.dist vendor/magento/data-migration-tool/etc/ce-to-ce/packt-migration/config.xml
By adding a composer dependency, we installed the data migration tool for Magento 2 in the codebase. This migration tool is a Magento console command that will handle the migration steps from a Magento 1 shop.
If you want to migrate an existing Magento 1 shop, you have to customize these configuration files so it matches your preferred state.
In the next recipe, we will learn how we can use the script to start the migration.
You need a Magento 1 website and a Magento 2 website. The Magento 2 website needs to have the database migration tool installed and configured as described in the previous recipe.
In this recipe, we will do a migration from a clean Magento 1 site, to a Magento 2 site without sample data.
We did a migration from a clean Magento 1 database with some test products. Make sure you have a cleanly installed Magento 1 shop with some test data (products, orders, and so on) in it.
First we need to make sure that the database settings are correct in the
vendor/magento/data-migration-tool/etc/ce-to-ce/packt-migration/config.xmlfile. Open that file and check that the database credentials are correct. We created this file in the previous recipe:
<source version="1.9.1"> <database host="localhost" name="magento1_migration" user="root"/> </source> <destination version="22.214.171.124"> <database host="localhost" name="magento2_migration" user="root"/> </destination>
If you have a database prefix in your source or destination database, you can optionally configure
<options>section of the same configuration file.
php bin/magento migrate:data --help
This gives us the following output:
To start or test a migration, we have to run the following command:
php bin/magento migrate:data vendor/magento/data-migration-tool/etc/ce-to-ce/packt-migration/config.xml
The migration will start and will give the following output:
We can also migrate the settings from the Magento 1 website. To do this, you have to replace the
dataparameter in the command using
To check if the upgrade works, you have to look at the data of the Magento 2 installation. We can check the following things in the backend:
The orders (Sales | Orders)
The products (Products | Catalog)
The customers (Customers | All Customers)
You can also check in the database if you look at the following tables:
When the migration tool starts, it starts checking all the configurations that are in the configuration files of the migration tool. If there are more things available in the Magento 1 database than the things that are configured, the migration tool will give a notification and stop the migration.
It's likely that every existing Magento 1 shop works with custom attributes, custom entities, and so on. Each entity, attribute, and so on needs to be declared in the configuration files.
The most time-consuming part of a migration is to create a good configuration file so that the migration tool won't fail on missing stuff. It is on you to decide what to ignore and what to migrate. If the configuration files are valid, the migration will start and the data will come into the Magento 2 database. The same principle applies when migrating the settings, but you have to think about whether you want it.
In this recipe, we did a migration of a clean Magento 1 installation to a clean Magento 2 installation. However almost every running Magento 1 shop is not clean. It contains custom attributes, custom modules, and a custom configuration.
When migrating such a shop to a new shop, the migration is a bit more complex. The first question is: What needs to be migrated? With the tool, you can migrate every entity, from products, customers, and orders to reviews, settings, and more.
If you want to skip data that must be migrated, you can use the
map.xml file. If you open the file
vendor/magento/data-migration-tool/etc/ce-to-ce/packt-migration/map.xml, you see that a lot of entities are ignored in the
If you want to change something in the
map.xml file, you have to make sure that the right
map.xml file is loaded. This file is configured in the
config.xml file (where you did your database configuration). In that file, you have to look for the XML tag
If you have an error such as Source documents not mapped, you have to add the configuration for these entities in the
map/source/document_rules tag of the
map.xml file. If the error is something like Destination documents not mapped, you have to add configuration in the
map/destination/document tag of the
To solve errors such as Source fields not mapped you have to add configuration in the
Migrating configuration files is the most time consuming part of a data migration. If you want more information on the migration tool, you can have a look at the Magento Migration Whitepaper, available at http://magento.com/resources/magento-2-migration-whitepaper.
Writing good code starts with a good development environment. An Integrated Development Environment (IDE) is the main part of a good development environment. NetBeans is a free and open source PHP editor that can be used for Magento development. In this recipe, we will set up a Magento 2 project in NetBeans.
For PHP development, you need to download the
HTML5 & PHP bundle.
To create a new project, open NetBeans and navigate to File | New Project.
A window like the one in the following screenshot will appear on your screen. Click on PHP and PHP Application with Existing Sources.
Source Folder: This field is set to the location of your Magento code (like
Project Name: The NetBeans project name is entered in this field
PHP Version: This field is set to PHP 5.5
Default Encoding: This field is set to UTF-8
In the next screenshot, you can see how everything is configured:
When you are working with a version control system like GIT, it is recommended that you check the checkbox. Put NetBeans metadata into a separate directory. If not checked, a
.nbprojectfolder is created in your Magento root, and you don't want to have that folder in your version control system. Another possibility is to add the
.nbprojectfolder in the
Run as: If you are developing on a local PC, choose Local Web Server
Project URL: The URL of your website
Index file: Set this to
The settings are shown in the following screenshot:
Maintaining clean code is much more efficient than maintaining spaghetti code, but writing clean code is not as easy as it sounds. These days there are some tools that help you with writing clean code, such as PHPMD and PHP_CodeSniffer.
PHPMD stands for PHP Mess Detector; this tool will check your code on complexity and how variables are used and will detect some possible bugs. It goes a bit further than the syntax check in your IDE.
PHP_CodeSniffer or PHPCS checks your code on coding standards such as PSR-1 and PSR-2.
Before installing PHPMD and PHP_CodeSniffer, we have to make sure that PHP is installed on our development machine. Especially if you are developing on a remote server, it could be that PHP is not installed.
Download and install PHPMD. Depending on your OS, the protocol could be different. You can find instructions at:
Everything is installed, so we can run a test for PHPMD. For the PHPMD command, these are the required options:
Filename or directory
The format of the report
Let's run the following command to check the file on clean code and output text:
phpmd app/code/Magento/Cms/Model/Observer.php text cleancode
It gives us the following output:
/var/www/magento2/app/code/Magento/Cms/Model/Observer.php:70 Avoid using static access to class '\Magento\Cms\Helper\Page' in method 'noCookies' /var/www/magento2/app/code/Magento/Cms/Model/Observer.php:71 Avoid using static access to class '\Magento\Store\Model\ScopeInterface' in method 'noCookies'. /var/www/magento2/app/code/Magento/Cms/Model/Observer.php:77 The method noCookies uses an else expression. Else is never necessary and you can simplify the code to work without else.
There are a lot of errors, but Magento 2 defines its own rules for PHPMD. To run a test with these rules, we can run the following command:
phpmd app/code/Magento/Cms/Model/Observer.php text dev/tests/static/testsuite/Magento/Test/Php/_files/phpmd/ruleset.xml
We will now run a test on the same file with PHP_CodeSniffer. With the next command, we will run a test on the same file we used for PHPMD.
This test gives us the following output:
FILE: /var/www/magento2/app/code/Magento/Cms/Model/Observer.php ---------------------------------------------------------------------- FOUND 22 ERRORS AND 2 WARNINGS AFFECTING 12 LINES ---------------------------------------------------------------------- 5 | WARNING | [ ] PHP version not specified 5 | ERROR | [ ] Missing @category tag in file comment 5 | ERROR | [ ] Missing @package tag in file comment 5 | ERROR | [ ] Missing @author tag in file comment 5 | ERROR | [ ] Missing @license tag in file comment 5 | ERROR | [ ] Missing @link tag in file comment 10 | ERROR | [ ] Missing @category tag in class comment 10 | ERROR | [ ] Missing @package tag in class comment 10 | ERROR | [ ] Missing @author tag in class comment 10 | ERROR | [ ] Missing @license tag in class comment 10 | ERROR | [ ] Missing @link tag in class comment 18 | ERROR | [ ] Protected member variable "_cmsPage" must not be | | prefixed with an underscore 25 | ERROR | [ ] Protected member variable "_scopeConfig" must not | | be prefixed with an underscore 27 | ERROR | [ ] Missing short description in doc comment 28 | ERROR | [ ] Missing parameter comment 28 | ERROR | [x] Expected 27 spaces after parameter type; 1 found 29 | ERROR | [ ] Missing parameter comment 42 | ERROR | [ ] Missing parameter comment 42 | ERROR | [x] Tag value indented incorrectly; expected 2 spaces | | but found 1 43 | ERROR | [ ] Tag cannot be grouped with parameter tags in a | | doc comment 62 | ERROR | [ ] Missing parameter comment 62 | ERROR | [x] Tag value indented incorrectly; expected 2 spaces | | but found 1 63 | ERROR | [ ] Tag cannot be grouped with parameter tags in a | | doc comment 78 | WARNING | [ ] Line exceeds 85 characters; contains 94 | | characters ---------------------------------------------------------------------- PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY ---------------------------------------------------------------------- Time: 28ms; Memory: 3.75Mb
When we specify the ruleset of Magento 2, we have the following command:
phpcs app/code/Magento/Cms/Model/Observer.php --standard=dev/tests/static/testsuite/Magento/Test/Php/_files/phpcs/ruleset.xml
This command gives us the following output:
FILE: /var/www/magento2/app/code/Magento/Cms/Model/Observer.php ---------------------------------------------------------------------- FOUND 5 ERRORS AFFECTING 5 LINES ---------------------------------------------------------------------- 18 | ERROR | Missing variable doc comment 25 | ERROR | Missing variable doc comment 31 | ERROR | Missing function doc comment 45 | ERROR | Missing function doc comment 65 | ERROR | Missing function doc comment ---------------------------------------------------------------------- Time: 35ms; Memory: 3.75Mb
When developing custom code in Magento 2, it is recommended that you configure these rulesets when working with PHPMD and PHP_CodeSniffer.
Some IDE's have built-in support for PHPMD and PHP_CodeSniffer. These plugins will run a test when saving a file.
In PHPStorm, there is built-in support for PHPMD and PHP_CodeSniffer. If it is configured, there is a color indicator that says how clean your code is. More information can be found at https://www.jetbrains.com/phpstorm/help/using-php-mess-detector.html.