Cloud 8.03

Debug with XDebug

Understanding XDebug configuration, SSH tunnels, path mapping, and debugging workflows on Cloud.

Exam Critical: Understanding how to configure XDebug on Cloud, including path mapping and SSH tunnels, is important for the exam!

Debug with XDebug

mindmap root((XDebug Setup)) Step 1 PHP extensions Include xdebug Deploy changes Step 2 PHPStorm config Path mapping app directory Step 3 SSH tunnel Port forwarding 9000 to 9090 Step 4 Xdebug helper IDE key Enable listening Step 5 Browser extension Refresh page Debug session

XDebug on Cloud Overview

What is XDebug?

Purpose

XDebug is a powerful debugging and profiling tool for PHP that allows you to:

  • Set breakpoints in code
  • Step through execution line by line
  • Inspect variables and their values
  • Track function calls and stack traces
  • Profile performance bottlenecks

Critical Warning

It goes without saying that you shouldn't use this in production.

Why Not Production?
  • Significant performance overhead
  • Security risk (exposes code paths)
  • Can cause timeouts and memory issues
  • Affects all users on the environment

Best Practice: Debug on Integration Branch

Instead, sync data and code from the master branch to a new integration branch and debug there.

Workflow:
  1. Create new integration branch from master
  2. Sync database from production/staging
  3. Configure XDebug on integration branch
  4. Debug issues safely
  5. Fix code and deploy to production

Configuration Requirements

What You'll Need

This requires a good deal of configuration, but it is quite worth it if you have major problems to troubleshoot.

Component Purpose Configuration Required
Cloud Environment XDebug PHP extension enabled .magento.app.yaml modification
PHPStorm IDE debugging interface Path mapping, server config
SSH Tunnel Connect IDE to Cloud Port forwarding setup
Browser Extension Trigger debug sessions Xdebug Helper, IDE key

Step 1: Include XDebug in PHP Extensions

Enable XDebug Extension

First Step

You must include xdebug in the PHP extensions and deploy.

Modify .magento.app.yaml

.magento.app.yaml
runtime:
    extensions:
        - redis
        - xsl
        - newrelic
        - sodium
        - xdebug
Important Note:

Remember that these changes affect everything but Pro staging and production environments.

  • Starter: All environments (master, integration branches)
  • Pro: Integration environments only
  • Pro Staging/Production: NOT affected (good for safety!)

Deploy Changes

git add .magento.app.yaml
git commit -m "Enable XDebug for debugging"
git push origin integration-debug

After deployment, XDebug extension will be available in the environment. This triggers a full rebuild of the environment.

Step 2: Configure PHPStorm

IDE Path Mapping Setup

Second Step

You must configure PHPStorm with proper path mapping.

Path Mapping Basics

What is Path Mapping?

Path mapping basically is mapping the root project directory to the /app directory.

Directory Mapping:
  • Starter & Pro Integration: Local root → /app
  • Pro Production: Local root → /app/{PROJECT}
  • Pro Staging: Local root → /app/{PROJECT}_stg

PHPStorm Configuration Steps

1. Add Server Configuration
  1. Go to Settings → PHP → Servers
  2. Click + to add new server
  3. Enter server details:
    • Name: Cloud Debug (or your choice)
    • Host: Your Cloud environment URL
    • Port: 80 or 443
    • Debugger: Xdebug
  4. Check "Use path mappings"
2. Configure Path Mappings
Environment Local Path Remote Path
Starter / Pro Integration /path/to/local/project /app
Pro Production /path/to/local/project /app/abc123xyz
Pro Staging /path/to/local/project /app/abc123xyz_stg
3. Set Debug Configuration
  1. Go to Settings → PHP → Debug
  2. Set Debug port: 9000 (or your chosen port)
  3. Ensure "Can accept external connections" is checked
  4. Set Max simultaneous connections: 5

Step 3: Establish SSH Tunnel

Port Forwarding Setup

Third Step

You must establish the SSH tunnel to connect PHPStorm to Cloud.

SSH Tunnel Command

Terminal / Command Line
ssh -R 9000:localhost:9090 ssh-path--mymagento@ssh.us-4.magento.cloud
Command Breakdown:
  • ssh -R - Reverse port forwarding
  • 9000 - Port number on the server (Cloud environment)
  • localhost:9090 - Local port number (as configured in PHPStorm)
  • ssh-path--mymagento@ssh.us-4.magento.cloud - Cloud SSH connection string

Port Numbers Explained

Understanding the Ports:
  • First port (9000): Port on Cloud environment where XDebug sends data
  • Second port (9090): Local port where PHPStorm listens
  • Must match PHPStorm debug configuration
  • Tunnels XDebug data from Cloud to your local IDE

Getting SSH Connection String

# Get SSH access information
magento-cloud ssh --info -e integration-debug

# Or connect directly
magento-cloud ssh -e integration-debug

Full Example

# Example for integration branch
ssh -R 9000:localhost:9090 abcdefg123-integration-xyz123--mymagento@ssh.us-4.magento.cloud

# Keep this terminal window open during debugging session!
Important!

Keep the SSH tunnel terminal window OPEN during your entire debugging session. Closing it will break the connection.

Step 4: Install Xdebug Helper & Set IDE Key

Browser Extension Setup

Fourth Step

Install the Xdebug helper (and set the correct IDE key).

1. Install Browser Extension

Xdebug Helper Extensions:
  • Chrome: Xdebug Helper
  • Firefox: Xdebug Helper
  • Edge: Xdebug Helper for Microsoft Edge

Search for "Xdebug Helper" in your browser's extension store.

2. Configure IDE Key

Set IDE Key in Extension:
  1. Click Xdebug Helper icon in browser
  2. Click Options
  3. Set IDE key: PHPSTORM
  4. Save settings
Common IDE Keys:
  • PHPStorm: PHPSTORM
  • VS Code: VSCODE
  • Sublime: sublime.xdebug

3. Enable Listening in PHPStorm

Enable Listening for PHP Connections
  1. In PHPStorm, click the "Start Listening for PHP Debug Connections" button (phone icon in toolbar)
  2. Icon should turn green when listening
  3. Set breakpoint: Click in gutter next to line number
  4. Configure to "start at first line" if needed

Step 5: Enable XDebug in Browser

Start Debugging Session

Final Step

Enable Xdebug in the browser and refresh the page.

Activate Debugging

  1. Navigate to the Cloud environment URL in browser
  2. Click Xdebug Helper icon in toolbar
  3. Select "Debug" (turns icon green)
  4. Refresh the page
  5. PHPStorm should now catch the breakpoint!
Success Indicators:
  • PHPStorm opens debugger panel
  • Shows current file and line
  • Variables panel displays values
  • Can step through code (F8, F7, F9)

Complete Step-by-Step Summary

Five Steps to XDebug on Cloud

Step Action Key Details
1 Include xdebug in PHP extensions Modify .magento.app.yaml, deploy (not on Pro staging/prod)
2 Configure PHPStorm Path mapping: root → /app (or /app/{PROJECT} for Pro)
3 Establish SSH tunnel ssh -R 9000:localhost:9090 [SSH_PATH]
4 Install Xdebug helper Set IDE key (PHPSTORM), enable listening
5 Enable in browser Activate debug mode, refresh page

Troubleshooting Resources

Official Documentation

Further Reading:

  • View logs for troubleshooting
  • Project structure
  • Pro Project log locations
  • Starter Project log locations
  • Troubleshooting

Common Issues and Solutions

Debugging XDebug Setup

Issue 1: PHPStorm Not Catching Breakpoint

Possible Causes:
  • SSH tunnel not established or closed
  • Wrong port numbers in tunnel or PHPStorm
  • Path mapping incorrect
  • IDE key mismatch
Solution:
  1. Verify SSH tunnel is active (keep terminal open)
  2. Check ports: 9000 on server, 9090 in PHPStorm
  3. Verify path mapping: local root → /app
  4. Confirm IDE key is PHPSTORM
  5. Restart listening in PHPStorm

Issue 2: XDebug Not Enabled After Deploy

Solution:
  1. Verify .magento.app.yaml includes xdebug in extensions
  2. Confirm deployment completed successfully
  3. SSH to environment and check: php -m | grep xdebug
  4. If not listed, redeploy with blank commit

Issue 3: Connection Timeouts

Solution:
  • XDebug can slow execution significantly
  • Increase max_execution_time if needed
  • Don't debug heavy processes (imports, reindex)
  • Use on integration only, never production

Best Practices

XDebug Usage Guidelines

Do's

  • Use integration branch: Never on production
  • Sync production data: Debug with real data
  • Keep SSH tunnel open: During entire session
  • Remove XDebug after debugging: Don't leave enabled
  • Document configuration: For team members
  • Test fixes without XDebug: Verify performance

Don'ts

  • Don't use in production: Performance and security risk
  • Don't leave enabled: Remove after debugging
  • Don't debug heavy operations: Will timeout
  • Don't forget path mapping: Won't work without it
  • Don't close SSH tunnel: Breaks connection

Practical Experience

Hands-On Exercise

Required Practice:

Configure and execute a Xdebug session

Exercise Steps:

  1. Create new integration branch for debugging
  2. Add xdebug to .magento.app.yaml extensions
  3. Deploy and wait for completion
  4. Configure PHPStorm with path mapping
  5. Establish SSH tunnel
  6. Install browser extension and set IDE key
  7. Set breakpoint in controller or block class
  8. Enable listening in PHPStorm
  9. Enable debug in browser
  10. Navigate to page and hit breakpoint
  11. Step through code, inspect variables
  12. Fix issue and verify

Exam Tips

Key Points to Remember

  • Don't use in production: Performance and security risk
  • Debug on integration branch: Sync data from master/production
  • Step 1: Include xdebug in PHP extensions (.magento.app.yaml)
  • Affects integration only: Not Pro staging/production
  • Step 2: Configure PHPStorm with path mapping
  • Path mapping: Root → /app (or /app/{PROJECT} for Pro)
  • Pro staging: /app/{PROJECT}_stg
  • Step 3: Establish SSH tunnel (ssh -R)
  • Port numbers: First = server (9000), Second = local (9090)
  • Step 4: Install Xdebug helper, set IDE key (PHPSTORM)
  • Step 5: Enable in browser, refresh page
  • Keep SSH tunnel open: During entire debug session
  • Five steps: Extensions, PHPStorm, SSH tunnel, Helper, Browser
Previous: Cloud 8.02 Snapshots and Backups Practice Cloud 8.03