Some quick notes on setting up LocalWP on the Mac for debugging and profiling:
- nginx has an annoying habit of timing out early, so I generally use Apache for this and set the max_execution_time = 7200 (two hours is generally sufficient for a single debugging session)
- Start the IDE (phpstorm / IntelliJ) in the <site>/app/public folder (this is required so local knows where to update the config)
- In the Local app, install the xdebug extension if it’s not already installed, under “installed”, turn it on.
- In the site tools, select “XDebug + PHPStorm”, then click the green text “Add Run Configuration to PHPStorm” – this is actually an action button that does something.
- Restart Local and your IDE (not always necessary)
At this point, you should be able to go to index.php and click the “bug” button to start debugging the app. The important keys are F7 (step into) and F8 (step over) – these are the same as were available on Turbo Pascal/C “back in the day”, so if you started programming in the ’80s… this should feel familiar.
You can also learn a LOT about your code by just stepping through the functions and seeing what’s happening. I certainly learned quite a bit about WordPress internals this way.
For the mac, I’ve also gone into “System Preferences | Keyboard” and checked “Use F1, F2, etc. keys as standard function keys on the external keyboard” because I always program with the external keyboard attached. You can still hit the “Fn” key to use the special features, if necessary.
Another feature you can enable is profiling, looking at where time is spent. That plugin you just installed taking down your site? Find out why.
Open <site>/conf/php/php.ini.hbs (this is a templated php.ini that is parsed by Local before starting up)
Change / add the following two lines:
xdebug.profiler_enable=1
xdebug.profiler_output_dir=/tmp (feel free to use whatever directory you choose)
Now, go to the Local App and restart the site – this re-parses and reloads your config.
Now, whenever you browse the site, a profiler file (cachegrind.out.<pid>) is created.
To STOP profiling, you need to reverse the process, setting profiler_enable to 0 and restarting the site.
There is also a way to set up a “token” that starts the profiling, however, I never have been able to get this to work … would love some hints.
Once you have the cachegrind file, you can use “Tools | Analyze Xdebug Profiler Snapshot” to see the breakdown of your run.
Hint: if you open a cachegrind file, and see a lot of CLI lines, that’s Local doing its work and not an actual capture of your site’s profiling data. Move on to the next one.
Hope this helps save you a bit of time in setting up Xdebug for PHPStorm on Local.
(PHPStorm 2021.1 / Local 6.1.1 / August, 2021)