Blogfactory428

This guide will explain how to configure PhpStorm to use PHP’s Xdebug extension through Vagrant. The process is not as straightforward as it should be, and available documentation has not been clear on this usage. It will be significantly easier when PhpStorm 8 is released, due to its ability to define remote interpreters. When that is available, a new post will be written, with a link to it from this one.

Virtualbox provides virtual 'hardware' that an OS can use, and a network that allows the OS to talk to the outside world. My config is: Virtualbox V6, i connect in SSH via PUTTY and i develop with PHPStorm. So i spent 6 hours testing / debugging, network interfaces, reinstall git, create a new VM, test with Vmware, create new repository. So I just spent the day setting up PHPStorm for the purpose of component development. Although it was a bit of work, now that I've finished the setup my life is going to be SOOOO much easier. I don't have a tutorial to point you to, but here is the step-by-step for setting up PHPStorm with Git, VirtualBox, Vagrant, and Joomlatools/box.

Update Feb. 22, 2015: PhpStorm 8 was released late 2014. As indicated in the original publication, the steps to take advantage of remote interpreters will be delineated. The process only varies slightly from the original, so the steps will be included below—instead of in a new article—with a clear distinction between the original steps, which still work very well, and the new ones. Jump to the revision.

Note that as of PhpStorm 8 some of the preferences have been structured and named differently. For example, many parts of this guide mention a “Project Settings [project-name]” heading to find the “PHP” subheading; this no longer exists in PhpStorm 8. That location has been moved to “Languages & Frameworks,” and then “PHP.”

Who will benefit from reading this guide?

Anyone who has been frustrated and ultimately defeated by attempts to run a successful debugging session through Vagrant will benefit from reading this guide. It will not explain how to install Vagrant, Xdebug, or any other tool referenced. It is also assumed that the application to debug will be accessed through a browser.

How do Xdebug and PhpStorm communicate through Vagrant?

There are two communication points to be aware of when developing in Vagrant. The first (1) is the host: the host is the main operating system (OS) that Vagrant was installed on. The second (2) is the guest: the guest is the virtual OS installed by Vagrant.

Generally, the Internet works on a client-server model. Connections between Xdebug and PhpStorm are no exception. For this use case, Xdebug is the client, and PhpStorm is the server ^[1]. This means that Xdebug will connect to Phpstorm whenever the PHP application is accessed, for example, through a browser. However, in order for the client on the guest (Xdebug) to connect to the server on the host (PhpStorm), it must know where to send its request.

Vagrant acts as an intermediary between these two communication points.

A connection to PhpStorm can be established if Xdebug knows the IP address (IP) of the host, where PhpStorm resides. The IP of the host is usually known to the guest, so if Vagrant is configured mostly with defaults, the IP will be something like 10.0.2.2. Upon running vagrant ssh and authenticating into the guest OS, the date of the last login and the IP are displayed. The IP can also be discovered by running netstat -r from within the guest ^[2]; look at the Gateway value. This IP is required for the Xdebug configuration file.

Configuring the guest installation of Xdebug, and what the settings do

The location of the Xdebug configuration file depends on the guest OS. On CentOS, it is usually located at /etc/php.d/xdebug.ini if installed through PECL. Configuration settings can also be written directly in PHP’s /etc/php.ini file. However, the server may fail to start if there are duplicate entries, so be sure only one location houses them.

The Xdebug configuration settings

The configuration should, at minimum, include the settings just below. It is also important to make sure the Xdebug extension is enabled in PHP. The line for enabling it can be included directly above the configuration settings, and will look something like this: zend_extension=/usr/lib64/php/modules/xdebug.so. The path may be different, so verify where the extension is located.

The meaning and purpose of these Xdebug configuration settings

xdebug.idekey type: string

The value can be any valid string. This is the string that will notify the browser, and thus Xdebug, that a debugging session should begin. The browser is notified by either having a cookie set (PHP COOKIE), an argument passed as a string in the URL (PHP GET), or an argument posted to the application (PHP POST); the key name is always XDEBUG_SESSION, and for this guide the IDE key (idekey) value is debugit. When a debug session is triggered, that idekey is read by Xdebug, which is listening to all incoming requests to the server hosting the application, and if it is valid, that in turn will cause Xdebug to send a request to the host server, being PhpStorm.

xdebug.remote_host type: string, default: localhost

This setting can trump people first trying to run a debug session through Vagrant. Prior to Vagrant and other virtual development environments, a default of localhost would be sufficient: the IDE, the Web server, PHP, and Xdebug, would all be running on the same machine, in the same OS. That would mean that the localhost for each tool would be the same. Vagrant changes that. The localhost for the guest OS is different from the localhost for the host OS. Their resources are virtually divorced, to put it one way. To establish that connection again, the IP of the host must be set as the value. This guide has determined that the likely IP of the host is 10.0.2.2, but be sure to verify this using the techniques described earlier.

xdebug.remote_port type: integer, default: 9000

This is the port that the server on the host OS—meaning PhpStorm—will listen to for incoming connections from Xdebug. It should be noted that the default is port 9000, but the guide uses 10000. If development takes place exclusively within the virtual machine, then it is okay to maintain that default. However, if there was no virtual layer, that port would conflict with another popular tool also listening on that port, namely, PHP-FPM, which would eliminate the likelihood of having a successful debug session.

In a typical LAMP stack setup, Apache takes care of running PHP using the mod_php extension. In more advanced setups, Apache and PHP run as separate daemons; one such setup involves a tool called PHP-FPM, which takes care of parsing and running all PHP scripts, and it listens to requests sent to it from Apache on port 9000. If the environment is hosted using Nginx, in a setup referred to as a LEMP stack, this is almost exclusively the default. This would mean that if Vagrant was not being used, the PHP-FPM daemon and PhpStorm—both running in the same OS—would each listen for connections on port 9000, resulting in a conflict.

Fortunately, Vagrant introduces that virtual divorce of resources, so it is okay to use the default remote port of 9000 for Xdebug. Though, for reasons of clarity, and if by chance the host OS has the lingering vestige of a forgotten or neglected development environment, this guide uses port 10000.

xdebug.remote_enable type: boolean, default: 0

Xdebug has a number of uses. Stepping through code in an IDE like PhpStorm is just one. This is why the default is 0; there is no need in sending off unnecessary requests, especially when nothing is waiting for them on the receiving end. Knowing this, and understanding the very purpose of this guide, the setting must be 1. Debugging in PhpStorm would be impossible otherwise.

xdebug.remote_autostart type: boolean, default: 0

Keeping the default of 0 permits finer control over when and how a debug session should be started. Setting this to 1 means Xdebug will attempt to connect with PhpStorm on every request. This is unnecessary. There are excellent browser tools available to start a debuggin session on demand.

xdebug.remote_handler type: string, default: dbgp

This setting can be excluded, but for backwards-compatibility and verboseness, it is probably best to include it. Following the release of Xdebug 2.1, dbgp is the only option. Moving forward, it is okay to ignore defining the setting, but should the version of Xdebug be unknown or old, this setting should be defined as dbgp. An explanation of the DBGp protocol is available as part of Xdebug’s documentation.

A complete list of the Xdebug configuration settings are available on the Xdebug Web site. It is beneficial to skim through the settings to become more familiar with the tool. Further settings could also be added to the configuration provided just above. A good addition would be to define xdebug.remote_log.

Configuring PhpStorm to accept connections from Xdebug, and setting up the local-to-remote file path mappings

PhpStorm requires a fairly involved setup process to listen for connections from Xdebug, and map the file paths between the remote / virtual filesystem in the guest OS and the local / internal filesystem of the host OS. In fact, this alone has probably been the reason for some developers abandoning Vagrant altogether. The process is not straightforward, and the available documentation fails to cohere the necessary steps. This is where the rest of guide diverges from most guides on configuring Xdebug—and consequently where closest attention is due.

Configure the PHP Debug settings

This step is not complicated. It must be made sure that the Xdebug port defined in PhpStorm matches the one defined in the guest OS’ Xdebug configuration, and that the ports match. The steps for this are delineated below, followed by a screenshot of the UI where these steps take place.

1. Open PhpStorm’s preferences and find the “Project Settings [project-name]” heading.

2. Expand the “PHP” setting and click on “Debug.” On the right are options pertaining to this setting. The relevant section is entitled “Xdebug.” The other ones will be ignored.

3. Ensure that the “Debug port” is 10000, as already discussed in this guide.

4. Ensure that the checkbox with the text, “Can accept external connections,” is checked. The other two checkbox options are checked by default. They are good defaults, so it is good to keep them as they are.

5. Save the changes.

The screenshot lists two additional suboptions, namely, “Skipped Paths,” and “DBGp Proxy.” They can be ignored. The latter may seem like it could be needed, as it provides an “IDE key,” “Host,” and “Port” option as well—and in all likeliness appears to correspond with settings already configured—but it is not. This is for setting up a proxy on a remote server that will accept simultaneous connections from multiple developers. In order to do that, a script is installed on the remote server that listens for these connections, and delegates each debug session based on the incoming IDE key.

Add a remote server to the current project’s settings (and optionally define a remote interpreter in version 8)

In order for PhpStorm to make sense of what Vagrant is, and how connections between it and Xdebug are established, it needs to be told. In PhpStorm’s case, Vagrant should be regarded just like any other remote server. It would not matter if the server was across the globe, or operating in a virtual machine on the same computer. Vagrant is a remote server. That means it needs to be defined as such for PhpStorm to allow communications with it. The steps for this are delineated below, followed by a screenshot of the UI where these steps take place.

1. Open PhpStorm’s preferences and find the “Project Settings [project-name]” heading.

2. Expand the “PHP” setting and click on “Servers.” On the right are options pertaining to this setting.

3. Add a new server by clicking on the “+” symbol.

   Update: As of PhpStorm 8, a remote PHP interpreter can be defined. This makes the next step (4) different depending on the version of PhpStorm in use. While the original step continues to work perfectly fine with version 8, this guide will also provide the step for taking advantage of PhpStorm 8’s remote interpreters feature. The main benefit of defining a remote interpreter is that PhpStorm will not need to have paths manually mapped, which can become very cumbersome when dealing with large projects, or when PHP hits code outside of the main project.

4. Provide the server a “Name” (this is just for easy reference, so call it anything), the actual “Host” address (this will be localhost, 127.0.0.1, or any other valid host name defined in the host OS’ hosts file), the “Port” of the Web server (most likely 80, or 8080, or wherever else the guest OS’ port has been forwarded to on the host), a “Debugger” of Xdebug.

5. PhpStorm version 7.x and below: If PhpStorm 8 and above is installed, skip this step and continue reading from step 6 below. Finally—one of the most important steps in this guide—check the checkbox that states “Use path mappings (select if the server is remote or symlinks are used).” Due to Vagrant’s status as a remote server, there is no possible way for PhpStorm to actually know where files on the remote server (in the guest OS) are located in that filesystem. All that is available is an exact duplicate of the files on the local / host OS filesystem. This is why setting up file path mappings are essential to debugging through Vagrant.

   • Just below the checkbox option, in the left column, entitled, “File/Directory,” there is a list of all the files in the current project. These are the local files. Select the project to debug. Now, in the right column, entitled, “Absolute path on the server,” provide the corresponding path to the location of that directory in the guest OS; this is typically located in /vagrant/path/to/project-name. That path, to make an example, assumes the path on the host OS is something like /var/www/project-name. Note that the actual project name directory in the guest OS filesystem should exactly correspond with the project name directory in the host OS filesystem. Their contents should be an exact mirror of each other. This step provides the missing link between the remote and local filesystem.

   • Save the changes.

   Notes about the screenshot: to elucidate any possible confusion from the values defined in the screenshot, some of them will be explained.

   • The directory of the project on the host OS is /Users/dane/dev/vanilla/vhosts/vanilla and the corresponding path in the guest OS—in Vagrant—is /vanilla/vhosts/vanilla. That is because Vagrant’s Vagrantfile configuration file was configured to mount an additional directory in the guest filesystem, named, /vanilla. The /vagrant directory also exists, though. Most default setups will just use /vagrant.

   • In addition, the “Host” provided is www.vanilla.dev, but it could have also just been localhost. The host OS’ /etc/hosts file contains a custom entry, which allows custom domains like that.

6. PhpStorm version 8.x and above: Unlike in version 7.x and under, leave the option, “Use path mappings (select if the server is remote or symlinks are used),” alone. Leave it unchecked. Version 8 can define a remote PHP interpreter.

   • Open PhpStorm’s preferences and find the “Languages & Frameworks” heading.

   • Click the “PHP” setting. On the right are options pertaining to it.

   • The “Interpreter” setting has a small ellipsis (“…”) button. Click that to open a new window of options.

   • Add a new remote PHP interpreter by clicking the “+” symbol.

   • Select “Vagrant” and provide the path to the Vagrant instance installation on the host OS; this is the directory where the VagrantFile exists, and where commands like vagrant up and vagrant ssh are run from the terminal.

   • Provide a path for the “PHP interpreter path” setting. It is typically located at /usr/bin/php, but if PhpStorm is having issues locating the binary, SSH into the guest OS (vagrant ssh from the instance directory), and run which php; copy the resulting path into the designated section in PhpStorm.

   • Save the changes.

   • By this point PhpStorm should have automatically tested the connection and reported the version of the remote PHP interpreter in the guest OS. It will have also named the remote interpreter.

   Notes about the screenshot: There are two windows layered on top of the main preferences window. The foremost one is triggered by clicking the “+” symbol in the middle layer window. That middle layer window is triggered by clicking the “…” button next to the “Interpreter” setting.

The most essential component to debugging PHP applications hosted in a Vagrant box using PhpStorm is now complete.

Create PhpStorm’s debug configuration

This is the last section to follow in order to run a successful debugging session. The Xdebug configuration settings have been defined in the guest OS; PhpStorm on the host OS has been configured to use the right port and allow external connections; the local-to-remote file path mappings have been set up so the IDE knows exactly how to step through any line of code. All that remains is setting up the “Run/Debug Configurations,” and starting the service listener so PhpStorm can actually debug code. The previous steps in this guideline must be completed prior to the next and final section.

The steps for creating the debug configuration are delineated below, followed by a screenshot of the UI where these steps take place.

1. Click on the “Run” toolbar menu option at the top of PhpStorm.

2. The dropdown of options all pertain to debugging code. Click on “Edit Configurations.” A window appears with the relevant settings.

3. The left column lists different types of run and debug configurations. They are kind of like different tool definitions that PhpStorm can implement to analyze code more effectively. Add a new configuration by clicking on the “+” symbol, and select “PHP Web Application.” An “unnamed” tool definition is created. The right column displays its configuration interface.

4. Provide the configuration a “Name.” This can be anything, but for clarity, this guide uses “Vagrant.”

5. The “Server” setting should have the name provided in Step 4 of ‘Add a remote server to the current project’s settings’ earlier in the guide. If it is not an available option in the dropdown, revisit that section of the guide; make sure it is configured properly.

6. The “Start URL” will depend on the application. Many MVC-type frameworks, though, will use the root of the URL, so a / will suffice. That essentially means that the index file of the document root will be used: index.php in most instances.

7. Choose the “Browser” where most development takes place. This is to ensure that the browser will automatically switch to PhpStorm when a breakpoint is reached. Later, the browser will be configured with an addon that simplifies debugging.

8. Save the changes.

Listen for incoming debug connections to PhpStorm from Xdebug

At the top right of PhpStorm should be a toolbar similar to the images provided. With the project open, select “Vagrant” from the dropdown. Remember that this was just defined. It is the “PHP Web Application.” A few buttons over there is a telephone receiver icon with a bug at the mouthpiece and a banned symbol at the earpiece. Click on this. The banned symbol at the earpiece should change into a sort of abstract visualization indicating that PhpStorm is listening for connections.

PhpStorm is ready to accept connections from Xdebug. All that remains is knowing how to trigger them.

Starting a debug session

There are a few methods to start a debug session. PhpStorm provides bookmarklets for this, but they are not ideal. Do not even bother. The best option is one that integrates with a Web browser. Both Firefox and Chrome provide addons for this. It is unnecessary to install each if only one Web browser will be used.

Install an Xdebug addon for Firefox

Install The easiest Xdebug addon for Firefox. It provides only one option: define its “IDE key for remote debugging.” Remember that this guide defined the IDE key as debugit, so use that.

Install an Xdebug addon for Chrome

Install the Xdebug helper addon for Chrome. There are some additional options, but the relevant one for this guide is to define the IDE key. It provides different IDEs to select from—which provide the most common IDE key values for each IDE—as well as an “Other” option. Choose that and type in debugit as the IDE key.

Define a breakpoint in PhpStorm

PhpStorm is already listening for incoming connections, but if a breakpoint is not set, the code will execute to the end without pausing.

Open a file in the project, and click in the empty margin to the left of a line number. A tiny orb will indicate that a breakpoint has been set.

Trigger a debug session from a Web browser

Return to the browser and click on the the debug icon that it provides. That will set a browser cookie with the defined IDE key, which will be read by Xdebug where PHP is running code in the guest OS, as mentioned earlier. In turn, that commands Xdebug to send a request to PhpStorm, which is listening for a connection. Navigate to a page that will be affected by the breakpoint set in PhpStorm, or refresh the page if that has already been done; note that the page appears to hang. That means PhpStorm has paused execution of the PHP script at the designated breakpoint until the code has been stepped through or execution resumed. Return to PhpStorm and look for the file with the set breakpoint. The debuger tab should be visible, with all the variables and constants of the page ready to get populated with data. This is how it should appear:

Notice the $_COOKIE superglobal includes the XDEBUG_SESSION = 'debugit' cookie set by the browser.

Summary of how to configure and run PHP Xdebug in PhpStorm through Vagrant

• Xdebug in the virtual guest OS installed by Vagrant is configured for remote debugging.

• PhpStorm’s debug settings are configured. External connections are allowed through the designated port.

• A remote server is added and defined for PhpStorm. This allows it to know how to communicate with the guest OS in Vagrant. Most importantly, the local-to-remote file path mappings are defined. That allows the files in the guest filesystem to map to the files in the host filesystem, where PhpStorm will step through code.

• A new “PHP Web Application” is created. It points to the server just added.

• Set PhpStorm to start listening for incoming debug connections.

• Install a browser addon to easily trigger debug sessions.

• Set a breakpoint in PhpStorm for the given project.

• Start the debug session in the browser, refresh it, and return to PhpStorm to view the open debugger tab.

Appendix and troubleshooting

• This guide uses CentOS 6.5 as the guest OS, and Mac OSX as the host OS. The steps should not change much or at all if the OS of either is different. For example, the process for a Windows host OS should not be very different.

• The most common IDE key used in PhpStorm is PHPSTORM. The guide uses debugit. It does not matter what key is used, but it should be noted that some debugger tools, like Chrome’s “Xdebug helper” addon, does not provide a text box to define a key if PhpStorm is chosen. It automatically assumes that the key will be PHPSTORM. This is why “Other” was chosen. Another popular IDE, NetBeans, commonly defines the IDE key as netbeans-xdebug.

• If the project contains symlinks to other code being used from other locations, PhpStorm’s debugger tab will complain about missing file path mappings. Make sure any symlinked code is properly mapped with its guest filesystem counterpart in Vagrant.

• The assumption has not been tested, but it is very possible that the steps to configure PHPUnit to work in PhpStorm through Vagrant would be similar.

Other reference material

1. http://xdebug.org/docs/remote#communication

2. http://superuser.com/questions/310697/connect-to-the-host-machine-from-a-virtualbox-guest-os/310745#310745

3. http://confluence.jetbrains.com/display/PhpStorm/Zero-configuration+Web+Application+Debugging+with+Xdebug+and+PhpStorm

Feedback

Did you notice something wrong with this guide? Have you found related material on the Web somewhere? Let me know in the comments. Also, if you know someone who might want to read this, share it with them.

Introduction

This article will show you how to set up a virtual machine for a local Shopware 6 environment in development mode. Some of you might stumbled upon the restrictions of Shopware when it comes to Windows as operating system. Everyone that might have tried to get shopware working on Windows might know, that it is more likely to fail than to succeed. It is important to use a Unix-based system (like Linux or MacOS) as environment for a local setup. Surely not everyone is that familiar with Linux or has an Apple product to work with. This guide will help you to set up a Linux virtual machine on your local operating system regardless with OS you are currently using.

First of all you will need a local installation of Virtual Box from Oracle. Just download it from https://www.oracle.com/de/index.html and start the installation process. The main reason for a virtual box image is, that you can use it independently on every operating system you are using - even if you change e.g. from Windows to MacOS in the future. Since the settings are saved inside the virtual image, a re-installation of your laptop will keep the configuration and you are ready to go in a few steps after the installation of virtual box.

Downloading Ubuntu

This guide will focus on Ubuntu and use it as a foundation for the setup. Ubuntu is a well known and documented Linux distribution and might be the best choice for beginners. Since we won’t need the whole Desktop-Manager version of Ubuntu, just grab the network installer image from their site: https://ubuntu.com/download/alternative-downloads

Just wait until the download finishes and we will start with the configuration of the virtual box.

Creating a Virtual Box Image

First of all, you need to start your newly installed Virtual Box. Just create a new virtual machine by using the „new“ button on the right side of the new menu or use the top menu (Machine -> New).

Further you need to define what operating system you want to virtualize and have to Select „Type: Linux“ and „Version: Ubuntu“ in the sub-menu. Feel free to choose any name you want for the newly created virtual box image.
You can confirm your selection with „continue“.
The next context menu will ask you about the preferred memory size, we recommend using 2GB or more for your environment, but it highly depends on your available resources on your computer (e.g. if you have only 4gb of RAM, you won’t be able to add more than 2GB to the virtual machine). In our case we will use „2048MB“ as selection. Confirm to go to the next step.
Now you need to define your hard disk for the virtual machine - just keep the selection at „Create a virtual hard disk now“ and use the „create“ button to confirm this.

Inside this new sub-menu you can keep the selection at „VDI (VirtualBox Disk Image“) and go on with continue. The new image should be „Dynamically Allocated“ in our case and 15-20GB should be enough for the local environment. The steps will show you comprehensive information on what to do. After you have finished the configuration of your VM, you will be back at the start screen from above.

Before we will start our newly created virtual box, we need to do some additional configuration. Just select the newly created VM and open the „Settings“ menu. Change to the „Network“ configuration and open the hidden „advanced“ configuration. In this section you will find the „Port Forwarding“ - just click this button for a new sub-menu.

Add the configuration from the screenshot in order to make your VM available from your local computer on localhost. If you need to change this ports, please keep those changes in mind, because we need them later on. Often there are already services listening to port 22 and 80 on your local computer, so we changed the host ports to unused ones. Confirm your selection and close the sub-menues.

Environment Setup

Ubuntu Setup

Just start your newly created virtual machine in the main menu of virtual box. Since the virtual environment is empty for now, you will need to add your downloaded iso file of Ubuntu in the menu. Just select it from your hard drive and hit the start button.
The system will boot from your Ubuntu ISO and will show the boot loader with some possible selections. Start the standard installation in this case.
The Ubuntu installer will start and you are asked for your preferred language and region. After you confirm your selection the system will try to guess your keyboard layout, this can be done automatically or by choosing the right one. Either way you will use, make sure that you choose the right one. After this basic system configuration is done, the installer will establish a connection to the Ubuntu servers to download the needed packages for the installation. You will be prompted to define hostname (feel free to choose any) and a mirror (just select the pre-defined one). When using a proxy for your internet connection you can configure it as well, but in most cases you won’t need to do anything.

The next step will be the setup of the user name and password. In our case we will select „shopware“ as username and „shopware“ as password, but you are free to define a different one - but please make sure, that you will remember it. The time zone will be detected afterwards, you only need to change this, if it really differs from your current time zone.

Just choose the guided partitioning of the hard drive in the next menu and go on with the installation and write your changes to the disk. The basic installation of the software will take place. Since most of the packages will be downloaded from the Ubuntu mirrors, this will take a while depending on your internet connection. Feel free to install security updates automatically in the next step. Further on we will be asked for additional software that might needs to be installed. From this new menu choose „LAMP Server“ (Apache, MySQL, PHP) and „OpenSSH server“ (the selection can be done by hitting the space bar). The process will install the newly choosen software and the bootloader (you may need to confirm this too). Finish the installation and we are ready to do some additional configuration of the system.

Ubuntu Configuration

Remove the Ubuntu ISO from the VM (by clicking the small CD-ROM symbol at the bottom of the VM window) and shut down your newly created virtual image. Start it again while holding the „Shift“-key. This will start the VM in the background and we are able to access it via SSH. On most environments this is possible via a terminal with the command „ssh shopware@127.0.0.1 -p2222“. Please make sure to add your newly created user instead of „shopware“ if it differs. On Windows environments software like Putty is used for SSH connections, but you can use the VM window too, if you don’t want to use an additional software.

First of all, you can check your installation. Just open 127.0.0.1:8080 (keep in mind, that you might have changed this port) - an Apache test page should be visible in your browser. Inside the terminal you can verify the installation of PHP by using „php -v“ and it will show you the used PHP version (it should be 7.2 at least).

We will need to set a password for MySQL - you can do this with the following commands:

In our case we will set the password of the user „root“ to „root“. You may want to change this, but keep in mind to remember this password at a later time.

Installation of dependencies

In order to use Shopware, you will need to install some additional dependencies on your local machine. This can be done by the following commands:

After the installation make sure, that you use a current version of npm by ececuting this:

Installation of Virtual Box guest additions

For a smooth integration of virtual box on your computer, we recommend adding the guest additions to your virtual machine. Just open your virtual machine (button „show“ in the virtual box main menu) and add it via the conext menu Devices -> Insert Guest Additions CD Image. After the image is inserted, you need to mount it and start the installation:

You might have to establish the SSH connection again after rebooting.

Configuration of Apache

First of all you need to activate mod-rewrite, this can be done by executing the following command in your vitual machine:

After this you will need to add a new vhost-configuration, just disable the existing one:

And at last you need to create a new configuration:

Just add the following configuration to the editor:

With CTRL + O you can save it and with CTRL + X you can leave the editor. Afterwards you need to restart the webserver:

Since Linux is a system that is really strict with right- and permission management, we need to add the user 'shopware' to the 'www-data' group, in order to prevent issues with the permissions:

You might need to restart the SSH connection after rebooting the VM.

Installation of Composer

Just keep in mind, that the verification of the installer might change, so you need to use the commands from the Composer website to make sure: https://getcomposer.org/download/

For Example:

After you have downloaded Composer sucessfully, you need to make it executable via the command „composer“, just copy it to the /bin folder:

You can verify your installation by running „composer“ in your terminal.

Installation of Shopware 6 development environment

Shopware 6 comes in two different versions. There is an official release-package for production systems, that won’t provide you any development tooling (e.g. for building plugin assets) and there is the GitHub repository that will be your development environment. Change the directory to the web folder and download shopware 6 from github:

In order to start the installation, you can simply execute the following commands, a wizard will guide you through the installation of Shopware.

You will be asked for your environment (select „dev“), your public url (in our case http://127.0.0.1:8080, the port may differ according to your configuration), your database (keep localhost, shopware as database name and root/root as user/password).

After you confirm your environment parameters, the installation will take place. It will take 37 steps to finish this installation, so you might have to wait a bit. The Composer dependencies will be downloaded at first.
For the next installation they will be taken from cache, this will speed up the installation quite a bit. When the installation is finished, you can access the installation via your browser on your local environment: http://127.0.0.1:8080. The administration is accessible with /admin and the user/password combination of admin/shopware.

Optional configuration

Reset installation

Since the master branch of Shopware 6 is updated frequently, you may want to reset your installation. This can be easily done by deleting the folder and cloning the repository once again. But you may want to have a script for that, here is an example:
Add the following content to it:
Now you can re-install your whole installation by just executing the newly created script. Just make it executable and move it to the /bin folder:

Updating the master branch

In some cases you might want to keep your settings and database and just get the newest files from Github. This can be achieved by the following commands inside the Shopware 6 folder:
Feel free to create a script from it like the one we created above.

Installation of a Release-Tag

Since we already have a released version of Shopware 6 available on our download page, you might want to install this exact version instead the current master branch. You can achieve this by adding a specific parameter that points to the tag:

PHPStorm configuration

You can use this setup as development environment, so you surely want to configure PHPStorm accordingly. When creating a new project in PHPStorm you can choose the option 'Create new project from existing files' from the sub menu. Just choose 'Web server is on remote host, files are accessible via FTP/SFTP/FTPS'.

When going to the next step you need to add a project name and a local folder (feel free to choose anything).
In the next window you need to add your SSH/SFTP configuration of the virtual environment.

Just finish the wizard afterwards without any further configuration and the download of your project files will start. This may take a while. After the download, you are able to use this connection to develop locally on e.g. on Windows and upload your changes to the Linux virtual environment.

Visual Studio Code configuration

Visual Studio Code might be a good alternative to PHPStorm, when it comes to license costs, since it is completely free. You can add a remote host too, but you will need the 'Visual Studio Code Remote Development Extension Pack' from the extension list. Just open the extension list from the left panel and search for this extension and install it. A restart may be required. After rebooting a whole new menu will appear on the left of the Visual Studio Code menu.
Create a new ssh configuration:
At first you may be promted with a new input field for the password while trying to connect:
Afterwards you can use the terminal and the file editor of Visual Studio Code to access your Shopware 6 installation and start development.

Download the VM

We highly recommend creating your own VM in order to learn about the difficulties and challenges while using Linux, but we do offer you a ready to use VM that will be updated frequently: shopware.ova
Just use the import dialog of Virtual Box, all settings will be imported.

Shopware 6:

• Frontend: 127.0.0.1:8080
• Administration; 127.0.0.1:8080/admin
• Admin Username/Password: admin/shopware
  

Virtual Machine:

• SSH-Host/Port: 127.0.0.1 / Port 2222
• SSH Username/Password: shopware/shopware
• Database Username/Password: root/root

Please note, that there is already an installation inside this VM, if you want to make sure that it is the current master, please execute the command 'sw6' inside the VM the check out the newest version.

As one step of the installation process we set up a network share that you can access directly from your local computer without using any SSH/SFTP connection. This is also part of the VM. In the next steps we will show you how to use it on your local computer.

Phpstorm Virtualbox Free

MacOS network share

Phpstorm Vagrant Virtualbox

Open the Finder and go the the 'Go' menu at the top. Open to 'connect to server'. Add your network share adress and port to the new window:

To finish the set up of the local network share, just hit 'connect' on this menu. The Finder will establish a connection to the network share and you can use those files as a local folder:

Windows network share

Unfortunately it is not possible under Windows to map a network drive to a share in the VM under the IP 127.0.0.1. For this a few adjustments are necessary

Network adapter in Virtual Box
First change the network adapter from NAT to Bridged Adapter in the Virtual Box Manager for the Shopware VM
(It is necessary that the VM is switched off at this time)
At Settings > Network > Adapter 1 > Attached to: select Bridged Adapter
This assigns a new, own IP address to the VM through the DHCP server in the network.
(If no DHCP server is available in the network, it is necessary to manually assign an IP to the VM.)
Find out the IP assigned by DHCP
This is possible, for example, via the console displayed in the window of the VM.
To do this, type ifconfig in the console and the IP settings will be listed.
(net-tools is required for this. This is included in the prepared VM, if you have your own system you may have to install it.)
Now the connection via SSH is possible via the IP of the VM and Port 22
Customize settings in Shopware
First call the admin via http://IPoftheVM/admin
Now it is necessary to adjust the URL for the sales channel 'Storefront' in the section 'Domains' to http://IPoftheVM
After you have saved the URL change, you can directly call the frontend via IPoftheVM
Mapping the network drive
It is now possible to mount the network drive in Windows.
To do this, proceed as follows
Open 'This PC' and in the tab 'Computer' click on 'Map network drive'

In the new window choose a drive letter and enter as folder 'IPoftheVMVM' and also check 'Connect using different credentials'
Optional you can also check 'Reconnect at sign-in'

When you click on the Finish button, a window to enter the credentials is shown.
As user enter 'ubuntu/shopware' and as password 'shopware'.
(if the connection is to be re-established when logging on, it is recommended to save the login credentials)

After confirming via the OK button, the connection is now established and the network drive is connected.

Phpstorm Virtualbox Tutorial