Skip to content
Magento 2 Local Development Environment
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Magento 2 Local Development Environment

1. Overview

The purpose of this repo is to provide Magento 2 extensions developers an easy to setup local environment.

The setup was created using Docker, on top of the following images repository: (please check this repo for more info about technology stack, assumptions, etc.).

The setup was created on Ubuntu 18.04 and is tested on this OS, however the plan is to make it OS-agnostic.

In current state the setup includes three Magento versions: 2.1.17, 2.2.8 and 2.3.2. They are all installed with sample data.

Disclaimer: In many places of this README file the following strings are used as placeholders for version numbers:

  • For Magento: <MAGE_VER>. Please replace it with 21 for Magento 2.1.17, 22 for Magento 2.2.8 or 23 for Magento 2.3.2.
  • For PHP-CLI: <PHP_VER>. Please replace it with 71 for PHP 7.1 or 72 for PHP 7.2.

2. Prerequisites

In order to setup this environment you need Docker and Docker Compose installed on your machine.

3. Installation

  1. Clone this repository.
  2. Copy .env.sample file to src/mage<MAGE_VER>/.env.
  3. Customize .env files if you need.
  4. CD to src/mage<MAGE_VER> and run docker-compose up.
  5. Add magento2.local to your local hosts file (on Ubuntu: /etc/hosts).
  6. Your Magento frontend will be accessible by the following URL: https://magento2.local:80<MAGE_VER>.
  7. Your Magento backend will be accessible by the following URL: https://magento2.local:80<MAGE_VER>/admin. Admin credentials can be found in .env file.

4. Additional setup

4.1. SSL certificates

Import docker/app/files/magento2root.pem root certificate to your browsers so they don't complain about self-signed certificates.

If you need to access Magento URLs not only from your browsers (eg. CURL), import the root certificate to your OS.

4.2. PHPStorm

4.2.1. Docker

  1. Open Settings.
  2. Go to "Build, Execution, Deployment" > "Docker".
  3. Add new Docker server with default config.

PHPStorm Docker

4.2.2. PHP

  1. Open Settings.
  2. Go to "Languages & Frameworks" > "PHP".
  3. Set "PHP language level" to the version you will be using.
  4. Create new remote PHP interpreter using Docker:
    • Use Docker server created in 4.2.1
    • Use magento2env_phpcli<PHP_VER>:latest Docker image
    • Set "Debugger extension":
      • for PHP 7.1: /usr/local/lib/php/extensions/no-debug-non-zts-20160303/
      • for PHP 7.2: /usr/local/lib/php/extensions/no-debug-non-zts-20170718/


PHPStorm PHP Interpreter

4.2.3. PHP Server

  1. Open Settings.
  2. Go to "Languages & Frameworks" > "PHP" > "Servers".
  3. Add new server:
    • Name it mage<MAGE_VER>
    • Put magento2.local as a host
    • Put 80<MAGE_VER> as a port
    • Put Xdebug as a debugger
    • Set path mapping:
      • src/mage<MAGE_VER> > /var/www/html
      • src/modules > /var/www/modules

PHPStorm PHP Server

4.2.4. Xdebug

No configuration needed for debugging browser requests. See:

4.2.5. PHPUnit

  1. Open Settings.
  2. Go to "Languages & Frameworks" > "PHP" > "Test Frameworks".
  3. Add new config:
    • Use CLI interpreter created in 4.2.2
    • Use Composer autoloader with following path to script: /opt/project/src/mage<MAGE_VER>/vendor/autoload.php
    • Set Default configuration file to /opt/project/src/mage<MAGE_VER>/dev/tests/unit/phpunit.xml.dist

PHPStorm PHPUnit

4.2.6. E-mail communication

No configuration needed. All e-mails sent by Magento are caught by MailHog. Simply open in your browser to check them.

5. Common routines

5.1. Run already installed Magento

cd src/mage<MAGE_VER>
docker-compose up

5.2. Go inside container (SSH like)

First find mage<MAGE_VER> container name by running docker ps. Then run docker exec -it <container name> /bin/bash, example: docker exec -it magento2env_mage22_1_fcb38b06f0c6 /bin/bash.

When you're inside, you act as docker user and you can perform any console command (also with sudo), eg. bin/magento.

5.3. Set up your Magento extension to be developed locally

  1. GIT clone your extension to src/modules/<VENDOR>/<Extension>, eg. src/modules/Orba/Payupl.
  2. Add your extension as a dependency to Composer, using src/mage<MAGE_VER>/composer.json file. Set the same version as in extension's composer.json file. Example:
        "require": {
            "orba/magento2-payupl": "2.0.0-dev"
  3. Go inside container (see: 5.2).
  4. Run composer update.
  5. Run bin/magento setup:upgrade inside container.
  6. If your extension uses template files, you need to set config value "Advanced > Developer > Template Settings > Allow Symlinks" to "Yes".

Disclaimer: composer.json file is created automatically from a template during first docker-compose up run.

Watchout: This setup requires that your extension's registration.php looks like this:

    isset($file) ? dirname($file) : __DIR__

This is a workaround for symbolic links issue.

5.4. Xdebug console script

  1. Enable Listening for PHP Debug Connections (green icon in toolbar)
  2. Go inside container (see: 5.2).
  3. Run export XDEBUG_CONFIG="idekey=123" (this is needed only once per session).
  4. Run your PHP script with the following param: -dxdebug.remote_enable=1, eg. php -dxdebug.remote_enable=1 bin/magento.

6. Contribution

Please don't hesitate to create an issue if you found any bug.

Also, please suggest your enhancements either via an issue or a pull request.

You can’t perform that action at this time.