Some time it may require users to have modules like xdebug on their hosted app. By default, xdebug module is not avail in the PHP app due to security & performance reasons.

To work around this you will need to build your entire web stack from source (including PHP and Nginx) and then build xdebug against that and enable it in your own php.ini.

This post deals with workaround on getting xdebug enabled for your PHP app. Hope this may be useful for future readers (and future me as well) .

In short:

Need to build entire web stack from source (including PHP and Nginx/Apache)
Run a private PHP-FPM stack on Nginx or Apache
Build xdebug against that and enable it in your own php.ini
Validate the config

Detailed steps

1a Building PHP

wget https://www.php.net/distributions/php-8.1.1.tar.gz
tar -xzf php-8.1.1.tar.gz
cd php-8.1.1/
./configure --prefix=/home/kesavan/opt/ --with-pdo-mysql
make install && make
You may check the installed version by executing ~/opt/bin/php -v
~/opt/bin/php -m
[PHP Modules]
Core
ctype
...
xmlreader
xmlwriter

[Zend Modules]
0 ✓ success ^_^  ______

1b Building Apache

./configure --prefix=/home/kesavan/opt/  --enabled-shared=max --enable-module=most
make && make install

At the end, you'll likely have the following binaries:

$ls ~/opt/bin/
ab         apxs      dbmmanage  envvars-std  htcacheclean  htdigest  httpd      logresolve  phar.phar  php-cgi     phpdbg  rotatelogs
apachectl  checkgid  envvars    fcgistarter  htdbm         htpasswd  httxt2dbm  phar        php        php-config  phpize
$ls ~/opt/**sbin**/
php-fpm
$~/opt/bin/phpize
Configuring for:
PHP Api Version:         20210902
Zend Module Api No:      20210902
Zend Extension Api No:   420210902

2 Run a private PHP-FPM stack on Nginx or Apache
There's a good article on the forum on the same. HOWTO run a private PHP-FPM stack on Nginx or Apache on Opalstack - Opalstack Community Forum. Please follow the steps. Also don't forgot to link the php-fpm to the above build php-fpm. On completion of the set-up, you may end up with similar to :

Note back , don't link the httpd; Let it mapped with system's default httpd

httpd -> /usr/sbin/httpd
nginx -> /usr/sbin/nginx
php-fpm -> $HOME/opt/sbin/php-fpm
php-fpm.orig -> /opt/remi/php80/root/usr/sbin/php-fpm
restart
start -> start-httpd
start-httpd
start-nginx
stop -> stop-httpd
stop-httpd
stop-nginx

3. Building & enabling Xdebug
There's good tool at http://xdebug.org/wizard to refer which may help building the xdebug
The environment variables set at the beginning of the steps are important to tell the compiler to build xdebug against the correct version of PHP.

cd ~
export CPPFLAGS="-I$HOME/opt/include $CPPFLAGS"
export LDFLAGS="-L$HOME/opt/lib $LDFLAGS"
export LD_LIBRARY_PATH=$HOME/opt/lib
export PATH=$HOME/opt/bin:$PATH
wget https://xdebug.org/files/xdebug-3.1.2.tgz
tar zxf xdebug-3.1.2.tgz
cd xdebug-3.1.2
phpize
./configure --enable-xdebug
make
make install

Also update ~/opt/lib/php.ini with the following line
zend_extension = $HOME/xdebug-3.1.2/modules/xdebug.so

4. Validate the config
phpinfo(); into some sample .php file at php-app directory $HOME/apps/app1

~/apps/<proxy-port-app>/bin/restart

You should able to see XDEBUG module enabled in the browser output

Good luck and Happy debugging.

Thanks @sean for your patience and guidance getting this.

Port forwarding / SSH tunnel

Even after completing the above 4 steps, the local development IDE may not able to communicate with the remote proxy app. To successfully communicate with remote proxy app from local, we need to establish a SSH tunnel to make the remote port available locally.

Create another proxy port app to get a port assignment for xdebug.
Configure php.ini to tell xdebug to use port from step 1, eg xdebug.remote_port = NNNNN
Establish a SSH tunnel on your own computer to make the remote port available locally, eg:
ssh -R user@opal99.opalstack.com NNNNN:127.0.0.1:NNNNN
Configure your IDE to connect to that port on 127.0.0.1 or localhost instead of on your URL

Finally opt/lib/php.ini will look similar to :

$cat $HOME/opt/lib/php.ini
zend_extension = /home/username/xdebug-3.1.2/modules/xdebug.so
xdebug.mode=debug
xdebug.remote_port = 45227

Remember, still your local IDE's port to listen for Xdebug should match with your app's .user.ini

[XDEBUG]
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = localhost
xdebug.client_port = 9006
xdebug.remote_handler=dbgp
xdebug.remote_enable=on
xdebug.discover_client_host=true