How to Debug a Laravel Project Using PhpStorm and Docker

The system has already been deployed to my customer since 2015. The system still works very well. But sometimes I still receive my customer call. I need to restore database data from my monthly backup to fix some issues. I need to trace the program logic to see what makes the issues happen. So I decided to use Docker to build a test environment.

Monthly Backup Action

Back up my Laravel website, because the user will add some photos.
Back up my database.

Docker environment composition

#docker-compose.yml
version: '3.8'

services:
  php:
    build:
      context: ./php
      dockerfile: Dockerfile
    container_name: laravel-php
    networks:
      - app-network
    command: php-fpm
    volumes:
      - ./ams:/var/www/ams
      - ./php/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
    extra_hosts:
      - "host.docker.internal:host-gateway"

  nginx:
    image: nginx:latest
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/sites-available/default:/etc/nginx/conf.d/default.conf:ro
      - ./ams:/var/www/ams
      - ./init.sh:/usr/local/bin/init.sh # 將腳本掛載到容器中
    ports:
      - "80:80"
    depends_on:
      - php
    networks:
      - app-network
    command: /bin/bash /usr/local/bin/init.sh  # 執行腳本

  db:
    image: mysql:5.7
    container_name: mysql-db
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: amsuser456
      MYSQL_DATABASE: AmsSchema
      MYSQL_USER: amsuser
      MYSQL_PASSWORD: amsuser456
    volumes:
      - db_data:/var/lib/mysql
      - ./db/my.conf:/etc/mysql/my.cnf
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - app-network
    ports:
      - "3306:3306"

networks:
  app-network:
    driver: bridge

volumes:
  db_data:

#php/Dockerfile
FROM php:5.6-fpm

# 替換過期的 apt 源，移除 stretch-updates
RUN sed -i 's|http://deb.debian.org/debian|http://archive.debian.org/debian|g' /etc/apt/sources.list && \
    sed -i '/stretch-updates/d' /etc/apt/sources.list && \
    sed -i '/security.debian.org/d' /etc/apt/sources.list && \
    echo 'Acquire::Check-Valid-Until \"false\";' > /etc/apt/apt.conf.d/99no-check-valid-until && \
    apt-get update

# 安裝系統依賴和 PHP 擴展
RUN apt-get install -y --allow-unauthenticated \
    libpng-dev libjpeg-dev libfreetype6-dev \
    zip unzip git curl wget vim \
    libmcrypt-dev libtool autoconf automake \
    && apt-get clean

# 手動安裝 Mcrypt for PHP 5.6
RUN mkdir -p /usr/src/php/ext/mcrypt && \
    curl -fsSL https://pecl.php.net/get/mcrypt-1.0.1.tgz | tar xvz -C /usr/src/php/ext/mcrypt --strip 1 && \
    docker-php-ext-install mcrypt

# 安裝 Xdebug (v2.5.5 is compatible with PHP 5.6)
RUN pecl install xdebug-2.5.5 \
    && docker-php-ext-enable xdebug

# 安裝其他 PHP 擴展
RUN docker-php-ext-configure gd --with-freetype --with-jpeg && \
    docker-php-ext-install -j$(nproc) gd pdo pdo_mysql mbstring exif opcache

# 安裝 Composer
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# 設定工作目錄
WORKDIR /var/www/ams

# 暴露 PHP-FPM 端口
EXPOSE 9000

# 設定容器啟動命令
CMD ["php-fpm"]

[Xdebug]
zend_extension=/usr/lib/php56/modules/xdebug.so
xdebug.idekey="PHPSTORM" ; CHANGE this key from "Code" to "PHPSTORM" for PhpStorm compatibility
xdebug.default_enable=on
xdebug.remote_enable=on
xdebug.remote_autostart=on
xdebug.remote_handler="dbgp"
xdebug.remote_port=9000    ; Default port for Xdebug 2 (PhpStorm must listen on 9000)

; *** Recommended fix for Docker connectivity ***
; Set the explicit host for the debugger.
; 'host.docker.internal' resolves to your host machine's IP address.
xdebug.remote_host=host.docker.internal

#init.sh
#!/bin/bash

# 修改文件和目錄權限
chown -R www-data:www-data /var/www/ams
find /var/www/ams -type d -exec chmod 755 {} \;
find /var/www/ams -type f -exec chmod 644 {} \;

# 啟動 Nginx
nginx -g 'daemon off;'

#init.sql
-- Initialize MySQL tables if missing
CREATE DATABASE IF NOT EXISTS AmsSchema;
CREATE USER IF NOT EXISTS 'amsuser'@'%' IDENTIFIED BY 'amsuser456';
GRANT ALL PRIVILEGES ON AmsSchema.* TO 'amsuser'@'%';
FLUSH PRIVILEGES;

#my.conf
[mysqld]
bind-address = 0.0.0.0
default_authentication_plugin = mysql_native_password
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
max_connections = 200
innodb_buffer_pool_size = 256M
innodb_log_file_size = 64M
sql_mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"