Add xdebug make command.

.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"
+            }
+        }
+    ]
+}

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

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

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

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
 ###############################################################################

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"
+            }
+        }
+    ]
+}

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