Skip to content

Commit db7c60b

Browse files
jrfnljrfnl
committed
✨ New Utils\MessageHelper class
This class initially introduces four new utility methods for working with error/warning messages. The class currently contains the following methods: * `addMessage()` - simple method to add either an error or a warning to PHPCS based on an `$isError` parameter. Returns boolean (same as PHPCS natively). Supports all optional parameters supported by PHPCS. * `addFixableMessage()` - simple method to add either a fixable error or a fixable warning to PHPCS based on an `$isError` parameter. Returns boolean (same as PHPCS natively). Supports all optional parameters supported by PHPCS. * `stringToErrorcode()` - to convert an arbitrary text string to an alphanumeric string with underscores. Returns the adjusted text string. This method is intended to pre-empt issues in XML and PHP when arbitrary text strings are used as (part of) an error code. * `hasNewLineSupport()` - to check whether PHPCS can properly handle new lines in violation messages. Prior to PHPCS 3.3.1, new line support in error messages was buggy. Ref: squizlabs/PHP_CodeSniffer#2093 Includes dedicated unit tests for each method.
1 parent 602d7a3 commit db7c60b

6 files changed

+603
-0
lines changed

‎PHPCSUtils/Utils/MessageHelper.php

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<?php
2+
/**
3+
* PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
4+
*
5+
* @package PHPCSUtils
6+
* @copyright 2019-2020 PHPCSUtils Contributors
7+
* @license https://opensource.org/licenses/LGPL-3.0 LGPL3
8+
* @link https://github.com/PHPCSStandards/PHPCSUtils
9+
*/
10+
11+
namespace PHPCSUtils\Utils;
12+
13+
use PHP_CodeSniffer\Files\File;
14+
use PHPCSUtils\BackCompat\Helper;
15+
16+
/**
17+
* Helper functions for creating PHPCS error/warning messages.
18+
*
19+
* @since 1.0.0
20+
*/
21+
class MessageHelper
22+
{
23+
24+
/**
25+
* Add a PHPCS message to the output stack as either a warning or an error.
26+
*
27+
* @since 1.0.0-alpha4
28+
*
29+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
30+
* @param string $message The message.
31+
* @param int $stackPtr The position of the token
32+
* the message relates to.
33+
* @param bool $isError Whether to report the message as an
34+
* 'error' or 'warning'.
35+
* Defaults to true (error).
36+
* @param string $code The error code for the message.
37+
* Defaults to 'Found'.
38+
* @param array $data Optional input for the data replacements.
39+
* @param int $severity Optional. Severity level. Defaults to 0 which will
40+
* translate to the PHPCS default severity level.
41+
*
42+
* @return bool
43+
*/
44+
public static function addMessage(
45+
File $phpcsFile,
46+
$message,
47+
$stackPtr,
48+
$isError = true,
49+
$code = 'Found',
50+
$data = [],
51+
$severity = 0
52+
) {
53+
if ($isError === true) {
54+
return $phpcsFile->addError($message, $stackPtr, $code, $data, $severity);
55+
}
56+
57+
return $phpcsFile->addWarning($message, $stackPtr, $code, $data, $severity);
58+
}
59+
60+
/**
61+
* Add a PHPCS message to the output stack as either a fixable warning or a fixable error.
62+
*
63+
* @since 1.0.0-alpha4
64+
*
65+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
66+
* @param string $message The message.
67+
* @param int $stackPtr The position of the token
68+
* the message relates to.
69+
* @param bool $isError Whether to report the message as an
70+
* 'error' or 'warning'.
71+
* Defaults to true (error).
72+
* @param string $code The error code for the message.
73+
* Defaults to 'Found'.
74+
* @param array $data Optional input for the data replacements.
75+
* @param int $severity Optional. Severity level. Defaults to 0 which will
76+
* translate to the PHPCS default severity level.
77+
*
78+
* @return bool
79+
*/
80+
public static function addFixableMessage(
81+
File $phpcsFile,
82+
$message,
83+
$stackPtr,
84+
$isError = true,
85+
$code = 'Found',
86+
$data = [],
87+
$severity = 0
88+
) {
89+
if ($isError === true) {
90+
return $phpcsFile->addFixableError($message, $stackPtr, $code, $data, $severity);
91+
}
92+
93+
return $phpcsFile->addFixableWarning($message, $stackPtr, $code, $data, $severity);
94+
}
95+
96+
/**
97+
* Convert an arbitrary text string to an alphanumeric string with underscores.
98+
*
99+
* Pre-empt issues in XML and PHP when arbitrary strings are being used as error codes.
100+
*
101+
* @since 1.0.0-alpha4
102+
*
103+
* @param string $text Arbitrary text string intended to be used in an error code.
104+
*
105+
* @return string
106+
*/
107+
public static function stringToErrorcode($text)
108+
{
109+
return \preg_replace('`[^a-z0-9_]`i', '_', $text);
110+
}
111+
112+
/**
113+
* Check whether PHPCS can properly handle new lines in violation messages.
114+
*
115+
* @link https://github.com/squizlabs/PHP_CodeSniffer/pull/2093
116+
*
117+
* @since 1.0.0-alpha4
118+
*
119+
* @return bool
120+
*/
121+
public static function hasNewLineSupport()
122+
{
123+
static $supported;
124+
if (isset($supported) === false) {
125+
$supported = \version_compare(Helper::getVersion(), '3.3.1', '>=');
126+
}
127+
128+
return $supported;
129+
}
130+
}

‎Tests/Utils/MessageHelper/AddMessageTest.inc

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<?php
2+
3+
/* testAddErrorMessage */
4+
echo 'test 1';
5+
6+
/* testAddWarningMessage */
7+
echo 'test 2';
8+
9+
/* testAddFixableErrorMessage */
10+
echo 'test 3';
11+
12+
/* testAddFixableWarningMessage */
13+
echo 'test 4';

‎Tests/Utils/MessageHelper/AddMessageTest.php

+243
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
<?php
2+
/**
3+
* PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
4+
*
5+
* @package PHPCSUtils
6+
* @copyright 2019-2021 PHPCSUtils Contributors
7+
* @license https://opensource.org/licenses/LGPL-3.0 LGPL3
8+
* @link https://github.com/PHPCSStandards/PHPCSUtils
9+
*/
10+
11+
namespace PHPCSUtils\Tests\Utils\MessageHelper;
12+
13+
use PHPCSUtils\TestUtils\UtilityMethodTestCase;
14+
use PHPCSUtils\Utils\MessageHelper;
15+
16+
/**
17+
* Tests for the \PHPCSUtils\Utils\MessageHelper::addMessage() and the
18+
* \PHPCSUtils\Utils\MessageHelper::addFixableMessage() methods.
19+
*
20+
* {@internal Note: this is largely testing PHPCS native functionality, but as PHPCS doesn't
21+
* have any unit tests in place for this functionality, that's not a bad thing.}
22+
*
23+
* @group messagehelper
24+
*
25+
* @since 1.0.0
26+
*/
27+
class AddMessageTest extends UtilityMethodTestCase
28+
{
29+
30+
/**
31+
* Dummy error code to use for the test.
32+
*
33+
* Using the dummy full error code to force it to record.
34+
*
35+
* @var string
36+
*/
37+
const CODE = 'PHPCSUtils.MessageHelper.AddMessageTest.Found';
38+
39+
/**
40+
* Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
41+
*
42+
* @var array
43+
*/
44+
protected static $selectedSniff = ['PHPCSUtils.MessageHelper.AddMessageTest'];
45+
46+
/**
47+
* Test the addMessage wrapper.
48+
*
49+
* @dataProvider dataAddMessage
50+
* @covers \PHPCSUtils\Utils\MessageHelper::addMessage
51+
*
52+
* @param string $testMarker The comment which prefaces the target token in the test file.
53+
* @param bool $isError Whether to test adding an error or a warning.
54+
* @param array $expected Expected error details.
55+
*
56+
* @return void
57+
*/
58+
public function testAddMessage($testMarker, $isError, $expected)
59+
{
60+
$tokens = self::$phpcsFile->getTokens();
61+
$stackPtr = $this->getTargetToken($testMarker, \T_CONSTANT_ENCAPSED_STRING);
62+
$severity = \mt_rand(5, 10);
63+
$expected['severity'] = $severity;
64+
65+
$return = MessageHelper::addMessage(
66+
self::$phpcsFile,
67+
'Message added. Text: %s',
68+
$stackPtr,
69+
$isError,
70+
static::CODE,
71+
[$tokens[$stackPtr]['content']],
72+
$severity
73+
);
74+
75+
$this->assertTrue($return);
76+
77+
$this->verifyRecordedMessages($stackPtr, $isError, $expected);
78+
}
79+
80+
/**
81+
* Data Provider.
82+
*
83+
* @see testAddMessage() For the array format.
84+
*
85+
* @return array
86+
*/
87+
public function dataAddMessage()
88+
{
89+
return [
90+
'add-error' => [
91+
'/* testAddErrorMessage */',
92+
true,
93+
[
94+
'message' => "Message added. Text: 'test 1'",
95+
'source' => static::CODE,
96+
'fixable' => false,
97+
],
98+
],
99+
'add-warning' => [
100+
'/* testAddWarningMessage */',
101+
false,
102+
[
103+
'message' => "Message added. Text: 'test 2'",
104+
'source' => static::CODE,
105+
'fixable' => false,
106+
],
107+
],
108+
];
109+
}
110+
111+
/**
112+
* Test the addFixableMessage wrapper.
113+
*
114+
* @dataProvider dataAddFixableMessage
115+
* @covers \PHPCSUtils\Utils\MessageHelper::addFixableMessage
116+
*
117+
* @param string $testMarker The comment which prefaces the target token in the test file.
118+
* @param bool $isError Whether to test adding an error or a warning.
119+
* @param array $expected Expected error details.
120+
*
121+
* @return void
122+
*/
123+
public function testAddFixableMessage($testMarker, $isError, $expected)
124+
{
125+
$tokens = self::$phpcsFile->getTokens();
126+
$stackPtr = $this->getTargetToken($testMarker, \T_CONSTANT_ENCAPSED_STRING);
127+
$severity = \mt_rand(5, 10);
128+
$expected['severity'] = $severity;
129+
130+
$return = MessageHelper::addFixableMessage(
131+
self::$phpcsFile,
132+
'Message added. Text: %s',
133+
$stackPtr,
134+
$isError,
135+
static::CODE,
136+
[$tokens[$stackPtr]['content']],
137+
$severity
138+
);
139+
140+
// Fixable message recording only returns true when the fixer is enabled (=phpcbf).
141+
$this->assertFalse($return);
142+
143+
$this->verifyRecordedMessages($stackPtr, $isError, $expected);
144+
}
145+
146+
/**
147+
* Data Provider.
148+
*
149+
* @see testAddFixableMessage() For the array format.
150+
*
151+
* @return array
152+
*/
153+
public function dataAddFixableMessage()
154+
{
155+
return [
156+
'add-fixable-error' => [
157+
'/* testAddFixableErrorMessage */',
158+
true,
159+
[
160+
'message' => "Message added. Text: 'test 3'",
161+
'source' => static::CODE,
162+
'fixable' => true,
163+
],
164+
],
165+
'add-fixable-warning' => [
166+
'/* testAddFixableWarningMessage */',
167+
false,
168+
[
169+
'message' => "Message added. Text: 'test 4'",
170+
'source' => static::CODE,
171+
'fixable' => true,
172+
],
173+
],
174+
];
175+
}
176+
177+
/**
178+
* Helper method to verify the expected message details.
179+
*
180+
* @param int $stackPtr The stack pointer on which the error/warning is expected.
181+
* @param bool $isError Whether to test adding an error or a warning.
182+
* @param array $expected Expected error details.
183+
*
184+
* @return void
185+
*/
186+
protected function verifyRecordedMessages($stackPtr, $isError, $expected)
187+
{
188+
$tokens = self::$phpcsFile->getTokens();
189+
$errors = self::$phpcsFile->getErrors();
190+
$warnings = self::$phpcsFile->getWarnings();
191+
$result = ($isError === true) ? $errors : $warnings;
192+
193+
/*
194+
* Make sure that no errors/warnings were recorded when the other type is set to be expected.
195+
*/
196+
if ($isError === true) {
197+
$this->assertArrayNotHasKey(
198+
$tokens[$stackPtr]['line'],
199+
$warnings,
200+
'Expected no warnings on line ' . $tokens[$stackPtr]['line'] . '. At least one found.'
201+
);
202+
} else {
203+
$this->assertArrayNotHasKey(
204+
$tokens[$stackPtr]['line'],
205+
$errors,
206+
'Expected no errors on line ' . $tokens[$stackPtr]['line'] . '. At least one found.'
207+
);
208+
}
209+
210+
/*
211+
* Make sure the expected array keys for the the errors/warnings are available.
212+
*/
213+
$this->assertArrayHasKey(
214+
$tokens[$stackPtr]['line'],
215+
$result,
216+
'Expected a violation on line ' . $tokens[$stackPtr]['line'] . '. None found.'
217+
);
218+
219+
$this->assertArrayHasKey(
220+
$tokens[$stackPtr]['column'],
221+
$result[$tokens[$stackPtr]['line']],
222+
'Expected a violation on line ' . $tokens[$stackPtr]['line'] . ', column '
223+
. $tokens[$stackPtr]['column'] . '. None found.'
224+
);
225+
226+
$messages = $result[$tokens[$stackPtr]['line']][$tokens[$stackPtr]['column']];
227+
228+
// Expect one violation.
229+
$this->assertCount(1, $messages, 'Expected 1 violation, found: ' . \count($messages));
230+
231+
$violation = $messages[0];
232+
233+
// PHPCS 2.x places `unknownSniff.` before the actual error code for utility tests with a dummy error code.
234+
$violation['source'] = \str_replace('unknownSniff.', '', $violation['source']);
235+
236+
/*
237+
* Test the violation details.
238+
*/
239+
foreach ($expected as $key => $value) {
240+
$this->assertSame($value, $violation[$key], \ucfirst($key) . ' comparison failed');
241+
}
242+
}
243+
}

‎Tests/Utils/MessageHelper/HasNewLineSupportTest.inc

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<?php
2+
3+
/* testMessageWithNewLine */
4+
echo 'test 1';

0 commit comments

Comments
 (0)