Merge pull request #320 from laravel/model-doc-blocks

Option to disable model doc block generation + fix doc block extends

Author: joetannenbaum

package.json

@@ -113,6 +113,11 @@
                     "default": true,
                     "description": "Show popups for errors."
                 },
+                "Laravel.eloquent.generateDocBlocks": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Automatically generate Eloquent doc blocks for models as IDE helpers."
+                },
                 "Laravel.blade.autoSpaceTags": {
                     "type": "boolean",
                     "default": true,

php-templates/models.php

@@ -119,13 +119,30 @@ protected function collectExistingProperties($reflection)
         return collect();
     }
 
+    protected function getParentClass(\ReflectionClass $reflection)
+    {
+        if (!$reflection->getParentClass()) {
+            return null;
+        }
+
+        $parent = $reflection->getParentClass()->getName();
+
+        if ($parent === \Illuminate\Database\Eloquent\Model::class) {
+            return null;
+        }
+
+        return \Illuminate\Support\Str::start($parent, '\\');
+    }
+
     protected function getInfo($className)
     {
         if (($data = $this->fromArtisan($className)) === null) {
             return null;
         }
 
-        $reflection = (new \ReflectionClass($className));
+        $reflection = new \ReflectionClass($className);
+
+        $data["extends"] = $this->getParentClass($reflection);
 
         $existingProperties = $this->collectExistingProperties($reflection);
 

src/index.d.ts

@@ -82,6 +82,7 @@ declare namespace Eloquent {
         events: Event[];
         observers: Observer[];
         scopes: string[];
+        extends: string | null;
     }
 
     interface Attribute {

src/support/config.ts

@@ -10,7 +10,8 @@ type ConfigKey =
     | "tests.ssh.enabled"
     | "tests.suiteSuffix"
     | "showErrorPopups"
-    | "blade.autoSpaceTags";
+    | "blade.autoSpaceTags"
+    | "eloquent.generateDocBlocks";
 
 export const config = <T>(key: ConfigKey, fallback: T): T =>
     vscode.workspace.getConfiguration("Laravel").get<T>(key, fallback);

src/support/docblocks.ts

@@ -1,12 +1,14 @@
 import fs from "fs";
 import { Eloquent } from "..";
+import { config } from "./config";
 import { internalVendorPath } from "./project";
 import { indent } from "./util";
 
 interface ClassBlock {
     namespace: string;
     className: string;
     blocks: string[];
+    extends: string | null;
 }
 
 const modelBuilderType = (className: string) =>
@@ -16,7 +18,7 @@ export const writeEloquentDocBlocks = (
     models: Eloquent.Models,
     builderMethods: Eloquent.BuilderMethod[],
 ) => {
-    if (!models) {
+    if (!models || !config("eloquent.generateDocBlocks", true)) {
         return;
     }
 
@@ -28,6 +30,7 @@ export const writeEloquentDocBlocks = (
             namespace: pathParts.join("\\"),
             className: cls || "",
             blocks: getBlocks(model, cls || "", builderMethods),
+            extends: model.extends || null,
         };
     });
 
@@ -113,7 +116,9 @@ const getBlocks = (
         .concat(
             [...model.scopes, "newModelQuery", "newQuery", "query"].map(
                 (method) => {
-                    return `@method static ${modelBuilderType(className)} ${method}()`;
+                    return `@method static ${modelBuilderType(
+                        className,
+                    )} ${method}()`;
                 },
             ),
         )
@@ -178,7 +183,9 @@ const classToDocBlock = (block: ClassBlock, namespace: string) => {
         ...block.blocks,
         " * @mixin \\Illuminate\\Database\\Query\\Builder",
         " */",
-        `class ${block.className} extends \\Illuminate\\Database\\Eloquent\\Model`,
+        `class ${block.className} extends ${
+            block.extends ?? "\\Illuminate\\Database\\Eloquent\\Model"
+        }`,
         `{`,
         indent("//"),
         `}`,
@@ -205,7 +212,9 @@ const getAttributeBlocks = (
 
     if (!["accessor", "attribute"].includes(attr.cast || "")) {
         blocks.push(
-            `@method static ${modelBuilderType(className)} where${attr.title_case}($value)`,
+            `@method static ${modelBuilderType(className)} where${
+                attr.title_case
+            }($value)`,
         );
     }
 

src/templates/models.ts

@@ -119,13 +119,30 @@ $models = new class($factory) {
         return collect();
     }
 
+    protected function getParentClass(\\ReflectionClass $reflection)
+    {
+        if (!$reflection->getParentClass()) {
+            return null;
+        }
+
+        $parent = $reflection->getParentClass()->getName();
+
+        if ($parent === \\Illuminate\\Database\\Eloquent\\Model::class) {
+            return null;
+        }
+
+        return \\Illuminate\\Support\\Str::start($parent, '\\\\');
+    }
+
     protected function getInfo($className)
     {
         if (($data = $this->fromArtisan($className)) === null) {
             return null;
         }
 
-        $reflection = (new \\ReflectionClass($className));
+        $reflection = new \\ReflectionClass($className);
+
+        $data["extends"] = $this->getParentClass($reflection);
 
         $existingProperties = $this->collectExistingProperties($reflection);