Merge 1.13.x into 1.14.x (#458)

.github/workflows/coding-standards.yml

@@ -12,4 +12,4 @@ on:
 jobs:
   coding-standards:
     name: "Coding Standards"
-    uses: "doctrine/.github/.github/workflows/coding-standards.yml@1.5.1"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@2.1.0"

.github/workflows/composer-lint.yml

@@ -15,4 +15,4 @@ on:
 jobs:
   composer-lint:
     name: "Composer Lint"
-    uses: "doctrine/.github/.github/workflows/composer-lint.yml@1.5.1"
+    uses: "doctrine/.github/.github/workflows/composer-lint.yml@2.1.0"

.github/workflows/continuous-integration.yml

@@ -14,6 +14,6 @@ env:
 jobs:
   phpunit:
     name: "PHPUnit"
-    uses: "doctrine/.github/.github/workflows/continuous-integration.yml@1.5.1"
+    uses: "doctrine/.github/.github/workflows/continuous-integration.yml@2.1.0"
     with:
-      php-versions: '["7.1", "7.2", "7.3", "7.4", "8.0"]'
+      php-versions: '["7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2"]'

.github/workflows/release-on-milestone-closed.yml

@@ -8,7 +8,7 @@ on:
 jobs:
   release:
     name: "Git tag, release & create merge-up PR"
-    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@1.5.1"
+    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@2.1.0"
     secrets:
       GIT_AUTHOR_EMAIL: ${{ secrets.GIT_AUTHOR_EMAIL }}
       GIT_AUTHOR_NAME: ${{ secrets.GIT_AUTHOR_NAME }}

.github/workflows/static-analysis.yml

@@ -12,4 +12,4 @@ on:
 jobs:
   static-analysis:
     name: "Static Analysis"
-    uses: "doctrine/.github/.github/workflows/static-analysis.yml@1.5.1"
+    uses: "doctrine/.github/.github/workflows/static-analysis.yml@2.1.0"

README.md

@@ -1,3 +1,9 @@
+⚠️ PHP 8 introduced
+[attributes](https://www.php.net/manual/en/language.attributes.overview.php),
+which are a native replacement for annotations. As such, this library is
+considered feature complete, and should receive exclusively bugfixes and
+security fixes.
+
 # Doctrine Annotations
 
 [![Build Status](https://github.com/doctrine/annotations/workflows/Continuous%20Integration/badge.svg?label=build)](https://github.com/doctrine/persistence/actions)

composer.json

@@ -39,12 +39,15 @@
     },
     "require-dev": {
         "doctrine/cache": "^1.11 || ^2.0",
-        "doctrine/coding-standard": "^6.0 || ^8.1",
-        "phpstan/phpstan": "^1.4.10 || ^1.8.0",
-        "phpunit/phpunit": "^7.5 || ^8.0 || ^9.1.5",
-        "symfony/cache": "^4.4 || ^5.2",
+        "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",
         "vimeo/psalm": "^4.10"
     },
+    "suggest": {
+        "php": "PHP 8.0 or higher comes with attributes, a native replacement for annotations"
+    },
     "autoload": {
         "psr-4": {
             "Doctrine\\Common\\Annotations\\": "lib/Doctrine/Common/Annotations"

docs/en/custom.rst

@@ -69,7 +69,7 @@ When using the ``@NamedArgumentConstructor`` tag, the first argument of the
 constructor is considered as the default one.
 
 
-Usage with the ``@NamedArgumentContrustor`` tag
+Usage with the ``@NamedArgumentConstructor`` tag
 
 .. code-block:: php
 

docs/en/index.rst

@@ -1,3 +1,12 @@
+Deprecation notice
+==================
+
+PHP 8 introduced `attributes
+<https://www.php.net/manual/en/language.attributes.overview.php>`_,
+which are a native replacement for annotations. As such, this library is
+considered feature complete, and should receive exclusively bugfixes and
+security fixes.
+
 Introduction
 ============
 

lib/Doctrine/Common/Annotations/Annotation.php

@@ -18,9 +18,7 @@ class Annotation
      */
     public $value;
 
-    /**
-     * @param array<string, mixed> $data Key-value for properties to be defined in this class.
-     */
+    /** @param array<string, mixed> $data Key-value for properties to be defined in this class. */
     final public function __construct(array $data)
     {
         foreach ($data as $key => $value) {

lib/Doctrine/Common/Annotations/Annotation/Enum.php

@@ -34,9 +34,9 @@ final class Enum
     public $literal;
 
     /**
-     * @throws InvalidArgumentException
-     *
      * @phpstan-param array{literal?: mixed[], value: list<scalar>} $values
+     *
+     * @throws InvalidArgumentException
      */
     public function __construct(array $values)
     {

lib/Doctrine/Common/Annotations/Annotation/IgnoreAnnotation.php

@@ -21,9 +21,9 @@ final class IgnoreAnnotation
     public $names;
 
     /**
-     * @throws RuntimeException
-     *
      * @phpstan-param array{value: string|list<string>} $values
+     *
+     * @throws RuntimeException
      */
     public function __construct(array $values)
     {

lib/Doctrine/Common/Annotations/Annotation/Target.php

@@ -56,9 +56,9 @@ final class Target
     public $literal;
 
     /**
-     * @throws InvalidArgumentException
-     *
      * @phpstan-param array{value?: string|list<string>} $values
+     *
+     * @throws InvalidArgumentException
      */
     public function __construct(array $values)
     {

lib/Doctrine/Common/Annotations/AnnotationException.php

@@ -133,10 +133,9 @@ public static function requiredError($attributeName, $annotationName, $context,
      * @param string $annotationName
      * @param string $context
      * @param mixed  $given
+     * @phpstan-param list<string>        $available
      *
      * @return AnnotationException
-     *
-     * @phpstan-param list<string>        $available
      */
     public static function enumeratorError($attributeName, $annotationName, $context, $available, $given)
     {
@@ -150,19 +149,15 @@ public static function enumeratorError($attributeName, $annotationName, $context
         ));
     }
 
-    /**
-     * @return AnnotationException
-     */
+    /** @return AnnotationException */
     public static function optimizerPlusSaveComments()
     {
         return new self(
             'You have to enable opcache.save_comments=1 or zend_optimizerplus.save_comments=1.'
         );
     }
 
-    /**
-     * @return AnnotationException
-     */
+    /** @return AnnotationException */
     public static function optimizerPlusLoadComments()
     {
         return new self(

lib/Doctrine/Common/Annotations/CachedReader.php

@@ -38,9 +38,7 @@ final class CachedReader implements Reader
     /** @var int[] */
     private $loadedFilemtimes = [];
 
-    /**
-     * @param bool $debug
-     */
+    /** @param bool $debug */
     public function __construct(Reader $reader, Cache $cache, $debug = false)
     {
         $this->delegate = $reader;

lib/Doctrine/Common/Annotations/DocParser.php

@@ -357,10 +357,10 @@ public function setTarget($target)
      * @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
-     *
-     * @phpstan-return list<object> Array of annotations. If no annotations are found, an empty array is returned.
      */
     public function parse($input, $context = '')
     {
@@ -426,9 +426,9 @@ private function match(int $token): bool
      * If any of them matches, this method updates the lookahead token; otherwise
      * a syntax error is raised.
      *
-     * @throws AnnotationException
-     *
      * @phpstan-param list<mixed[]> $tokens
+     *
+     * @throws AnnotationException
      */
     private function matchAny(array $tokens): bool
     {
@@ -674,10 +674,10 @@ private function collectAttributeTypeMetadata(array &$metadata, Attribute $attri
     /**
      * Annotations ::= Annotation {[ "*" ]* [Annotation]}*
      *
+     * @phpstan-return list<object>
+     *
      * @throws AnnotationException
      * @throws ReflectionException
-     *
-     * @phpstan-return list<object>
      */
     private function Annotations(): array
     {
@@ -1166,9 +1166,7 @@ private function identifierEndsWithClassConstant(string $identifier): bool
         return $this->getClassConstantPositionInIdentifier($identifier) === strlen($identifier) - strlen('::class');
     }
 
-    /**
-     * @return int|false
-     */
+    /** @return int|false */
     private function getClassConstantPositionInIdentifier(string $identifier)
     {
         return stripos($identifier, '::class');
@@ -1357,10 +1355,10 @@ private function Arrayx(): array
      * KeyValuePair ::= Key ("=" | ":") PlainValue | Constant
      * Key ::= string | integer | Constant
      *
+     * @phpstan-return array{mixed, mixed}
+     *
      * @throws AnnotationException
      * @throws ReflectionException
-     *
-     * @phpstan-return array{mixed, mixed}
      */
     private function ArrayEntry(): array
     {

lib/Doctrine/Common/Annotations/TokenParser.php

@@ -46,9 +46,7 @@ class TokenParser
      */
     private $pointer = 0;
 
-    /**
-     * @param string $contents
-     */
+    /** @param string $contents */
     public function __construct($contents)
     {
         $this->tokens = token_get_all($contents);

phpcs.xml.dist

@@ -12,6 +12,8 @@
     <!-- Show progress of the run and show sniff names -->
     <arg value="ps"/>
 
+    <config name="php_version" value="70100"/>
+
     <file>lib</file>
     <file>tests</file>
 
@@ -105,16 +107,6 @@
         <exclude-pattern>*/tests/Doctrine/Tests/Common/Annotations/Fixtures/ClassWithRequire.php</exclude-pattern>
     </rule>
 
-    <!-- these classes have unused properties, and is unused in a benchmark for the parser -->
-    <rule ref="SlevomatCodingStandard.Classes.UnusedPrivateElements.UnusedProperty">
-        <exclude-pattern>*/tests/Doctrine/Tests/Common/Annotations/Fixtures/SingleClassLOC1000.php</exclude-pattern>
-        <exclude-pattern>*/tests/Doctrine/Tests/Common/Annotations/Fixtures/NamespacedSingleClassLOC1000.php</exclude-pattern>
-    </rule>
-
-    <rule ref="SlevomatCodingStandard.Classes.UnusedPrivateElements.UnusedMethod">
-        <exclude-pattern>*/tests/Doctrine/Tests/Common/Annotations/Fixtures/Controller.php</exclude-pattern>
-    </rule>
-
     <!-- these classes do not have a namespace on purpose -->
     <rule ref="PSR1.Classes.ClassDeclaration.MissingNamespace">
         <exclude-pattern>*/tests/Doctrine/Tests/Common/Annotations/Fixtures/SingleClassLOC1000.php</exclude-pattern>
@@ -156,4 +148,9 @@
     <rule ref="Squiz.Functions.GlobalFunction.Found">
         <exclude-pattern>*/tests/Doctrine/Tests/Common/Annotations/Fixtures/functions.php</exclude-pattern>
     </rule>
+
+    <!-- Single-line PHPDoc blocks will confuse PHPUnit 7.5 -->
+    <rule ref="SlevomatCodingStandard.Commenting.RequireOneLineDocComment.MultiLineDocComment">
+        <exclude-pattern>*/tests</exclude-pattern>
+    </rule>
 </ruleset>