N°8796 - Add pre-commit hooks for auto PHP code style fixing

.gitignore

@@ -58,6 +58,10 @@ tests/*/vendor/*
 /tests/php-unit-tests/phpunit.xml
 /tests/php-unit-tests/postbuild_integration.xml
 
+# CaptainHook: For Git hooks management
+# - Never version local config file
+/captainhook.config.json
+
 
 # Jetbrains
 /.idea/**

.make/git-hooks/README.md

@@ -1,13 +1,16 @@
 # Git hooks for iTop
 
+> [!WARNING]
+> This read me and the `install.php` / `pre-commit.php` files are outdated. If we were to keep using what it is supposed to do, we should migrate it to the proper CaptainHook Git hooks manager.\
+
 ## ❓ Goal
 
-Those [git hooks](https://git-scm.com/docs/githooks) aims to ease developing on [iTop](https://github.com/Combodo/iTop).
+~~Those [git hooks](https://git-scm.com/docs/githooks) aims to ease developing on [iTop](https://github.com/Combodo/iTop).~~
 
 ## ☑ Available hooks
 
-* pre-commit : rejects commit if you have at least one SCSS file staged, and no CSS file
+* ~~pre-commit : rejects commit if you have at least one SCSS file staged, and no CSS file~~
 
 ## ⚙ Install
 
-Just run install.php !
+~~Just run install.php !~~

.make/git-hooks/pre-commit-php-code-style-fixer.php

@@ -0,0 +1,87 @@
+<?php
+
+/**
+ * Git pre-commit hook to run PHP-CS-Fixer on staged PHP files which are not in third-party libs.
+ */
+
+$sRootFolderAbsPath = dirname(dirname(__DIR__));
+$sPhpCsFixerBinaryAbsPath = $sRootFolderAbsPath.'/tests/php-code-style/vendor/bin/php-cs-fixer';
+$sPhpCsFixerConfigFileAbsPath = $sRootFolderAbsPath.'/tests/php-code-style/.php-cs-fixer.dist.php';
+
+// Retrieve list of staged (`--cached`) files (ACMR: Added, Changed, Modified, Renamed only)
+$sStagedFilesCmd = 'git diff --cached --name-only --diff-filter=ACMR';
+exec($sStagedFilesCmd, $aStagedFiles);
+
+// Ignore non-PHP files and third-party folders
+$aStagedFiles = array_filter($aStagedFiles, function ($sStagedFile) {
+	// Ignore non-PHP files
+	if (false === preg_match('/\.php$/i', $sStagedFile)) {
+		return false;
+	}
+	// Ignore files in third-party folders
+	$sNormalizedStagedFile = str_replace('\\', '/', $sStagedFile);
+	if (
+		strpos($sNormalizedStagedFile, 'lib/') !== false             // Our root Composer libs folder
+		|| strpos($sNormalizedStagedFile, 'vendor/') !== false       // Any sub-folder Composer libs folder
+		|| strpos($sNormalizedStagedFile, 'node_modules/') !== false // OUr root NPM libs folder
+	) {
+		return false;
+	}
+
+	return true;
+});
+
+$iStagedFilesCount = count($aStagedFiles);
+if ($iStagedFilesCount === 0) {
+	echo "No file to check for PHP code style.\n";
+	exit(0);
+}
+echo "{$iStagedFilesCount} file(s) to check for PHP code style.\n";
+
+// Prepare batch of files to process (limit command line length as it could fail on some systems)
+$aChunks = array_chunk(array_values($aStagedFiles), 50);
+$iExitCode = 0;
+
+// Execute chunks
+$iNbChunks = count($aChunks);
+foreach ($aChunks as $iIdx => $aChunk) {
+	$iChunkNumber = $iIdx + 1;
+
+	$sChunkFilesAsArgs = implode(' ', array_map('escapeshellarg', $aChunk));
+	$sPhpCsFixerCmd = escapeshellcmd(PHP_BINARY)
+		.' '.escapeshellarg($sPhpCsFixerBinaryAbsPath)
+		.' fix --using-cache=no --config='.escapeshellarg($sPhpCsFixerConfigFileAbsPath)
+		.' --verbose '.$sChunkFilesAsArgs;
+
+	echo "Executing chunk {$iChunkNumber}/{$iNbChunks} : {$sPhpCsFixerCmd}\n\n";
+	passthru($sPhpCsFixerCmd, $iExitCode);
+	if ($iExitCode !== 0) {
+		echo "Failed to fix chunk #{$iChunkNumber} Aborting.\n";
+		exit($iExitCode);
+	}
+}
+
+// Find which files have been fixed and re-stage them
+$sFixedFilesCmd = 'git diff --name-only --diff-filter=M';
+exec($sFixedFilesCmd, $aFixedFiles);
+$aFixedFilesToRestage = array_intersect($aFixedFiles, $aStagedFiles);
+
+// Re-stage fixed files to include them in the commit
+if (count($aFixedFilesToRestage) === 0) {
+	echo "No file needed PHP code style fixing, it was already ok.\n";
+	exit(0);
+}
+
+echo "Re-staging fixed files:\n";
+foreach ($aFixedFilesToRestage as $sFixedFileToRestage) {
+	$sGitAddCmd = 'git add '.escapeshellarg($sFixedFileToRestage);
+
+	echo " - {$sFixedFileToRestage}\n";
+	passthru($sGitAddCmd, $iRetCode);
+	if ($iRetCode !== 0) {
+		echo "  Failed to re-stage fixed file '{$sFixedFileToRestage}'. Continuing anyway.\n";
+	}
+}
+
+echo "All done, file(s) PHP code style fixed and added to commit.\n";
+exit($iExitCode);

captainhook.config.json.dist

@@ -0,0 +1,9 @@
+// * Duplicate file into `captainhook.config.json`
+// * Remove all comments (`// ...`)
+// * Keep only 1 `php-path` line and adjust it to your environment
+{
+  // Example of Windows path to PHP binary
+  "php-path": "C:/wamp64/bin/php/php8.2.26/php.exe"
+  // Example of Unix path tp PHP binary
+  "php-path": "/usr/bin/php"
+}

captainhook.json

@@ -0,0 +1,21 @@
+{
+  "config" : {
+    "bootstrap" : "lib/autoload.php"
+  },
+  "commit-msg" : {
+    "enabled" : true,
+    "actions" : []
+  },
+  "pre-commit" : {
+    "enabled" : true,
+    "actions" : [
+      {
+        "action" : "{$CONFIG|value-of:php-path} .make/git-hooks/pre-commit-php-code-style-fixer.php",
+        "config" : {
+          "label" : "PHP code style fixer",
+          "allow-failure": false
+        }
+      }
+    ]
+  }
+}

composer.json

@@ -36,6 +36,7 @@
     "soundasleep/html2text": "~2.1"
   },
   "require-dev": {
+    "captainhook/captainhook": "^5.25",
     "symfony/debug-bundle": "~6.4.0",
     "symfony/stopwatch": "~6.4.0",
     "symfony/web-profiler-bundle": "~6.4.0"
@@ -98,8 +99,9 @@
     }
   },
   "scripts": {
-    "post-install-cmd": ["@rmUnnecessaryFolders", "@tcpdfCustomFonts"],
-    "post-update-cmd": ["@rmUnnecessaryFolders", "@tcpdfCustomFonts"],
+    "post-install-cmd": ["@installGitHooks","@rmUnnecessaryFolders", "@tcpdfCustomFonts"],
+    "post-update-cmd": ["@installGitHooks","@rmUnnecessaryFolders", "@tcpdfCustomFonts"],
+    "installGitHooks": "@php lib/bin/captainhook install --force",
     "rmUnnecessaryFolders":  "@php .make/dependencies/rmUnnecessaryFolders.php --manager composer",
     "tcpdfCustomFonts":  "@php .make/dependencies/composer/tcpdf/tcpdfUpdateFonts.php"
   }