Fixing: pecl/xdebug requires PHP (version >= 8.0.0, version <= 8.2.99), installed version is 7.4.33

Summary

Installing Xdebug on PHP7.4 returns an error stating "pecl/xdebug requires PHP (version >= 8.0.0, version <= 8.2.99), installed version is 7.4.33". This can be replicated using a docker container as shown in the example below.

chris@chris-xps:~$ docker run --rm -it php:7.4 bash
root@8036afe9b83b:/# pecl install xdebug
pecl/xdebug requires PHP (version >= 8.0.0, version <= 8.2.99), installed version is 7.4.33
No valid packages found
install failed
root@8036afe9b83b:/#

Reason

At the time of writing, Xdebug 3.2 is the latest stable version and PECL will attempt to install this, however, Xdebug 3.2 requires at least PHP 8 or later. As a result, trying to install this on a PHP version lower than this results in this error. There are 2 possible solutions to this

• Upgrade to PHP8
• Install an earlier version of Xdebug i.e. 3.1.5

Solution 1: Upgrade to PHP 8

This would be the recommended option, if available. Upgrading will allow the benefit of Xdebug 3.2 but likely a host of other fixes and performance improvements as a by product.

Start PHP 8 container and install Xdebug

chris@chris-xps:~$ docker run --rm -it php:8 bash
root@cf1d7bb26c64:/# pecl install xdebug

...
...  output from build steps ...
...

Build process completed successfully
Installing '/usr/local/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so'
install ok: channel://pecl.php.net/xdebug-3.2.0
configuration option "php_ini" is not set to php.ini location
You should add "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so" to php.ini

Enable xdebug

root@cf1d7bb26c64:/# docker-php-ext-enable xdebug

Check Xdebug is installed and running

root@cf1d7bb26c64:/# php -v
PHP 8.2.1 (cli) (built: Jan  5 2023 23:22:41) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.1, Copyright (c) Zend Technologies
    with Xdebug v3.2.0, Copyright (c) 2002-2022, by Derick Rethans

Solution 2: Install older version of xdebug 3.1.5

If upgrading to PHP8 is not an option, you can install an earlier version of Xdebug onto your PHP7 environment

Start PHP 7.4 container and install Xdebug

chris@chris-xps:~$ docker run --rm -it php:7.4 bash
root@aeb100b038dd:/# pecl install xdebug-3.1.5

...
...  output from build steps ...
...

Build process completed successfully
Installing '/usr/local/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so'
install ok: channel://pecl.php.net/xdebug-3.1.5
configuration option "php_ini" is not set to php.ini location
You should add "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so" to php.ini

Enable xdebug

root@aeb100b038dd:/# docker-php-ext-enable xdebug

Check xdebug is installed and running

root@aeb100b038dd:/# php -v
PHP 7.4.33 (cli) (built: Nov 15 2022 06:01:17) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Xdebug v3.1.5, Copyright (c) 2002-2022, by Derick Rethans

References

• Xdebug - Supported Versions and Compatibility - https://xdebug.org/docs/compat

Originally published at https://chrisshennan.com/blog/fixing-pecl-xdebug-requires-php-version-8-installed-version-7-4