Merge branch 'php8.4' of https://github.com/LongTermSupport/php-qa-ci into php8.4

Author: LTSCommerce

bin/qa

@@ -11,6 +11,19 @@
 # Run all PHPUnit tests:
 # phpUnitQuickTests=0 ./bin/qa
 
+# Early --json detection: redirect all decoration to stderr before any echo
+# Full --json validation happens later in options.inc.bash
+_qa_has_json_flag=0
+for _qa_arg in "$@"; do
+    [[ "$_qa_arg" == "--json" ]] && _qa_has_json_flag=1 && break
+done
+if [[ "$_qa_has_json_flag" == "1" ]]; then
+    exec 3>&1 1>&2
+else
+    exec 3>&1
+fi
+unset _qa_has_json_flag _qa_arg
+
 if [[ "$COMPOSER_RUNTIME_BIN_DIR" != "" ]]; then
   echo "new composer detected, no longer a symlink, instead its a parent script"
   binDir="$COMPOSER_RUNTIME_BIN_DIR"
@@ -49,6 +62,9 @@ $(hostname) $0 $@
 
 source ./../includes/options.inc.bash
 
+# Note: fd 3 redirection is set up at the top of this script (early --json detection)
+# so that ALL decoration output goes to stderr before any echo statements.
+
 #### FUNCTIONS #################################################
 
 phpBinPath=${PHP_QA_CI_PHP_EXECUTABLE:-$(which php)}

includes/generic/phpstan.inc.bash

@@ -9,30 +9,57 @@ if [[ "true" == "$CI" ]]; then
   phpstanNoProgress+=(--no-progress)
 fi
 
-while ((phpStanExitCode > 0)); do
-  # Run PHPStan with tee to capture output to both file and stdout
+if [[ "1" == "${useJsonOutput:-0}" ]]; then
+  # JSON mode: single run, no retry loop, structured output
+  phpStanJsonFile="$phpStanLogDir/phpstan.json"
+
   phpNoXdebug -f "$pharDir"/phpstan.phar -- \
     analyse ${pathsToCheck[@]} \
     -c "$phpstanConfigPath" \
-    ${phpstanNoProgress[@]:-} \
-    2>&1 | tee "$phpStanLogDir/$phpStanLogFile"
+    --no-progress \
+    --error-format=json \
+    > "$phpStanJsonFile"
+
+  phpStanExitCode=$?
 
-  phpStanExitCode=${PIPESTATUS[0]}
+  # Output JSON to fd 3 (original stdout, bypassing stderr redirect)
+  cat "$phpStanJsonFile" >&3
 
-  # Archive PHPStan log with timestamp - keep last 10 per pattern
-  # Do this BEFORE tryAgainOrAbort so log is archived even on failure (in CI mode)
-  # Uses shared archiveToolLog function from functions.inc.bash
-  archiveToolLog "PHPStan" "$phpStanLogDir" "$phpStanLogFile" "$specifiedPath" "${pathsToCheck[@]}"
+  # Archive the JSON log
+  archiveToolLog "PHPStan" "$phpStanLogDir" "phpstan.json" "$specifiedPath" "${pathsToCheck[@]}"
 
-  #exit code 0 = fine, 1 = ran fine but found errors, else it means it crashed
   if ((phpStanExitCode > 1)); then
-    printf "\n\n\nPHPStan Crashed!!....\n\nrunning again with debug mode:\nWhere ever it stops is probably a fatal PHP error\n\n"
-    eval phpNoXdebug -f "$pharDir"/phpstan.phar -- analyse $pathsStringArray -c "$phpstanConfigPath" --debug -v
+    echo "PHPStan crashed (exit code: $phpStanExitCode)" >&2
     exit 1
   fi
-  if ((phpStanExitCode > 0)); then
-    tryAgainOrAbort "PHPStan"
-  fi
-done
+  # Exit code 1 = found errors — expected for JSON consumption, don't retry
+else
+  # Text mode: original behavior with retry loop
+  while ((phpStanExitCode > 0)); do
+    # Run PHPStan with tee to capture output to both file and stdout
+    phpNoXdebug -f "$pharDir"/phpstan.phar -- \
+      analyse ${pathsToCheck[@]} \
+      -c "$phpstanConfigPath" \
+      ${phpstanNoProgress[@]:-} \
+      2>&1 | tee "$phpStanLogDir/$phpStanLogFile"
+
+    phpStanExitCode=${PIPESTATUS[0]}
+
+    # Archive PHPStan log with timestamp - keep last 10 per pattern
+    # Do this BEFORE tryAgainOrAbort so log is archived even on failure (in CI mode)
+    # Uses shared archiveToolLog function from functions.inc.bash
+    archiveToolLog "PHPStan" "$phpStanLogDir" "$phpStanLogFile" "$specifiedPath" "${pathsToCheck[@]}"
+
+    #exit code 0 = fine, 1 = ran fine but found errors, else it means it crashed
+    if ((phpStanExitCode > 1)); then
+      printf "\n\n\nPHPStan Crashed!!....\n\nrunning again with debug mode:\nWhere ever it stops is probably a fatal PHP error\n\n"
+      eval phpNoXdebug -f "$pharDir"/phpstan.phar -- analyse $pathsStringArray -c "$phpstanConfigPath" --debug -v
+      exit 1
+    fi
+    if ((phpStanExitCode > 0)); then
+      tryAgainOrAbort "PHPStan"
+    fi
+  done
+fi
 
 set -e

includes/options.inc.bash

@@ -9,17 +9,30 @@ IFS=$'\n\t'
 
 singleToolToRun=
 specifiedPath=
+useJsonOutput=0
+
+# Pre-process long options (getopts only handles short options)
+processedArgs=()
+for arg in "$@"; do
+    case "$arg" in
+        --json) useJsonOutput=1 ;;
+        *) processedArgs+=("$arg") ;;
+    esac
+done
+set -- "${processedArgs[@]}"
 
 function usage {
     echo "Usage:"
-    echo "$binDir/qa [-t tool to run ] [ -p path to scan ]"
+    echo "$binDir/qa [-t tool to run ] [ -p path to scan ] [ --json ]"
     echo ""
     echo "Defaults to using all tools and scanning whole project based on platform"
     echo ""
     echo " - use -h to see this help"
     echo ""
     echo " - use -p to specify a specific path to scan"
     echo ""
+    echo " - use --json to get structured JSON output (supported tools only)"
+    echo ""
     echo " - use -t to specify a single tool:"
     echo "     allLints                   all linting tools"
     echo "     allStatic                  all static analysis tools"
@@ -178,6 +191,26 @@ then
     echo "Running Single Tool: $singleToolToRun"
 fi
 
+# Validate JSON output compatibility
+if [[ "1" == "$useJsonOutput" ]]; then
+    if [[ -z "$singleToolToRun" ]]; then
+        printf "\nERROR: --json requires a single tool (-t)\n" >&2
+        printf "  Example: vendor/bin/qa -t phpstan --json\n\n" >&2
+        exit 1
+    fi
+
+    case "$singleToolToRun" in
+        phpstan) ;; # Native --error-format=json
+        *)
+            printf "\nERROR: --json is not yet supported for '%s'\n\n" "$singleToolToRun" >&2
+            printf "Tools with --json support:\n" >&2
+            printf "  phpstan    (native --error-format=json)\n\n" >&2
+            printf "Run without --json, or use a supported tool.\n\n" >&2
+            exit 1
+            ;;
+    esac
+fi
+
 if [[ "" != "$specifiedPath" ]]
 then
     echo "Scanning Specified Path: $specifiedPath"