Skip to content

Commit

Permalink
Merge pull request #523 from PHPCSStandards/feature/docs-improve-repo…
Browse files Browse the repository at this point in the history 
…rts-array-format-info

Documentation: improve information about Report data format + remove unused foreach keys
  • Loading branch information
@jrfnl
jrfnl authored Jul 2, 2024
2 parents df258d4 + 52c891a commit e245088
Show file tree
Hide file tree
Showing 18 changed files with 139 additions and 78 deletions.
24 changes: 23 additions & 1 deletion src/Reporter.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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 <Line number> => array(
* int <Column number> => array(
* int <Message index> => 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)
{
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Cbf.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Checkstyle.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
15 changes: 8 additions & 7 deletions src/Reports/Code.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down Expand Up @@ -121,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) {
Expand Down Expand Up @@ -264,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.': ';
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Csv.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Diff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Emacs.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
15 changes: 8 additions & 7 deletions src/Reports/Full.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down Expand Up @@ -61,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']);
Expand Down Expand Up @@ -138,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'],
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Info.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Json.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Junit.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Notifysend.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
9 changes: 5 additions & 4 deletions src/Reports/Performance.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand Down
31 changes: 27 additions & 4 deletions src/Reports/Report.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <Line number> => array(
* int <Column number> => array(
* int <Message index> => 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<string, string|int|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
*/
Expand Down
13 changes: 7 additions & 6 deletions src/Reports/Source.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string|int|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
*/
Expand All @@ -39,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) {
Expand Down
Loading

0 comments on commit e245088

Please sign in to comment.