Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: improve information about Report data format + remove unused foreach keys #523

Merged
merged 2 commits into from
Jul 2, 2024
Merged

Documentation: improve information about Report data format + remove unused foreach keys #523

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3107205
Documentation: improve information about report data format
jrfnl Jun 5, 2024
52c891a
CS/QA: remove unused `foreach` keys from report code
jrfnl Jun 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 23 additions & 1 deletion src/Reporter.php
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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