Phpstorm Laravel Docker

Creating a Simple Laravel Docker Environment

The docker folder contains three folders, nginx, php, and mysql. These folders will hold Docker related files, Dockerfiles.inis, configuration files, etc. The www folder will be our environments web root where laravel will be installed. Apparently you need to specify to phpstorm the network mode he should use for interacting with the container. Go to File Settings PHP and click on the folder icon of the 'Docker Container' config. In the Network mode instead of 'Bridge'use the network name you used in your docker-compose.yml. PhpStorm can be setup to use Docker. Thanks to Gary Hockin’s excellent YouTube video Running PHPUnit Tests in PhpStorm with Docker, the setup process can be easily replicated. There is a four stage process: Configure PhpStorm to use Docker.

Since I started at liquidfish a little over a year ago I was introduced to the wonderful world of Laravel Homestead. Laravel Homestead is great, it supports multiple php versions, xDebug, MySQL and allows the user to install any other required software straight into the virtual machine.

This is a tried and tested method of local development that has worked incredibly well for our development team for many years, but as we continue to grow we are always looking for ways to improve our development and deployment process, enter docker.

- Docker is a platform for developers and sysadmins to develop, deploy, and run applications with containers. - docs.docker.com

Today we are going to create a dead simple docker environment to run Laravel 5.8 using PHP 7 with xDebug and Mysql on Windows 10 WSL.

My current development environment:

  • Windows Subsystem for Linux (WSL)

    • My main hard drive is mounted under /c/ in the WSL

  • ConEmu using ZSH hooked up to WSL

  • Docker for Windows

  • Docker & Docker Compose installed on WSL

    Mac os mojave

  • PHPSTORM

As long as you have Docker & Docker Compose running on your machine you will be able to follow along with this tutorial. Let’s get started!

First create a new project folder for our docker environment, mine will be under /c/docker/laravel.

Now create the following directories inside the project folder

  • docker
    • nginx
    • php
      • config
  • www

The docker folder contains three folders, nginx, php, and mysql. These folders will hold Docker related files, Dockerfiles, .inis, configuration files, etc.

The www folder will be our environments web root where laravel will be installed.

First we are going to create a .env file in the root of the project to hold our Docker configuration variables that our compose file and PHP Docker file will use. The .env file will allow for easier flexibility in the event you need to change your environment.

Now lets create our docker-compose.yml file inside the root of our project and add the following services to it.

Docker-compose.yml explanation

  • Version

    • The version of the docker-compose file

  • Services

    • Defines the services that will be ran on docker-compose up

  • App - PHP-FPM service

    • Build - We are going to be building a docker file

      • Context - The location of the docker file

      • Args - Variables we want to use in the Docker file from the .env

        • APP_ENV - Docker environment

        • PHP_VERSION - Version of php

        • REMOTE_WORKING_DIR - Remote working directory laravel will live

    • Container_name - Name of the container

    • Restart - Service will always restart unless it is stopped

    • Volumes - Local directories we want to mount and files we want to mount to the service

      • ./www (LOCAL_WORKING_DIR) to /var/www/html (REMOTE_WORKING_DIR)

      • Local xdebug ini file

    • Env_file - location of our env file

    • Ports - Ports we want to expose to the outside

      • 9001:9001

    • Networks - Internal app-network for inter-container communication

      • App-network

  • Nginx - Nginx service

    • Image - Nginx image we are using

      • Nginx:alpine

    • Container_name - name of container

      • Nginx

    • Restart - Service will always restart unless it is stopped

    • Volumes - Local directories we want to mount and files we want to mount to the service

      • ./www (LOCAL_WORKING_DIR) to /var/www/html (REMOTE_WORKING_DIR)

      • ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf

        • Default nginx configuration file

      • ./docker/nginx/conf.d/:/etc/nginx/conf.d/

        • Nginx site configuration files

      • ./docker/nginx/ssl/:/etc/nginx/ssl/

        • SSL directory

    • Ports - Ports we want to expose to the outside

      • 80:80

      • 443:443

    • Depends_on - Nginx depends on the app service to start

    • Networks - Internal app-network for inter-container communication

      • App-network

  • Database - Mysql service

    • Image - Mysql image we are using

      • Mysql:5.7

    • Container_name - name of container

    • Enviroment - Environment variables the image will use

      • MYSQL_DATABASE: 'laravel'

      • MYSQL_USER: 'user'

      • MYSQL_PASSWORD: 'secret'

      • MYSQL_ROOT_PASSWORD: 'password'

    • Ports - Ports we want to expose to the outside

      • 3306:3306

    • Volumes - The data volume for mysql, this will allow data to persist.

      • database-volume:/var/lib/mysql

    • Depends_on - database service depends on the app service to start

    • Networks - Internal app-network for inter-container communication

      • App-network

  • Volumes: - Volumes to create
    Database-volume: - Mysql data volume

  • Networks - Networks our services are using

    • App-network - name of network

      • Driver bridge

        • Bridge network is used for inter-container communication

Next up is creating our php Dockerfile

Dockerfile Explanation

  • ARG “VARIABLE”

    • sets the arguments supplied in the docker-comopose.yml for use within the Dockerfile

  • FROM php:$PHP_VERSION-fpm-alpine

    • is installing the php-fpm alpine image supplied through the variable

      • Alpine Linux is an independent, non-commercial, general purpose Linux distribution designed for power users who appreciate security, simplicity and resource efficiency. - https://alpinelinux.org/about/

      • Using Alpine Linux will help keep our image sizes down

  • RUN apk update

    • Is updating Alpine Linux and then adding our dependencies, if you need additional php extensions or linux packages this is where you would add them.

  • RUN docker-php-ext install and enable

    • install the php extension into docker and then enable it so we can edit the configuration of these extensions. For the sake of simplicity I am only install pdo. If you need a more robust configuration you would install and enable the extension here.

  • RUN if [ $APP_ENV = “local” ]

    • we are only installing xdebug if we are on a local development environment, there is no need to install it on staging or production.

  • RUN curl -sS composer

    • We are installing composer for laravel

  • RUN rm -rf /var/cache/apk/*

    • we are cleaning up the apk cache

  • RUN apk add shadow && usermod

    • we are adding the UID 1000 to www-data for php-fpm

  • COPY --chown=www-data

    • we are copying the application directory permissions

  • USER www-data

    • changing the current user to www

  • EXPOSE 9000

    • exposing port 9000 for internal use within the containers

  • CMD [“php-fpm”]

    • start php-fpm

Phpstorm Laravel Docker Download

Now lets create our default configuration files

Create a nginx.conf file in the root of our docker/nginx folder with the following contents.

Create a site.conf file in the root of our docker/nginx/conf.d folder with the following contents. This is a standard laravel nginx config.

I am using test.local as my local domain, be sure to add 127.0.0.1 test.local (or your preferred local domain) to your hosts file.

Phpstorm Docker Compose

Create a xdebug.ini file in the root of our docker/php/config folder with the following contents.

The big takeaway with this xdebug configuration is setting connect_back to 0, setting your idekey to PHPSTORM, and setting your hoist to host.docker.internal. I ran into issues with enabling setting remote_connect_back instead of using the remote_host. This has been tested on Windows 10 WSL and has been working really well. If you can’t get xdebug to work with that configuration you may need to search around to find one that will work for you.

Lets build it

Phpstorm Xdebug Docker

Phpstorm

To build the environment make sure you are in your projects root folder and run docker-compose build and let it run. When it is done you should see the following output.

Phpstorm Laravel Docker Tutorial

Now that PHP is built lets run docker-compose up -d this command starts all of the containers in detached mode, if you want to be able to run the containers while looking at the output logs just run docker-compose up. If you are in detached mode and want to view the logs for a specific container you can run the following command, docker-compose logs app (container name.)

Installing Laravel

Now that are containers are running lets install laravel, run the following command to jump into the container docker-compose exec app bash.

Now that we are in the container run the following command to install laravel composer create-project --prefer-dist laravel/laravel . Setting the directory to the (.) just means we are going to install laravel inside the current directory.

Great Laravel is installed, now open up test.local (or the domain you set in the nginx config / hosts file) and you will see the Laravel welcome screen!

Phpstorm Xdebug Docker Cli

Setting the laravel mysql environment variables

Phpstorm Xdebug Docker Laravel

Just like in the Nginx config where we set the fastcgi_pass to app:9000 we are going to do a similar thing to the mysql environment variables.

Now that we have the environment variables set lets exec back into our container (docker-compose exec app bash) and run the default migrations (php artisan migrate)

Creating a PHP Remote Debug configuration in PHPSTORM

To enable use xdebug in PHPSTORM follow these steps

  • Top right of PHPSTORM there is a drop down, click add or edit configuration

  • Set the name (Can be anything)

  • Select Filter debug connection by IDE key

  • IDE Key is PHPSTORM

  • Click the servers button to the right of the server dropdown

  • Set the name of the server (Can be anything)

  • Set the host to your local site url (mine is test.local) Port 80, Debugger Xdebug

  • Open the File/Directory selection until you see the www folder

  • On the right where it says absolute path on the server click to edit it

  • Enter /var/www/html which is the remote path and hit enter on the keyboard to save it

  • Apply the changes then hit ok on the servers menu and then the debug menu

Phpstorm Laravel Docker

To test this go into the web.php routes file and add the following code

Break on the first $word variable and you will now be able to step through the code!

Sweet! Docker is setup, Laravel is installed and configured, our migrations have been ran, and our xDebug configuration for PHPSTORM has been setup!

Now all that's left to do is get building!