Debugging PHP library code with xdebug from PhpStorm when the code is executing on a virtual machine

Question

I have code on my local machine which IntelliJ / PhpStorm can see, and I have the same code executing inside Apache on a virtual machine.

I have remote debugging working fine and hitting breakpoints when I hit my CodeIgniter controller using zero configuration remote debugging. But, when I try to step into code that uses a require_once(), the breakpoint doesn't get hit.

It looks to be something like path mapping issues.

The local directory layout is along these lines:

- root_directory
  - libraries_named_differently
  - calling_code_same_name

The virtual machine directory layout is along these lines:

- root_directory
  - libraries_with_a_different_name
  - calling_code_same_name

I wonder if the libraries folder having a different name on the virtual machine and locally is causing any path mapping issues.

I highly doubt this has anything to do with CodeIgniter by the way.

For example, in a CodeIgniter controller where breakpoints are working fine, I load a library using:

require_once('/var/www/libraries/ClassExample.php');

Then I have a controller method in CodeIgniter like this:

public function endpoint {
   $hello = 'world';  // debugger works here, breakpoint hit
   $instance = new ClassExample();
   $instance->someMethod(); // <-- the debugger does not hit breakpoints inside someMethod, although I can see them being executed in the call stack view inside IntelliJ.
}

The path /var/www/libraries does not exist on my local machine, only on the virtual machine.

I thought a symlink from where my libraries directory is on my local machine to the /var/www/libraries directory would solve it, but it did not.

How can I get these breakpoints to activate in my other dependent projects?