[v5]

.github/workflows/build.yml

@@ -15,20 +15,8 @@ jobs:
       fail-fast: true
       matrix:
         operating-system: [ ubuntu-latest ]
-        php: [ '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4' ]
+        php: [ '7.4', '8.0', '8.1', '8.2', '8.3', '8.4' ]
         dependencies: [ 'lowest', 'highest' ]
-        exclude:
-          - php: '8.1'
-            dependencies: 'lowest'
-          - php: '8.2'
-            dependencies: 'lowest'
-          - php: '8.3'
-            dependencies: 'lowest'
-          - php: '8.4'
-            dependencies: 'lowest'
-        include:
-          - php: '8.2'
-            composer-options: "--ignore-platform-req=php+"
 
     name: PHP ${{ matrix.php }} on ${{ matrix.operating-system }} with ${{ matrix.dependencies }} dependencies
 

.github/workflows/security-checks.yml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: true
       matrix:
         operating-system: [ ubuntu-latest ]
-        php: [ '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ]
+        php: [ '7.4', '8.0', '8.1', '8.2', '8.3', '8.4' ]
         dependencies: [ 'highest' ]
 
     name: PHP ${{ matrix.php }} on ${{ matrix.operating-system }} with ${{ matrix.dependencies }} dependencies

README.md

@@ -4,7 +4,7 @@
 
 # swagger-php
 
-Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (preferred) or 
+Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (preferred) or
 [doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) (requires additional `doctrine/annotations` library).
 
 See the [documentation website](https://zircote.github.io/swagger-php/guide/attributes.html) for supported attributes and annotations.

composer.json

@@ -40,16 +40,17 @@
     "minimum-stability": "stable",
     "extra": {
         "branch-alias": {
-            "dev-master": "4.x-dev"
+            "dev-master": "5.x-dev"
         }
     },
     "require": {
-        "php": ">=7.2",
+        "php": ">=7.4",
         "ext-json": "*",
+        "nikic/php-parser": "^4.19",
         "psr/log": "^1.1 || ^2.0 || ^3.0",
         "symfony/deprecation-contracts": "^2 || ^3",
-        "symfony/finder": ">=2.2",
-        "symfony/yaml": ">=3.3"
+        "symfony/finder": "^5.0 || ^6.0 || ^7.0",
+        "symfony/yaml": "^5.0 || ^6.0 || ^7.0"
     },
     "autoload": {
         "psr-4": {
@@ -58,14 +59,15 @@
     },
     "require-dev": {
         "composer/package-versions-deprecated": "^1.11",
-        "doctrine/annotations": "^1.7 || ^2.0",
-        "friendsofphp/php-cs-fixer": "^2.17 || 3.62.0",
+        "doctrine/annotations": "^2.0",
+        "friendsofphp/php-cs-fixer": "^3.62.0",
         "phpstan/phpstan": "^1.6",
-        "phpunit/phpunit": ">=8",
-        "vimeo/psalm": "^4.23"
+        "phpunit/phpunit": "^9.0",
+        "rector/rector": "^1.0",
+        "vimeo/psalm": "^4.30"
     },
     "suggest": {
-        "doctrine/annotations": "^1.7 || ^2.0"
+        "doctrine/annotations": "^2.0"
     },
     "autoload-dev": {
         "exclude-from-classmap": [
@@ -79,6 +81,7 @@
     },
     "scripts-descriptions": {
         "cs": "Fix all codestyle issues",
+        "rector": "Automatic refactoring",
         "lint": "Test codestyle",
         "test": "Run all non-legacy and codestyle tests",
         "testlegacy": "Run tests using the legacy TokenAnalyser",
@@ -93,7 +96,11 @@
     },
     "scripts": {
         "cs": "export XDEBUG_MODE=off && php-cs-fixer fix --allow-risky=yes",
-        "lint": "@cs --dry-run",
+        "rector": "rector process src",
+        "lint": [
+            "@cs --dry-run",
+            "@rector --dry-run"
+        ],
         "test": [
             "export XDEBUG_MODE=off && phpunit",
             "@lint"

docs/index.md

@@ -20,7 +20,10 @@ features:
 
 ### 2. Update your code
 
-Add `swagger-php` attributes or annotations to your source code.
+Add `swagger-php` attributes (or legacy annotations) to your source code.
+
+⚠️ `doctrine/annotations` is going to be deprecated in the future, so wherever
+possible attributes should be used.
 
 <codeblock id="minimal">
   <template v-slot:at>
@@ -53,4 +56,5 @@ Use an OpenAPI tool like [Swagger UI ](https://swagger.io/tools/swagger-ui/) to
 - [OpenApi Specification](https://spec.openapis.org/oas/v3.1.0.html)
 - [Learn by example](https://github.com/zircote/swagger-php/tree/master/Examples)
 - [Related projects](related-projects.md)
-- [Swagger-php 2.x documentation](https://github.com/zircote/swagger-php/tree/2.x/docs)
+- [swagger-php 2.x documentation](https://github.com/zircote/swagger-php/tree/2.x/docs)
+- [swagger-php 3.x documentation](https://github.com/zircote/swagger-php/tree/3.x/docs)

phpstan-baseline.neon

@@ -16,7 +16,7 @@ parameters:
 			path: Examples/using-links-php81/User.php
 
 		-
-			message: "#^Strict comparison using \\=\\=\\= between array\\|string and false will always evaluate to false\\.$#"
+			message: "#^Call to function array_key_exists\\(\\) with string and array\\{\\} will always evaluate to false\\.$#"
 			count: 1
 			path: src/Analysers/TokenScanner.php
 
@@ -50,11 +50,6 @@ parameters:
 			count: 1
 			path: src/Annotations/Schema.php
 
-		-
-			message: "#^If condition is always true\\.$#"
-			count: 1
-			path: src/Generator.php
-
 		-
 			message: "#^Result of && is always false\\.$#"
 			count: 3

rector.php

@@ -0,0 +1,34 @@
+<?php
+
+use Rector\CodeQuality\Rector\ClassMethod\ExplicitReturnNullRector;
+use Rector\CodeQuality\Rector\For_\ForRepeatedCountToOwnVariableRector;
+use Rector\CodeQuality\Rector\If_\CombineIfRector;
+use Rector\CodeQuality\Rector\If_\ExplicitBoolCompareRector;
+use Rector\CodeQuality\Rector\If_\ShortenElseIfRector;
+use Rector\Config\RectorConfig;
+use Rector\DeadCode\Rector\If_\RemoveAlwaysTrueIfConditionRector;
+use Rector\DeadCode\Rector\If_\RemoveDeadInstanceOfRector;
+use Rector\TypeDeclaration\Rector\Property\TypedPropertyFromStrictConstructorRector;
+use Rector\ValueObject\PhpVersion;
+
+return RectorConfig::configure()
+    ->withRules([
+        TypedPropertyFromStrictConstructorRector::class
+    ])
+    ->withSkip([
+        CombineIfRector::class,
+        ExplicitBoolCompareRector::class,
+        ExplicitReturnNullRector::class => [
+            __DIR__ . '/src/Analysers/TokenAnalyser.php',
+        ],
+        ForRepeatedCountToOwnVariableRector::class,
+        RemoveAlwaysTrueIfConditionRector::class => [
+            __DIR__ . '/src/Processors/ExpandEnums.php',
+        ] ,
+        RemoveDeadInstanceOfRector::class => [
+            __DIR__ . '/src/Processors/ExpandEnums.php',
+        ],
+        ShortenElseIfRector::class,
+    ])
+    ->withPreparedSets(true, true)
+    ->withPhpVersion(PhpVersion::PHP_74);

src/Analysers/AttributeAnnotationFactory.php

@@ -12,19 +12,13 @@
 
 class AttributeAnnotationFactory implements AnnotationFactoryInterface
 {
-    /** @var Generator|null */
-    protected $generator;
+    use GeneratorAwareTrait;
 
     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 (!$this->isSupported() || !method_exists($reflector, 'getAttributes')) {
@@ -116,9 +110,7 @@ public function build(\Reflector $reflector, Context $context): array
             Generator::$context = null;
         }
 
-        $annotations = array_values(array_filter($annotations, function ($a) {
-            return $a instanceof OA\AbstractAnnotation;
-        }));
+        $annotations = array_values(array_filter($annotations, fn ($a) => $a instanceof OA\AbstractAnnotation));
 
         // merge backwards into parents...
         $isParent = function (OA\AbstractAnnotation $annotation, OA\AbstractAnnotation $possibleParent): bool {
@@ -141,7 +133,7 @@ public function build(\Reflector $reflector, Context $context): array
 
             // Attachables can always be nested (unless explicitly restricted)
             return ($isAttachable && $isParentAllowed)
-                || ($annotation->getRoot() != $possibleParent->getRoot() && $explicitParent);
+                || ($annotation->getRoot() !== $possibleParent->getRoot() && $explicitParent);
         };
 
         $annotationsWithoutParent = [];

src/Analysers/DocBlockAnnotationFactory.php

@@ -12,11 +12,9 @@
 
 class DocBlockAnnotationFactory implements AnnotationFactoryInterface
 {
-    /** @var DocBlockParser|null */
-    protected $docBlockParser = null;
+    use GeneratorAwareTrait;
 
-    /** @var Generator|null */
-    protected $generator = null;
+    protected ?DocBlockParser $docBlockParser = null;
 
     public function __construct(?DocBlockParser $docBlockParser = null)
     {

src/Analysers/DocBlockParser.php

@@ -16,10 +16,7 @@
  */
 class DocBlockParser
 {
-    /**
-     * @var DocParser
-     */
-    protected $docParser;
+    protected DocParser $docParser;
 
     /**
      * @param array<string, class-string> $aliases

src/Analysers/GeneratorAwareTrait.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Analysers;
+
+use OpenApi\Generator;
+
+trait GeneratorAwareTrait
+{
+    protected ?Generator $generator = null;
+
+    public function setGenerator(Generator $generator): void
+    {
+        $this->generator = $generator;
+    }
+}

src/Analysers/ReflectionAnalyser.php

@@ -22,18 +22,16 @@
  */
 class ReflectionAnalyser implements AnalyserInterface
 {
-    /** @var AnnotationFactoryInterface[] */
-    protected $annotationFactories;
+    use GeneratorAwareTrait;
 
-    /** @var Generator|null */
-    protected $generator;
+    /** @var AnnotationFactoryInterface[] */
+    protected array $annotationFactories = [];
 
     /**
      * @param array<AnnotationFactoryInterface> $annotationFactories
      */
     public function __construct(array $annotationFactories = [])
     {
-        $this->annotationFactories = [];
         foreach ($annotationFactories as $annotationFactory) {
             if ($annotationFactory->isSupported()) {
                 $this->annotationFactories[] = $annotationFactory;
@@ -113,13 +111,11 @@ protected function analyzeFqdn(string $fqdn, Analysis $analysis, array $details)
             'methods' => [],
             'context' => $context,
         ];
-        $normaliseClass = function (string $name): string {
-            return '\\' . ltrim($name, '\\');
-        };
+        $normaliseClass = fn (string $name): string => '\\' . ltrim($name, '\\');
         if ($parentClass = $rc->getParentClass()) {
             $definition['extends'] = $normaliseClass($parentClass->getName());
         }
-        $definition[$contextType == 'class' ? 'implements' : 'extends'] = array_map($normaliseClass, $details['interfaces']);
+        $definition[$contextType === 'class' ? 'implements' : 'extends'] = array_map($normaliseClass, $details['interfaces']);
         $definition['traits'] = array_map($normaliseClass, $details['traits']);
 
         foreach ($this->annotationFactories as $annotationFactory) {

src/Analysers/TokenAnalyser.php

@@ -15,13 +15,7 @@
  */
 class TokenAnalyser implements AnalyserInterface
 {
-    /** @var Generator|null */
-    protected $generator;
-
-    public function setGenerator(Generator $generator): void
-    {
-        $this->generator = $generator;
-    }
+    use GeneratorAwareTrait;
 
     /**
      * Extract and process all doc-comments from a file.
@@ -166,7 +160,9 @@ protected function fromTokens(array $tokens, Context $parseContext): Analysis
 
                 if ($token[0] === T_IMPLEMENTS) {
                     $schemaContext->implements = $this->parseNamespaceList($tokens, $token, $parseContext);
-                    $classDefinition['implements'] = array_map([$schemaContext, 'fullyQualifiedName'], $schemaContext->implements);
+                    $classDefinition['implements'] = array_map(function (?string $source) use ($schemaContext): string {
+                        return $schemaContext->fullyQualifiedName($source);
+                    }, $schemaContext->implements);
                 }
 
                 if ($comment) {
@@ -207,7 +203,9 @@ protected function fromTokens(array $tokens, Context $parseContext): Analysis
 
                 if ($token[0] === T_EXTENDS) {
                     $schemaContext->extends = $this->parseNamespaceList($tokens, $token, $parseContext);
-                    $interfaceDefinition['extends'] = array_map([$schemaContext, 'fullyQualifiedName'], $schemaContext->extends);
+                    $interfaceDefinition['extends'] = array_map(function (?string $source) use ($schemaContext): string {
+                        return $schemaContext->fullyQualifiedName($source);
+                    }, $schemaContext->extends);
                 }
 
                 if ($comment) {