Skip to content

Fix Xdebug connection warnings and improve documentation #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nielsdrost7 merged 12 commits into from
Jan 7, 2026
Merged

Fix Xdebug connection warnings and improve documentation #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
cf13606
Initial plan
Copilot Jan 5, 2026
f6e4010
Fix Xdebug connection warnings during Docker build by using trigger mode
Copilot Jan 5, 2026
98c4530
Add Xdebug usage documentation to README
Copilot Jan 5, 2026
7b18731
Add Docker build caching documentation to README
Copilot Jan 5, 2026
fe2f4e5
Add explanatory comments for Xdebug configuration in Dockerfiles
Copilot Jan 5, 2026
40b1a7f
docs: Create comprehensive guidelines and improve README
Copilot Jan 5, 2026
2a23f76
docs: Fix script name typo and update dates to 2025
Copilot Jan 5, 2026
f729909
Fix comments and sed patterns, add beginner-friendly setup guide
Copilot Jan 5, 2026
9bf2b50
Make sed pattern consistent across all Dockerfiles
Copilot Jan 5, 2026
2a04a31
Improve setup guide clarity and fix documentation nitpicks
Copilot Jan 5, 2026
22e3663
Add missing section header for hosts file step
Copilot Jan 5, 2026
8e89ed7
Remove tenants directory mapping from volumes
nielsdrost7 Jan 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .docker/php-fpm/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,17 +241,20 @@ RUN if [ ${INSTALL_XDEBUG} = true ]; then \
# Copy xdebug configuration for remote debugging
COPY php-fpm/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

# Configure Xdebug settings based on PHP version
# For Xdebug 3 (PHP 7.3, 7.4, 8.x): Use trigger mode to prevent connection warnings during build
# For Xdebug 2 (older PHP): Keep autostart disabled to prevent connection warnings during build
RUN if [ $(php -r "echo PHP_MAJOR_VERSION;") = "8" ] || { [ $(php -r "echo PHP_MAJOR_VERSION;") = "7" ] && { [ $(php -r "echo PHP_MINOR_VERSION;") = "4" ] || [ $(php -r "echo PHP_MINOR_VERSION;") = "3" ] ;} ;}; then \
sed -i "s/xdebug.remote_host=/xdebug.client_host=/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_connect_back=0/xdebug.discover_client_host=false/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_port=9003/xdebug.client_port=${XDEBUG_PORT}/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug\.\(remote_port\|client_port\)=[0-9]*/xdebug.client_port=${XDEBUG_PORT}/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_enable=0/; xdebug.profiler_enable=0/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_output_dir=/xdebug.output_dir=/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_mode=req/; xdebug.remote_mode=req/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=yes/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=trigger/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.mode=debug/" /usr/local/etc/php/conf.d/xdebug.ini \
;else \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=1/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=0/" /usr/local/etc/php/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.remote_enable=1/" /usr/local/etc/php/conf.d/xdebug.ini \
;fi
RUN sed -i "s/xdebug.cli_color=0/xdebug.cli_color=1/" /usr/local/etc/php/conf.d/xdebug.ini
Expand Down
9 changes: 6 additions & 3 deletions .docker/workspace/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -329,17 +329,20 @@ RUN echo "##### PHP Version #####" \
# ADD for REMOTE debugging
COPY workspace/xdebug.ini /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini

# Configure Xdebug settings based on PHP version
# For Xdebug 3 (PHP 7.3, 7.4, 8.x): Use trigger mode to prevent connection warnings during build
# For Xdebug 2 (older PHP): Keep autostart disabled to prevent connection warnings during build
RUN if [ $(php -r "echo PHP_MAJOR_VERSION;") = "8" ] || { [ $(php -r "echo PHP_MAJOR_VERSION;") = "7" ] && { [ $(php -r "echo PHP_MINOR_VERSION;") = "4" ] || [ $(php -r "echo PHP_MINOR_VERSION;") = "3" ] ;} ;}; then \
sed -i "s/xdebug.remote_host=/xdebug.client_host=/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_connect_back=0/xdebug.discover_client_host=false/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_port=9000/xdebug.client_port=${XDEBUG_PORT}/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug\.\(remote_port\|client_port\)=[0-9]*/xdebug.client_port=${XDEBUG_PORT}/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_enable=0/; xdebug.profiler_enable=0/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_output_dir=/xdebug.output_dir=/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_mode=req/; xdebug.remote_mode=req/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=yes/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=trigger/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.mode=debug/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini \
;else \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=0/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.remote_enable=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini \
;fi
RUN sed -i "s/xdebug.cli_color=0/xdebug.cli_color=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini
Expand Down
9 changes: 6 additions & 3 deletions .docker/workspace/Dockerfile.74
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,17 +360,20 @@ RUN if [ ${INSTALL_XDEBUG} = true ]; then \
# ADD for REMOTE debugging
COPY ./xdebug.ini /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini

# Configure Xdebug settings based on PHP version
# For Xdebug 3 (PHP 7.3, 7.4, 8.x): Use trigger mode to prevent connection warnings during build
# For Xdebug 2 (older PHP): Keep autostart disabled to prevent connection warnings during build
RUN if [ $(php -r "echo PHP_MAJOR_VERSION;") = "8" ] || { [ $(php -r "echo PHP_MAJOR_VERSION;") = "7" ] && { [ $(php -r "echo PHP_MINOR_VERSION;") = "4" ] || [ $(php -r "echo PHP_MINOR_VERSION;") = "3" ] ;} ;}; then \
sed -i "s/xdebug.remote_host=/xdebug.client_host=/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_connect_back=0/xdebug.discover_client_host=false/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_port=9000/xdebug.client_port=${XDEBUG_PORT}/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug\.\(remote_port\|client_port\)=[0-9]*/xdebug.client_port=${XDEBUG_PORT}/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_enable=0/; xdebug.profiler_enable=0/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_output_dir=/xdebug.output_dir=/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_mode=req/; xdebug.remote_mode=req/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=yes/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=trigger/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.mode=debug/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini \
;else \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=0/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.remote_enable=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini \
;fi
RUN sed -i "s/xdebug.cli_color=0/xdebug.cli_color=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini
Expand Down
9 changes: 6 additions & 3 deletions .docker/workspace/Dockerfile.81
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,17 +292,20 @@ RUN echo "##### PHP Version #####" \
# ADD for REMOTE debugging
COPY ./xdebug.ini /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini

# Configure Xdebug settings based on PHP version
# For Xdebug 3 (PHP 7.3, 7.4, 8.x): Use trigger mode to prevent connection warnings during build
# For Xdebug 2 (older PHP): Keep autostart disabled to prevent connection warnings during build
RUN if [ $(php -r "echo PHP_MAJOR_VERSION;") = "8" ] || { [ $(php -r "echo PHP_MAJOR_VERSION;") = "7" ] && { [ $(php -r "echo PHP_MINOR_VERSION;") = "4" ] || [ $(php -r "echo PHP_MINOR_VERSION;") = "3" ] ;} ;}; then \
sed -i "s/xdebug.remote_host=/xdebug.client_host=/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_connect_back=0/xdebug.discover_client_host=false/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_port=9000/xdebug.client_port=${XDEBUG_PORT}/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug\.\(remote_port\|client_port\)=[0-9]*/xdebug.client_port=${XDEBUG_PORT}/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_enable=0/; xdebug.profiler_enable=0/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.profiler_output_dir=/xdebug.output_dir=/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_mode=req/; xdebug.remote_mode=req/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=yes/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.start_with_request=trigger/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.mode=debug/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini \
;else \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_autostart=0/xdebug.remote_autostart=0/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini && \
sed -i "s/xdebug.remote_enable=0/xdebug.remote_enable=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini \
;fi
RUN sed -i "s/xdebug.cli_color=0/xdebug.cli_color=1/" /etc/php/${IVPLDOCK_PHP_VERSION}/cli/conf.d/xdebug.ini
Expand Down
2 changes: 1 addition & 1 deletion .docker/workspace/xdebug.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ zend_extension=xdebug.so

; Xdebug Mode
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.start_with_request=trigger
Copy link

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The workspace/xdebug.ini template uses Xdebug 3 syntax, but the Dockerfiles expect to transform Xdebug 2 syntax placeholders. For PHP versions ≤7.2 that use Xdebug 2, the sed commands in the Dockerfile's else branch (e.g., line 376 in Dockerfile.74) look for 'xdebug.remote_autostart=0' to transform, but this file doesn't contain that placeholder. This means Xdebug 2 configurations won't be properly set. Consider adding Xdebug 2 placeholder settings to this template file (e.g., 'xdebug.remote_autostart=0', 'xdebug.remote_enable=0') so the sed transformations work for older PHP versions, or use separate template files for Xdebug 2 and Xdebug 3.

Copilot uses AI. Check for mistakes.
Copy link
Contributor

@nielsdrost7 nielsdrost7 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot

The workspace/xdebug.ini template uses Xdebug 3 syntax, but the Dockerfiles expect to transform Xdebug 2 syntax placeholders. For PHP versions ≤7.2 that use Xdebug 2, the sed commands in the Dockerfile's else branch (e.g., line 376 in Dockerfile.74) look for 'xdebug.remote_autostart=0' to transform, but this file doesn't contain that placeholder. This means Xdebug 2 configurations won't be properly set. Consider adding Xdebug 2 placeholder settings to this template file (e.g., 'xdebug.remote_autostart=0', 'xdebug.remote_enable=0') so the sed transformations work for older PHP versions, or use separate template files for Xdebug 2 and Xdebug 3.

I'm not using xdebug version 2, but I definitely want everything to work correctly for xdebug version 3

xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.discover_client_host=false
Expand Down
Loading