Skip to content

feat: add separate phpfpm container dedicated to xdebug #1355

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.

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

Open
wants to merge 8 commits into
base: master
Choose a base branch
from

Conversation

Jarzebowsky
Copy link

@Jarzebowsky Jarzebowsky commented Jul 6, 2025

⚠️ The PR is not finished as it needs some answers regarding the process of publishing the images within the changes.
It should probably also include the changes to the README (didn't do anything as the initial approve should be happening before that happens).

⚠️ The changes are applied only to the default images and should be expanded to the rest of them after initial approval of the solution.

There is also one thing that I don't have idea how to solve as it requires manual change after setting up the project - perhaps some core contributors have better understanding of the repository to drop the lead or give concrete approach for that.

Context

This resolves #1230 which drops manual interaction with turning on/off xdebug which is problematic to remember for a user but also even if it's turned off the xdebug lib is all the time installed.

Description

We need to add mapping to nginx configuration so it will pass the request to concrete phpfpm container based on the cookie attached to request.

Changes in the codebase

The changes includes separation of phpfpm container to two separate container (phpfpm, phpfpm-xdebug). This allows us to drop xdebug for phpfpm container.
We also have changed the socket names for each of the containers which are named accordingly /sock/phpfpm.sock and /sock/phpfpm-xdebug.sock. Since we are running both in the same time there were conflicts regarding names so that what was needed to be done.

There are also changes regarding nginx configuration regarding app container which uses this image. First - we adjusted upstream definition after changes of name for currently existing phpfpm one and added second one which covers new one regarding xdebug.

The magic and thing that does the job is the next one: map. Based on the cookie being sent within the request XDEBUG_SESSION we define to which phpfpm container the request should be passed.

Additional information

The changes were tested within VSCode and PHPStorm configuration and we would need to adjust the README regarding the usage of the xdebug thing. For PHPStorm we need to declare the concrete name for record in PHP | Servers so it will map correctly to the files tree.

This is a part of the changes that should be applied because the same thing should happen to CLI usage so instead of using whole FPM to run commands we could use smaller php CLI and php CLI with xdebug. The final outcome should give us:

  • phpfpm
  • phpfpm-xdebug
  • php
  • php-xdebugThe changes contains:
  • drop xdebug from current php-fpm container
  • add new php-fpm container with xdebug configuration
  • changes to nginx to name sockets accordingly and apply mapping to do it based on cookie in request

Copy link

what-the-diff bot commented Jul 6, 2025

PR Summary

  • Simplified debug-cli script: The task of executing Docker commands is made easier with a more simplified script. All prior coding associated with managing Xdebug settings has been disposed.
  • Removal of Xdebug script: The file handling Xdebug configurations isn’t needed anymore and has been omitted.
  • New phpfpm-Xdebug service: New service called phpfpm-xdebug has been introduced, which works with shared app volumes across several Docker Compose files to improve your development environments.
  • Introduced environment file for Xdebug settings: A new file phpfpm-xdebug.env is made specifically for handling Xdebug settings.
  • Dockerfile for PHP modifications: The Dockerfile for PHP now has an extra build for phpfpm-xdebug, aptly set up with Xdebug related configurations and dependencies.
  • Enhanced Nginx configuration: The existing Nginx configuration is upgraded to support Xdebug by defining a new method (upstream) for phpfpm-xdebug.
  • Revised PHP Configurations: New directory 8.3-xdebug contains configuration files tailoring settings for Xdebug, Blackfire, and PHP-FPM.
  • Excluded Xdebug from regular PHP container: Xdebug is no longer installed from the standard PHP Dockerfile to prevent unwanted debugging in production environments.
  • Updates to onelinesetup script: Redirection in setup script to a more related new repository for Docker Magento project has been implemented.
  • Git setup template upgrade: The template has been updated to fetch from a new repository instead of the old one, reflecting changes made to Xdebug handling.

Comment on lines +15 to +18
# image: markoshust/magento-nginx:1.24-0
build:
context: ./images/nginx/1.24
dockerfile: Dockerfile
Copy link
Author

Choose a reason for hiding this comment

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

@markshust This should be replaced with dedicated image build

Comment on lines +36 to +39
# image: markoshust/magento-php:8.3-fpm-4
build:
context: ./images/php/8.3
dockerfile: Dockerfile
Copy link
Author

Choose a reason for hiding this comment

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

@markshust This should be replaced with dedicated image build

Comment on lines +45 to +48
# image: markoshust/magento-php:8.3-fpm-4
build:
context: ./images/php/8.3-xdebug
dockerfile: Dockerfile
Copy link
Author

Choose a reason for hiding this comment

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

@markshust This should be replaced with dedicated image build

server unix:/sock/phpfpm-xdebug.sock;
}

map $cookie_XDEBUG_SESSION $fastcgi_backend {
Copy link
Author

Choose a reason for hiding this comment

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

The problem I mentioned in the description is that mapping requires to put $ sign when assigned to variable. There is a logic which copies nginx.conf.sample to nginx.conf but this sample file has

fastcgi_pass   fastcgi_backend;

but it should be

fastcgi_pass   $fastcgi_backend;

The occurence is repeated 3 times - perhaps some post-script with sed that would replace it?

Comment on lines +8 to +9
# curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/template | bash
curl -s https://raw.githubusercontent.com/Jarzebowsky/docker-magento/xdebug-change-trigger-method/lib/template | bash
Copy link
Author

Choose a reason for hiding this comment

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

This change was introduced to fully test the approach so it should be reverted.
It's left for the sake of testing it locally.

Comment on lines +9 to +18
# git remote add origin https://github.com/markshust/docker-magento
git remote add origin https://github.com/Jarzebowsky/docker-magento
git fetch origin -qqq
git checkout origin/master -- compose
# git checkout origin/master -- compose
git checkout origin/xdebug-change-trigger-method -- compose images

mv compose/* ./
mv compose/.gitignore ./
mv compose/.vscode ./
mv images/* ./images
Copy link
Author

Choose a reason for hiding this comment

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

This change was introduced to fully test the approach so it should be reverted.
It's left for the sake of testing it locally.

@Jarzebowsky Jarzebowsky marked this pull request as ready for review July 6, 2025 15:15
@dosubot dosubot bot added size:XL This PR changes 500-999 lines, ignoring generated files. feature labels Jul 6, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature size:XL This PR changes 500-999 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant