Generate PHPDocs for Scopes

src/Services/GeneratePhpDocService.php

@@ -9,6 +9,7 @@
 use SethPhat\EloquentDocs\Services\Generators\PhpDocGeneratorContract;
 use SethPhat\EloquentDocs\Services\Generators\RelationshipsGenerator;
 use SethPhat\EloquentDocs\Services\Generators\TableGenerator;
+use SethPhat\EloquentDocs\Services\Generators\ScopesGenerator;
 
 class GeneratePhpDocService
 {
@@ -17,6 +18,7 @@ class GeneratePhpDocService
         ColumnsGenerator::class,
         RelationshipsGenerator::class,
         AccessorsGenerator::class,
+        ScopesGenerator::class,
     ];
 
     protected Model $model;
@@ -48,19 +50,16 @@ public function setOptions(array $options): self
      */
     public function generate(): string
     {
-        $phpDocStr = '/**';
-
-        foreach (static::GENERATORS as $generatorClass) {
+        $phpDocStr = "/**\n "
+          . join("\n *\n ", array_filter(array_map(function (string $generatorClass): string {
             /**
              * @var PhpDocGeneratorContract $generator
              */
             $generator = $this->laravel->make($generatorClass);
 
-            $phpDocStr .= $generator->generate($this->model, $this->options);
-        }
-
-        $phpDocStr .= "\n*/";
-
+            return trim($generator->generate($this->model, $this->options));
+          }, static::GENERATORS), fn ($item) => !empty($item)))
+          . "\n */";
         return $phpDocStr;
     }
-}
+}

src/Services/Generators/AccessorsGenerator.php

@@ -20,7 +20,7 @@ class AccessorsGenerator implements PhpDocGeneratorContract
 
     public function generate(Model $model, array $options = []): string
     {
-        $phpDocStr = "\n*\n* === Accessors/Attributes ===";
+        $phpDocStr = "\n * === Accessors/Attributes ===";
 
         $virtualAttributes = $this->getVirtualAttributes($model);
         if ($virtualAttributes->isEmpty()) {
@@ -98,4 +98,4 @@ protected function getVirtualAttributes(Model $model): Collection
             ])
             ->values();
     }
-}
+}

src/Services/Generators/ColumnsGenerator.php

@@ -27,7 +27,7 @@ public function generate(Model $model, array $options = []): string
         }
 
         // columns
-        $phpDocStr = "\n*\n* === Columns ===";
+        $phpDocStr = "\n * === Columns ===";
         foreach ($columns as $column) {
             $phpDocStr .= sprintf(
                 '%s * @property %s %s',
@@ -116,4 +116,4 @@ protected function getJsonCastType(string $column): string
 
         return 'string';
     }
-}
+}

src/Services/Generators/RelationshipsGenerator.php

@@ -26,7 +26,7 @@ class RelationshipsGenerator implements PhpDocGeneratorContract
 
     public function generate(Model $model, array $options = []): string
     {
-        $phpDocStr = "\n*\n* === Relationships ===";
+        $phpDocStr = "\n * === Relationships ===";
         $relationships = $this->getRelations($model);
         $isUseShortClass = $options['useShortClass'] ?? false;
 
@@ -99,4 +99,4 @@ protected function getRelations($model)
             ->filter()
             ->values();
     }
-}
+}

src/Services/Generators/ScopesGenerator.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace SethPhat\EloquentDocs\Services\Generators;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use ReflectionClass;
+use ReflectionMethod;
+use ReflectionNamedType;
+
+class ScopesGenerator implements PhpDocGeneratorContract
+{
+    public function generate(Model $model, array $options = []): string
+    {
+        $phpDoc = "";
+        $className = class_basename($model);
+        $reflection = new ReflectionClass($model);
+
+        foreach ($reflection->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
+            if ($this->isLocalScope($method)) {
+                // Remove 'scope' from method name and convert to camelCase
+                $scopeName = lcfirst(substr($method->getName(), 5));
+                $args="";
+                $i = -1;
+                $args = join(", ", array_filter(array_map(function ($param) use (&$i) {
+                    $type = $param->getType();
+                    $typeDoc = "";
+                    $i += 1;
+                    print("$i: $param\n  $type\n");
+                    if ($type) {
+                        if ($type instanceof ReflectionNamedType && $type->getName() === Builder::class) {
+                            return null;
+                        }
+                        $typeDoc = "$type ";
+                    } else if ($i === 0) {
+                        // First argument is the query builder
+                        return null;
+                    }
+                    if ($param->isPassedByReference()) {
+                        $typeDoc .= "&";
+                    }
+                    if ($param->isVariadic()) {
+                        $typeDoc .= "...";
+                    }
+                    return $typeDoc . '$' . $param->getName();
+                }, $method->getParameters()), fn ($item) => !empty($item)));
+                $phpDoc .= " * @method static \\Illuminate\\Database\\Eloquent\\Builder<{$className}> {$scopeName}($args)\n";
+            }
+        }
+
+        if (!$phpDoc) {
+          return "";
+        }
+
+        return " * === Scopes ===\n$phpDoc";
+    }
+
+    private function isLocalScope(ReflectionMethod $method): bool
+    {
+        $methodName = $method->getName();
+        return str_starts_with($methodName, 'scope') && strlen($methodName) > 5;
+    }
+}

tests/Units/Generators/ScopesGeneratorTest.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Tests\Units\Generators;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use PHPUnit\Framework\TestCase;
+use SethPhat\EloquentDocs\Services\Generators\ScopesGenerator;
+
+class ScopesTestModel1 extends Model {
+    public function scopePopular1(Builder $query, ...$args)
+    {
+        $query->where('votes', '>', 100);
+    }
+
+    public function scopePopular2(Builder $query, array ...$args)
+    {
+        $query->where('votes', '>', 100);
+    }
+
+    public function scopeUnpopular(Builder $query, ?int $votes = null)
+    {
+        $query->where('votes', '<=', $votes);
+    }
+
+    public function scopeInactive(Builder $query, bool &$foo)
+    {
+      $query->where('status', '!=', 'active');
+    }
+
+    public function scopeActive($query)
+    {
+        $query->where('status', '=', 'active');
+    }
+}
+
+class ScopesTestModel2 extends Model {
+    public function nonScopeMethod()
+    {
+        return 'This is not a scope';
+    }
+}
+
+class ScopesGeneratorTest extends TestCase
+{
+    public function testGenerateIncludesLocalScopes(): void
+    {
+
+        $model = new ScopesTestModel1();
+
+        $generator = new ScopesGenerator();
+        $phpDoc = $generator->generate($model, []);
+
+        print("phpdoc:\n$phpDoc");
+
+        $this->assertStringContainsString('=== Scopes ===', $phpDoc);
+        $this->assertStringContainsString('@method static \Illuminate\Database\Eloquent\Builder<ScopesTestModel1> popular1(...$args)', $phpDoc);
+        $this->assertStringContainsString('@method static \Illuminate\Database\Eloquent\Builder<ScopesTestModel1> popular2(array ...$args)', $phpDoc);
+        $this->assertStringContainsString('@method static \Illuminate\Database\Eloquent\Builder<ScopesTestModel1> unpopular(?int $votes)', $phpDoc);
+        $this->assertStringContainsString('@method static \Illuminate\Database\Eloquent\Builder<ScopesTestModel1> active()', $phpDoc);
+        $this->assertStringContainsString('@method static \Illuminate\Database\Eloquent\Builder<ScopesTestModel1> inactive(bool &$foo)', $phpDoc);
+    }
+
+    public function testGenerateExcludesNonScopeMethods(): void
+    {
+        $model = new ScopesTestModel2();
+
+        $generator = new ScopesGenerator();
+        $phpDoc = $generator->generate($model, []);
+
+        $this->assertStringNotContainsString('=== Scopes ===', $phpDoc);
+        $this->assertStringNotContainsString('@method static \Illuminate\Database\Eloquent\Builder<ScopesTestModel2> nonScopeMethod()', $phpDoc);
+    }
+}