sync with repo-template-php

.devcontainer/Dockerfile

@@ -0,0 +1,16 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.209.6/containers/php/.devcontainer/base.Dockerfile
+
+# [Choice] PHP version (use -bullseye variants on local arm64/Apple Silicon): 8, 8.1, 8.0, 7, 7.4, 7.3, 8-bullseye, 8.1-bullseye, 8.0-bullseye, 7-bullseye, 7.4-bullseye, 7.3-bullseye, 8-buster, 8.1-buster, 8.0-buster, 7-buster, 7.4-buster
+ARG VARIANT="8.1-apache-bullseye"
+FROM mcr.microsoft.com/vscode/devcontainers/php:0-${VARIANT}
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

.devcontainer/devcontainer.json

@@ -0,0 +1,44 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.209.6/containers/php
+{
+	"name": "PHP",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"args": { 
+			// Update VARIANT to pick a PHP version: 8, 8.1, 8.0, 7, 7.4
+			// Append -bullseye or -buster to pin to an OS version.
+			// Use -bullseye variants on local on arm64/Apple Silicon.
+			"VARIANT": "8",
+			"NODE_VERSION": "16"
+		}
+	},
+
+	// Set *default* container specific settings.json values on container create.
+	"settings": { 
+		"php.validate.executablePath": "/usr/local/bin/php"
+	},
+
+	// Add the IDs of extensions you want installed when the container is created.
+	"extensions": [
+		"aaron-bond.better-comments",
+		"bmewburn.vscode-intelephense-client",
+		"felixfbecker.php-debug",
+		"ikappas.composer",
+		"lextudio.restructuredtext",
+		"mrmlnc.vscode-apache",
+		"neilbrayfield.php-docblocker"
+	],
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	"forwardPorts": [8080],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html"
+
+	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode",
+	"features": {
+		"git": "latest",
+		"github-cli": "latest"
+	}
+}

.github/workflows/php.yml

@@ -1,10 +1,17 @@
 name: PHP Composer
 
 on:
+  workflow_dispatch:
   push:
     branches: [ main ]
+    paths:
+      - 'src/**/*.php'
+      - '!vendor'
   pull_request:
     branches: [ main ]
+    paths:
+      - 'src/**/*.php'
+      - '!vendor'
 
 jobs:
   build:
@@ -14,8 +21,14 @@ jobs:
     steps:
     - uses: actions/checkout@v2
 
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.1'
+        tools: composer:v2, phpdoc
+
     - name: Validate composer.json and composer.lock
-      run: composer validate
+      run: composer validate --strict
 
     - name: Cache Composer packages
       id: composer-cache
@@ -25,8 +38,18 @@ jobs:
         key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
         restore-keys: |
           ${{ runner.os }}-php-
+
     - name: Install dependencies
       uses: php-actions/composer@v6
 
     - name: Run test suite
       run: composer test
+
+    - name: Build documentation
+      run: phpdoc
+
+    - name: Deploy documentation
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./public

.gitignore

@@ -1,2 +1,18 @@
-/vendor
-composer.lock
+# Composer
+composer.phar
+vendor/
+
+# NPM
+node_modules/
+
+# Visual Studio Code extensions
+# Local History (xyz.local-history): https://marketplace.visualstudio.com/items?itemName=xyz.local-history
+.history
+
+# user-configured files
+# PHPUnit
+.phpunit.xml
+
+# phpDocumentor
+.phpdoc
+phpdoc.xml

.phpcs.xml

@@ -1,9 +1,33 @@
 <?xml version="1.0"?>
 <ruleset>
-	<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki"/>
+	<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki" />
+	<!-- don't need to document typed return values -->
+	<rule ref="MediaWiki.Commenting.FunctionComment.MissingReturn">
+		<severity>0</severity>
+	</rule>
+	<rule ref="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic">
+		<severity>0</severity>
+	</rule>
+	<!-- don't need to document private members -->
+	<rule ref="MediaWiki.Commenting.FunctionComment.MissingDocumentationPrivate">
+		<severity>0</severity>
+	</rule>
+	<rule ref="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationPrivate">
+		<severity>0</severity>
+	</rule>
+
+	<rule ref="Squiz.Commenting.FunctionComment.IncorrectTypeHint"/>
+	<rule ref="Generic.Files.LineLength">
+		<properties>
+			<!-- inherited line limit from MediaWiki is 100; make it at least 120 -->
+			<property name="lineLimit" value="120" />
+		</properties>
+	</rule>
+
 	<file>.</file>
 	<exclude-pattern>/tests/*</exclude-pattern>
-	<arg name="bootstrap" value="./vendor/mediawiki/mediawiki-codesniffer/utils/bootstrap-ci.php"/>
-	<arg name="extensions" value="php,php5,inc"/>
-	<arg name="encoding" value="UTF-8"/>
+	<exclude-pattern>.history</exclude-pattern>
+	<arg name="bootstrap" value="./vendor/mediawiki/mediawiki-codesniffer/utils/bootstrap-ci.php" />
+	<arg name="extensions" value="php" />
+	<arg name="encoding" value="UTF-8" />
 </ruleset>

.phpunit.xml.dist

@@ -1,20 +1,26 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit bootstrap="tests/phpunit/bootstrap.php"
-		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-		 xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/9.3/phpunit.xsd"
+<phpunit
+	bootstrap="vendor/autoload.php"
+	colors="true"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
 
-		 colors="true"
-		 backupGlobals="false"
-		 convertErrorsToExceptions="true"
-		 convertNoticesToExceptions="true"
-		 convertWarningsToExceptions="true"
-		 forceCoversAnnotation="true"
-		 failOnWarning="true"
-		 stopOnFailure="false"
-		 beStrictAboutTestsThatDoNotTestAnything="true"
-		 beStrictAboutOutputDuringTests="true"
-		 verbose="false">
+	backupGlobals="false"
+	beStrictAboutTestsThatDoNotTestAnything="true"
+	beStrictAboutOutputDuringTests="true"
+	convertErrorsToExceptions="true"
+	convertNoticesToExceptions="true"
+	convertWarningsToExceptions="true"
+	forceCoversAnnotation="true"
+	failOnWarning="true"
+	stopOnFailure="false"
+	verbose="false">
 	<php>
 		<ini name="memory_limit" value="512M" />
 	</php>
+	<testsuites>
+		<testsuite name="Unit">
+			<directory suffix="Test.php">./tests</directory>
+		</testsuite>
+	</testsuites>
 </phpunit>

composer.json

@@ -38,7 +38,8 @@
 			"parallel-lint . --exclude vendor --exclude node_modules",
 			"./vendor/bin/phpunit tests",
 			"minus-x check .",
-			"phpcs -p -s"
+			"phpcs -p -s",
+			"psalm"
 		],
 		"fix": [
 			"minus-x fix .",