Configuring xdebug on local develpment environment without docker or workers

[Donatello-za]

Hi everyone,

As per the title, I would like to try and configure xdebug to run on a local Ubuntu development environment without docker and without workers mode. As basic as it can get. I don't know Go or Caddy so I'm a little new to all this and I can't seem to find the exact documentation explaining how to configure it.

From what I understand xdebug cannot be statically linked and so it doesn't ship with frankenphp so I thought I would try and get it running with my installed version of xdebug.so. If there is another way please point me to the relevant documentation and/or provide some guidance if you have the time.

I installed php 8.3 using this:

sudo apt update
sudo apt install -y software-properties-common
sudo LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install php8.3 php8.3-cli php8.3-fpm php8.3-mysql php8.3-sqlite3 php8.3-zip php8.3-gd php8.3-mbstring php8.3-curl php8.3-xml php8.3-xdebug -y

I then configured the Caddyfile like this:

{
	frankenphp {
	    php_ini {
	        zend_extension /usr/lib/php/20230831/xdebug.so
	        xdebug.mode develop,debug
            xdebug.discover_client_host true
            xdebug.client_port 9003
            #xdebug.client_host 0.0.0.0
            xdebug.connect_timeout_ms 200
            xdebug.scream 0
            xdebug.cli_color 1
            xdebug.show_local_vars 1
            xdebug.max_nesting_level 512
            xdebug.remote_handler dbgp
            xdebug.idekey phpstorm
	    }
	}
}

:8083 {
	root src/public/
	encode zstd br gzip
	php_server {
		try_files {path} index.php
	}
}

Note that I'm pointing to the install location of xdebug.so: /usr/lib/php/20230831/xdebug.so

I installed frankenphp using: curl https://frankenphp.dev/install.sh | sh

frankenphp is running in my project's root using: ./frankenphp run

I'm getting the following error but I think I know why: Failed loading /usr/lib/php/20230831/xdebug.so: /usr/lib/php/20230831/xdebug.so: undefined symbol: compiler_globals

I think the reason is that frankenphp expects a specific version of xdebug.so, hence the error. I'm obviously approaching this in the wrong way. Can someone help me out on this please?

[dunglas]

It's because the extension you installed is not compiled with ZTS support.

Try using the Debian packages we provide and install xdebug using Pie or pecl, this should work.

[henderkes]

Try using the Debian packages we provide and install xdebug using Pie or pecl, this should work.

This is not possible, because our .deb release doesn't contain build scripts, header includes, or the phpize/php-config scripts.

https://debs.henderkes.com offers this in the php-zts-devel package (but I also ship xdebug precompiled, so that isn't necessary).

[henderkes]

Keep in mind that I currently only build 8.4 for .deb systems because apt doesn't support modular streams. I'm looking to eventually offer 8.2-8.5 like ondrej does (apt install frankenphp8.3 php-zts8.3-xdebug). RPM's are already available from 8.2 to 8.5.

[Donatello-za]

Keep in mind that I currently only build 8.4 for .deb systems because apt doesn't support modular streams. I'm looking to eventually offer 8.2-8.5 like ondrej does (apt install frankenphp8.3 php-zts8.3-xdebug). RPM's are already available from 8.2 to 8.5.

I'm willing to try PHP 8.4 as I want to start a new project, hence my new-found interest in frankenphp as well. The only installation instructions I can find though is the standalone binary download, Docker and Homebrew. Where can I find your .deb package? Does it include xdebug?

[henderkes]

https://debs.henderkes.com/ includes installation instructions.

[Donatello-za]

@henderkes Thanks so much! I will try it out this afternoon. Is this part of the one of the official frankenphp configurations?

[henderkes]

Not yet.

[Donatello-za]

Ok, awesome, I got it working and my PHPStorm IDE connected to it with the following:

As per your instructions:

sudo curl -fsSL https://key.henderkes.com/static-php.gpg -o /usr/share/keyrings/static-php.gpg && \
 echo "deb [signed-by=/usr/share/keyrings/static-php.gpg] https://deb.henderkes.com/ stable main" | sudo tee /etc/apt/sources.list.d/static-php.list && \
 sudo apt update

sudo apt install frankenphp php-zts-xdebug -y

This is my Caddyfile:

{
	admin 0.0.0.0:2020

	frankenphp {
		php_ini {
			xdebug.mode develop,debug
			xdebug.discover_client_host true
			xdebug.client_port 9003
			#xdebug.client_host 0.0.0.0
			xdebug.connect_timeout_ms 200
			xdebug.scream 0
			xdebug.cli_color 1
			xdebug.show_local_vars 1
			xdebug.max_nesting_level 512
			xdebug.remote_handler dbgp
			xdebug.idekey phpstorm
		}
	}
}

:8083 {
	root src/public/
	encode zstd br gzip
	php_server {
		try_files {path} index.php
	}
} 

I had to change the Caddy admin port from 2019 to 2020 because it was conflicting with another service running on my machine.

I also had to pass through ?XDEBUG_SESSION_START=PHPSTORM from the browser initially for xdebug to pick it up through PHPStorm. PHPSTORM is the idekey I chose to use.

In other words: http://localhost:8083/?XDEBUG_SESSION_START=PHPSTORM. I'm just supplying the additional information here in case someone else runs into the same issues.

[henderkes]

I suppose we can close this?

I would avoid publishing the admin api externally, by the way. I think that's what 0.0.0.0 does. Localhost should do the trick.

[Donatello-za]

Yes I'll be closing it thanks.