FEATURE: Support Xdebug Native Path Mapping

[jrenggli]

Is there an existing issue for this?

• [x] I have searched the existing issues

Description

Flow relies heavily on Proxy Classes, which complicates debugging and intercepting traffic using traditional tools. To address this, developers have previously used the Flow Debug Proxy as a workaround.

In February 2024, Robert Lemke initiated a funding request to support Derick Rethans, the author of Xdebug, in developing native path mapping support. The goal: significantly improve the debugging experience for Flow and Neos developers.

This is one of the most requested improvements related to testing and debugging Flow. A long time after I first discussed this with Derick, we now finally have the chance to make it happen.

As of May 2025, Derick has released an update titled "Finishing the Initial Preview", indicating substantial progress on this feature.

As far as I see, there have been no visible efforts from the Neos community to prepare Flow for adoption of this feature once it's officially released.

After experimenting with recent Xdebug builds and the Flow Proxy Compiler, I can confirm that the native path mapping feature works as expected in my local setup.

IMHO we need to do the following steps:

• Implement a builder for path maps directly in the Neos Flow core.
• Update documentation, write tutorials
• Testing, Testing, Testing...

If this initiative is already being tracked elsewhere—apologies for the redundancy. At the very least, I hope this post helps centralize the conversation and points interested developers toward the right direction.

Possible Solution

No response

[jrenggli]

The following content is just a dump of all the steps necessary to make Xdebug Native Path Mapping available on "my machine".

Build and install xdebug development version

I'm using DDEV here

ENV XDEBUG_REPOSITORY=https://github.com/derickr/xdebug.git
ENV XDEBUG_REF=001-native-path-mapping
RUN cd /opt \
    && apt-get update \
    && apt-get install --yes php${DDEV_PHP_VERSION}-dev build-essential \
    && git clone --depth=1 ${XDEBUG_REPOSITORY} --branch ${XDEBUG_REF} \
    && cd /opt/xdebug \
    && sed -i '/fprintf/d' ./src/lib/maps/maps.c \
    && phpize${DDEV_PHP_VERSION} \
    && ./configure --enable-xdebug \
    && make \
    && make install \
    && echo -e "\nxdebug.path_mapping=yes\n" >> /etc/php/${DDEV_PHP_VERSION}/mods-available/xdebug.ini

Patch Proxy Compiler

Neos\Flow\ObjectManagement\Proxy\Compiler

Probably this code could be invoked via Signal Slot. But this is not working here as Compiler is not proxied (@Flow\Proxy(false)) and therefore the annotation @Flow\Signal from emitCompiledClasses() not evaluated. As this is not working atm we could discuss about changing the signature and sending a map instead of just an array.

public function compile()
      ...
      $classNameLocalRemoteClassMap = [];
      ...

         $classNameLocalRemoteClassMap[$fullOriginalClassName] = $classPathAndFilename;

      ...

        if ($classNameLocalRemoteClassMap !== []) {
            $cacheDirectory = $this->classesCache->getBackend()?->getCacheDirectory();

            $localRemoteMapContent = '';
            foreach ($classNameLocalRemoteClassMap as $className => $localRemoteClass) {
                $localRemoteMapContent .= sprintf(
                    "%s%s = %s\n",
                    $cacheDirectory,
                    str_replace('\\', '_', $className) . '.php',
                    $localRemoteClass
                );
            }

            Files::createDirectoryRecursively('.xdebug');
            file_put_contents(
                '.xdebug/flow.map',
                $localRemoteMapContent
            );
        }

Debugging

After clearing cache and warming up Neos it just worked.

rm -rf Data/Temporary/
./flow cache:warmup

[kaystrobach]

Would love to see this i a debug package, which can be installed as dev dependency. Then we could optimize that further independent from flow itself.

But this still needs to be prepared in the compile code as stated above.

[bwaidelich]

Dereks Teaser Video made me wonder: Would it be possible to debug Fusion code even? 🤯

[kaystrobach]

Yes fluid, fusion, you name it

[robinroloff]

That would be awesome of course, but php debugging would be a good start :D

[kaystrobach]

For sure. To solve it for now i would use the following approach:

Composer patches to inject the minimal needed entrypoint to trigger the generation. Otherwise i would need to find a way to do the same like compiling, but with a different command.

To make this easy this can be wrapped in a command to modify composer.json. Same goes for ddev config, can be „delivered“ via command.