From 9fd489f7d5888578d5988fcb5a5184944f2b6fd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= Date: Sat, 17 Dec 2022 17:10:12 +0100 Subject: [PATCH] Drop support for PHP < 8.1 This allows us to add parameter type declarations. --- .github/workflows/continuous-integration.yml | 2 +- UPGRADE.md | 6 +- composer.json | 14 ++-- .../Common/Annotations/Annotation.php | 9 +-- .../Annotations/AnnotationException.php | 64 ++++++++----------- .../Common/Annotations/AnnotationReader.php | 20 ++---- .../Common/Annotations/AnnotationRegistry.php | 2 +- .../Common/Annotations/CachedReader.php | 11 +--- lib/Doctrine/Common/Annotations/DocParser.php | 25 ++------ .../Common/Annotations/FileCacheReader.php | 21 +++--- .../Common/Annotations/IndexedReader.php | 3 +- lib/Doctrine/Common/Annotations/PhpParser.php | 6 +- .../Annotations/SimpleAnnotationReader.php | 4 +- .../Common/Annotations/TokenParser.php | 7 +- 14 files changed, 73 insertions(+), 121 deletions(-) diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index f160d3efb..d46cd0f52 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -16,4 +16,4 @@ jobs: name: "PHPUnit" uses: "doctrine/.github/.github/workflows/continuous-integration.yml@2.1.0" with: - php-versions: '["7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2"]' + php-versions: '["8.1", "8.2"]' diff --git a/UPGRADE.md b/UPGRADE.md index ae9509cd5..4cf4b1c89 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,6 +1,10 @@ # Upgrade from 1.0.x to 2.0.x -`DocLexer::peek()` and `DocLexer::glimpse` now return +- `DocLexer::peek()` and `DocLexer::glimpse` now return `Doctrine\Common\Lexer\Token` objects. When using `doctrine/lexer` 2, these implement `ArrayAccess` as a way for you to still be able to treat them as arrays in some ways. +- Parameter type declarations have been added to all methods of all classes. If +you have classes inheriting from classes inside this package, you should add +parameter and return type declarations. +- Support for PHP < 8.1 has been reoved diff --git a/composer.json b/composer.json index 8dc634be3..dd7aa6f8d 100644 --- a/composer.json +++ b/composer.json @@ -32,17 +32,17 @@ ], "homepage": "https://www.doctrine-project.org/projects/annotations.html", "require": { - "php": "^7.1 || ^8.0", + "php": "^8.1", "ext-tokenizer": "*", "doctrine/lexer": "^2", - "psr/cache": "^1 || ^2 || ^3" + "psr/cache": "^3" }, "require-dev": { - "doctrine/cache": "^1.11 || ^2.0", - "doctrine/coding-standard": "^9 || ^10", - "phpstan/phpstan": "~1.4.10 || ^1.8.0", - "phpunit/phpunit": "^7.5 || ^8.5 || ^9.5", - "symfony/cache": "^4.4 || ^5.4 || ^6", + "doctrine/cache": "^2.0", + "doctrine/coding-standard": "^10", + "phpstan/phpstan": "^1.8.0", + "phpunit/phpunit": "^9.5.27", + "symfony/cache": "^6", "vimeo/psalm": "^4.10" }, "suggest": { diff --git a/lib/Doctrine/Common/Annotations/Annotation.php b/lib/Doctrine/Common/Annotations/Annotation.php index 9cae3dacd..eed131150 100644 --- a/lib/Doctrine/Common/Annotations/Annotation.php +++ b/lib/Doctrine/Common/Annotations/Annotation.php @@ -29,11 +29,9 @@ final public function __construct(array $data) /** * Error handler for unknown property accessor in Annotation class. * - * @param string $name Unknown property name. - * * @throws BadMethodCallException */ - public function __get($name) + public function __get(string $name) { throw new BadMethodCallException( sprintf("Unknown property '%s' on annotation '%s'.", $name, static::class) @@ -43,12 +41,9 @@ public function __get($name) /** * Error handler for unknown property mutator in Annotation class. * - * @param string $name Unknown property name. - * @param mixed $value Property value. - * * @throws BadMethodCallException */ - public function __set($name, $value) + public function __set(string $name, mixed $value) { throw new BadMethodCallException( sprintf("Unknown property '%s' on annotation '%s'.", $name, static::class) diff --git a/lib/Doctrine/Common/Annotations/AnnotationException.php b/lib/Doctrine/Common/Annotations/AnnotationException.php index dcdfe4df6..849f05179 100644 --- a/lib/Doctrine/Common/Annotations/AnnotationException.php +++ b/lib/Doctrine/Common/Annotations/AnnotationException.php @@ -19,11 +19,9 @@ class AnnotationException extends Exception /** * Creates a new AnnotationException describing a Syntax error. * - * @param string $message Exception message - * * @return AnnotationException */ - public static function syntaxError($message) + public static function syntaxError(string $message) { return new self('[Syntax Error] ' . $message); } @@ -31,11 +29,9 @@ public static function syntaxError($message) /** * Creates a new AnnotationException describing a Semantical error. * - * @param string $message Exception message - * * @return AnnotationException */ - public static function semanticalError($message) + public static function semanticalError(string $message) { return new self('[Semantical Error] ' . $message); } @@ -44,11 +40,9 @@ public static function semanticalError($message) * Creates a new AnnotationException describing an error which occurred during * the creation of the annotation. * - * @param string $message - * * @return AnnotationException */ - public static function creationError($message, ?Throwable $previous = null) + public static function creationError(string $message, ?Throwable $previous = null) { return new self('[Creation Error] ' . $message, 0, $previous); } @@ -56,11 +50,9 @@ public static function creationError($message, ?Throwable $previous = null) /** * Creates a new AnnotationException describing a type error. * - * @param string $message - * * @return AnnotationException */ - public static function typeError($message) + public static function typeError(string $message) { return new self('[Type Error] ' . $message); } @@ -68,12 +60,9 @@ public static function typeError($message) /** * Creates a new AnnotationException describing a constant semantical error. * - * @param string $identifier - * @param string $context - * * @return AnnotationException */ - public static function semanticalErrorConstants($identifier, $context = null) + public static function semanticalErrorConstants(string $identifier, ?string $context = null) { return self::semanticalError(sprintf( "Couldn't find constant %s%s.", @@ -85,16 +74,15 @@ public static function semanticalErrorConstants($identifier, $context = null) /** * Creates a new AnnotationException describing an type error of an attribute. * - * @param string $attributeName - * @param string $annotationName - * @param string $context - * @param string $expected - * @param mixed $actual - * * @return AnnotationException */ - public static function attributeTypeError($attributeName, $annotationName, $context, $expected, $actual) - { + public static function attributeTypeError( + string $attributeName, + string $annotationName, + string $context, + string $expected, + mixed $actual + ) { return self::typeError(sprintf( 'Attribute "%s" of @%s declared on %s expects %s, but got %s.', $attributeName, @@ -108,15 +96,14 @@ public static function attributeTypeError($attributeName, $annotationName, $cont /** * Creates a new AnnotationException describing an required error of an attribute. * - * @param string $attributeName - * @param string $annotationName - * @param string $context - * @param string $expected - * * @return AnnotationException */ - public static function requiredError($attributeName, $annotationName, $context, $expected) - { + public static function requiredError( + string $attributeName, + string $annotationName, + string $context, + string $expected + ) { return self::typeError(sprintf( 'Attribute "%s" of @%s declared on %s expects %s. This value should not be null.', $attributeName, @@ -129,16 +116,17 @@ public static function requiredError($attributeName, $annotationName, $context, /** * Creates a new AnnotationException describing a invalid enummerator. * - * @param string $attributeName - * @param string $annotationName - * @param string $context - * @param mixed $given - * @phpstan-param list $available + * @phpstan-param list $available * * @return AnnotationException */ - public static function enumeratorError($attributeName, $annotationName, $context, $available, $given) - { + public static function enumeratorError( + string $attributeName, + string $annotationName, + string $context, + array $available, + mixed $given + ) { return new self(sprintf( '[Enum Error] Attribute "%s" of @%s declared on %s accepts only [%s], but got %s.', $attributeName, diff --git a/lib/Doctrine/Common/Annotations/AnnotationReader.php b/lib/Doctrine/Common/Annotations/AnnotationReader.php index 1f538ee53..23e9b72b9 100644 --- a/lib/Doctrine/Common/Annotations/AnnotationReader.php +++ b/lib/Doctrine/Common/Annotations/AnnotationReader.php @@ -48,20 +48,16 @@ class AnnotationReader implements Reader /** * Add a new annotation to the globally ignored annotation names with regard to exception handling. - * - * @param string $name */ - public static function addGlobalIgnoredName($name) + public static function addGlobalIgnoredName(string $name) { self::$globalIgnoredNames[$name] = true; } /** * Add a new annotation to the globally ignored annotation namespaces with regard to exception handling. - * - * @param string $namespace */ - public static function addGlobalIgnoredNamespace($namespace) + public static function addGlobalIgnoredNamespace(string $namespace) { self::$globalIgnoredNamespaces[$namespace] = true; } @@ -264,11 +260,9 @@ public function getFunctionAnnotation(ReflectionFunction $function, string $anno /** * Returns the ignored annotations for the given class or function. * - * @param ReflectionClass|ReflectionFunction $reflection - * * @return array */ - private function getIgnoredAnnotationNames($reflection): array + private function getIgnoredAnnotationNames(ReflectionClass|ReflectionFunction $reflection): array { $type = $reflection instanceof ReflectionClass ? 'class' : 'function'; $name = $reflection->getName(); @@ -285,11 +279,9 @@ private function getIgnoredAnnotationNames($reflection): array /** * Retrieves imports for a class or a function. * - * @param ReflectionClass|ReflectionFunction $reflection - * * @return array */ - private function getImports($reflection): array + private function getImports(ReflectionClass|ReflectionFunction $reflection): array { $type = $reflection instanceof ReflectionClass ? 'class' : 'function'; $name = $reflection->getName(); @@ -354,10 +346,8 @@ private function getPropertyImports(ReflectionProperty $property) /** * Collects parsing metadata for a given class or function. - * - * @param ReflectionClass|ReflectionFunction $reflection */ - private function collectParsingMetadata($reflection): void + private function collectParsingMetadata(ReflectionClass|ReflectionFunction $reflection): void { $type = $reflection instanceof ReflectionClass ? 'class' : 'function'; $name = $reflection->getName(); diff --git a/lib/Doctrine/Common/Annotations/AnnotationRegistry.php b/lib/Doctrine/Common/Annotations/AnnotationRegistry.php index 259d497dd..ef71a7b03 100644 --- a/lib/Doctrine/Common/Annotations/AnnotationRegistry.php +++ b/lib/Doctrine/Common/Annotations/AnnotationRegistry.php @@ -79,7 +79,7 @@ public static function registerFile(string $file): void * * @phpstan-param string|list|null $dirs */ - public static function registerAutoloadNamespace(string $namespace, $dirs = null): void + public static function registerAutoloadNamespace(string $namespace, string|array|null $dirs = null): void { self::$autoloadNamespaces[$namespace] = $dirs; } diff --git a/lib/Doctrine/Common/Annotations/CachedReader.php b/lib/Doctrine/Common/Annotations/CachedReader.php index 85dbefab5..627a9b2e0 100644 --- a/lib/Doctrine/Common/Annotations/CachedReader.php +++ b/lib/Doctrine/Common/Annotations/CachedReader.php @@ -168,7 +168,7 @@ public function clearLoadedAnnotations() * * @return mixed The cached value or false when the value is not in cache. */ - private function fetchFromCache($cacheKey, ReflectionClass $class) + private function fetchFromCache(string $cacheKey, ReflectionClass $class) { $data = $this->cache->fetch($cacheKey); if ($data !== false) { @@ -183,12 +183,9 @@ private function fetchFromCache($cacheKey, ReflectionClass $class) /** * Saves a value to the cache. * - * @param string $cacheKey The cache key. - * @param mixed $value The value. - * * @return void */ - private function saveToCache($cacheKey, $value) + private function saveToCache(string $cacheKey, mixed $value) { $this->cache->save($cacheKey, $value); if (! $this->debug) { @@ -201,11 +198,9 @@ private function saveToCache($cacheKey, $value) /** * Checks if the cache is fresh. * - * @param string $cacheKey - * * @return bool */ - private function isCacheFresh($cacheKey, ReflectionClass $class) + private function isCacheFresh(string $cacheKey, ReflectionClass $class) { $lastModification = $this->getLastModification($class); if ($lastModification === 0) { diff --git a/lib/Doctrine/Common/Annotations/DocParser.php b/lib/Doctrine/Common/Annotations/DocParser.php index 37c352409..d82119286 100644 --- a/lib/Doctrine/Common/Annotations/DocParser.php +++ b/lib/Doctrine/Common/Annotations/DocParser.php @@ -286,7 +286,7 @@ public function setIgnoredAnnotationNames(array $names) * * @return void */ - public function setIgnoredAnnotationNamespaces($ignoredAnnotationNamespaces) + public function setIgnoredAnnotationNamespaces(array $ignoredAnnotationNamespaces) { $this->ignoredAnnotationNamespaces = $ignoredAnnotationNamespaces; } @@ -294,25 +294,21 @@ public function setIgnoredAnnotationNamespaces($ignoredAnnotationNamespaces) /** * Sets ignore on not-imported annotations. * - * @param bool $bool - * * @return void */ - public function setIgnoreNotImportedAnnotations($bool) + public function setIgnoreNotImportedAnnotations(bool $bool) { - $this->ignoreNotImportedAnnotations = (bool) $bool; + $this->ignoreNotImportedAnnotations = $bool; } /** * Sets the default namespaces. * - * @param string $namespace - * * @return void * * @throws RuntimeException */ - public function addNamespace($namespace) + public function addNamespace(string $namespace) { if ($this->imports) { throw new RuntimeException('You must either use addNamespace(), or setImports(), but not both.'); @@ -342,11 +338,9 @@ public function setImports(array $imports) /** * Sets current target context as bitmask. * - * @param int $target - * * @return void */ - public function setTarget($target) + public function setTarget(int $target) { $this->target = $target; } @@ -354,15 +348,12 @@ public function setTarget($target) /** * Parses the given docblock string for annotations. * - * @param string $input The docblock string to parse. - * @param string $context The parsing context. - * * @phpstan-return list Array of annotations. If no annotations are found, an empty array is returned. * * @throws AnnotationException * @throws ReflectionException */ - public function parse($input, $context = '') + public function parse(string $input, string $context = '') { $pos = $this->findInitialTokenPosition($input); if ($pos === null) { @@ -379,10 +370,8 @@ public function parse($input, $context = '') /** * Finds the first valid annotation - * - * @param string $input The docblock string to parse */ - private function findInitialTokenPosition($input): ?int + private function findInitialTokenPosition(string $input): ?int { $pos = 0; diff --git a/lib/Doctrine/Common/Annotations/FileCacheReader.php b/lib/Doctrine/Common/Annotations/FileCacheReader.php index 6c6c22c3a..561e59d9a 100644 --- a/lib/Doctrine/Common/Annotations/FileCacheReader.php +++ b/lib/Doctrine/Common/Annotations/FileCacheReader.php @@ -55,15 +55,13 @@ class FileCacheReader implements Reader /** @var int */ private $umask; - /** - * @param string $cacheDir - * @param bool $debug - * @param int $umask - * - * @throws InvalidArgumentException - */ - public function __construct(Reader $reader, $cacheDir, $debug = false, $umask = 0002) - { + /** @throws InvalidArgumentException */ + public function __construct( + Reader $reader, + string $cacheDir, + bool $debug = false, + int $umask = 0002 + ) { if (! is_int($umask)) { throw new InvalidArgumentException(sprintf( 'The parameter umask must be an integer, was: %s', @@ -210,12 +208,11 @@ public function getMethodAnnotations(ReflectionMethod $method) /** * Saves the cache file. * - * @param string $path - * @param mixed $data + * @param mixed $data * * @return void */ - private function saveCacheFile($path, $data) + private function saveCacheFile(string $path, $data) { if (! is_writable($this->dir)) { throw new InvalidArgumentException(sprintf( diff --git a/lib/Doctrine/Common/Annotations/IndexedReader.php b/lib/Doctrine/Common/Annotations/IndexedReader.php index 62dcf7487..77b5b9cb2 100644 --- a/lib/Doctrine/Common/Annotations/IndexedReader.php +++ b/lib/Doctrine/Common/Annotations/IndexedReader.php @@ -88,12 +88,11 @@ public function getPropertyAnnotation(ReflectionProperty $property, $annotationN /** * Proxies all methods to the delegate. * - * @param string $method * @param mixed[] $args * * @return mixed */ - public function __call($method, $args) + public function __call(string $method, array $args) { return call_user_func_array([$this->delegate, $method], $args); } diff --git a/lib/Doctrine/Common/Annotations/PhpParser.php b/lib/Doctrine/Common/Annotations/PhpParser.php index d2263c033..c1dfce933 100644 --- a/lib/Doctrine/Common/Annotations/PhpParser.php +++ b/lib/Doctrine/Common/Annotations/PhpParser.php @@ -33,11 +33,9 @@ public function parseClass(ReflectionClass $class) /** * Parse a class or function for use statements. * - * @param ReflectionClass|ReflectionFunction $reflection - * * @psalm-return array a list with use statements in the form (Alias => FQN). */ - public function parseUseStatements($reflection): array + public function parseUseStatements(ReflectionClass|ReflectionFunction $reflection): array { if (method_exists($reflection, 'getUseStatements')) { return $reflection->getUseStatements(); @@ -70,7 +68,7 @@ public function parseUseStatements($reflection): array * * @return string|null The content of the file or null if the file does not exist. */ - private function getFileContent($filename, $lineNumber) + private function getFileContent(string $filename, $lineNumber) { if (! is_file($filename)) { return null; diff --git a/lib/Doctrine/Common/Annotations/SimpleAnnotationReader.php b/lib/Doctrine/Common/Annotations/SimpleAnnotationReader.php index 8a78c119d..cde40dac0 100644 --- a/lib/Doctrine/Common/Annotations/SimpleAnnotationReader.php +++ b/lib/Doctrine/Common/Annotations/SimpleAnnotationReader.php @@ -31,11 +31,9 @@ public function __construct() /** * Adds a namespace in which we will look for annotations. * - * @param string $namespace - * * @return void */ - public function addNamespace($namespace) + public function addNamespace(string $namespace) { $this->parser->addNamespace($namespace); } diff --git a/lib/Doctrine/Common/Annotations/TokenParser.php b/lib/Doctrine/Common/Annotations/TokenParser.php index 69259fccf..0534fd17c 100644 --- a/lib/Doctrine/Common/Annotations/TokenParser.php +++ b/lib/Doctrine/Common/Annotations/TokenParser.php @@ -46,8 +46,7 @@ class TokenParser */ private $pointer = 0; - /** @param string $contents */ - public function __construct($contents) + public function __construct(string $contents) { $this->tokens = token_get_all($contents); @@ -71,7 +70,7 @@ public function __construct($contents) * * @return mixed[]|string|null The token if exists, null otherwise. */ - public function next($docCommentIsComment = true) + public function next(bool $docCommentIsComment = true) { for ($i = $this->pointer; $i < $this->numTokens; $i++) { $this->pointer++; @@ -149,7 +148,7 @@ public function parseUseStatement() * * @return array A list with all found use statements. */ - public function parseUseStatements($namespaceName) + public function parseUseStatements(string $namespaceName) { $statements = []; while (($token = $this->next())) {