PhpDocValidatorTest
class PhpDocValidatorTest extends ValidatorTestBase (View source)
Validates that PhpDoc comments in stubs contain only recognized tag names, and that @since/@deprecated/@removed use "major.minor" version format.
Unlike other validator tests, this test iterates stubs entities directly (not reflection data) and only runs at the LATEST PHP version — PhpDoc content does not vary by PHP version.
Each stub entity (function, class, interface, enum) is a separate test case. For class-like entities the check also examines all declared method phpDocs.
Constants
| private CORE_STUB_CATEGORIES |
Stub categories whose entities participate in the version-format check. The check only applies to bundled PHP distribution stubs (Core + Bundled). EXTERNAL and PECL extensions use their own library version numbers (e.g. "1.2.0" for the MongoDB driver, "5.6.1" for gmp) which must not be forced to PHP's "major.minor" format. |
Methods
Return check descriptors for declarative test registration.
Override to iterate stubs entities (not reflection) at LATEST version only.
No description
Get entities to test based on the method name.
Get the unique identifier for an entity.
Build a unique test name from method, entity, and version.
Execute a validation check and assert results.
No description
Check that PhpDoc comments contain only valid phpDocumentor/PHPStan tags.
Check that all @link URLs in PhpDoc comments use the https scheme and, when CHECK_LINKS=true is set in the environment, are reachable.
Data provider for checkDeprecatedRemovedSinceVersionsMajor.
Check that @since, @deprecated, and @removed tags use "major.minor" version format (e.g. 8.0) rather than "major.minor.patch" (e.g. 8.0.1).
Details
protected void
setUp()
No description
static protected array
getCheckDescriptors()
Return check descriptors for declarative test registration.
Each entry maps a logical check name to a CheckDescriptor.
static iterable
entityProvider()
Override to iterate stubs entities (not reflection) at LATEST version only.
PhpDoc tag validity does not depend on the PHP runtime version, so there is no benefit to running the same check across all supported versions.
void
testEntity(string $methodName, string $entityId, string $phpVersion)
No description
static protected iterable
getEntitiesForMethod(string $methodName, StubDataQueryInterface $reflection)
Get entities to test based on the method name.
Subclasses should override to return specific entity types.
static protected string
getEntityId(mixed $entity)
Get the unique identifier for an entity.
static protected string
buildTestName(string $methodName, string $entityId, string $phpVersion)
Build a unique test name from method, entity, and version.
protected void
executeCheck(CheckInterface $check, string $entityId, string $phpVersion, string|null $customMessage = null)
Execute a validation check and assert results.
void
testCoreEntity(string $methodName, string $entityId, string $phpVersion)
No description
void
checkPhpDocContainsOnlyValidTag(string $entityId, string $phpVersion)
Check that PhpDoc comments contain only valid phpDocumentor/PHPStan tags.
Tags with phpstan-, psalm-, or phan-* prefixes are invalid. Any tag not in the recognized whitelist is also flagged.
void
checkPhpDocLinks(string $entityId, string $phpVersion)
Check that all @link URLs in PhpDoc comments use the https scheme and, when CHECK_LINKS=true is set in the environment, are reachable.
The liveness check is skipped by default because fetching thousands of URLs would make the test suite unacceptably slow for regular CI runs. Enable it explicitly:
CHECK_LINKS=true php vendor/bin/phpunit tests/PhpDocValidatorTest.php \ --filter checkPhpDocLinks
static iterable
coreStubsProvider()
Data provider for checkDeprecatedRemovedSinceVersionsMajor.
Yields only core PHP stubs entities (third-party PECL/library stubs use their own version numbers which must not be forced to "major.minor" format).
void
checkDeprecatedRemovedSinceVersionsMajor(string $entityId, string $phpVersion)
Check that @since, @deprecated, and @removed tags use "major.minor" version format (e.g. 8.0) rather than "major.minor.patch" (e.g. 8.0.1).
This method is invoked via coreStubsProvider (not entityProvider) so that only core PHP extension entities are checked — third-party extensions use their own library version numbers.