From 908ca600c38a60959a126ad0ce8c24a2f3c16e4d Mon Sep 17 00:00:00 2001 From: Alexander O'Neill Date: Wed, 26 Jun 2024 14:56:52 -0300 Subject: [PATCH] Add xdebug make command. (#378) * Add 'make xdebug' command. * Explicitly add hosts entry for host.docker.internal on Linux hosts. * Add host.docker.internal: host-gateway to Drupal image to support XDebug on Linux hosts. --- .vscode/launch.json | 51 ++++++++++++++++ Makefile | 38 +++++++++++- README.md | 24 +++++++- .../docker-compose/docker-compose.drupal.yml | 2 + sample.env | 3 + scripts/extra/launch.json | 58 +++++++++++++++++++ scripts/extra/xdebug.ini | 9 +++ 7 files changed, 182 insertions(+), 3 deletions(-) create mode 100644 .vscode/launch.json create mode 100644 scripts/extra/launch.json create mode 100644 scripts/extra/xdebug.ini diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 000000000..089ed03fc --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,51 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/var/www/drupal": "${workspaceRoot}/codebase", + } + }, + { + "name": "Launch currently open script", + "type": "php", + "request": "launch", + "program": "${file}", + "cwd": "${fileDirname}", + "port": 0, + "runtimeArgs": [ + "-dxdebug.start_with_request=yes" + ], + "env": { + "XDEBUG_MODE": "debug,develop", + "XDEBUG_CONFIG": "client_port=${port}" + } + }, + { + "name": "Launch Built-in web server", + "type": "php", + "request": "launch", + "runtimeArgs": [ + "-dxdebug.mode=debug", + "-dxdebug.start_with_request=yes", + "-S", + "localhost:0" + ], + "program": "", + "cwd": "${workspaceRoot}", + "port": 9003, + "serverReadyAction": { + "pattern": "Development Server \\(http://islandora.traefik.me:([0-9]+)\\) started", + "uriFormat": "http://islandora.traefik.me:%s", + "action": "openExternally" + } + } + ] +} diff --git a/Makefile b/Makefile index b08d014f8..48870a1e8 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,6 @@ else # GNU/Linux SED_DASH_I=sed -i endif - # If custom.makefile exists include it. -include custom.Makefile @@ -41,6 +40,9 @@ export ## Add necessary variables ## ############################################# +PHP_MAJOR_VERSION?=8 +PHP_MINOR_VERSION?=3 + # Services that are not produced by isle-buildkit. EXTERNAL_SERVICES := etcd watchtower traefik @@ -687,3 +689,37 @@ wait-for-drupal-locally: echo "Waiting for https://$(DOMAIN) to be available..."; \ sleep 1; \ done + +.PHONY: xdebug +## Turn on xdebug. +xdebug: TIMEOUT_VALUE=3600 +xdebug: + + $(MAKE) set-timeout TIMEOUT_VALUE=3600 + sleep 10 + docker compose exec -T drupal with-contenv bash -lc "apk add php${PHP_MAJOR_VERSION}${PHP_MINOR_VERSION}-pecl-xdebug" + docker cp scripts/extra/xdebug.ini $$(docker compose ps -q drupal):/etc/php${PHP_MAJOR_VERSION}${PHP_MINOR_VERSION}/conf.d/xdebug.ini + -docker compose exec -T drupal with-contenv bash -lc "chown root:root /etc/php${PHP_MAJOR_VERSION}${PHP_MINOR_VERSION}/conf.d/xdebug.ini" + $(XDEBUG_HOST_COMMAND) + + docker compose restart drupal + sleep 6 + docker compose exec -T drupal with-contenv bash -lc "php -i | grep xdebug" + +.phony: set-timeout +## Update all PHP and NGinx timeouts to TIMEOUT_VALUE +set-timeout: + $(SED_DASH_I) 's/NGINX_FASTCGI_READ_TIMEOUT: .*s/NGINX_FASTCGI_READ_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/NGINX_FASTCGI_CONNECT_TIMEOUT: .*s/NGINX_FASTCGI_CONNECT_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/NGINX_FASTCGI_SEND_TIMEOUT: .*s/NGINX_FASTCGI_SEND_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/NGINX_KEEPALIVE_TIMEOUT: .*s/NGINX_KEEPALIVE_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/NGINX_PROXY_CONNECT_TIMEOUT: .*s/NGINX_PROXY_CONNECT_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/NGINX_PROXY_READ_TIMEOUT: .*s/NGINX_PROXY_READ_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/NGINX_PROXY_SEND_TIMEOUT: .*s/NGINX_PROXY_SEND_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/NGINX_SEND_TIMEOUT: .*s/NGINX_SEND_TIMEOUT: $(TIMEOUT_VALUE)s/g' docker-compose.yml + $(SED_DASH_I) 's/PHP_DEFAULT_SOCKET_TIMEOUT: ".*"/PHP_DEFAULT_SOCKET_TIMEOUT: "$(TIMEOUT_VALUE)"/g' docker-compose.yml + $(SED_DASH_I) 's/PHP_MAX_EXECUTION_TIME: ".*"/PHP_MAX_EXECUTION_TIME: "$(TIMEOUT_VALUE)"/g' docker-compose.yml + $(SED_DASH_I) 's/PHP_MAX_INPUT_TIME: ".*"/PHP_MAX_INPUT_TIME: "$(TIMEOUT_VALUE)"/g' docker-compose.yml + $(SED_DASH_I) 's/PHP_PROCESS_CONTROL_TIMEOUT: ".*"/PHP_PROCESS_CONTROL_TIMEOUT: "$(TIMEOUT_VALUE)"/g' docker-compose.yml + $(SED_DASH_I) 's/PHP_REQUEST_TERMINATE_TIMEOUT: ".*"/PHP_REQUEST_TERMINATE_TIMEOUT: "$(TIMEOUT_VALUE)"/g' docker-compose.yml + docker compose up -d --force-recreate --remove-orphans diff --git a/README.md b/README.md index 9e620ac04..44c35c870 100644 --- a/README.md +++ b/README.md @@ -224,7 +224,7 @@ To enable using secrets prior to running the `make` commands, copy sample.env to .env. Set `USE_SECRETS=true` in your .env file. Make a copy of the files in /secrets/template/ to /secrets/live/. -To enable using secrets after run `make local` or `make up`, set +To enable using secrets after run `make local` or `make up`, set `USE_SECRETS=true` in your .env file. When you run `make docker-compose.yml`, a large block of `secrets` will be added at the top of your `docker-compose.yml` file. @@ -258,6 +258,26 @@ Setting admin password now ``` +### Enable XDebug + +```shell +make xdebug +``` + +This will download and enable the [XDebug](https://xdebug.org) +PHP debugger. + +It also changes all of the PHP and Nginx timeouts so your +debugging session doesn't get shut down while you're working. + +Bringing ISLE down and back up will disable the debugger again. + +You can put custom XDebug config settings in scripts/extra/xdebug.ini + +See the documentation for your code editor for further +details on how to debug PHP applications. +Specifically the 'Listen for XDebug' command. + ## Services Islandora is composed of many different services, this project has split these @@ -385,7 +405,7 @@ lowercasename: echo "first line in command needs to be indented. There are exceptions to this, review functions in the Makefile for examples of these exceptions." ``` -NOTE: A target you add in the custom.Makefile will not override an existing target with the same label in this repository's defautl Makefile. +NOTE: A target you add in the custom.Makefile will not override an existing target with the same label in this repository's defautl Makefile. Running the new `custom.Makefile` commands are exactly the same as running any other Makefile command. Just run `make` and the function's name. ```bash diff --git a/build/docker-compose/docker-compose.drupal.yml b/build/docker-compose/docker-compose.drupal.yml index 9de21bfa3..22859bd72 100644 --- a/build/docker-compose/docker-compose.drupal.yml +++ b/build/docker-compose/docker-compose.drupal.yml @@ -30,6 +30,8 @@ services: PHP_MAX_INPUT_TIME: ${PHP_MAX_EXECUTION_TIME} PHP_PROCESS_CONTROL_TIMEOUT: ${PHP_MAX_EXECUTION_TIME} PHP_REQUEST_TERMINATE_TIMEOUT: ${PHP_MAX_EXECUTION_TIME} + extra_hosts: + host.docker.internal: host-gateway labels: - traefik.enable=${EXPOSE_DRUPAL:-true} - traefik.http.services.${COMPOSE_PROJECT_NAME-isle-dc}-drupal.loadbalancer.server.port=80 diff --git a/sample.env b/sample.env index aada66dac..d988eb056 100644 --- a/sample.env +++ b/sample.env @@ -96,6 +96,9 @@ REPOSITORY=islandora # their versions specified explicitly in their respective docker-compose files. TAG=main +PHP_MAJOR_VERSION=8 +PHP_MINOR_VERSION=3 + ############################################################################### # Exposed Containers & Ports ############################################################################### diff --git a/scripts/extra/launch.json b/scripts/extra/launch.json new file mode 100644 index 000000000..67d731f73 --- /dev/null +++ b/scripts/extra/launch.json @@ -0,0 +1,58 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/var/www/drupal": "${workspaceRoot}/codebase", + } + }, + { + "name": "Launch Chrome", + "request": "launch", + "type": "chrome", + "url": "https://islandora.traefik.me", + "webRoot": "${workspaceFolder}/codebase/web" + }, + { + "name": "Launch currently open script", + "type": "php", + "request": "launch", + "program": "${file}", + "cwd": "${fileDirname}", + "port": 0, + "runtimeArgs": [ + "-dxdebug.start_with_request=yes" + ], + "env": { + "XDEBUG_MODE": "debug,develop", + "XDEBUG_CONFIG": "client_port=${port}" + } + }, + { + "name": "Launch Built-in web server", + "type": "php", + "request": "launch", + "runtimeArgs": [ + "-dxdebug.mode=debug", + "-dxdebug.start_with_request=yes", + "-S", + "localhost:0" + ], + "program": "", + "cwd": "${workspaceRoot}", + "port": 9003, + "serverReadyAction": { + "pattern": "Development Server \\(http://islandora.traefik.me:([0-9]+)\\) started", + "uriFormat": "http://islandora.traefik.me:%s", + "action": "openExternally" + } + } + ] +} diff --git a/scripts/extra/xdebug.ini b/scripts/extra/xdebug.ini new file mode 100644 index 000000000..220546891 --- /dev/null +++ b/scripts/extra/xdebug.ini @@ -0,0 +1,9 @@ +zend_extension=xdebug.so +xdebug.mode=debug +xdebug.start_with_request=true +xdebug.cli_color=1 +xdebug.discover_client_host=0 +xdebug.client_host=host.docker.internal +xdebug.max_nesting_level=512 +xdebug.log_level = 0 +xdebug.log=/var/log/xdebug.log