PHP Storm Remote Files

TODO: This section is still experimental. Feedback is welcome.

The PHP Storm IDE supports the ability to use FTP to transfer files between a remote server and a local machine. The provided Docker container includes a SFTP server for performing such transfers.

For advanced front-end developers, one of the advantages of this approach is you can then use Gulp to speed up the regeneration of CSS files for a page. Gulp takes a little more effort to set up, but once set up the developer workflow is faster. Magento 2 currently also provides Grunt configuration files with the distribution, whereas Gulp is supported using external tools. The Docker container includes both Grunt and Gulp support. However, Gulp is faster than Grunt and so used by the book series. Grunt is not discussed further here – refer to the official Magento 2 documentation if you wish to use Grunt instead of Gulp.

Gulp can be configured to watch a file system for file changes, triggering the regeneration of CSS files automatically. However, this approach does not work across “volume” mounted directories. The approach described on this page copies files into the container, which will cause Gulp to notice the file system changes meaning Gulp can be used.

For the approach on this page, do not mount the Docker volumes. However you need to set up correct port mappings. If using Kitematic, click on the “Settings” tab and go to “Ports”, you will notice ports for HTTP (80), SFTP (22), and Gulp/BrowserSync (3000 and 3001). Clicking just to the right of the IP addresses allows you to specify the port number to use for these services. (Docker will pick random port numbers otherwise.) A suggested choice for the HTTP port is port 80 on your local machne, or a higher port such as 8080. Use ports 3000 and 3001 for BrowserSync (you connect to these ports also using a web browser). The recommended SFTP port is 2222. Port 22 cannot be used as that port is already used by Kitematic for controlling Docker.



To start the docker container from the command line, use a command such as

% docker run -i -t -d -p 8080:80 -p 2222:22 -p 3000:3000 -p 3001:3001 --name gsd alankent/gsd

It is worth remembering that running Magento and MySQL inside a Docker container results in them running on your local development machine. A reasonably high powered development machine is recommended for the best results. If this is not an option, you may wish to run Magento on a remote server for better performance. Again it is recommended to read the Docker documentation if you wish to proceed down this path. Docker has some handy tools for managing a remote Docker container (see also “Docker Machine”).

The following uses a PHP Storm feature called “remote files”. PHP Storm has a mode to “create a new project from remote files” which can download the files to your host OS via SFTP. It will then upload any changes automatically back to the SFTP site. In this approach you do not enable volumes. Instead, you use PHP Storm to copy changes into the container.

In practice however this does not work with the full Magento code base. After 24 hours PHP Storm was only half way through the initial sync on my laptop. The approach does however work by using “remote files” with just the “app” directory (which includes “app/code”, “app/design”, and “app/i18n”).

The example settings for PHP Storm are as follows. Note you have to insert the IP address Kitematic selects on your local environment. The SFTP username/password combination is hard coded to be magento/magento in this Docker image. (Clearly this is not satisfactory for a production environment!)  The web server root URL should include “:8080” if you are exposing the web server port on port 8080.


Try the “Test SFTP connection” button to make sure the settings are working. The first time you attempt to connect, it should warn you that it is a new RSA fingerprint. (If you delete and re-create the container you will get some very dire warnings about potential security breaches. You can ignore such warnings – they are just because you created a new container at the same IP address with different RSA credentials.)


The next step is a little finicky. PHP Storm will bring up a dialog box showing a tree view. Click on “/magento2” then click “Project root” at the top of the page. This tells PHP storm where the project root is. DO NOT CLICK NEXT YET! If you do so PHP Storm will try to check out the whole directory tree, and this is simply too slow due to PHP Storm inefficiencies.


What you need to do next is select all the top level directories under “/magento2” except “app” and click the “Exclude” button at the top of the page. This tells PHP Storm to only remotely manage the files under “app”. Step through the remaining pages to complete the new project setup.


You can now create files under “app/design”, “app/code”, or “app/i18n” and use the “deployment” menu option to push changes to the site. (Read up on the PHP Storm “remote files” feature for more details as there are several ways to access this feature. Basically you can easily sync your changes from PHP Storm back to the Docker container over SFTP.)


Access to Rest of Code

You can stop here if you wish. However, there is one additional step that makes this mode of operation that much more convenient. This is to put a copy of the files in the Docker container (other than “app”) into your PHP Storm project directory. PHP Storm will notice these files and add them to your project, but will not sync them back to the Docker container. It will be up to you to remember not to edit these files, but it will allow you to browse around the full code base locally, including access the XSD files for schema validation of configuration files.

For example, run the following commands on your local machine in the “Docker CLI” window (shown here for Windows assuming you created your project under “C:\Users\akent\git\GSD-vol2”).

docker cp gsd:/magento2/lib C:\Users\akent\git\GSD-vol2
docker cp gsd:/magento2/dev C:\Users\akent\git\GSD-vol2
docker cp gsd:/magento2/setup C:\Users\akent\git\GSD-vol2
docker cp gsd:/magento2/vendor C:\Users\akent\git\GSD-vol2

These commands copy the bulk of the Magento 2 code to your host OS. (You can do this for all directories you excluded above, but this list of 4 is the most important directories.)

All of the path names in the books are now relative to the root of the project.


One of the key benefits of this approach is if you want to use Gulp for optimized Less compilation. This mode of PHP Storm pushing changes into the container means Gulp can be used to monitor for file changes, and regenerate Less files on demand. Gulp is supported using “frontools” from “SnowdogApps” ( and is pre-installed in the the Docker image. It resides in /magento2/tools. Please refer to the “frontools” documentation or the book series for further details.

For other related pages, see the “Book” menu at the top right of this page.

%d bloggers like this: