Prevent adding PHPDoc types instead of native types

PHPDoc types can sometimes be entirely expressed as PHP native types. It
is better because it avoids code duplication and enables type runtime
check.

This will help us slowly migrate away from PHPDoc typing to PHP native typing.

.github/workflows/main.yml

@@ -61,6 +61,23 @@ jobs:
           FAILURE_ACTION: "${{ matrix.experimental == true }}"
         run: vendor/bin/phpunit --verbose || $FAILURE_ACTION
 
+  phpdoc-types:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup PHP, with composer and extensions
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.1
+          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          coverage: none
+          tools: cs2pr
+
+      - name: Check PHPDoc types
+        run: ./bin/check-phpdoc-types
+
   php-cs-fixer:
     runs-on: ubuntu-latest
     steps:

bin/check-phpdoc-types

@@ -0,0 +1,29 @@
+#!/usr/bin/env php
+<?php
+
+/**
+ * This will check that the "current patch" does not add or modify lines that contain types as PHPDoc when we can express
+ * them with PHP native types. The "current patch" is either the file about to be committed, the non-committed file, or
+ * the latest commit.
+ *
+ * This will help us slowly migrate away from PHPDoc typing to PHP native typing.
+ */
+function checkPhpDocTypes(): void
+{
+    $content = `git diff --cached` ?? `git diff` ?? `git show HEAD`;
+    preg_match_all('~^\+ +\* @(param|var) (mixed|string|int|float|bool|null|array|\?|\|)+ \$\w+$~m', $content, $parameters);
+    preg_match_all('~^\+ +\* @return (mixed|string|int|float|bool|null|array|void|\?|\|)+$~m', $content, $returns);
+
+    $errors = [
+        ...$parameters[0],
+        ...$returns[0],
+    ];
+
+    if ($errors) {
+        echo 'PHP native types must be used instead of PHPDoc types (without comments), for the following lines:' . PHP_EOL . PHP_EOL;
+        echo join(PHP_EOL, $errors) . PHP_EOL;
+        exit(1);
+    }
+}
+
+checkPhpDocTypes();

bin/pre-commit

@@ -23,6 +23,12 @@ if [ "$files" != "" ]; then
     echo "$files" | xargs git add
 fi
 
+# Check PHPDoc types
+./bin/check-phpdoc-types
+if [ $? -ne 0 ]; then
+    pass=false
+fi
+
 if $pass; then
     exit 0
 else

composer.json

@@ -42,6 +42,7 @@
     ],
     "scripts": {
         "check": [
+            "./bin/check-phpdoc-types",
             "phpcs src/ tests/ --report=checkstyle",
             "phpcs --report-width=200 samples/ src/ tests/ --ignore=samples/Header.php --standard=PHPCompatibility --runtime-set testVersion 8.0- -n",
             "php-cs-fixer fix --ansi --dry-run --diff",