Annotations in single-line doc-comments are not handled correctly

[ostrolucky]

Q	A
PHPUnit version	master
PHP version	any
Installation Method	git

Summary

PHPUnit seems to require multiline docblocks for its annotations, eg. @requires. Some users prefer single line docblocks though and this is also now set in doctrine/coding-standard. We had this problem in https://github.com/doctrine/DoctrineBundle/pull/1365/files#diff-6c0dba5076ce8a2e9ff3e1e07f6661e095a18f80e32ad9766945f55c0414f8a2.

This seems to be because in your regexes you don't expect /** to be on same line as meat of the regex at

phpunit/src/Util/Annotation/DocBlock.php

Lines 73 to 87 in dba1e6c

	public const REGEX_DATA_PROVIDER = '/@dataProvider\s+([a-zA-Z0-9._:-\\\\x7f-\xff]+)/';
	private const REGEX_REQUIRES_VERSION = '/@requires\s+(?P<name>PHP(?:Unit)?)\s+(?P<operator>[<>=!]{0,2})\s*(?P<version>[\d\.-]+(dev|(RC|alpha|beta)[\d\.])?)[ \t]*\r?$/m';
	private const REGEX_REQUIRES_VERSION_CONSTRAINT = '/@requires\s+(?P<name>PHP(?:Unit)?)\s+(?P<constraint>[\d\t \-.|~^]+)[ \t]*\r?$/m';
	private const REGEX_REQUIRES_OS = '/@requires\s+(?P<name>OS(?:FAMILY)?)\s+(?P<value>.+?)[ \t]*\r?$/m';
	private const REGEX_REQUIRES_SETTING = '/@requires\s+(?P<name>setting)\s+(?P<setting>([^ ]+?))\s*(?P<value>[\w\.-]+[\w\.]?)?[ \t]*\r?$/m';
	private const REGEX_REQUIRES = '/@requires\s+(?P<name>function|extension)\s+(?P<value>([^\s<>=!]+))\s*(?P<operator>[<>=!]{0,2})\s*(?P<version>[\d\.-]+[\d\.]?)?[ \t]*\r?$/m';
	private const REGEX_TEST_WITH = '/@testWith\s+/';
	private const REGEX_EXPECTED_EXCEPTION = '(@expectedException\s+([:.\w\\\\x7f-\xff]+)(?:[\t ]+(\S*))?(?:[\t ]+(\S*))?\s*$)m';

How to reproduce

/** @requires PHP 8 */
public function test(): void
{
}

Doesn't have any effect. Test case is not skipped on PHP < 8.

But with

/**
 * @requires PHP 8
 */
public function test(): void
{
}

It works.

Expected behavior

Both examples should work the same way.

[sebastianbergmann]

This is due to the expected and documented behaviour of how PHP's Reflection API handled "doc comments". This cannot be changed. Furthermore, annotations are closed for further development in PHPUnit and will, over time, be superseded by attributes.

[sebastianbergmann]

I replied too quickly, sorry. I thought you were refering to /** versus /*, which is an issue that is brought up frequently.

I agree that

/** @requires PHP 8 */

should work just like

/**
 * @requires PHP 8
 */

and consider the fact that is does not to be a bug.

A patch that fixes this would be appreciated.

[ostrolucky]

I could fix it, but can you tell me where should the test case go? I'm not familiar with your setup.

[sebastianbergmann]

For PHPUnit 10 (master) this is easy to answer: https://github.com/sebastianbergmann/phpunit/blob/master/tests/unit/Metadata/Parser/AnnotationParserTest.php For PHPUnit 8.5 and PHPUnit 9.5 it is not that easy, unfortunately.

I suggest you send a pull request against master and I backport it from there.