Merge pull request #467 from greg0ire/param-type-declarations

Add parameter type declarations
doctrine · Dec 18, 2022 · 96c1475 · 96c1475
2 parents 6d49292 + 5ccddc6
commit 96c1475
Show file tree

Hide file tree

Showing 11 changed files with 57 additions and 84 deletions.
diff --git 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: '["7.2", "7.3", "7.4", "8.0", "8.1", "8.2"]'
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -5,5 +5,9 @@
 implement `ArrayAccess` as a way for you to still be able to treat them as
 arrays in some ways.
 - `CachedReader` and `FileCacheReader` have been removed.
-- `AnnotationRegistry` method related to registering annotations instead of
+- `AnnotationRegistry` methods related to registering annotations instead of
   using autoloading have been removed.
+- 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 < 7.2 has been removed
diff --git 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": "^7.2 || ^8.0",
         "ext-tokenizer": "*",
         "doctrine/lexer": "^2",
         "psr/cache": "^1 || ^2 || ^3"
     },
     "require-dev": {
-        "doctrine/cache": "^1.11 || ^2.0",
-        "doctrine/coding-standard": "^9 || ^10",
-        "phpstan/phpstan": "~1.4.10 || ^1.8.0",
+        "doctrine/cache": "^2.0",
+        "doctrine/coding-standard": "^10",
+        "phpstan/phpstan": "^1.8.0",
         "phpunit/phpunit": "^7.5 || ^8.5 || ^9.5",
-        "symfony/cache": "^4.4 || ^5.4 || ^6",
+        "symfony/cache": "^5.4 || ^6",
         "vimeo/psalm": "^4.10"
     },
     "suggest": {

diff --git 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,11 @@ public function __get($name)
     /**
      * Error handler for unknown property mutator in Annotation class.
      *
-     * @param string $name  Unknown property name.
-     * @param mixed  $value Property value.
+     * @param mixed $value Property value.
      *
      * @throws BadMethodCallException
      */
-    public function __set($name, $value)
+    public function __set(string $name, $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
@@ -19,23 +19,19 @@ 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);
     }
 
     /**
      * 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,36 +40,29 @@ 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);
     }
 
     /**
      * 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);
     }
 
     /**
      * 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,17 @@ 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
+     * @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,
+        $actual
+    ) {
         return self::typeError(sprintf(
             'Attribute "%s" of @%s declared on %s expects %s, but got %s.',
             $attributeName,
@@ -108,15 +98,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 +118,18 @@ 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<string>        $available
+     * @param mixed $given
+     * @phpstan-param list<string> $available
      *
      * @return AnnotationException
      */
-    public static function enumeratorError($attributeName, $annotationName, $context, $available, $given)
-    {
+    public static function enumeratorError(
+        string $attributeName,
+        string $annotationName,
+        string $context,
+        array $available,
+        $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
@@ -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;
     }

diff --git a/lib/Doctrine/Common/Annotations/DocParser.php b/lib/Doctrine/Common/Annotations/DocParser.php
@@ -286,33 +286,29 @@ public function setIgnoredAnnotationNames(array $names)
      *
      * @return void
      */
-    public function setIgnoredAnnotationNamespaces($ignoredAnnotationNamespaces)
+    public function setIgnoredAnnotationNamespaces(array $ignoredAnnotationNamespaces)
     {
         $this->ignoredAnnotationNamespaces = $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,27 +338,22 @@ 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;
     }
 
     /**
      * Parses the given docblock string for annotations.
      *
-     * @param string $input   The docblock string to parse.
-     * @param string $context The parsing context.
-     *
      * @phpstan-return list<object> 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/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
@@ -70,7 +70,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
@@ -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
@@ -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<string, string> A list with all found use statements.
      */
-    public function parseUseStatements($namespaceName)
+    public function parseUseStatements(string $namespaceName)
     {
         $statements = [];
         while (($token = $this->next())) {