From da0af0b6e0225c407ef57ecd8b5dfbf8366d2655 Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Thu, 8 Oct 2026 17:38:37 +0100
Subject: [PATCH 1/4] Feat: Install StructArmed into `/tools`

Signed-off-by: George Steel <george@net-glue.co.uk>
---
 mago.toml                                     |  1 +
 makefiles/StructArmed.mk                      | 57 +++++++++++++++++++
 migrations/InstallStructArmed/Install.mk      | 36 ++++++++++++
 migrations/InstallStructArmed/migrate         | 25 ++++++++
 migrations/InstallStructArmed/structarmed.php |  9 +++
 5 files changed, 128 insertions(+)
 create mode 100644 makefiles/StructArmed.mk
 create mode 100644 migrations/InstallStructArmed/Install.mk
 create mode 100644 migrations/InstallStructArmed/migrate
 create mode 100644 migrations/InstallStructArmed/structarmed.php

diff --git a/mago.toml b/mago.toml
index afbcaf6..50954bc 100644
--- a/mago.toml
+++ b/mago.toml
@@ -11,6 +11,7 @@ workspace = "."
 paths = ["migrations/"]
 excludes = [
     "migrations/*/templates/rector.php",
+    "migrations/*/structarmed.php",
 ]
 [analyzer]
 
diff --git a/makefiles/StructArmed.mk b/makefiles/StructArmed.mk
new file mode 100644
index 0000000..aee992b
--- /dev/null
+++ b/makefiles/StructArmed.mk
@@ -0,0 +1,57 @@
+STRUCT_ARMED_DIRECTORY ?= $(PROJECT_DIR)tools/structarmed
+HAS_STRUCT_ARMED := $(strip $(shell if [ -d $(STRUCT_ARMED_DIRECTORY) ]; then echo TRUE; fi))
+
+ifeq ("$(HAS_STRUCT_ARMED)", "TRUE")
+
+BUMP_TOOLS_TARGETS += structarmed-bump
+UPDATE_TOOLS_TARGETS += structarmed-update
+INSTALL_TOOLS_TARGETS += structarmed-install
+
+HELP += $(call MK_HELP,'structarmed','Check the codebase with StructArmed')
+QA_TARGETS += structarmed
+CLEAN_TARGETS += structarmed-clear
+
+structarmed:
+	@$(DOCKER_RUN) $(DOCKER_IMAGE_NAME) \
+		$(STRUCT_ARMED_DIRECTORY)/vendor/bin/structarmed \
+		--config $(STRUCT_ARMED_DIRECTORY)/structarmed.php \
+		analyze
+.PHONY: structarmed
+
+HELP += $(call MK_HELP,'structarmed-fix','Run automatic fixes provided by StructArmed')
+structarmed-fix:
+	@$(DOCKER_RUN) $(DOCKER_IMAGE_NAME) \
+		$(STRUCT_ARMED_DIRECTORY)/vendor/bin/structarmed \
+		--config $(STRUCT_ARMED_DIRECTORY)/structarmed.php \
+		analyze --fix
+.PHONY: structarmed-fix
+
+structarmed-clear:
+	@$(DOCKER_RUN) $(DOCKER_IMAGE_NAME) \
+		$(STRUCT_ARMED_DIRECTORY)/vendor/bin/structarmed \
+		--config $(STRUCT_ARMED_DIRECTORY)/structarmed.php \
+		clear-cache
+.PHONY: structarmed-clear
+
+structarmed-update:
+	$(DOCKER_RUN) ${DOCKER_IMAGE_NAME} composer \
+    		--working-dir=$(STRUCT_ARMED_DIRECTORY) \
+    		update
+.PHONY: structarmed-update
+
+structarmed-install:
+	$(DOCKER_RUN) ${DOCKER_IMAGE_NAME} composer \
+    		--working-dir=$(STRUCT_ARMED_DIRECTORY) \
+    		install
+.PHONY: structarmed-install
+
+structarmed-bump: structarmed-update _do-structarmed-bump structarmed-update
+.PHONY: structarmed-bump
+
+_do-structarmed-bump:
+	$(DOCKER_RUN) ${DOCKER_IMAGE_NAME} composer \
+    		--working-dir=$(STRUCT_ARMED_DIRECTORY) \
+    		bump -D
+.PHONY: _do-structarmed-bump
+
+endif
diff --git a/migrations/InstallStructArmed/Install.mk b/migrations/InstallStructArmed/Install.mk
new file mode 100644
index 0000000..1435e45
--- /dev/null
+++ b/migrations/InstallStructArmed/Install.mk
@@ -0,0 +1,36 @@
+_STRUCT_ARMED_MIGRATION_DIRECTORY := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+STRUCT_ARMED_DIRECTORY := $(PROJECT_DIR)tools/structarmed
+HAS_STRUCT_ARMED_DIR := $(strip $(shell if [ -d $(STRUCT_ARMED_DIRECTORY) ]; then echo TRUE; fi))
+
+ifneq ("$(HAS_STRUCT_ARMED_DIR)","TRUE")
+
+PROJECT_COMPOSER_PLATFORM := $(shell $(DOCKER_RUN) ${DOCKER_IMAGE_NAME} composer config platform.php)
+HELP += $(call MK_HELP,'install-structarmed','Install a standalone copy of structarmed into tools/structarmed')
+
+install-structarmed: $(STRUCT_ARMED_DIRECTORY) _do-install-structarmed
+	@echo 'Now StructArmed is installed, you should edit its configuration file to define appropriate layers:'
+	@echo 'https://boundwize.github.io/structarmed/configuration/'
+.PHONY: install-structarmed
+
+_do-install-structarmed:
+	@$(DOCKER_RUN) --env PHP_EXTENSIONS="$(PHP_EXTENSIONS)" ${DOCKER_IMAGE_NAME} php $(_STRUCT_ARMED_MIGRATION_DIRECTORY)migrate $(PROJECT_DIR)
+.PHONY: _do-install-structarmed
+
+# Installation routine for rector:
+$(STRUCT_ARMED_DIRECTORY):
+	mkdir -p $(STRUCT_ARMED_DIRECTORY)
+	echo '{}' > $(STRUCT_ARMED_DIRECTORY)/composer.json
+	$(DOCKER_RUN) $(DOCKER_IMAGE_NAME) composer \
+		--working-dir=$(STRUCT_ARMED_DIRECTORY) \
+		config platform.php $(PROJECT_COMPOSER_PLATFORM)
+	$(DOCKER_RUN) $(DOCKER_IMAGE_NAME) composer \
+		--working-dir=$(STRUCT_ARMED_DIRECTORY) \
+		require --dev boundwize/structarmed
+	cp $(_STRUCT_ARMED_MIGRATION_DIRECTORY)structarmed.php $(STRUCT_ARMED_DIRECTORY)/
+	echo vendor > $(STRUCT_ARMED_DIRECTORY)/.gitignore
+	$(DOCKER_RUN) $(DOCKER_IMAGE_NAME) composer \
+    		--working-dir=$(STRUCT_ARMED_DIRECTORY) \
+    		install
+# end
+
+endif
diff --git a/migrations/InstallStructArmed/migrate b/migrations/InstallStructArmed/migrate
new file mode 100644
index 0000000..a79d2d2
--- /dev/null
+++ b/migrations/InstallStructArmed/migrate
@@ -0,0 +1,25 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+use Laminas\Internal\Migrations\GitAttributes;
+use Laminas\Internal\Migrations\ProjectInformation;
+
+require __DIR__ . '/../autoloader.php';
+
+/** @var mixed $rootDirectory */
+$rootDirectory = $argv[1] ?? null;
+if (
+    ! is_string($rootDirectory)
+    || $rootDirectory === ''
+    || ! is_dir($rootDirectory)
+) {
+    throw new RuntimeException('Pass a single argument representing the root directory of the target library');
+}
+
+$project = ProjectInformation::fromDirectory($rootDirectory);
+
+// Ensure that the 'tools' directory is export-ignored
+$attributes = new GitAttributes($project->gitAttributes);
+$attributes->ignore('tools');
diff --git a/migrations/InstallStructArmed/structarmed.php b/migrations/InstallStructArmed/structarmed.php
new file mode 100644
index 0000000..828f585
--- /dev/null
+++ b/migrations/InstallStructArmed/structarmed.php
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+use Boundwize\StructArmed\Architecture;
+use Boundwize\StructArmed\Preset\Preset;
+
+return Architecture::define()
+    ->withPresets(Preset::PER(), Preset::CODEQUALITY());

From 813b1ba7a92abcc2524b483d8841b50130a6a2bb Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Thu, 8 Oct 2026 17:38:52 +0100
Subject: [PATCH 2/4] Update documentation for recent additions

Signed-off-by: George Steel <george@net-glue.co.uk>
---
 README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 4e51b42..6ab994a 100644
--- a/README.md
+++ b/README.md
@@ -32,12 +32,8 @@ Other host machine dependencies include:
 
 ### Out-of-the-box `Makefile`
 
-Create a Makefile in the project root with the following contents, after installing this dependency via composer:
-
-```makefile
-# ./Makefile
-include vendor/laminas/internal-tooling/Makefile
-```
+After copying the shipped `Makefile` template, it will need a few minor adjustments.
+These are documented in the template.
 
 Now, running `make` should list a number of useful targets for general QA work on Laminas and Mezzio libraries.
 
@@ -96,6 +92,33 @@ When rector is installed to `./tools/rector`
 - `make rector` (Run rector with --dry-run)
 - `make rector-fix`
 
+### Infection Targets
+
+When infection is installed to `./tools/infection`
+
+- `make infection`
+
+### StructArmed Targets
+
+When [StructArmed](https://boundwize.github.io/structarmed/) is installed to `./tools/structarmed`
+
+- `make structarmed` Runs the analysis
+- `make structarmed-fix` Runs auto fixers
+- `make structarmed-clear` Clears the cache
+
+### Dependency Management Targets
+
+- `make install` - Often not required because this lib is distributed via composer itself
+- `make update` - Runs composer update with the project docker image
+- `make bump-dev` - Bumps _development_ dependencies
+- `make outdated` - Run `composer outdated`
+
+For tools that are installed in subdirectories, it's a pain to cd to each one and run composer for each tool, therefore these targets operate on all installed tools:
+
+- `make install-tools`
+- `make update-tools`
+- `make bump-tools`
+
 ## Migrations
 
 Migrations represent small units of automation for common or one-off maintenance tasks for Laminas Repos.
@@ -127,7 +150,26 @@ Install rector into `./tools/rector`
 make install-rector
 ```
 
-For more information about this migration [see the README](migrations/InstallStandaloneRector/README.md).
+### Infection Installation
+
+Install [infection](https://infection.github.io/) into `./tools/infection`
+
+```bash
+make install-infection
+```
+
+By default, the Min MSI is not configured, so tweaking the configuration file may be necessary.
+Additionally, depending on what version of PHPUnit is installed, some settings may need adjusting for PHPUnit such as `executionOrder`
+
+### StructArmed Installation
+
+Install [StructArmed](https://boundwize.github.io/structarmed/) into `./tools/structarmed`
+
+```bash
+make install-structarmed
+```
+
+Once installed, further [configuration](https://boundwize.github.io/structarmed/quick-start/) will be required.
 
 ### Psalm Removal
 

From 4878768f7a9577e4d75bf8a83312948ced5e74c2 Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Thu, 8 Oct 2026 17:39:42 +0100
Subject: [PATCH 3/4] Add struct-armed installation to the migrations list and
 main tools

Signed-off-by: George Steel <george@net-glue.co.uk>
---
 Makefile                 | 1 +
 migrations/Migrations.mk | 1 +
 2 files changed, 2 insertions(+)

diff --git a/Makefile b/Makefile
index a5ec642..681908b 100644
--- a/Makefile
+++ b/Makefile
@@ -78,6 +78,7 @@ include $(_MAKEFILE_DIR)makefiles/PHPUnit.mk
 include $(_MAKEFILE_DIR)makefiles/Psalm.mk
 include $(_MAKEFILE_DIR)makefiles/Rector.mk
 include $(_MAKEFILE_DIR)makefiles/Infection.mk
+include $(_MAKEFILE_DIR)makefiles/StructArmed.mk
 include $(_MAKEFILE_DIR)makefiles/Utilities.mk
 
 # Include the Tools fragment after all other tooling so that bump and update of stand-alone tools collects all necessary targets
diff --git a/migrations/Migrations.mk b/migrations/Migrations.mk
index bca1cee..55583f0 100644
--- a/migrations/Migrations.mk
+++ b/migrations/Migrations.mk
@@ -4,3 +4,4 @@ include $(_MAKEFILE_DIR)migrations/InstallStandaloneRector/InstallStandaloneRect
 include $(_MAKEFILE_DIR)migrations/InstallMago/InstallMago.mk
 include $(_MAKEFILE_DIR)migrations/UninstallPsalm/UninstallPsalm.mk
 include $(_MAKEFILE_DIR)migrations/InstallInfectionWithMago/Install.mk
+include $(_MAKEFILE_DIR)migrations/InstallStructArmed/Install.mk

From fecc594e131f20914c8e62cbe2fd8bc63cd3fd3e Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Thu, 8 Oct 2026 17:53:43 +0100
Subject: [PATCH 4/4] Fix incorrect CLI argument

Signed-off-by: George Steel <george@net-glue.co.uk>
---
 makefiles/StructArmed.mk | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/makefiles/StructArmed.mk b/makefiles/StructArmed.mk
index aee992b..01d2308 100644
--- a/makefiles/StructArmed.mk
+++ b/makefiles/StructArmed.mk
@@ -30,7 +30,7 @@ structarmed-clear:
 	@$(DOCKER_RUN) $(DOCKER_IMAGE_NAME) \
 		$(STRUCT_ARMED_DIRECTORY)/vendor/bin/structarmed \
 		--config $(STRUCT_ARMED_DIRECTORY)/structarmed.php \
-		clear-cache
+		--clear-cache
 .PHONY: structarmed-clear
 
 structarmed-update: