Installing XDebug for an old version of PHP inside a Docker container

So, you’re given a Docker container with PHP 7.1.33, Alpine Linux, and Nginx, including an appropriate version of the php-devel or php-dev package. You want to install Xdebug inside the container, and these are the top three constraints in front of you:

1. You cannot rebuild the docker images being used for the container
2. You have a fairly stripped down version of Alpine Linux inside the container.
3. You don’t have convenient service management commands like systemctl, service, or rc-service.

Given the constraints, the options in front of you are as follows:

1. Install through PHP Extension Community Library (PECL)
2. Installation through Alpine Package Manager (apk)
3. Installation from Xdebug Source Code

Having exercised all the options, I can tell that the right way to install Xdebug for an old version of PHP is number 3 in the list above. Why not follow option 1 and 2 in the list above? When following option 1 or 2, you’re highly likely to encounter these errors, especially when you’re not using the latest versions of PHP:

Fig. 1. No such file or directory error

Fig. 2. Error relocating <library name>: symbol not found

1. Error loading shared library <library Name>: No such file or directory. You get this error when you specify the wrong path for the module file (the one with .so extension). You also get this error when the module is not where PHP is expecting it to be. Figure 1 above shows a concrete example of this error.
2. Failed loading </the/extension/path>: Error relocating </the/extension/path>: zend_hash_next_index_insert: symbol not found. Figure 2 above shows a concrete example of this error. I don’t exactly know the reason for this error, but it seems to be caused by the version mismatch among PHP and supported Xdebug.

Fig. 3. The mapping between PHP and supported Xdebug versions

Now that you’re ready to install Xdebug from source code, you need to decide the correct Xdebug version for your PHP version by following figure 3 above. The safest bet for PHP 7.1.33 is Xdebug version 2.9. You can download it from the XDebug: Historical Releases website. Follow the procedure outlined in the ‘compile’ and the ‘configure PHP’ sections.

These are the commands that might be helpful to you:

Fig 4. Swiss Army Knife for installing Xdebug inside a docker container

To summarise, you should install Xdebug from source code, especially if you’re not using the latest versions of PHP. When doing so, you should consult a compatibility matrix provided by Xdebug to choose a safe version. Apart from that, you might need to start or stop things in an unconventional manner when operating inside a constrained environment such as a docker container.