Develop

composer.json

@@ -12,9 +12,9 @@
         "php": "^8.1",
         "illuminate/contracts": "^10.0|^11.0",
         "myclabs/deep-copy": "^1.12",
-        "nikic/php-parser": "^5.0",
+        "nikic/php-parser": "^5.3",
         "phpstan/phpdoc-parser": "^1.0",
-        "spatie/laravel-package-tools": "^1.9.2"
+        "spatie/laravel-package-tools": "^1.17.0"
     },
     "require-dev": {
         "laravel/pint": "^v1.1.0",

src/Generator.php

@@ -29,11 +29,11 @@ class Generator
     protected bool $throwExceptions = true;
 
     public function __construct(
-        private TypeTransformer $transformer,
-        private OperationBuilder $operationBuilder,
-        private ServerFactory $serverFactory,
-        private FileParser $fileParser,
-        private Infer $infer
+        protected TypeTransformer $transformer,
+        protected OperationBuilder $operationBuilder,
+        protected ServerFactory $serverFactory,
+        protected FileParser $fileParser,
+        protected Infer $infer,
     ) {}
 
     public function setThrowExceptions(bool $throwExceptions): static
@@ -44,6 +44,11 @@ public function setThrowExceptions(bool $throwExceptions): static
     }
 
     public function __invoke(?GeneratorConfig $config = null)
+    {
+        return $this->generate($config)->toArray();
+    }
+
+    public function generate(?GeneratorConfig $config = null): OpenApi
     {
         $config ??= (new GeneratorConfig(config('scramble')))
             ->routes(Scramble::$routeResolver)
@@ -64,21 +69,21 @@ public function __invoke(?GeneratorConfig $config = null)
                         $method = $route->methods()[0];
                         $action = $route->getAction('uses');
 
-                        dump("Error when analyzing route '$method $route->uri' ($action): {$e->getMessage()} – ".($e->getFile().' on line '.$e->getLine()));
-                        logger()->error("Error when analyzing route '$method $route->uri' ($action): {$e->getMessage()} – ".($e->getFile().' on line '.$e->getLine()));
+                        dump("Error when analyzing route '$method $route->uri' ($action): {$e->getMessage()} – " . ($e->getFile() . ' on line ' . $e->getLine()));
+                        logger()->error("Error when analyzing route '$method $route->uri' ($action): {$e->getMessage()} – " . ($e->getFile() . ' on line ' . $e->getLine()));
                     }
 
                     throw $e;
                 }
             })
             ->filter() // Closure based routes are filtered out for now, right here
-            ->sortBy(fn (Operation $o) => $o->tags[0] ?? $o->description)
-            ->each(fn (Operation $operation) => $openApi->addPath(
+            ->sortBy(fn(Operation $o) => $o->tags[0] ?? $o->description)
+            ->each(fn(Operation $operation) => $openApi->addPath(
                 Path::make(
                     (string) Str::of($operation->path)
-                        ->replaceFirst($config->get('api_path', 'api'), '')
-                        ->trim('/')
-                )->addOperation($operation)
+                        ->replaceFirst(rtrim($config->get('api_path', 'api'), '/') . '/', '/')
+                        ->trim('/'),
+                )->addOperation($operation),
             ))
             ->toArray();
 
@@ -90,35 +95,36 @@ public function __invoke(?GeneratorConfig $config = null)
             $afterOpenApiGenerated($openApi);
         }
 
-        return $openApi->toArray();
+        return $openApi;
     }
 
-    private function makeOpenApi(GeneratorConfig $config)
+    protected function makeOpenApi(GeneratorConfig $config)
     {
         $openApi = OpenApi::make('3.1.0')
             ->setComponents($this->transformer->getComponents())
             ->setInfo(
                 InfoObject::make($config->get('ui.title', $default = config('app.name')) ?: $default)
                     ->setVersion($config->get('info.version', '0.0.1'))
-                    ->setDescription($config->get('info.description', ''))
+                    ->setDescription($config->get('info.description', '')),
             );
 
         [$defaultProtocol] = explode('://', url('/'));
-        $servers = $config->get('servers') ?: [
-            '' => ($domain = $config->get('api_domain'))
-                ? $defaultProtocol.'://'.$domain.'/'.$config->get('api_path', 'api')
-                : $config->get('api_path', 'api'),
-        ];
+        $servers = $config->get('servers')
+            ?: [
+                '' => ($domain = $config->get('api_domain'))
+                    ? $defaultProtocol . '://' . $domain . '/' . $config->get('api_path', 'api')
+                    : $config->get('api_path', 'api'),
+            ];
         foreach ($servers as $description => $url) {
             $openApi->addServer(
-                $this->serverFactory->make(url($url ?: '/'), $description)
+                $this->serverFactory->make(url($url ?: '/'), $description),
             );
         }
 
         return $openApi;
     }
 
-    private function getRoutes(GeneratorConfig $config): Collection
+    protected function getRoutes(GeneratorConfig $config): Collection
     {
         return collect(RouteFacade::getRoutes())
             ->pipe(function (Collection $c) {
@@ -145,11 +151,11 @@ private function getRoutes(GeneratorConfig $config): Collection
                 return ! ($name = $route->getAction('as')) || ! Str::startsWith($name, 'scramble');
             })
             ->filter($config->routes())
-            ->filter(fn (Route $r) => $r->getAction('controller'))
+            ->filter(fn(Route $r) => $r->getAction('controller'))
             ->values();
     }
 
-    private function routeToOperation(OpenApi $openApi, Route $route, GeneratorConfig $config)
+    protected function routeToOperation(OpenApi $openApi, Route $route, GeneratorConfig $config)
     {
         $routeInfo = new RouteInfo($route, $this->fileParser, $this->infer);
 
@@ -164,7 +170,7 @@ private function routeToOperation(OpenApi $openApi, Route $route, GeneratorConfi
         return $operation;
     }
 
-    private function ensureSchemaTypes(Route $route, Operation $operation): void
+    protected function ensureSchemaTypes(Route $route, Operation $operation): void
     {
         if (! Scramble::getSchemaValidator()->hasRules()) {
             return;
@@ -183,14 +189,16 @@ private function ensureSchemaTypes(Route $route, Operation $operation): void
         }
     }
 
-    private function createSchemaEnforceTraverser(Route $route)
+    protected function createSchemaEnforceTraverser(Route $route)
     {
-        $traverser = new OpenApiTraverser([$visitor = new SchemaEnforceVisitor($route, $this->throwExceptions, $this->exceptions)]);
+        $traverser = new OpenApiTraverser([$visitor = new SchemaEnforceVisitor($route,
+            $this->throwExceptions,
+            $this->exceptions)]);
 
         return [$traverser, $visitor];
     }
 
-    private function moveSameAlternativeServersToPath(OpenApi $openApi)
+    protected function moveSameAlternativeServersToPath(OpenApi $openApi)
     {
         foreach (collect($openApi->paths)->groupBy('path') as $pathsGroup) {
             if ($pathsGroup->isEmpty()) {
@@ -200,9 +208,9 @@ private function moveSameAlternativeServersToPath(OpenApi $openApi)
             $operations = collect($pathsGroup->pluck('operations')->flatten());
 
             $operationsHaveSameAlternativeServers = $operations->count()
-                && $operations->every(fn (Operation $o) => count($o->servers))
+                && $operations->every(fn(Operation $o) => count($o->servers))
                 && $operations->unique(function (Operation $o) {
-                    return collect($o->servers)->map(fn (Server $s) => $s->url)->join('.');
+                    return collect($o->servers)->map(fn(Server $s) => $s->url)->join('.');
                 })->count() === 1;
 
             if (! $operationsHaveSameAlternativeServers) {
@@ -217,9 +225,9 @@ private function moveSameAlternativeServersToPath(OpenApi $openApi)
         }
     }
 
-    private function setUniqueOperationId(OpenApi $openApi)
+    protected function setUniqueOperationId(OpenApi $openApi)
     {
-        $names = new UniqueNamesOptionsCollection;
+        $names = new UniqueNamesOptionsCollection();
 
         $this->foreachOperation($openApi, function (Operation $operation) use ($names) {
             $names->push($operation->getAttribute('operationId'));
@@ -234,7 +242,7 @@ private function setUniqueOperationId(OpenApi $openApi)
         });
     }
 
-    private function foreachOperation(OpenApi $openApi, callable $callback)
+    protected function foreachOperation(OpenApi $openApi, callable $callback)
     {
         foreach (collect($openApi->paths)->groupBy('path') as $pathsGroup) {
             if ($pathsGroup->isEmpty()) {

src/Infer/Analyzer/ClassAnalyzer.php

@@ -29,7 +29,9 @@ private function shouldAnalyzeParentClass(ReflectionClass $parentClassReflection
          * Classes from `vendor` aren't analyzed at the moment. Instead, it is up to developers to provide
          * definitions for them using the dictionaries.
          */
-        return ! str_contains($parentClassReflection->getFileName(), DIRECTORY_SEPARATOR.'vendor'.DIRECTORY_SEPARATOR);
+
+        return ! str_contains($parentClassReflection->getFileName(),
+            DIRECTORY_SEPARATOR . 'vendor' . DIRECTORY_SEPARATOR);
     }
 
     /**
@@ -51,7 +53,35 @@ public function analyze(string $name): ClassDefinition
             // @todo: Here we still want to fire the event, so we can add some details to the definition.
             $parentDefinition = new ClassDefinition($parentName = $classReflection->getParentClass()->name);
 
-            Context::getInstance()->extensionsBroker->afterClassDefinitionCreated(new ClassDefinitionCreatedEvent($parentDefinition->name, $parentDefinition));
+            Context::getInstance()->extensionsBroker->afterClassDefinitionCreated(new ClassDefinitionCreatedEvent($parentDefinition->name,
+                $parentDefinition));
+        }
+
+        $annotations = [];
+
+        if ($doc = $classReflection->getDocComment()) {
+            preg_match_all(
+                '/@(\w+)(\s\w+)?/',
+                $doc,
+                $annotations,
+            );
+
+            $annotations = array_map(
+                static fn($value) => empty($value) ? null : trim($value),
+                array_combine($annotations[1], $annotations[2]),
+            );
+        }
+
+        $attrs = $classReflection->getAttributes() ?? [];
+
+        foreach ($attrs as $index => $attr) {
+            if (! class_exists($attr->getName())) {
+                unset($attrs[$index]);
+
+                continue;
+            }
+
+            $attrs[$index] = new ($attr->getName())(...$attr->getArguments());
         }
 
         /*
@@ -61,9 +91,11 @@ public function analyze(string $name): ClassDefinition
         $classDefinition = new ClassDefinition(
             name: $name,
             templateTypes: $parentDefinition?->templateTypes ?: [],
-            properties: array_map(fn ($pd) => clone $pd, $parentDefinition?->properties ?: []),
+            properties: array_map(fn($pd) => clone $pd, $parentDefinition?->properties ?: []),
             methods: $parentDefinition?->methods ?: [],
             parentFqn: $parentName ?? null,
+            annotations: $annotations,
+            attributes: $attrs,
         );
 
         /*
@@ -79,12 +111,12 @@ public function analyze(string $name): ClassDefinition
             if ($reflectionProperty->isStatic()) {
                 $classDefinition->properties[$reflectionProperty->name] = new ClassPropertyDefinition(
                     type: $reflectionProperty->hasDefaultValue()
-                        ? (TypeHelper::createTypeFromValue($reflectionProperty->getDefaultValue()) ?: new UnknownType)
-                        : new UnknownType,
+                        ? (TypeHelper::createTypeFromValue($reflectionProperty->getDefaultValue()) ?: new UnknownType())
+                        : new UnknownType(),
                 );
             } else {
                 $classDefinition->properties[$reflectionProperty->name] = new ClassPropertyDefinition(
-                    type: $t = new TemplateType('T'.Str::studly($reflectionProperty->name)),
+                    type: $t = new TemplateType('T' . Str::studly($reflectionProperty->name)),
                     defaultType: $reflectionProperty->hasDefaultValue()
                         ? TypeHelper::createTypeFromValue($reflectionProperty->getDefaultValue())
                         : null,
@@ -94,23 +126,21 @@ public function analyze(string $name): ClassDefinition
         }
 
         foreach ($classReflection->getMethods() as $reflectionMethod) {
-            if ($reflectionMethod->class !== $name) {
-                continue;
-            }
-
             $classDefinition->methods[$reflectionMethod->name] = new FunctionLikeDefinition(
                 new FunctionType(
-                    $reflectionMethod->name,
+                    name: $reflectionMethod->name,
                     arguments: [],
-                    returnType: new UnknownType,
+                    returnType: new UnknownType(),
                 ),
                 definingClassName: $name,
             );
         }
 
         $this->index->registerClassDefinition($classDefinition);
 
-        Context::getInstance()->extensionsBroker->afterClassDefinitionCreated(new ClassDefinitionCreatedEvent($classDefinition->name, $classDefinition));
+        Context::getInstance()->extensionsBroker->afterClassDefinitionCreated(
+            new ClassDefinitionCreatedEvent($classDefinition->name, $classDefinition),
+        );
 
         return $classDefinition;
     }

src/Infer/Definition/ClassDefinition.php

@@ -31,6 +31,8 @@ public function __construct(
         /** @var array<string, FunctionLikeDefinition> $methods */
         public array $methods = [],
         public ?string $parentFqn = null,
+        public array $annotations = [],
+        public array $attributes = [],
     ) {}
 
     public function isInstanceOf(string $className)

src/Infer/Scope/Scope.php

@@ -4,6 +4,7 @@
 
 use Dedoc\Scramble\Infer\Definition\ClassDefinition;
 use Dedoc\Scramble\Infer\Services\FileNameResolver;
+use Dedoc\Scramble\Infer\Services\ReferenceTypeResolver;
 use Dedoc\Scramble\Infer\SimpleTypeGetters\BooleanNotTypeGetter;
 use Dedoc\Scramble\Infer\SimpleTypeGetters\CastTypeGetter;
 use Dedoc\Scramble\Infer\SimpleTypeGetters\ClassConstFetchTypeGetter;
@@ -305,6 +306,17 @@ public function addVariableType(int $line, string $name, Type $type)
         $this->variables[$name][] = compact('line', 'type');
     }
 
+    /**
+     * @deprecated
+     */
+    public function getPropertyFetchType(Type $calledOn, string $propertyName): Type
+    {
+        return (new ReferenceTypeResolver($this->index))->resolve(
+            $this,
+            new PropertyFetchReferenceType($calledOn, $propertyName)
+        );
+    }
+
     private function getVariableType(Node\Expr\Variable $node)
     {
         $name = (string) $node->name;

src/Support/ExceptionToResponseExtensions/AuthenticationExceptionToResponseExtension.php

@@ -40,6 +40,10 @@ public function toResponse(Type $type)
 
     public function reference(ObjectType $type)
     {
-        return new Reference('responses', Str::start($type->name, '\\'), $this->components);
+        return app(Reference::class, [
+            'referenceType' => 'responses',
+            'fullName' => Str::start($type->name, '\\'),
+            'components' => $this->components,
+        ]);
     }
 }

src/Support/ExceptionToResponseExtensions/AuthorizationExceptionToResponseExtension.php

@@ -40,6 +40,10 @@ public function toResponse(Type $type)
 
     public function reference(ObjectType $type)
     {
-        return new Reference('responses', Str::start($type->name, '\\'), $this->components);
+        return app(Reference::class, [
+            'referenceType' => 'responses',
+            'fullName' => Str::start($type->name, '\\'),
+            'components' => $this->components,
+        ]);
     }
 }

src/Support/ExceptionToResponseExtensions/NotFoundExceptionToResponseExtension.php

@@ -44,6 +44,10 @@ public function toResponse(Type $type)
 
     public function reference(ObjectType $type)
     {
-        return new Reference('responses', Str::start($type->name, '\\'), $this->components);
+        return app(Reference::class, [
+            'referenceType' => 'responses',
+            'fullName' => Str::start($type->name, '\\'),
+            'components' => $this->components,
+        ]);
     }
 }

src/Support/ExceptionToResponseExtensions/ValidationExceptionToResponseExtension.php

@@ -46,6 +46,10 @@ public function toResponse(Type $type)
 
     public function reference(ObjectType $type)
     {
-        return new Reference('responses', Str::start($type->name, '\\'), $this->components);
+        return app(Reference::class, [
+            'referenceType' => 'responses',
+            'fullName' => Str::start($type->name, '\\'),
+            'components' => $this->components,
+        ]);
     }
 }