DataMates Studio

Digital Pipeline Development Services

Step 5 – Configure PHP Remote Debug with IDE Key

Configure PHP Remote Debug with IDE Key on Your Personal Computer.

Prerequisite

You are working through Step Debugging PHP on Your Personal Computer.

✅ Installed Chrome web browser.
✅ Installed Xdebug Chrome Extension in your Chrome web browser.
✅ Installed WPEngine LocalWP 9.x (Lightning) application.
✅ Installed JetBrains IntelliJ IDEA 2022.x with PHP plugin; or PHP Storm is working.

✅ Ensured LocalWP has a ‘Local Site’. Use [Add a Local Site] button or Import/Export.
✅ Ensured LocalWP -> ‘Local Sites’ -> ‘{LocalWebsite}’ has ‘Xdebug’ option turned ‘On’.
✅ Ensured LocalWP -> ‘Local Sites’ -> ‘{LocalWebsite}’ is alive. Use [Start Site] button.
✅ Ensured Chrome web browser can show the ‘{LocalWebsite}’. Use [Open Site] button.

✅ Ensured Test Incoming PHP Debug Connection to JetBrains IntelliJ is working.

Configure LocalWP Xdebug Trigger for Local Website

Objective: To ensure the LocalWP website is configured to respond to Xdebug Chrome Extension requests, properly.

Hint: Written for Xdebug Chrome Extension (by gxumyd / mydogger).

Hint: Written for WPEngine LocalWP 9.x (Lightning).

Hint: Written for JetBrains IntelliJ IDEA 2022.x (Ultimate Edition).

  1. Start LocalWP application.
    • Navigate to ‘Local Sites’ -> ‘{LocalWebsite}’.
    • Click ‘Stop Site’ button.
      • Hint: The local website server services will be stopped.
    • Click ‘Site Folder’ button.
      • Hint: The system default file manager will be started; like Windows File Explorer, MacOS Finder, etc.
      • Hint: The default directory being shown should be the exact location of the local website, on your personal computer.
      • Hint: This local website source code is used to deliver web page content to a web browser.
      • Hint: This local website source code is used during a PHP debug session.
  2. In the File application.
    • Navigate down into the ./conf/php/ directory.
    • Right-Click on the php.ini.hbs file to show the popup menu.
    • Select ‘Open With’ option.
    • Select any Text Editor application.
  3. In any Text Editor application, to respond to Remote Debug requests.
    • Scroll to the bottom of the file content and find this configuration option.
      • xdebug.start_with_request=yes
    • Change that configuration option to be a trigger.
      • xdebug.start_with_request=trigger
    • Add a new configuration option just below it, on a new line.
      • Beginner Scenario: Use single IDE Key (PHPSTORM).
        • xdebug.trigger_value=PHPSTORM
      • Advanced Scenario: Use unique IDE Key for your {LocalWebsite}.
        • xdebug.trigger_value={LocalWebsite}
        • Recommend: {LocalWebsite} is a string placeholder that should be the LocalWP ‘Site Domain’ name for consistency across the applications allowing the individual debugging sessions to recognise their unique IDE Key.
    • [Optional] Do you want to create an xdebug.log file?
      • Add a new configuration option just below it, on a new line.
        • Beginner Scenario: Use level 1 for ‘Connection Errors’.
          • xdebug.log_level=1
        • Advanced Scenario: Use level 3 for ‘Connection Warnings’.
          • xdebug.log_level=3
      • Add a new configuration option just below it, on a new line.
        • xdebug.log={FQOSFN}
        • Hint: Fully Qualified Operating System File Name (FQOSFN) includes the full path from the hard drive root directory.
        • Recommend: Use the same directory as php error log file.
        • Example: /Users/john.lang/Documents/myDevelopment/LocalWP/blanky-001/logs/php/xdebug.log
    • Save and close the text file.
  4. In the LocalWP application.
    • Navigate to ‘Local Sites’ -> ‘{LocalWebsite}’.
    • Click ‘Start Site’ button.
      • Hint: If it already says ‘Stop Site’, because you missed the first step above, then be sure to do both ‘Stop Site’ and ‘Start Site’ actions.
      • Hint: The local website server services will be started, and use the new Xdebug configuration in ./conf/php/php.ini.hbs file.
  5. Done.

Create IntelliJ Project for Local Website

Objective: To create a new JetBrains IntelliJ Project in the local website source code directory, for easier PHP debug sessions and code development.

Hint: Written for WPEngine LocalWP 9.x (Lightning).

Hint: Written for JetBrains IntelliJ IDEA 2022.x (Ultimate Edition).

  1. Start LocalWP application.
    • Navigate to ‘Local Sites’ -> ‘{LocalWebsite}’.
    • Click ‘Site Folder’ button.
      • Hint: The system default file manager will be started; like Windows File Explorer, MacOS Finder, etc.
      • Hint: The default directory being shown should be the exact location of the local website, on your personal computer.
      • Hint: This local website source code is used to deliver web page content to a web browser.
      • Hint: This local website source code is used during a PHP debug session.
  2. In the File application.
    • Navigate up one directory level to show the parent directory.
    • Right-Click on the parent directory to show the popup menu.
    • Select ‘Open With’ option.
    • Select the JetBrains IntelliJ application.
      • Hint: The JetBrains IntelliJ application will be started, with a new project using the local website directory (aka Server Root) as the project directory (aka Project Root).
      • Hint: A new ‘.idea’ folder will be created. This is where the JetBrains IntelliJ application project configuration will be stored.
  3. In the JetBrains IntelliJ application.
    • Navigate to ‘File’ menu -> ‘Close Project’ option.
      • Hint: It shows the ‘Welcome to IntelliJ’ window.
    • Notice the ‘Projects’ sidebar has the local website project.
      • Hint: Thie will make it easier to open, next time.
    • Close JetBrains IntelliJ application.
  4. Switch to LocalWP application.
    • Close LocalWP application.
  5. Done.

Configure a PHP Server in IntelliJ for Local Website

Objective: To create a JetBrains IntelliJ project local server reference to identify the local domain of the local website.

Prerequisite: Done LocalWP applicaton configuration for local website.
Prerequisite: Create IntelliJ Project for Local Website.

Hint: The local server reference will be used by other project settings; like a PHP Remote Debug Configuration.

Hint: Written for WPEngine LocalWP 9.x (Lightning).

Hint: Written for JetBrains IntelliJ IDEA 2022.x (Ultimate Edition).

  1. Start JetBrains IntelliJ application.
  2. Open the Project for the local website.
  3. Navigate to ‘IntelliJ IDEA’ menu -> ‘Settings’.
  4. Navigate to ‘Languages & Frameworks’ sidebar -> ‘PHP’ -> ‘Servers’.
  5. Click [+] button to add a new server.
  6. Enter a ‘Name’ for the PHP server.
    • Hint: Use the ‘LocalWP’ application -> ‘Local Sites’ -> ‘{LocalWebsite}’ -> ‘Site Domain’ for consistency.
    • Hint: It can be useful to add the port to the name. Use ‘{name}:{port}’ convention. For a local website called ‘Blanky-001’, the name would be ‘blanky-001.local:9003’ for that specific website server name within IntelliJ Server list.
  7. Enter a ‘Host’ for the PHP server.
    • Hint: Use the ‘LocalWP’ application -> ‘Local Sites’ -> ‘{LocalWebsite}’ -> ‘Site Domain’ for consistency.
    • Hint: Occassionally, it can be useful to use the more generic host ‘localhost’ name and rely on the port number to identify the website. However, the recommendation is still to use the ‘Site Domain’ as it makes troubleshooting a lot easier because each sep in the Xdebug journey is more clearly self-documented at what it is for and doing.
  8. Enter ‘9003’ in ‘Port’ option.
    • Hint: The 9003 port number can be double-checked while troubleshooting, by looking for the xdebug.client_port= option within the ./conf/php/php.ini.hbs configuration file. If it is different, use that xdebug.client_port number here, in the IntelliJ Server port setting.
  9. Select ‘Xdebug’ in ‘Debugger’ option.
  10. Untick ‘Use Path Mapping’ option.
    • Hint: This assumes that the code development project directory (aka Project Root) is also the exact same ‘LocalWP’ application -> ‘Local Sites’ -> ‘{LocalWebsite}’ -> ‘Site Folder’ directory (aka Server Root).
  11. Click [Ok] button.
  12. Done.

Configure a PHP Remote Debug Configuration in IntelliJ for Local Website

Objective: To create a JetBrains IntelliJ project run/debug configuration for PHP Remote Debug sessions to identify the local domain of the local website.

Prerequisite: Done LocalWP applicaton configuration for local website.
Prerequisite: Configure PHP Server in IntelliJ for Local Website.

Hint: The PHP Remote Debug Configuration can be used offline, not connected to the internet; because your personal computer is the server and the client, for the local website.

Hint: Written for WPEngine LocalWP 9.x (Lightning).

Hint: Written for JetBrains IntelliJ IDEA 2022.x (Ultimate Edition).

  1. Start JetBrains IntelliJ application.
  2. Open the Project for the local website.
  3. Navigate to ‘Run’ menu -> ‘Edit Configurations’.
  4. Click [+] button to add a new configuration.
  5. Select ‘PHP Remote Debug’ dropdown option.
  6. Enter a ‘Name’ for the PHP Remote Debug configuration.
    • Hint: Use the ‘LocalWP’ application -> ‘Local Sites’ -> ‘{LocalWebsite}’ -> ‘Site Domain’ for consistency.
  7. Untick ‘Allow Parallel Run’ option.
  8. Untick ‘Store as Project File’ option.
  9. Tick ‘Filter Debug Connection by IDE Key’ option.
  10. Select the local website PHP Server in the ‘Server’ dropdown option.
  11. Enter ‘PHPSTORM’ in ‘IDE Key (Session ID)’ option.
    • Hint: PHPSTORM is just a common string identifer used as a default value by a few debug applications.
    • Hint: We are using PHPSTORM, in these instructions, to simplify the default integration with the Xdebug Chrome Extension; only while we get familuar with the whole PHP Step Debug end-to-end process.
    • Hint: In the future, when you have many local websites on your personal computer, and have multiple JetBrains IntelliJ project open at the same time … then you would want to use a different and unique ‘IDE Key (Session ID)’ in each project. Then you only need to change the Xdebug Chrome Extension option to match the target IntelliJ project you are focused on; without having to close all the other IntelliJ projects.
  12. Untick ‘Show this Page’ option.
  13. Tick ‘Activate Tool Window’ option.
  14. Click [Ok] button.
  15. Done.
[Next] Start PHP Remote Debug Session in JetBrains IDE
[Overview] Step Debugging PHP on Your Personal Computer