Make doctrine/annotations optional (#1508)

README.md

@@ -4,7 +4,9 @@
 
 # swagger-php
 
-Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using [doctrine annotations](https://www.doctrine-project.org/projects/doctrine-annotations/en/latest/index.html).
+Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using
+[doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) (optional as of version 4.8)
+or [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php).
 
 For a full list of supported annotations, please have look at the [`OpenApi\Annotations` namespace](src/Annotations) or the [documentation website](https://zircote.github.io/swagger-php/guide/annotations.html).
 
@@ -41,6 +43,16 @@ For cli usage from anywhere install swagger-php globally and make sure to place
 composer global require zircote/swagger-php
 ```
 
+### doctrine/annotations
+As of version `4.8` the [doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) library **is optional** and **no longer installed by default**.
+
+If your code uses PHPDoc annotations you will need to install this as well:
+
+```shell
+composer require doctrine/annotations
+```
+
+
 ## Usage
 
 Add annotations to your php files.

composer.json

@@ -46,7 +46,6 @@
     "require": {
         "php": ">=7.2",
         "ext-json": "*",
-        "doctrine/annotations": "^1.7 || ^2.0",
         "psr/log": "^1.1 || ^2.0 || ^3.0",
         "symfony/deprecation-contracts": "^2 || ^3",
         "symfony/finder": ">=2.2",
@@ -59,11 +58,15 @@
     },
     "require-dev": {
         "composer/package-versions-deprecated": "^1.11",
+        "doctrine/annotations": "^1.7 || ^2.0",
         "friendsofphp/php-cs-fixer": "^2.17 || ^3.0",
         "phpstan/phpstan": "^1.6",
         "phpunit/phpunit": ">=8",
         "vimeo/psalm": "^4.23"
     },
+    "suggest": {
+        "doctrine/annotations": "^1.7 || ^2.0"
+    },
     "autoload-dev": {
         "exclude-from-classmap": [
             "/tests/Fixtures"

docs/guide/annotations.md

@@ -13,7 +13,7 @@ However, doctrine will be quite specific about whether an alias is valid or not.
 any additional work.
 
 ## Doctrine
-Annotations are PHP comments (docblocks) containing [doctrine style annotations](https://www.doctrine-project.org/projects/doctrine-annotations/en/latest/index.html).
+Annotations are PHP comments (docblocks) containing [doctrine style annotations](https://www.doctrine-project.org/projects/annotations.html).
 
 ::: info
 All documentation related to doctrine applies to annotations only.

src/Analysers/AnnotationFactoryInterface.php

@@ -12,6 +12,11 @@
 
 interface AnnotationFactoryInterface
 {
+    /**
+     * Checks if this factory is supported by the current runtime.
+     */
+    public function isSupported(): bool;
+
     public function setGenerator(Generator $generator): void;
 
     /**

src/Analysers/AttributeAnnotationFactory.php

@@ -15,14 +15,19 @@ class AttributeAnnotationFactory implements AnnotationFactoryInterface
     /** @var Generator|null */
     protected $generator;
 
+    public function isSupported(): bool
+    {
+        return \PHP_VERSION_ID >= 80100;
+    }
+
     public function setGenerator(Generator $generator): void
     {
         $this->generator = $generator;
     }
 
     public function build(\Reflector $reflector, Context $context): array
     {
-        if (\PHP_VERSION_ID < 80100 || !method_exists($reflector, 'getAttributes')) {
+        if (!$this->isSupported() || !method_exists($reflector, 'getAttributes')) {
             return [];
         }
 

src/Analysers/DocBlockAnnotationFactory.php

@@ -22,6 +22,11 @@ public function __construct(?DocBlockParser $docBlockParser = null)
         $this->docBlockParser = $docBlockParser ?: new DocBlockParser();
     }
 
+    public function isSupported(): bool
+    {
+        return DocBlockParser::isEnabled();
+    }
+
     public function setGenerator(Generator $generator): void
     {
         $this->generator = $generator;

src/Analysers/DocBlockParser.php

@@ -26,10 +26,20 @@ class DocBlockParser
      */
     public function __construct(array $aliases = [])
     {
-        $docParser = new DocParser();
-        $docParser->setIgnoreNotImportedAnnotations(true);
-        $docParser->setImports($aliases);
-        $this->docParser = $docParser;
+        if (DocBlockParser::isEnabled()) {
+            $docParser = new DocParser();
+            $docParser->setIgnoreNotImportedAnnotations(true);
+            $docParser->setImports($aliases);
+            $this->docParser = $docParser;
+        }
+    }
+
+    /**
+     * Check if we can process annotations.
+     */
+    public static function isEnabled(): bool
+    {
+        return class_exists('Doctrine\\Common\\Annotations\\DocParser');
     }
 
     /**

src/Analysers/ReflectionAnalyser.php

@@ -32,9 +32,14 @@ class ReflectionAnalyser implements AnalyserInterface
      */
     public function __construct(array $annotationFactories = [])
     {
-        $this->annotationFactories = $annotationFactories;
+        $this->annotationFactories = [];
+        foreach ($annotationFactories as $annotationFactory) {
+            if ($annotationFactory->isSupported()) {
+                $this->annotationFactories[] = $annotationFactory;
+            }
+        }
         if (!$this->annotationFactories) {
-            throw new \InvalidArgumentException('Need at least one annotation factory');
+            throw new \RuntimeException('No suitable annotation factory found. At least one of "Doctrine Annotations" or PHP 8.1 are required');
         }
     }
 

tests/Analysers/ReflectionAnalyserTest.php

@@ -35,6 +35,11 @@ public function build(\Reflector $reflector, Context $context): array
                 return [];
             }
 
+            public function isSupported(): bool
+            {
+                return true;
+            }
+
             public function setGenerator(Generator $generator): void
             {
                 // noop