Improve build tooling: fix CGL issues and enhance Makefile

Build/.php-cs-fixer.dist.php

@@ -14,7 +14,7 @@
     ->setRules([
         '@DoctrineAnnotation' => true,
         // @todo: Switch to @PER-CS2.0 once php-cs-fixer's todo list is done: https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/issues/7247
-        '@PER-CS1.0' => true,
+        '@PER-CS1x0' => true,
         'array_indentation' => true,
         'array_syntax' => ['syntax' => 'short'],
         'cast_spaces' => ['space' => 'none'],

Makefile

@@ -1,62 +1,130 @@
+# ==============================================================================
+# TYPO3 Documentation - Makefile
+# ==============================================================================
+# Run `make` or `make help` to see available commands
+#
+# Prerequisites:
+#   - Docker (for docs rendering)
+#   - DDEV (for code generation tasks)
+# ==============================================================================
+
+# ------------------------------------------------------------------------------
+# Configuration
+# ------------------------------------------------------------------------------
+DOCKER_IMAGE := ghcr.io/typo3-documentation/render-guides:latest
+DOCKER_USER := $(shell id -u):$(shell id -g)
+DOCS_DIR := Documentation
+DOCS_OUTPUT := Documentation-GENERATED-temp
+COMPOSER_AUTOLOAD := .Build/vendor/autoload.php
+
+.DEFAULT_GOAL := help
+
+# ------------------------------------------------------------------------------
+# Dependency Checks
+# ------------------------------------------------------------------------------
+.PHONY: check-dependencies
+check-dependencies:
+	@if [ ! -f "$(COMPOSER_AUTOLOAD)" ]; then \
+		echo ""; \
+		echo "ERROR: Dependencies not installed."; \
+		echo ""; \
+		echo "Please run:"; \
+		echo "  make install"; \
+		echo ""; \
+		exit 1; \
+	fi
+
+# ------------------------------------------------------------------------------
+# Help
+# ------------------------------------------------------------------------------
 .PHONY: help
-help: ## Displays this list of targets with descriptions
-	@echo "The following commands are available:\n"
-	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
-
+help: ## Display available commands
+	@echo "Usage: make [target]\n"
+	@echo "Targets:"
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[32m%-20s\033[0m %s\n", $$1, $$2}'
+
+# ------------------------------------------------------------------------------
+# Documentation
+# ------------------------------------------------------------------------------
 .PHONY: docs
-docs: ## Generate projects documentation (from "Documentation" directory)
-	mkdir -p Documentation-GENERATED-temp
-
-	docker run --user $(shell id -u):$(shell id -g) --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
+docs: ## Build documentation locally
+	mkdir -p $(DOCS_OUTPUT)
+	docker run --user $(DOCKER_USER) --rm --pull always -v "$(shell pwd)":/project -t $(DOCKER_IMAGE) --config=$(DOCS_DIR)
+
+.PHONY: docs-test
+docs-test: ## Build documentation with strict validation (CI mode)
+	mkdir -p $(DOCS_OUTPUT)
+	docker run --user $(DOCKER_USER) --rm --pull always -v "$(shell pwd)":/project -t $(DOCKER_IMAGE) --config=$(DOCS_DIR) --no-progress --fail-on-log
+
+.PHONY: docs-open
+docs-open: ## Open rendered documentation in browser
+	@if [ -f "$(DOCS_OUTPUT)/Index.html" ]; then \
+		xdg-open "$(DOCS_OUTPUT)/Index.html" 2>/dev/null || open "$(DOCS_OUTPUT)/Index.html" 2>/dev/null || echo "Open $(DOCS_OUTPUT)/Index.html in your browser"; \
+	else \
+		echo "Documentation not found. Run 'make docs' first."; \
+	fi
+
+# ------------------------------------------------------------------------------
+# Code Generation (requires DDEV)
+# ------------------------------------------------------------------------------
+.PHONY: generate
+generate: setup-typo3 codesnippets command-json ## Regenerate all auto-generated documentation
 
-.PHONY: test-docs
-test-docs: ## Test the documentation rendering
-	mkdir -p Documentation-GENERATED-temp
+.PHONY: codesnippets
+codesnippets: check-dependencies ## Regenerate PHP code snippets
+	ddev exec .Build/bin/typo3 codesnippet:create $(DOCS_DIR)/
 
-	docker run --user $(shell id -u):$(shell id -g) --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log
+.PHONY: command-json
+command-json: check-dependencies ## Regenerate console commands JSON
+	ddev exec .Build/bin/typo3 clinspector:gadget > $(DOCS_DIR)/ApiOverview/CommandControllers/commands.json
+	echo "" >> $(DOCS_DIR)/ApiOverview/CommandControllers/commands.json
 
-.PHONY: generate
-generate: setup-typo3 codesnippets command-json ## Regenerate automatic code documentation
+# ------------------------------------------------------------------------------
+# Setup (requires DDEV)
+# ------------------------------------------------------------------------------
+.PHONY: install
+install: composer-update ## Install project dependencies
 
-.PHONY: codesnippets
-codesnippets: ## Regenerate code snippets
-	ddev exec .Build/bin/typo3 codesnippet:create Documentation/
+.PHONY: composer-update
+composer-update: ## Update Composer dependencies
+	Build/Scripts/runTests.sh -s composerUpdate
 
 .PHONY: setup-typo3
-setup-typo3: ## Setup TYPO3 stub
+setup-typo3: check-dependencies ## Initialize TYPO3 for documentation generation
 	ddev exec '.Build/bin/typo3 setup --driver=sqlite --username=db --password=db --admin-username=john-doe --admin-user-password="John-Doe-1701D." --admin-email="[email protected]" --project-name="TYPO3 Docs" --no-interaction --server-type=apache --force'
 
-.PHONY: command-json
-command-json: ## Regenerate JSON file containing all console commands
-	ddev exec .Build/bin/typo3 clinspector:gadget > Documentation/ApiOverview/CommandControllers/commands.json
-	echo "" >> Documentation/ApiOverview/CommandControllers/commands.json
+# ------------------------------------------------------------------------------
+# Testing
+# ------------------------------------------------------------------------------
+.PHONY: test
+test: docs-test test-lint test-cgl test-yaml ## Run all tests
 
 .PHONY: test-lint
-test-lint: ## Regenerate code snippets
+test-lint: ## Check PHP syntax
 	Build/Scripts/runTests.sh -s lint
 
 .PHONY: test-cgl
-test-cgl: ## Regenerate code snippets
-	Build/Scripts/runTests.sh -s cgl
+test-cgl: check-dependencies ## Check TYPO3 Coding Guidelines (dry-run)
+	Build/Scripts/runTests.sh -s cgl -n
 
 .PHONY: test-yaml
-test-yaml: ## Regenerate code snippets
+test-yaml: check-dependencies ## Validate YAML files
 	Build/Scripts/runTests.sh -s yamlLint
 
-
-.PHONY: composerUpdate
-composerUpdate: ## Update all dependencies (the composer.lock is not commited)
-	Build/Scripts/runTests.sh -s composerUpdate
-
-.PHONY: install
-install: composerUpdate## Update all dependencies (the composer.lock is not commited)
-
-.PHONY: test
-test: test-docs test-lint test-cgl test-yaml## Test the documentation rendering
+# ------------------------------------------------------------------------------
+# Fixing
+# ------------------------------------------------------------------------------
+.PHONY: fix
+fix: fix-cgl ## Apply all automatic fixes
 
 .PHONY: fix-cgl
-fix-cgl: ## Fix cgl
+fix-cgl: check-dependencies ## Fix TYPO3 Coding Guidelines violations
 	Build/Scripts/runTests.sh -s cgl
 
-.PHONY: Fix all
-fix: fix-cgl## Test the documentation rendering
+# ------------------------------------------------------------------------------
+# Cleanup
+# ------------------------------------------------------------------------------
+.PHONY: clean
+clean: ## Remove generated documentation
+	rm -rf $(DOCS_OUTPUT)
+	@echo "Cleaned $(DOCS_OUTPUT)"

composer.json

@@ -4,6 +4,7 @@
     "license": "OPL-1.0",
     "type": "typo3-cms-documentation",
     "require": {
+        "php": ">=8.2",
         "typo3/cms-core": "dev-main as 13.4"
     },
     "require-dev": {