Skip to content

Commit e245088

Browse files
jrfnljrfnl
authored
Merge pull request #523 from PHPCSStandards/feature/docs-improve-reports-array-format-info
Documentation: improve information about Report data format + remove unused foreach keys
2 parents df258d4 + 52c891a commit e245088

18 files changed

+139
-78
lines changed

‎src/Reporter.php

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,29 @@ public function cacheFileReport(File $phpcsFile)
329329
*
330330
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file that has been processed.
331331
*
332-
* @return array
332+
* @return array<string, string|int|array> Prepared report data.
333+
* The format of prepared data is as follows:
334+
* ```
335+
* array(
336+
* 'filename' => string The name of the current file.
337+
* 'errors' => int The number of errors seen in the current file.
338+
* 'warnings' => int The number of warnings seen in the current file.
339+
* 'fixable' => int The number of fixable issues seen in the current file.
340+
* 'messages' => array(
341+
* int <Line number> => array(
342+
* int <Column number> => array(
343+
* int <Message index> => array(
344+
* 'message' => string The error/warning message.
345+
* 'source' => string The full error code for the message.
346+
* 'severity' => int The severity of the message.
347+
* 'fixable' => bool Whether this error/warning is auto-fixable.
348+
* 'type' => string The type of message. Either 'ERROR' or 'WARNING'.
349+
* )
350+
* )
351+
* )
352+
* )
353+
* )
354+
* ```
333355
*/
334356
public function prepareFileReport(File $phpcsFile)
335357
{

‎src/Reports/Cbf.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,11 @@ class Cbf implements Report
2828
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2929
* its data should be counted in the grand totals.
3030
*
31-
* @param array $report Prepared report data.
32-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
33-
* @param bool $showSources Show sources?
34-
* @param int $width Maximum allowed line width.
31+
* @param array<string, string|int|array> $report Prepared report data.
32+
* See the {@see Report} interface for a detailed specification.
33+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
34+
* @param bool $showSources Show sources?
35+
* @param int $width Maximum allowed line width.
3536
*
3637
* @return bool
3738
* @throws \PHP_CodeSniffer\Exceptions\DeepExitException

‎src/Reports/Checkstyle.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,11 @@ class Checkstyle implements Report
2424
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2525
* its data should be counted in the grand totals.
2626
*
27-
* @param array $report Prepared report data.
28-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29-
* @param bool $showSources Show sources?
30-
* @param int $width Maximum allowed line width.
27+
* @param array<string, string|int|array> $report Prepared report data.
28+
* See the {@see Report} interface for a detailed specification.
29+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
30+
* @param bool $showSources Show sources?
31+
* @param int $width Maximum allowed line width.
3132
*
3233
* @return bool
3334
*/

‎src/Reports/Code.php

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,11 @@ class Code implements Report
2525
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2626
* its data should be counted in the grand totals.
2727
*
28-
* @param array $report Prepared report data.
29-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
30-
* @param bool $showSources Show sources?
31-
* @param int $width Maximum allowed line width.
28+
* @param array<string, string|int|array> $report Prepared report data.
29+
* See the {@see Report} interface for a detailed specification.
30+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
31+
* @param bool $showSources Show sources?
32+
* @param int $width Maximum allowed line width.
3233
*
3334
* @return bool
3435
*/
@@ -121,8 +122,8 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false,
121122

122123
// Determine the longest error message we will be showing.
123124
$maxErrorLength = 0;
124-
foreach ($report['messages'] as $line => $lineErrors) {
125-
foreach ($lineErrors as $column => $colErrors) {
125+
foreach ($report['messages'] as $lineErrors) {
126+
foreach ($lineErrors as $colErrors) {
126127
foreach ($colErrors as $error) {
127128
$length = strlen($error['message']);
128129
if ($showSources === true) {
@@ -264,7 +265,7 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false,
264265

265266
echo str_repeat('-', $width).PHP_EOL;
266267

267-
foreach ($lineErrors as $column => $colErrors) {
268+
foreach ($lineErrors as $colErrors) {
268269
foreach ($colErrors as $error) {
269270
$padding = ($maxLineNumLength - strlen($line));
270271
echo 'LINE '.str_repeat(' ', $padding).$line.': ';

‎src/Reports/Csv.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ class Csv implements Report
2222
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2323
* its data should be counted in the grand totals.
2424
*
25-
* @param array $report Prepared report data.
26-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
27-
* @param bool $showSources Show sources?
28-
* @param int $width Maximum allowed line width.
25+
* @param array<string, string|int|array> $report Prepared report data.
26+
* See the {@see Report} interface for a detailed specification.
27+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28+
* @param bool $showSources Show sources?
29+
* @param int $width Maximum allowed line width.
2930
*
3031
* @return bool
3132
*/

‎src/Reports/Diff.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ class Diff implements Report
2222
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2323
* its data should be counted in the grand totals.
2424
*
25-
* @param array $report Prepared report data.
26-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
27-
* @param bool $showSources Show sources?
28-
* @param int $width Maximum allowed line width.
25+
* @param array<string, string|int|array> $report Prepared report data.
26+
* See the {@see Report} interface for a detailed specification.
27+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28+
* @param bool $showSources Show sources?
29+
* @param int $width Maximum allowed line width.
2930
*
3031
* @return bool
3132
*/

‎src/Reports/Emacs.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ class Emacs implements Report
2222
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2323
* its data should be counted in the grand totals.
2424
*
25-
* @param array $report Prepared report data.
26-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
27-
* @param bool $showSources Show sources?
28-
* @param int $width Maximum allowed line width.
25+
* @param array<string, string|int|array> $report Prepared report data.
26+
* See the {@see Report} interface for a detailed specification.
27+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28+
* @param bool $showSources Show sources?
29+
* @param int $width Maximum allowed line width.
2930
*
3031
* @return bool
3132
*/

‎src/Reports/Full.php

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,11 @@ class Full implements Report
2323
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2424
* its data should be counted in the grand totals.
2525
*
26-
* @param array $report Prepared report data.
27-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28-
* @param bool $showSources Show sources?
29-
* @param int $width Maximum allowed line width.
26+
* @param array<string, string|int|array> $report Prepared report data.
27+
* See the {@see Report} interface for a detailed specification.
28+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29+
* @param bool $showSources Show sources?
30+
* @param int $width Maximum allowed line width.
3031
*
3132
* @return bool
3233
*/
@@ -61,8 +62,8 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false,
6162

6263
// Make sure the report width isn't too big.
6364
$maxErrorLength = 0;
64-
foreach ($report['messages'] as $line => $lineErrors) {
65-
foreach ($lineErrors as $column => $colErrors) {
65+
foreach ($report['messages'] as $lineErrors) {
66+
foreach ($lineErrors as $colErrors) {
6667
foreach ($colErrors as $error) {
6768
// Start with the presumption of a single line error message.
6869
$length = strlen($error['message']);
@@ -138,7 +139,7 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false,
138139
$beforeAfterLength = strlen($beforeMsg.$afterMsg);
139140

140141
foreach ($report['messages'] as $line => $lineErrors) {
141-
foreach ($lineErrors as $column => $colErrors) {
142+
foreach ($lineErrors as $colErrors) {
142143
foreach ($colErrors as $error) {
143144
$errorMsg = wordwrap(
144145
$error['message'],

‎src/Reports/Info.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,11 @@ class Info implements Report
2323
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2424
* its data should be counted in the grand totals.
2525
*
26-
* @param array $report Prepared report data.
27-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28-
* @param bool $showSources Show sources?
29-
* @param int $width Maximum allowed line width.
26+
* @param array<string, string|int|array> $report Prepared report data.
27+
* See the {@see Report} interface for a detailed specification.
28+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29+
* @param bool $showSources Show sources?
30+
* @param int $width Maximum allowed line width.
3031
*
3132
* @return bool
3233
*/

‎src/Reports/Json.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,11 @@ class Json implements Report
2323
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2424
* its data should be counted in the grand totals.
2525
*
26-
* @param array $report Prepared report data.
27-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28-
* @param bool $showSources Show sources?
29-
* @param int $width Maximum allowed line width.
26+
* @param array<string, string|int|array> $report Prepared report data.
27+
* See the {@see Report} interface for a detailed specification.
28+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29+
* @param bool $showSources Show sources?
30+
* @param int $width Maximum allowed line width.
3031
*
3132
* @return bool
3233
*/

0 commit comments

Comments
 (0)