From 3107205c9f356bde809777ad162dffa98f806f93 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Wed, 5 Jun 2024 16:37:30 +0200 Subject: [PATCH 1/2] Documentation: improve information about report data format This commit adds detailed information about the array format `Report` classes receive in the `generateFileReport()` method to the `Report` interface and to the `Reporter::prepareFileReport()` method which prepares the data. It also makes the parameter specification in the individual reports a little more specific and references the `Report` interface for further details. --- src/Reporter.php | 24 +++++++++++++++++++++++- src/Reports/Cbf.php | 9 +++++---- src/Reports/Checkstyle.php | 9 +++++---- src/Reports/Code.php | 9 +++++---- src/Reports/Csv.php | 9 +++++---- src/Reports/Diff.php | 9 +++++---- src/Reports/Emacs.php | 9 +++++---- src/Reports/Full.php | 9 +++++---- src/Reports/Info.php | 9 +++++---- src/Reports/Json.php | 9 +++++---- src/Reports/Junit.php | 9 +++++---- src/Reports/Notifysend.php | 9 +++++---- src/Reports/Performance.php | 9 +++++---- src/Reports/Report.php | 31 +++++++++++++++++++++++++++---- src/Reports/Source.php | 9 +++++---- src/Reports/Summary.php | 9 +++++---- src/Reports/VersionControl.php | 9 +++++---- src/Reports/Xml.php | 9 +++++---- 18 files changed, 130 insertions(+), 69 deletions(-) diff --git a/src/Reporter.php b/src/Reporter.php index 288a78e61e..deaa8e2849 100644 --- a/src/Reporter.php +++ b/src/Reporter.php @@ -329,7 +329,29 @@ public function cacheFileReport(File $phpcsFile) * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file that has been processed. * - * @return array + * @return array Prepared report data. + * The format of prepared data is as follows: + * ``` + * array( + * 'filename' => string The name of the current file. + * 'errors' => int The number of errors seen in the current file. + * 'warnings' => int The number of warnings seen in the current file. + * 'fixable' => int The number of fixable issues seen in the current file. + * 'messages' => array( + * int => array( + * int => array( + * int => array( + * 'message' => string The error/warning message. + * 'source' => string The full error code for the message. + * 'severity' => int The severity of the message. + * 'fixable' => bool Whether this error/warning is auto-fixable. + * 'type' => string The type of message. Either 'ERROR' or 'WARNING'. + * ) + * ) + * ) + * ) + * ) + * ``` */ public function prepareFileReport(File $phpcsFile) { diff --git a/src/Reports/Cbf.php b/src/Reports/Cbf.php index b0be0ae12d..d3b70fab62 100644 --- a/src/Reports/Cbf.php +++ b/src/Reports/Cbf.php @@ -28,10 +28,11 @@ class Cbf implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool * @throws \PHP_CodeSniffer\Exceptions\DeepExitException diff --git a/src/Reports/Checkstyle.php b/src/Reports/Checkstyle.php index d7d486230c..8640561fb6 100644 --- a/src/Reports/Checkstyle.php +++ b/src/Reports/Checkstyle.php @@ -24,10 +24,11 @@ class Checkstyle implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Code.php b/src/Reports/Code.php index 50f4f028cd..e50a928e8e 100644 --- a/src/Reports/Code.php +++ b/src/Reports/Code.php @@ -25,10 +25,11 @@ class Code implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Csv.php b/src/Reports/Csv.php index aef7d7e375..ed7caca381 100644 --- a/src/Reports/Csv.php +++ b/src/Reports/Csv.php @@ -22,10 +22,11 @@ class Csv implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Diff.php b/src/Reports/Diff.php index 03f7bf20d5..9580b4e977 100644 --- a/src/Reports/Diff.php +++ b/src/Reports/Diff.php @@ -22,10 +22,11 @@ class Diff implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Emacs.php b/src/Reports/Emacs.php index 3f0036576a..076768a78e 100644 --- a/src/Reports/Emacs.php +++ b/src/Reports/Emacs.php @@ -22,10 +22,11 @@ class Emacs implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Full.php b/src/Reports/Full.php index 4f338c8ce8..b6af4c8e84 100644 --- a/src/Reports/Full.php +++ b/src/Reports/Full.php @@ -23,10 +23,11 @@ class Full implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Info.php b/src/Reports/Info.php index 4039056169..9f1f45aa57 100644 --- a/src/Reports/Info.php +++ b/src/Reports/Info.php @@ -23,10 +23,11 @@ class Info implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Json.php b/src/Reports/Json.php index 0b9ad34fa1..67c8b5e63e 100644 --- a/src/Reports/Json.php +++ b/src/Reports/Json.php @@ -23,10 +23,11 @@ class Json implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Junit.php b/src/Reports/Junit.php index cdbb1d67e3..aaeeb17749 100644 --- a/src/Reports/Junit.php +++ b/src/Reports/Junit.php @@ -25,10 +25,11 @@ class Junit implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Notifysend.php b/src/Reports/Notifysend.php index 1c296958c2..839d99036e 100644 --- a/src/Reports/Notifysend.php +++ b/src/Reports/Notifysend.php @@ -88,10 +88,11 @@ public function __construct() * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Performance.php b/src/Reports/Performance.php index ea90d0a84c..8436989906 100644 --- a/src/Reports/Performance.php +++ b/src/Reports/Performance.php @@ -24,10 +24,11 @@ class Performance implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Report.php b/src/Reports/Report.php index eec5eb1d0b..52d7883b5b 100644 --- a/src/Reports/Report.php +++ b/src/Reports/Report.php @@ -22,10 +22,33 @@ interface Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * The format of the `$report` parameter the function receives is as follows: + * ``` + * array( + * 'filename' => string The name of the current file. + * 'errors' => int The number of errors seen in the current file. + * 'warnings' => int The number of warnings seen in the current file. + * 'fixable' => int The number of fixable issues seen in the current file. + * 'messages' => array( + * int => array( + * int => array( + * int => array( + * 'message' => string The error/warning message. + * 'source' => string The full error code for the message. + * 'severity' => int The severity of the message. + * 'fixable' => bool Whether this error/warning is auto-fixable. + * 'type' => string The type of message. Either 'ERROR' or 'WARNING'. + * ) + * ) + * ) + * ) + * ) + * ``` + * + * @param array $report Prepared report data. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Source.php b/src/Reports/Source.php index 6aa891a4bd..47d6d80cdd 100644 --- a/src/Reports/Source.php +++ b/src/Reports/Source.php @@ -23,10 +23,11 @@ class Source implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Summary.php b/src/Reports/Summary.php index 3f1eb94ef9..165ad64b0c 100644 --- a/src/Reports/Summary.php +++ b/src/Reports/Summary.php @@ -23,10 +23,11 @@ class Summary implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/VersionControl.php b/src/Reports/VersionControl.php index e3ad74b845..daf558de12 100644 --- a/src/Reports/VersionControl.php +++ b/src/Reports/VersionControl.php @@ -31,10 +31,11 @@ abstract class VersionControl implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ diff --git a/src/Reports/Xml.php b/src/Reports/Xml.php index 07f7d0b9fb..68276d80d2 100644 --- a/src/Reports/Xml.php +++ b/src/Reports/Xml.php @@ -24,10 +24,11 @@ class Xml implements Report * and FALSE if it ignored the file. Returning TRUE indicates that the file and * its data should be counted in the grand totals. * - * @param array $report Prepared report data. - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. - * @param bool $showSources Show sources? - * @param int $width Maximum allowed line width. + * @param array $report Prepared report data. + * See the {@see Report} interface for a detailed specification. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on. + * @param bool $showSources Show sources? + * @param int $width Maximum allowed line width. * * @return bool */ From 52c891a1493de9b3874dd138b9dc871f7a9ea3f8 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Wed, 5 Jun 2024 16:54:47 +0200 Subject: [PATCH 2/2] CS/QA: remove unused `foreach` keys from report code As the array format is now documented, these unused variables are no longer needed for documentation purposes. Co-authored-by: Klaus Purer --- src/Reports/Code.php | 6 +++--- src/Reports/Full.php | 6 +++--- src/Reports/Source.php | 4 ++-- src/Reports/VersionControl.php | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/Reports/Code.php b/src/Reports/Code.php index e50a928e8e..6cbd7eb1e7 100644 --- a/src/Reports/Code.php +++ b/src/Reports/Code.php @@ -122,8 +122,8 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false, // Determine the longest error message we will be showing. $maxErrorLength = 0; - foreach ($report['messages'] as $line => $lineErrors) { - foreach ($lineErrors as $column => $colErrors) { + foreach ($report['messages'] as $lineErrors) { + foreach ($lineErrors as $colErrors) { foreach ($colErrors as $error) { $length = strlen($error['message']); if ($showSources === true) { @@ -265,7 +265,7 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false, echo str_repeat('-', $width).PHP_EOL; - foreach ($lineErrors as $column => $colErrors) { + foreach ($lineErrors as $colErrors) { foreach ($colErrors as $error) { $padding = ($maxLineNumLength - strlen($line)); echo 'LINE '.str_repeat(' ', $padding).$line.': '; diff --git a/src/Reports/Full.php b/src/Reports/Full.php index b6af4c8e84..9af4efaeab 100644 --- a/src/Reports/Full.php +++ b/src/Reports/Full.php @@ -62,8 +62,8 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false, // Make sure the report width isn't too big. $maxErrorLength = 0; - foreach ($report['messages'] as $line => $lineErrors) { - foreach ($lineErrors as $column => $colErrors) { + foreach ($report['messages'] as $lineErrors) { + foreach ($lineErrors as $colErrors) { foreach ($colErrors as $error) { // Start with the presumption of a single line error message. $length = strlen($error['message']); @@ -139,7 +139,7 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false, $beforeAfterLength = strlen($beforeMsg.$afterMsg); foreach ($report['messages'] as $line => $lineErrors) { - foreach ($lineErrors as $column => $colErrors) { + foreach ($lineErrors as $colErrors) { foreach ($colErrors as $error) { $errorMsg = wordwrap( $error['message'], diff --git a/src/Reports/Source.php b/src/Reports/Source.php index 47d6d80cdd..deedb3ebd0 100644 --- a/src/Reports/Source.php +++ b/src/Reports/Source.php @@ -40,8 +40,8 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false, $sources = []; - foreach ($report['messages'] as $line => $lineErrors) { - foreach ($lineErrors as $column => $colErrors) { + foreach ($report['messages'] as $lineErrors) { + foreach ($lineErrors as $colErrors) { foreach ($colErrors as $error) { $src = $error['source']; if (isset($sources[$src]) === false) { diff --git a/src/Reports/VersionControl.php b/src/Reports/VersionControl.php index daf558de12..296846c7d7 100644 --- a/src/Reports/VersionControl.php +++ b/src/Reports/VersionControl.php @@ -66,7 +66,7 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false, $praiseCache[$author]['bad']++; - foreach ($lineErrors as $column => $colErrors) { + foreach ($lineErrors as $colErrors) { foreach ($colErrors as $error) { $authorCache[$author]++;