annotations = []; $this->types = []; $this->parameters = []; $this->ranges = []; $this->stringConstraints = []; $this->reflectionMethod = new \ReflectionMethod($object, $method); $this->startLine = $this->reflectionMethod->getStartLine(); $this->file = $this->reflectionMethod->getFileName(); $docs = $this->reflectionMethod->getDocComment(); if ($docs !== false) { // extract everything prefixed by @ and first letter uppercase preg_match_all('/^\h+\*\h+@(?P[A-Z]\w+)((?P.*))?$/m', $docs, $matches); foreach ($matches['annotation'] as $key => $annotation) { $annotation = strtolower($annotation); $annotationValue = $matches['parameter'][$key]; if (str_starts_with($annotationValue, '(') && str_ends_with($annotationValue, ')')) { $cutString = substr($annotationValue, 1, -1); $cutString = str_replace(' ', '', $cutString); $splitArray = explode(',', $cutString); foreach ($splitArray as $annotationValues) { [$key, $value] = explode('=', $annotationValues); $this->annotations[$annotation][$key] = $value; } continue; } $this->annotations[$annotation] = [$annotationValue]; } // extract type parameter information preg_match_all('/@param\h+(?P\w+)\h+\$(?P\w+)/', $docs, $matches); $this->types = array_combine($matches['var'], $matches['type']); preg_match_all('/@(?:psalm-)?param\h+(\?)?(?P\w+)<(?P(-?\d+|min)),\h*(?P(-?\d+|max))>(\|null)?\h+\$(?P\w+)/', $docs, $matches); foreach ($matches['var'] as $index => $varName) { if ($matches['type'][$index] !== 'int') { // only int ranges are possible at the moment // @see https://psalm.dev/docs/annotating_code/type_syntax/scalar_types continue; } $this->ranges[$varName] = [ 'min' => $matches['rangeMin'][$index] === 'min' ? PHP_INT_MIN : (int)$matches['rangeMin'][$index], 'max' => $matches['rangeMax'][$index] === 'max' ? PHP_INT_MAX : (int)$matches['rangeMax'][$index], ]; } // extract psalm int aliases that imply a fixed range preg_match_all('/@(?:psalm-)?param\h+(\?)?(?Ppositive-int|non-negative-int|negative-int|non-positive-int)(\|null)?\h+\$(?P\w+)/', $docs, $matches); foreach ($matches['var'] as $index => $varName) { $this->ranges[$varName] = match ($matches['type'][$index]) { 'positive-int' => ['min' => 1, 'max' => PHP_INT_MAX], 'non-negative-int' => ['min' => 0, 'max' => PHP_INT_MAX], 'negative-int' => ['min' => PHP_INT_MIN, 'max' => -1], 'non-positive-int' => ['min' => PHP_INT_MIN, 'max' => 0], }; } // extract psalm scalar string types preg_match_all('/@(?:psalm-)?param\h+(\?)?(?Pnon-empty-lowercase-string|non-falsy-string|non-empty-string|lowercase-string|numeric-string)(\|null)?\h+\$(?P\w+)/', $docs, $matches); foreach ($matches['var'] as $index => $varName) { $this->stringConstraints[$varName] = $matches['type'][$index]; } } foreach ($this->reflectionMethod->getParameters() as $param) { // extract type information from PHP 7 scalar types and prefer them over phpdoc annotations $type = $param->getType(); if ($type instanceof \ReflectionNamedType) { $this->types[$param->getName()] = $type->getName(); } $default = null; if ($param->isOptional()) { $default = $param->getDefaultValue(); } $this->parameters[$param->name] = $default; } } /** * Inspects the PHPDoc parameters for types * @param string $parameter the parameter whose type comments should be * parsed * @return string|null type in the type parameters (@param int $something) * would return int or null if not existing */ #[\Override] public function getType(string $parameter) { if (array_key_exists($parameter, $this->types)) { return $this->types[$parameter]; } return null; } public function getRange(string $parameter): ?array { if (array_key_exists($parameter, $this->ranges)) { return $this->ranges[$parameter]; } return null; } public function getStringConstraint(string $parameter): ?string { return $this->stringConstraints[$parameter] ?? null; } /** * Whether $value satisfies the psalm string type annotated for $parameter, * or true if none was annotated */ public function satisfiesStringConstraint(string $parameter, string $value): bool { return match ($this->getStringConstraint($parameter)) { 'non-empty-string' => $value !== '', 'non-empty-lowercase-string' => $value !== '' && $value === strtolower($value), 'lowercase-string' => $value === strtolower($value), 'non-falsy-string' => $value !== '' && $value !== '0', 'numeric-string' => is_numeric($value), default => true, }; } /** * @return array the arguments of the method with key => default value */ #[\Override] public function getParameters(): array { return $this->parameters; } /** * @template T * * @param class-string $attributeClass */ #[\Override] public function hasAnnotationOrAttribute(?string $annotationName, string $attributeClass): bool { if (!empty($this->reflectionMethod->getAttributes($attributeClass))) { return true; } if ($annotationName && $this->hasAnnotation($annotationName)) { $this->logger->debug($this->reflectionMethod->getDeclaringClass()->getName() . '::' . $this->reflectionMethod->getName() . ' uses the @' . $annotationName . ' annotation and should use the #[' . $attributeClass . '] attribute instead'); return true; } return false; } /** * @template T * @param class-string $attributeClass * @return ?\ReflectionAttribute */ public function getAttribute(string $attributeClass): ?\ReflectionAttribute { $attributes = $this->reflectionMethod->getAttributes($attributeClass); if (!empty($attributes)) { return $attributes[0]; } return null; } /** * Check if a method contains an annotation * @param string $name the name of the annotation * @return bool true if the annotation is found */ #[\Override] public function hasAnnotation(string $name): bool { $name = strtolower($name); return array_key_exists($name, $this->annotations); } /** * Get optional annotation parameter by key * * @param string $name the name of the annotation * @param string $key the string of the annotation * @return string */ public function getAnnotationParameter(string $name, string $key): string { $name = strtolower($name); if (isset($this->annotations[$name][$key])) { return $this->annotations[$name][$key]; } return ''; } public function getStartLine(): int { return $this->startLine; } public function getFile(): string { return $this->file; } }