29-04-2021

Phpstorm Laravel Docker

Prerequisites

Phpstorm Docker Phpunit
Phpstorm Xdebug Docker Cli
Phpstorm Laravel Docker Download
Phpstorm Laravel Dockers
Phpstorm Docker Xdebug Not Working
Phpstorm Xdebug Docker Laravel

Before you start, you need to have some certain prerequisites in place:

PHP 7.2+
Local machine running the latest version of Docker.

In the PHP section in PHPStorm setting, create a new CLI interpreter config from your docker/docker-compose setting. PHPStorm will import the settings and magically getting CLI interpreter configs into place. If you already configured the CLI before, you can see it here. Docker container with PHP+XDebug installed; PHPStorm IDE on my host machine; Debugging PHP scripts # Configure docker container. I am using docker-compose to manage my containers. So let's start with the docker-compose.yml that I put in the root of my PHP project. $ cd $ docker build -t laravel-tutorial. The final step is to run the container you have just built using Docker: $ docker run -it -p 8000:8000 laravel-tutorial The command tells Docker to run the container and forward the exposed port 8000 to port 8000 on your local machine.

Get Started

Let's create a Laravel project and then see how we can dockerize it using Docker.

Laravel Requirements

The Laravel framework has a few system requirements:

PHP >= 5.5.9
PHP Extensions:
- OpenSSLup
- PDO
- Mbstring
- Tokenizer

Step 1 - Install Laravel

Laravel utilizes Composer to manage its dependencies. So, before using Laravel, make sure you have Composer installed on your machine.

Install Composer

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. To a install it quickly, just open up a terminal and run this command:

Composer is multi-platform and it run equally well on Windows, Linux and macOS. Here you will get more information regarding how to install composer in each platform:

Step 2 - Create a Laravel Project

Via Laravel Installer

First, download the Laravel installer using Composer:

Once installed, you can use the laravel new command to create a fresh laravel project.

Via Composer Create-Project

Alternatively, you may also install Laravel by issuing the Composer create-project command in your terminal:

Here is a brief breakdown of the directories in a common Laravel application:

app/: This is the source folder where our application code lives. All controllers, policies, and models are inside this folder
bootstrap/: Holds the application's startup script and a few class map files
config/: Holds the app's configuration files. These are usually not modified directly but instead, rely on the values set up in the .env (environment) file at the root of the app
database/: Houses the database files including migrations, seeds and test factories
public/: Publicly accessible folder holding compiled assets and of course an index.php file
resources/: Contains front-end assets such as javascript files, language files, CSS/SASS files and all templates used in the application (called blade templates)
routes/: All routes in the application are inside here. There are a few different 'scopes' of routes but the one we will be focusing on is the web.php file
storage/: All temporary cache files used by the application, session files, compiled view scripts and log files
tests/: Contains test files for the application such as unit tests and functional tests.
vendor/: All dependency packages installed with composer

Then, to install all dependencies and run the project, you need to run the following commads:

You will see your Laravel server running on: http://127.0.0.1:8000

Congratulations, you’ve created a Laravel project!

Note: For more extensive instructions on setting up Laravel, refer to the Laravel documentation here.

Step 3 - Dockerize the Project

Setup Docker

Before creating a container for the Laravel application and shipping it off, you need to install Docker on your local machine. For learning purpose, you will install Docker Community Edition. Select your OS from the list below and follow the setup instructions:

Make the docker App image

The next stage to improve your docker php development workflow is adding a Dockerfile to your project. The structure of a Dockerfile can be considered a series of instructions on how to build your container/image.

Start the Dockerfile by creating an empty file named Dockerfile in the root of your project. Then, complete each instruction according to the following example:

Building and Running the Container

Building the container is very straight forward once you have Docker and Docker Machine on your system. The following command will look for your Dockerfile and download all the necessary layers required to get your container image running. Afterwards, it will run the instructions in the Dockerfile and leave you with a container that is ready to start.

To build your php laravel docker container, you will use the docker build command and provide a tag or a name for the container, so you can reference it later when you want to run it. The final part of the command tells Docker which directory to build from.

The final step is to run the container you have just built using Docker:

The command tells Docker to run the container and forward the exposed port 8000 to port 8000 on your local machine. After you run this command, you should be able to visit http://localhost:8000 in your browser.

You can see the Docker containers that are currently running on your system (along with their Container IDs) with:

To turn off your Docker container, run:

Push to cloud

1. Create your app

In order to install your docker php example, just create a new app via cli or admin panel and set a port to 8000.

2. Push your docker container

3. Set up resources

4. Logs and app status

5. Release your app

After to click on the release button, your php docker tutorial will be deployed, Just click on the generated URL and you will get your app running.

Phpstorm Docker Phpunit

Now you can deploy your php laravel app without a massive build time.

Bonus 1: SSL certificate for HTTPS

It's already done for you. If you need to connect your custom domain, SSL certificate will be provided for it.

Bonus 2: Autoscaling

With autoscaling the app will be scaled up when CPU and RAM load goes up and scaled down when it goes down.

Now you can deploy your php laravel app without a massive build time.

Creating a Simple Laravel Docker Environment

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
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

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.

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

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.

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!

Setting the laravel mysql environment variables

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)

Phpstorm Xdebug Docker Cli

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