DataMates Studio

Step 1 – Install Local Applications

You should only need to install these once, for your operating system user.

Step 2 – Install Xdebug Chrome Extension

You should only need to set this up once, for your operating system user.

Step 3 – Learn Xdebug 3 with Derick Rethans

Want to understand more about Xdebug for PHP?

For an overview or a deep dive under the hood?

Derick Rethans, the author of Xdebug, has a Learning Xdebug 3 [YouTube] playlist.

Then come back here to continue the step-by-step walk through, to setup you local PHP step debugging environment on your personal computer.

Step 4 – Test LocalWP and JetBrains IDE with Xdebug

You should only need to test this once, for your operating system user.

Use step 4 to prove that all 3 applications used in a debug session, are talking together.

Xdebug Chrome Extension -> LocalWP website -> Coding IDE application

JetBrains coding IDE will use a new temporary project to listen for global debug sessions.

Online Help: Visit LocalWP Step Debug Troubleshooting to learn about using xdebug.log to find out where the debug session communication is not aligned properly. Often it can be as simple as ‘using the wrong port’ or ‘ports are fine but theres no talking; because a local firewall is blocking it’.

If step 5 stops working, come back to step 4 to remove the complexity of using unique IDE Keys. Going back-to-basics to explore where the debug session communication is blocked.

Step 5 – Configure PHP Remote Debug with IDE Key

You should only need to configure each website once, for your operating system user.

Beginner Scenario: Use a single IDE Key, like PHPSTORM, everywhere.

Advanced Scenario: Use step 5 to advance your debug session experience by using unique IDE Keys. The primary benefit is to have 2 or more local websites up and running on your personal computer, while the debug sessions leverage unique IDE Keys to debug a single website.

Advanced Benefit: The significant benefit of using unique IDE Keys for each local website, over time appears when you have dozens of local websites with a few running to form an integrated local network of services.

Advanced Opnion: Now your debug session can be conducted with a bit more confidence and less confusion because you know exactly which live-debug session you are performing. In turn, this unique IDE Key approach sets the foundation for running 2 coding IDE applications at the same time … if you want to live debug both sides of a local website-to-website conversation, at the same time on your local computer while offline and disconnected from the internet.

Advanced Recommendation: Use the LocalWP -> ‘Local Sites’ -> ‘Overview’ -> {siteDomain} of each website as the unique IDE Key string for each website. The unique IDE Key then gets configured into its respective website php.ini file.

Advanced Sessions: Each debug session then only has to ensure that the unique IDE Key is in the Xdebug Chrome Extension to trigger a debug session, and in the coding IDE to listen from that same unique IDE Key. Step 5 has the full details.

Step 6 – Start PHP Remote Debug Session in JetBrains IDE

This documentation is used for each debug session; provided all of the above prerequisite actions are done, for your operating system user.

The objective is to refresh a web browser page for a local website, have it start a forever-load because it looks like it not responding. Then switch over to the Jetbrains IDE where a PHP remote debugging session should be waiting for you to start stepping through the PHP code as it builds the output to send back to the web browser as the page content.

Hint: Often the debug session will take longer than the web browser wants to wait for. It will timeout and show the page as an error. This is ok. Nothing is broken.

A PHP debugging technique is to use Breakpoints [CMD+F8], while you explore the running code using Step Into [F7] and Step Over [F8]. I like to think of code breakpoints to be a bit like a mountain climbers spike (Piton, Pin, Peg) that they place along the way, to make it more easy to come back to that point.

Your first page load allowed you to explore a few aspects of the code. You would set breakpoints at convient points further into the runtime execution than were you started. Finish debugging that page. The goal was to become more familiar with the runtime code flow sequence; you did that, but now you have more questions.

Now refresh the web browser page again and instead of stepping through the code, you can Run [CTRL+OPT+R] it until it hits any breakpoint. It is literally a runtime fast-forward to any breakpoint it encounters. If it completes without stopping at any breakpoint then there is a good chance it is not broken, you are not crazy, the code just did not follow the same code flow sequence this time.

You can try setting breakpoints earlier in the code flow sequence to see where it behaved differently each time you refreshed the web browser page. The different behaviour could be for all sorts of reasons … like background cron triggers, a plugin, a theme, a decision key is not granular enough (like using hours for a key when it should be nano-seconds) or business rules that only allow an action to be done once (and every subsequent web browser page is the 3rd, 4th, 5th redundant action that gets ignored). Keep exploring the code, you should eventually find the answer.

Remember: To start a PHP remote debug session, the 3 applications (Xdebug Chrome Extension, LocalWP & JetBrains IDE) need to be alive and available, with their configuration aligned, for a PHP remote debug session to work.

Troubleshooting 1: Go back to step 5 and confirm the IDE Key is configured properly in all 3 applications. Also, ensure the xdebug.client_port number is consistently used in step 5.

Troubleshooting 2: Go back to step 4 and confirm a global debug session to listen on all ports is working.

Troubleshooting 3: Disconnect from the internet (temporarily) and then disable all your virus scanners and operating system firewall applications; as they may be blocking local traffic from your personal computer to your personal computer. Remember to turn them all back on before you reconnect to the internet.

Troubleshooting 4: Visit LocalWP Step Debug Troubleshooting to learn about using xdebug.log to find out where the debug session communication is not aligned properly.

Troubleshooting 5: Consider joining the LocalWP Community forum. Search for xdebug articles and ask questions if you still can not find the answer.

Happy debugging. 🖖

What is stopping you from having the development environment you desire?