From 5ac10fcf76b5e9680fffcd3c035ff8b7552759a8 Mon Sep 17 00:00:00 2001
From: arguskay99 <36620800+ArgusKay99@users.noreply.github.com>
Date: Sun, 8 Mar 2026 12:09:20 +0100
Subject: [PATCH 1/2] running $(PWD) outside from make will throw an error on
 linux debian 13

---
 CONTRIBUTING.md | 4 ++--
 Makefile        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0c1f81b7..09ac629f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -28,7 +28,7 @@ To create the docker image and then enter the docker container shell:
 
 ```shell
 docker image build -t phparkitect .
-docker run --rm -it --entrypoint= -v $(PWD):/arkitect phparkitect bash
+docker run --rm -it --entrypoint= -v "${PWD}":/arkitect phparkitect bash
 ```
 
 If you prefer use more shorter make commands (use `make` without arguments for help):
@@ -38,7 +38,7 @@ make dbi
 make shell
 ```
 
-The first time, after the docker container has been created, remember to install the packages with composer:
+The first time, after the docker container has been created, remember to install the packages with composer (from inside the container):
 
 ```shell
 composer install
diff --git a/Makefile b/Makefile
index 7e03e123..283f1fe5 100644
--- a/Makefile
+++ b/Makefile
@@ -7,10 +7,10 @@ help: ## it shows help menu
 	@awk 'BEGIN {FS = ":.*#"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z0-9_-]+:.*?#/ { printf "  \033[36m%-27s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
 dbi: ## it creates docker image
-	docker image build -t phparkitect .
+	docker image build --target php_build -t phparkitect .
 
 shell: ## it enters into the container
-	docker run --rm -it --entrypoint= -v $(PWD):/arkitect phparkitect bash
+	docker run --rm -it --entrypoint= -v "${PWD}":/arkitect phparkitect bash
 
 test: ## it launches tests
 	bin/phpunit

From 13339131b1cccf7370956631e930a31af66f179c Mon Sep 17 00:00:00 2001
From: arguskay99 <36620800+ArgusKay99@users.noreply.github.com>
Date: Sun, 8 Mar 2026 12:17:15 +0100
Subject: [PATCH 2/2] add xdebug as multi-stage Dockerfile for local
 development

---
 .github/workflows/build.yml |  2 +-
 CONTRIBUTING.md             |  4 +++-
 Dockerfile                  | 11 +++++++++++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index a8588dd9..3a3091f1 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -190,4 +190,4 @@ jobs:
         push: ${{ github.event_name != 'pull_request' }}
         tags: ${{ steps.meta.outputs.tags }}
         labels: ${{ steps.meta.outputs.labels }}
-
+        target: php_build
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 09ac629f..49be5776 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,7 +27,9 @@ Some common tasks are available in the Makefile file (you still can use it to se
 To create the docker image and then enter the docker container shell:
 
 ```shell
-docker image build -t phparkitect .
+docker image build --target php_build -t phparkitect .
+# or with xdebug
+docker image build --target with_xdebug -t phparkitect .
 docker run --rm -it --entrypoint= -v "${PWD}":/arkitect phparkitect bash
 ```
 
diff --git a/Dockerfile b/Dockerfile
index 04a400a3..5b6baa1c 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -20,3 +20,14 @@ RUN apk add zip git bash make icu-dev
 ENV PATH="/arkitect/bin-stub:${PATH}"
 
 ENTRYPOINT [ "phparkitect"]
+
+FROM php_build AS with_xdebug
+
+# compatibility chart: https://xdebug.org/docs/compat
+ARG XDEBUG_VERSION="xdebug-3.4.0"
+RUN apk add autoconf g++ linux-headers
+
+RUN pecl install ${XDEBUG_VERSION} \
+    && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" > /usr/local/etc/php/conf.d/xdebug.ini \
+    && echo "xdebug.remote_enable=on" >> /usr/local/etc/php/conf.d/xdebug.ini \
+    && echo "xdebug.remote_autostart=off" >> /usr/local/etc/php/conf.d/xdebug.ini