Refactor of DocBlock fuctionality

.github/workflows/build.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
           extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv
 
       - name: Cache Composer dependencies
@@ -44,7 +44,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
           extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv
 
       - name: Cache Composer dependencies
@@ -70,7 +70,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
           extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv
 
       - name: Cache Composer dependencies
@@ -96,7 +96,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
           extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, xdebug
           coverage: xdebug
 

composer.json

@@ -25,6 +25,7 @@
     },
     "autoload-dev": {
         "psr-4": {
+            "App\\": "vendor/orchestra/testbench-core/laravel/app",
             "LumoSolutions\\Actionable\\Tests\\": "tests/"
         }
     },
@@ -37,7 +38,7 @@
         "format": "vendor/bin/pint"
     },
     "require": {
-        "php": ">=8.2"
+        "php": ">=8.3"
     },
     "require-dev": {
         "larastan/larastan": "^2.9||^3.0",

src/Actions/Console/UpdateActionDocBlocks.php

@@ -0,0 +1,123 @@
+<?php
+
+namespace LumoSolutions\Actionable\Actions\Console;
+
+use Exception;
+use Illuminate\Support\Facades\File;
+use LumoSolutions\Actionable\Actions\Generation\GenerateDocBlocks;
+use LumoSolutions\Actionable\Actions\Generation\UpdateClassDocBlock;
+use LumoSolutions\Actionable\Dtos\Generation\DocBlockGenDto;
+use LumoSolutions\Actionable\Dtos\Generation\DocBlockUpdateDto;
+use LumoSolutions\Actionable\Support\ClassAnalyser;
+use LumoSolutions\Actionable\Support\DocBlockHelper;
+use LumoSolutions\Actionable\Traits\IsRunnable;
+
+class UpdateActionDocBlocks
+{
+    use IsRunnable;
+
+    public function __construct(
+        protected ClassAnalyser $classAnalyser
+    ) {}
+
+    public function handle(string $namespace = '\\App', bool $dryRun = false): array
+    {
+        $namespace = ltrim($namespace, '\\');
+        $classes = $this->findClassesInNamespace($namespace);
+        $results = [];
+
+        foreach ($classes as $className) {
+            try {
+                $diff = $this->processClass($className, $dryRun);
+
+                if (! empty($diff)) {
+                    $results[$className] = $diff;
+                }
+            } catch (Exception $e) {
+                continue;
+            }
+        }
+
+        return $results;
+    }
+
+    public function findClassesInNamespace(string $namespace): array
+    {
+        $classes = [];
+        $namespacePath = str_replace('\\', '/', $namespace);
+
+        $searchPaths = [];
+        if (str_starts_with($namespace, 'App')) {
+            $relativePath = str_replace('App', '', $namespacePath);
+            $relativePath = ltrim($relativePath, '/');
+            $searchPaths[] = app_path($relativePath);
+        }
+
+        $searchPaths[] = base_path('src/'.$namespacePath);
+        $searchPaths[] = base_path($namespacePath);
+
+        foreach ($searchPaths as $path) {
+            if (! is_dir($path)) {
+                continue;
+            }
+
+            $files = File::allFiles($path);
+            foreach ($files as $file) {
+                if ($file->getExtension() !== 'php') {
+                    continue;
+                }
+
+                $relativePath = $file->getRelativePathname();
+                $relativePath = str_replace(['/', '.php'], ['\\', ''], $relativePath);
+                $classes[] = $namespace.$relativePath;
+            }
+        }
+
+        return array_unique($classes);
+    }
+
+    public function processClass(string $className, bool $dryRun): array|bool
+    {
+        // Analyze the class
+        $data = rescue(
+            fn () => $this->classAnalyser->analyse($className),
+            fn ($e) => null,
+            false
+        );
+
+        if ($data == null) {
+            return false;
+        }
+
+        $actionableTraits = collect($data->traits)
+            ->filter(fn ($trait) => $trait->namespace === 'LumoSolutions\\Actionable\\Traits');
+
+        if ($actionableTraits->isEmpty()) {
+            return $dryRun ? [] : false;
+        }
+
+        $currentDocBlocks = ! empty($data->docBlock)
+            ? DocBlockHelper::extract($data->docBlock)
+            : [];
+
+        $newBlocks = GenerateDocBlocks::run(
+            new DocBlockGenDto(
+                isRunnable: (bool) $actionableTraits->firstWhere('name', 'IsRunnable'),
+                isDispatchable: (bool) $actionableTraits->firstWhere('name', 'IsDispatchable'),
+                handle: collect($data->methods)->firstWhere('name', 'handle'),
+                docBlocks: $currentDocBlocks,
+                usings: $data->includes ?? []
+            )
+        );
+
+        return UpdateClassDocBlock::run(
+            new DocBlockUpdateDto(
+                filePath: $data->filePath,
+                className: $data->className,
+                currentDocBlocks: $currentDocBlocks,
+                newDocBlocks: $newBlocks
+            ),
+            $dryRun
+        );
+    }
+}

src/Actions/Generation/GenerateDocBlocks.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace LumoSolutions\Actionable\Actions\Generation;
+
+use Exception;
+use LumoSolutions\Actionable\Dtos\Generation\DocBlockGenDto;
+use LumoSolutions\Actionable\Support\DocBlockHelper;
+use LumoSolutions\Actionable\Support\DocBlockProcessor;
+use LumoSolutions\Actionable\Traits\IsRunnable;
+
+class GenerateDocBlocks
+{
+    use IsRunnable;
+
+    private const string METHOD_RUN = 'run';
+
+    private const string METHOD_DISPATCH = 'dispatch';
+
+    private const string METHOD_DISPATCH_ON = 'dispatchOn';
+
+    /**
+     * @throws Exception
+     */
+    public function handle(DocBlockGenDto $dto): array
+    {
+        $processor = new DocBlockProcessor($dto->docBlocks);
+
+        $processor->removeMethodsIf(self::METHOD_RUN, ! $dto->isRunnable || ! $dto->handle);
+        $processor->removeMethodsIf(self::METHOD_DISPATCH, ! $dto->isDispatchable || ! $dto->handle);
+        $processor->removeMethodsIf(self::METHOD_DISPATCH_ON, ! $dto->isDispatchable || ! $dto->handle);
+
+        if ($dto->handle) {
+            if ($dto->isRunnable) {
+                $processor->addOrReplaceMethod(self::METHOD_RUN, $this->buildRunMethod($dto));
+            }
+
+            if ($dto->isDispatchable) {
+                $processor->addOrReplaceMethod(self::METHOD_DISPATCH, $this->buildDispatchMethod($dto));
+                $processor->addOrReplaceMethod(self::METHOD_DISPATCH_ON, $this->buildDispatchOnMethod($dto));
+            }
+        }
+
+        return $processor->getDocBlocks();
+    }
+
+    protected function buildRunMethod(DocBlockGenDto $dto): ?string
+    {
+        return DocBlockHelper::buildMethodLine(
+            'static',
+            DocBlockHelper::formatReturnType(
+                $dto->handle->returnTypes,
+                $dto->usings
+            ),
+            self::METHOD_RUN,
+            DocBlockHelper::formatParameters(
+                $dto->handle->parameters,
+                $dto->usings
+            )
+        );
+    }
+
+    protected function buildDispatchMethod(DocBlockGenDto $dto): ?string
+    {
+        return DocBlockHelper::buildMethodLine(
+            'static',
+            'void',
+            self::METHOD_DISPATCH,
+            DocBlockHelper::formatParameters(
+                $dto->handle->parameters,
+                $dto->usings
+            )
+        );
+    }
+
+    protected function buildDispatchOnMethod(DocBlockGenDto $dto): ?string
+    {
+        $parameters = DocBlockHelper::formatParameters($dto->handle->parameters, $dto->usings);
+        $queueParameter = 'string $queue';
+
+        return DocBlockHelper::buildMethodLine(
+            'static',
+            'void',
+            self::METHOD_DISPATCH_ON,
+            $parameters
+                ? $queueParameter.', '.$parameters
+                : $queueParameter
+        );
+    }
+}