1. class
  2. StubTests
  3. \
  4. Framework
  5. \
  6. Validator
  7. \
  8. Services
  9. \
  10. PhpDocConformanceService

PhpDocConformanceService

final class PhpDocConformanceService (View source)

Service for PhpDoc-vs-signature conformance checks.

Provides the compatibility algorithm and helper methods used by FunctionPhpDocConformsSignatureCheck, ClassMethodsPhpDocConformsSignatureCheck, and their Enum/Interface variants.

Extracted from PhpDocConformanceTrait for independent testability.

Constants

PRIMITIVES

PHP primitive types — used to distinguish class names from scalar/pseudo types.
private PHPSTAN_LEAF_MAP

Maps phpstan/psalm pseudo-type leaves to the closest built-in PHP type.

Keys are lowercased leaf tokens (after generics/shapes/[] have been stripped). A value may itself be a union (e.g. 'array-key' → 'int|string'); it is substituted verbatim and later flattened/sorted by TypeResolver::normalizeType().

Methods

bool
isPhpDocCompatibleWithSignature(string $sig, string $doc, array $templateNames = [])

Check if a PhpDoc type is compatible with a signature type.

array
extractTemplateNames(string|null $rawPhpDoc)

Extract @template variable names from a raw PhpDoc comment.

string
normalizeDocType(string $type)

Normalise a PhpDoc type string.

array
splitUnionComponents(string $type)

Split a union type string into individual components.

string|null
getParamSigTypeForPhpDoc(PHPParameter $param, string $phpVersion)

Get the signature type string for a parameter.

string|null
getPropertySigTypeForPhpDoc(PHPProperty $property, string $phpVersion)

Get the signature type string for a property.

array
filterAndDeduplicateParamsPhpDoc(array $params, string $phpVersion)

Filter parameters by version availability and deduplicate same-named variadic pairs.

Details

at line 55
bool isPhpDocCompatibleWithSignature(string $sig, string $doc, array $templateNames = [])

Check if a PhpDoc type is compatible with a signature type.

Permissive algorithm — avoids false positives from intentional patterns:

  • Typed-array narrowing: sig array, doc string[] → pass (string[] normalises to array)
  • phpstan generics: sig array, doc array<K,V> → pass (generics stripped)
  • resource widening: sig GMP, doc resource|GMP → pass (intersection non-empty)
  • bool/false split: sig bool, doc false → pass (bool expands to {false, true})
  • union reordering: sig string|false, doc false|string → pass (normalised)
  • mixed sig or doc: sig mixed, doc string → pass (mixed encompasses all)
  • object sig with class doc: sig object, doc SomeClass → pass
  • class sig with object doc: sig SomeClass, doc object → pass
  • resource→class migration: sig SomeClass, doc resource → pass (PHP8 object migration)
  • @template variable in doc: sig \SplFileInfo, doc \T (T declared via @template) → pass
  • static ↔ class name: sig \DateTime, doc static → pass
  • class-to-class narrowing: sig \Iterator, doc \ArrayIterator → pass

Catches: sig string, doc int → fail (no shared component)

Parameters

string $sig

Signature type string (always a real PHP type — no template variables)
string $doc

PhpDoc type string (may contain @template variable names)
array $templateNames

@template variable names declared on the enclosing entity

Return Value

bool

true = compatible, false = mismatch detected

at line 114
array extractTemplateNames(string|null $rawPhpDoc)

Extract @template variable names from a raw PhpDoc comment.

Parameters

string|null $rawPhpDoc

Return Value

array

Template variable names (without any leading backslash)

at line 152
string normalizeDocType(string $type)

Normalise a PhpDoc type string.

Strips phpstan/psalm annotations first, then applies standard normalizeType() (union ordering, FQN backslash, T[] → array).

Parameters

string $type

Return Value

string

at line 163
array splitUnionComponents(string $type)

Split a union type string into individual components.

Parameters

string $type

Return Value

array

at line 178
string|null getParamSigTypeForPhpDoc(PHPParameter $param, string $phpVersion)

Get the signature type string for a parameter.

Priority:

  1. Declared type from getDeclaredType() — if non-empty (not NoType)
  2. LanguageLevelTypeAware — highest version <= $phpVersion, or defaultType

Parameters

PHPParameter $param
string $phpVersion

Return Value

string|null

at line 203
string|null getPropertySigTypeForPhpDoc(PHPProperty $property, string $phpVersion)

Get the signature type string for a property.

Priority:

  1. Signature type from getType() — if non-empty (not NoType)
  2. LanguageLevelTypeAware — highest version <= $phpVersion, or defaultType

Parameters

PHPProperty $property
string $phpVersion

Return Value

string|null

at line 229
array filterAndDeduplicateParamsPhpDoc(array $params, string $phpVersion)

Filter parameters by version availability and deduplicate same-named variadic pairs.

Parameters

array $params
string $phpVersion

Return Value

array