Merge branch 'main' into main

dedoc · Mar 10, 2024 · da76921 · da76921
2 parents 59b287a + 6bd44d3
commit da76921
Show file tree

Hide file tree

Showing 61 changed files with 387 additions and 142 deletions.
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -13,16 +13,17 @@ jobs:
       fail-fast: true
       matrix:
         os: [ubuntu-latest]
-        php: [8.1]
-        laravel: [10.*, 9.*, 8.81.*]
+        php: [8.1, 8.2]
+        laravel: [11.*, 10.*]
         stability: [prefer-lowest, prefer-stable]
         include:
           - laravel: 10.*
             testbench: 8.*
-          - laravel: 9.*
-            testbench: 7.*
-          - laravel: 8.81.*
-            testbench: 6.24.*
+          - laravel: 11.*
+            testbench: 9.*
+        exclude:
+          - laravel: 11.*
+            php: 8.1
 
     name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.stability }} - ${{ matrix.os }}
 

diff --git a/composer.json b/composer.json
@@ -17,20 +17,19 @@
     ],
     "require": {
         "php": "^8.1",
-        "illuminate/contracts": "^8.0.0|^9.0.0|^10.0.0",
-        "nikic/php-parser": "^4.0",
+        "illuminate/contracts": "^10.0|^11.0",
+        "nikic/php-parser": "^5.0",
         "phpstan/phpdoc-parser": "^1.0",
         "spatie/laravel-package-tools": "^1.9.2"
     },
     "require-dev": {
-        "doctrine/dbal": "^3.4",
         "laravel/pint": "^v1.1.0",
-        "nunomaduro/collision": "^5.0|^v6.0",
-        "orchestra/testbench": "^6.0|^7.0|^8.0",
-        "pestphp/pest": "^1.21",
-        "pestphp/pest-plugin-laravel": "^1.2",
-        "phpunit/phpunit": "^9.5",
-        "spatie/pest-plugin-snapshots": "^1.1"
+        "nunomaduro/collision": "^7.0|^8.0",
+        "orchestra/testbench": "^8.0|^9.0",
+        "pestphp/pest": "^2.34",
+        "pestphp/pest-plugin-laravel": "^2.3",
+        "phpunit/phpunit": "^10.5",
+        "spatie/pest-plugin-snapshots": "^2.1"
     },
     "autoload": {
         "psr-4": {

diff --git a/config/scramble.php b/config/scramble.php
@@ -20,6 +20,12 @@
      */
     'export_path' => 'api.json',
 
+    /*
+     * Define the theme of the documentation.
+     * Available options are `light` and `dark`.
+     */
+    'theme' => 'dark',
+
     'info' => [
         /*
          * API version.

diff --git a/resources/views/docs.blade.php b/resources/views/docs.blade.php
@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="en">
+<html lang="en" data-theme="{{ config('scramble.theme', 'light') }}">
 <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

diff --git a/src/Infer/Definition/ClassDefinition.php b/src/Infer/Definition/ClassDefinition.php
@@ -81,7 +81,7 @@ public function getPropertyDefinition($name)
         return $this->properties[$name] ?? null;
     }
 
-    public function getMethodCallType(string $name, ObjectType $calledOn = null)
+    public function getMethodCallType(string $name, ?ObjectType $calledOn = null)
     {
         $methodDefinition = $this->methods[$name] ?? null;
 

diff --git a/src/Infer/Definition/FunctionLikeDefinition.php b/src/Infer/Definition/FunctionLikeDefinition.php
@@ -10,7 +10,7 @@ class FunctionLikeDefinition
     public bool $isFullyAnalyzed = false;
 
     /**
-     * @param  array<string, Type>  $argumentsDefaults A map where the key is arg name and value is a default type.
+     * @param  array<string, Type>  $argumentsDefaults  A map where the key is arg name and value is a default type.
      */
     public function __construct(
         public FunctionType $type,

diff --git a/src/Infer/Handler/ThrowHandler.php b/src/Infer/Handler/ThrowHandler.php
@@ -12,10 +12,10 @@ class ThrowHandler
 {
     public function shouldHandle($node)
     {
-        return $node instanceof Node\Stmt\Throw_;
+        return $node instanceof Node\Expr\Throw_;
     }
 
-    public function leave(Node\Stmt\Throw_ $node, Scope $scope)
+    public function leave(Node\Expr\Throw_ $node, Scope $scope)
     {
         if (! $scope->isInFunction()) {
             return;

diff --git a/src/Infer/Reflector/ClassReflector.php b/src/Infer/Reflector/ClassReflector.php
@@ -15,6 +15,8 @@ class ClassReflector
 
     private ?NameContext $nameContext = null;
 
+    private array $methods = [];
+
     private function __construct(
         private FileParser $parser,
         private string $className,

diff --git a/src/Infer/Reflector/MethodReflector.php b/src/Infer/Reflector/MethodReflector.php
@@ -73,7 +73,7 @@ public function __construct($nameContext)
                     $this->nameContext = $nameContext;
                 }
 
-                public function beforeTraverse(array $nodes)
+                public function beforeTraverse(array $nodes): ?array
                 {
                     return null;
                 }

diff --git a/src/Infer/Scope/Scope.php b/src/Infer/Scope/Scope.php
@@ -164,7 +164,7 @@ public function setType(Node $node, Type $type)
         return $type;
     }
 
-    public function createChildScope(ScopeContext $context = null)
+    public function createChildScope(?ScopeContext $context = null)
     {
         return new Scope(
             $this->index,

diff --git a/src/Infer/Services/ReferenceTypeResolver.php b/src/Infer/Services/ReferenceTypeResolver.php
@@ -312,7 +312,7 @@ private function getFunctionCallResult(
         FunctionLikeDefinition $callee,
         array $arguments,
         /* When this is a handling for method call */
-        ObjectType|SelfType $calledOnType = null,
+        ObjectType|SelfType|null $calledOnType = null,
     ) {
         $returnType = $callee->type->getReturnType();
         $isSelf = false;
@@ -401,7 +401,7 @@ private function getFunctionCallResult(
      * arguments defaults.
      *
      * @param  ?FunctionLikeDefinition  $callee
-     * @param  array  $realArguments The list of arguments a function has been called with.
+     * @param  array  $realArguments  The list of arguments a function has been called with.
      * @return array The actual list of arguments where not passed arguments replaced with default values.
      */
     private function prepareArguments(?FunctionLikeDefinition $callee, array $realArguments)

diff --git a/src/ScrambleServiceProvider.php b/src/ScrambleServiceProvider.php
@@ -26,6 +26,7 @@
 use Dedoc\Scramble\Support\InferExtensions\ResponseFactoryTypeInfer;
 use Dedoc\Scramble\Support\InferExtensions\ValidatorTypeInfer;
 use Dedoc\Scramble\Support\OperationBuilder;
+use Dedoc\Scramble\Support\OperationExtensions\DeprecationExtension;
 use Dedoc\Scramble\Support\OperationExtensions\ErrorResponsesExtension;
 use Dedoc\Scramble\Support\OperationExtensions\RequestBodyExtension;
 use Dedoc\Scramble\Support\OperationExtensions\RequestEssentialsExtension;
@@ -55,7 +56,7 @@ public function configurePackage(Package $package): void
 
         $this->app->singleton(FileParser::class, function () {
             return new FileParser(
-                (new ParserFactory)->create(ParserFactory::PREFER_PHP7)
+                (new ParserFactory)->createForHostVersion()
             );
         });
 
@@ -110,6 +111,7 @@ public function configurePackage(Package $package): void
                     RequestBodyExtension::class,
                     ErrorResponsesExtension::class,
                     ResponseExtension::class,
+                    DeprecationExtension::class,
                 ], $operationExtensions);
             });
 

diff --git a/src/Support/Generator/Operation.php b/src/Support/Generator/Operation.php
@@ -16,6 +16,8 @@ class Operation
 
     public string $summary = '';
 
+    public bool $deprecated = false;
+
     /** @var array<Security|array> */
     public array $security = [];
 
@@ -111,6 +113,13 @@ public function description(string $description)
         return $this;
     }
 
+    public function deprecated(bool $deprecated)
+    {
+        $this->deprecated = $deprecated;
+
+        return $this;
+    }
+
     public function setTags(array $tags)
     {
         $this->tags = array_map(fn ($t) => (string) $t, $tags);
@@ -141,6 +150,10 @@ public function toArray()
             $result['summary'] = $this->summary;
         }
 
+        if ($this->deprecated) {
+            $result['deprecated'] = $this->deprecated;
+        }
+
         if (count($this->tags)) {
             $result['tags'] = $this->tags;
         }

diff --git a/src/Support/Generator/Response.php b/src/Support/Generator/Response.php
@@ -39,7 +39,7 @@ public function toArray()
 
         $content = [];
         foreach ($this->content as $mediaType => $schema) {
-            $content[$mediaType] = $schema ? ['schema' => $schema->toArray()] : [];
+            $content[$mediaType] = $schema ? ['schema' => $schema->toArray()] : (object) [];
         }
 
         $result['content'] = $content;

diff --git a/src/Support/Generator/SecuritySchemes/OAuthFlow.php b/src/Support/Generator/SecuritySchemes/OAuthFlow.php
@@ -43,11 +43,14 @@ public function addScope(string $name, string $description = '')
 
     public function toArray()
     {
-        return array_filter([
-            'authorizationUrl' => $this->authorizationUrl,
-            'tokenUrl' => $this->tokenUrl,
-            'refreshUrl' => $this->refreshUrl,
-            'scopes' => $this->scopes,
-        ]);
+        return [
+            ...array_filter([
+                'authorizationUrl' => $this->authorizationUrl,
+                'tokenUrl' => $this->tokenUrl,
+                'refreshUrl' => $this->refreshUrl,
+            ]),
+            // Never filter 'scopes' as it is allowed to be empty. If empty it must be an object
+            'scopes' => empty($this->scopes) ? new \stdClass() : $this->scopes,
+        ];
     }
 }
diff --git a/src/Support/Generator/ServerVariable.php b/src/Support/Generator/ServerVariable.php
@@ -13,7 +13,7 @@ class ServerVariable
     public function __construct(
         string $default,
         array $enum = [],
-        string $description = null
+        ?string $description = null
     ) {
         $this->default = $default;
         $this->enum = $enum;
@@ -23,7 +23,7 @@ public function __construct(
     public static function make(
         string $default,
         array $enum = [],
-        string $description = null
+        ?string $description = null
     ) {
         return new self($default, $enum, $description);
     }

diff --git a/src/Support/Generator/UniqueNamesOptionsCollection.php b/src/Support/Generator/UniqueNamesOptionsCollection.php
@@ -42,7 +42,7 @@ public function push(UniqueNameOptions $name)
         return $this;
     }
 
-    public function getUniqueName(UniqueNameOptions $name, callable $onNotUniqueFallback = null): string
+    public function getUniqueName(UniqueNameOptions $name, ?callable $onNotUniqueFallback = null): string
     {
         if ($name->eloquent && count($this->eloquentNames[$name->eloquent]) === 1) {
             return $name->eloquent;

diff --git a/src/Support/InferExtensions/JsonResourceTypeInfer.php b/src/Support/InferExtensions/JsonResourceTypeInfer.php
@@ -147,17 +147,13 @@ private static function modelType(ClassDefinition $jsonClass, Scope $scope): ?Ty
         $modelType = new UnknownType("Cannot resolve [$modelClass] model type.");
         $modelClassDefinition = null;
         if ($modelClass && is_a($modelClass, Model::class, true)) {
-            try {
-                $modelClassDefinition = (new ModelInfo($modelClass))->type();
+            // @todo Use ModelExtension implementation of model info to type conversion.
+            // @todo The problem is that model extension type is dynamic and I'm not sure how to use it here.
+            $modelClassDefinition = (new ModelInfo($modelClass))->type();
 
-                $scope->index->registerClassDefinition($modelClassDefinition);
+            $scope->index->registerClassDefinition($modelClassDefinition);
 
-                $modelType = new ObjectType($modelClassDefinition->name);
-            } catch (\LogicException $e) {
-                // Here doctrine/dbal is not installed.
-                $modelType = null;
-                $modelClassDefinition = null;
-            }
+            $modelType = new ObjectType($modelClassDefinition->name);
         }
 
         static::$jsonResourcesModelTypesCache[$jsonClass->name] = [$modelType, $modelClassDefinition];

diff --git a/src/Support/InferExtensions/ModelExtension.php b/src/Support/InferExtensions/ModelExtension.php
@@ -68,18 +68,22 @@ public function getPropertyType(PropertyFetchEvent $event): ?Type
 
     private function getBaseAttributeType(Model $model, string $key, array $value)
     {
-        $type = explode(' ', $value['type']);
-        $typeName = explode('(', $type[0])[0];
+        $type = explode(' ', $value['type'] ?? '');
+        $typeName = explode('(', $type[0] ?? '')[0];
 
-        if (in_array($key, $model->getDates())) {
+        if (
+            ($model->getCasts()[$key] ?? null) === 'datetime'
+            || in_array($key, $model->getDates())
+        ) {
             return new ObjectType(Carbon::class);
         }
 
+        // @todo Fix to native types
         $attributeType = match ($typeName) {
             'int', 'integer', 'bigint' => new IntegerType(),
             'float', 'double', 'decimal' => new FloatType(),
-            'string', 'text', 'datetime' => new StringType(),
-            'bool', 'boolean' => new BooleanType(),
+            'varchar', 'string', 'text', 'datetime' => new StringType(), // string, text - needed?
+            'tinyint', 'bool', 'boolean' => new BooleanType(), // bool, boolean - needed?
             'json', 'array' => new ArrayType(),
             default => new UnknownType("unimplemented DB column type [$type[0]]"),
         };

diff --git a/src/Support/OperationExtensions/DeprecationExtension.php b/src/Support/OperationExtensions/DeprecationExtension.php
@@ -0,0 +1,71 @@
+<?php
+
+namespace Dedoc\Scramble\Support\OperationExtensions;
+
+use Dedoc\Scramble\Extensions\OperationExtension;
+use Dedoc\Scramble\Infer\Reflector\ClassReflector;
+use Dedoc\Scramble\Support\Generator\Operation;
+use Dedoc\Scramble\Support\PhpDoc;
+use Dedoc\Scramble\Support\RouteInfo;
+use Illuminate\Support\Str;
+use PHPStan\PhpDocParser\Ast\PhpDoc\DeprecatedTagValueNode;
+
+/**
+ * Extension to add deprecation notice to the operation description
+ * Skips if method is not deprecated
+ * If a whole class is deprecated, all methods are deprecated, only add the description if exists
+ */
+class DeprecationExtension extends OperationExtension
+{
+    public function handle(Operation $operation, RouteInfo $routeInfo)
+    {
+        // Skip if method is not deprecated
+        if (! $routeInfo->reflectionMethod() || $routeInfo->phpDoc()->getTagsByName('@not-deprecated')) {
+            return;
+        }
+
+        $fqdn = $routeInfo->reflectionMethod()->getDeclaringClass()->getName();
+        $deprecatedClass = $this->getClassDeprecatedValues($fqdn);
+        $deprecatedTags = $routeInfo->phpDoc()->getDeprecatedTagValues();
+
+        // Skip if no deprecations found
+        if (! $deprecatedClass && ! $deprecatedTags) {
+            return;
+        }
+
+        $description = Str::of($this->generateDescription($deprecatedClass));
+
+        if ($description->isNotEmpty()) {
+            $description = $description->append("\n\n");
+        }
+
+        $description = $description->append($this->generateDescription($deprecatedTags));
+
+        $operation
+            ->description((string) $description)
+            ->deprecated(true);
+    }
+
+    /**
+     * @return array<DeprecatedTagValueNode>
+     */
+    protected function getClassDeprecatedValues(string $fqdn)
+    {
+        $reflector = ClassReflector::make($fqdn);
+        $classPhpDocString = $reflector->getReflection()->getDocComment();
+
+        if ($classPhpDocString === false) {
+            return [];
+        }
+
+        return PhpDoc::parse($classPhpDocString)->getDeprecatedTagValues();
+    }
+
+    /**
+     * @return string
+     */
+    private function generateDescription(array $deprecation)
+    {
+        return implode("\n", array_map(fn ($tag) => $tag->description, $deprecation));
+    }
+}
diff --git a/src/Support/OperationExtensions/RequestEssentialsExtension.php b/src/Support/OperationExtensions/RequestEssentialsExtension.php
@@ -130,7 +130,7 @@ private function extractTagsForMethod(RouteInfo $routeInfo)
             return [];
         }
 
-        return explode(',', $tagNodes[0]->value->value);
+        return explode(',', array_values($tagNodes)[0]->value->value);
     }
 
     private function getParametersFromString(?string $str)