A ready-to-use PHP development environment with Docker, featuring PhpStorm integration and xDebug debugging support.

• Docker Desktop installed and running
• PhpStorm (optional, for debugging)

git clone [email protected]:jstormes/php-docker-quickstart.git
cd php-docker-quickstart
docker-compose up -d
docker-compose exec php-dev composer install

• Development server: http://localhost:8088
• Production like server: http://localhost:9088
• PhpMyAdmin: http://localhost:7088
• Command Line: docker-compose exec php-dev bash

php-docker-quickstart/
├── app/                         # Your PHP application code
│   └── public/                  # Web root directory
├── config/                      # Configuration files
│   └── docker/                  # Docker configuration files
│       ├── php.ini-development  # Development PHP configuration
│       ├── php.ini-production   # Production PHP configuration
│       └── xdebug_3.x.x.ini     # xDebug development settings
├── database/                    # Database initialization scripts
│   ├── 0_README.md              # Database setup documentation
│   └── 001_StartupTables.sql    # Initial database schema
├── xdebug.info/                 # xDebug profiling output directory
├── docker-compose.yml           # Main Docker configuration
├── Dockerfile                   # Docker image definition
├── README.md                    # This file
├── SETUP.md                     # Detailed setup guide
└── QUICK_REFERENCE.md           # Quick reference guide

• PHP 8.x with common extensions
• MariaDB database server
• PhpMyAdmin for database management
• Hot reload - code changes reflect immediately for Development server

• Host: localhost
• Port: 5000
• Username: root
• Password: password
• Database: app
• Initialization: Files in database/ directory

• Chrome: xDebug Helper
• Firefox: xDebug Helper
• Edge: xDebug Helper

• Set IDE key to: PHPSTORM
• Set Trace Trigger to: XDEBUG_TRACE
• Set Profile Trigger to: XDEBUG_PROFILE

1. Open Settings (Ctrl+Alt+S)
2. Go to Build, Execution, Deployment → Docker
3. Add Docker server with name: Docker

1. Click the bug icon in PhpStorm to start listening
2. Press Ctrl+Shift+X in browser and select "debug"
3. Set breakpoints in your PHP code
4. Refresh the page to trigger debugging

docker-compose -f docker-compose.yml up php-prod --build

1. Edit docker-compose.yml and update the image name:

   image: your-dockerid/yourimage

2. Push the image:

   docker compose push php-prod

To use private repositories inside the container:

1. Uncomment the secrets section in docker-compose.yml
2. Ensure your SSH keys are in ~/.ssh/ on your host machine
3. Test connection:

   docker-compose exec php-dev bash
   ssh [email protected]

To use AWS services inside the container:

1. Uncomment the AWS secrets in docker-compose.yml
2. Ensure your AWS credentials are in ~/.aws/ on your host machine
3. Uncomment "Install AWS-CLI" in the Dockerfile
4. Test connection:

   docker-compose exec php-dev bash
   aws sts get-caller-identity

This environment includes Claude Code CLI for AI-powered development assistance:

1. Uncomment the Claude secrets section in docker-compose.yml:

   secrets:
     claude-auth:
       file: ~/.claude/.credentials.json
     claude-cfg:
       file: ~/.claude.json

2. Uncomment the Claude secrets mapping in the php-dev service
3. (Optional) Set your Anthropic API key as an environment variable:

   export ANTHROPIC_API_KEY=your_api_key_here

4. Access Claude Code inside the development container:

   docker-compose exec php-dev bash
   claude

5. Claude Code can help with:
   • Code generation and refactoring
   • Debugging assistance
   • Code review and optimization
   • Documentation generation
   • Test writing and execution

This environment includes Gemini CLI for AI-powered development assistance:

1. Uncomment the Gemini secrets section in docker-compose.yml:

   secrets:
     gemini-auth:
       file: ~/.gemini

2. Uncomment the Gemini secrets mapping in the php-dev service

   secrets:
      - source: gemini-auth
        target: /home/user/.gemini.system

3. Access Gemini inside the development container:

   docker-compose exec php-dev bash
   gemini

# Start development environment
docker-compose up -d

# Stop all services
docker-compose down

# View logs
docker-compose logs php-dev

# Access container shell
docker-compose exec php-dev bash

# Rebuild containers
docker-compose up --build

If you get port conflicts, edit the ports in docker-compose.yml:

ports:
  - "8089:80"  # Change 8088 to another port

1. Ensure xDebug Helper extension is installed and configured
2. Check that PhpStorm is listening for connections
3. Verify the IDE key matches in both PhpStorm and browser extension

1. Ensure MariaDB container is running: docker-compose ps
2. Check database logs: docker-compose logs mariadb
3. Verify connection string in environment variables

• Docker Documentation
• xDebug Documentation
• PhpStorm Docker Integration
• Production Hosting Options
• Database Setup Guide

This project is a template. Feel free to fork and customize for your own projects.

Video Tutorial: PHP Docker Quickstart Setup