Add Flowpipe configuration, command for step creation, and YAML flow definition registry

Author: Grazulex

composer.json

@@ -22,7 +22,8 @@
         "php": "^8.3",
         "illuminate/support": "^12.19",
         "nesbot/carbon": "^3.10",
-        "illuminate/contracts": "^12.0"
+        "illuminate/contracts": "^12.0",
+        "symfony/yaml": "^7.3"
     },
     "require-dev": {
         "laravel/pint": "^1.22",
@@ -92,4 +93,4 @@
             "pestphp/pest-plugin": true
         }
     }
-}
+}

src/Config/flowpipe.php

@@ -3,6 +3,38 @@
 declare(strict_types=1);
 
 return [
+    /*
+    |--------------------------------------------------------------------------
+    | Flow Definition Path
+    |--------------------------------------------------------------------------
+    |
+    | This is where your YAML flow definitions live.
+    | Relative to the base_path() of the Laravel app.
+    |
+    */
+
+    'definitions_path' => 'flow_definitions',
+    /*
+    |--------------------------------------------------------------------------
+    | Default Step Namespace
+    |--------------------------------------------------------------------------
+    |
+    | This namespace will be prepended to step class names when resolving
+    | strings like 'MyStep' into 'App\\Flowpipe\\Steps\\MyStep'.
+    |
+    */
+
+    'step_namespace' => 'App\\Flowpipe\\Steps',
+
+    /*
+    |--------------------------------------------------------------------------
+    | Tracing Configuration
+    |--------------------------------------------------------------------------
+    |
+    | This section configures the tracing functionality of Flowpipe.
+    | You can enable or disable tracing and set the default tracer class.
+    | */
+
     'tracing' => [
         'enabled' => true,
         'default' => Grazulex\LaravelFlowpipe\Tracer\BasicTracer::class,

src/Console/Commands/FlowpipeMakeStepCommand.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Grazulex\LaravelFlowpipe\Console\Commands;
+
+use Illuminate\Console\GeneratorCommand;
+use Symfony\Component\Console\Input\InputArgument;
+
+final class FlowpipeMakeStepCommand extends GeneratorCommand
+{
+    protected $name = 'flowpipe:make-step';
+
+    protected $description = 'Create a new Flowpipe Step class';
+
+    protected $type = 'Step';
+
+    protected function getStub(): string
+    {
+        return __DIR__.'/stubs/step.stub';
+    }
+
+    protected function getDefaultNamespace($rootNamespace): string
+    {
+        return $rootNamespace.'\\Flowpipe\\Steps';
+    }
+
+    protected function getArguments(): array
+    {
+        return [
+            ['name', InputArgument::REQUIRED, 'The name of the Step class'],
+        ];
+    }
+}

src/Console/Commands/stubs/step.stub

@@ -0,0 +1,16 @@
+<?php
+
+namespace {{ namespace }};
+
+use Closure;
+use Grazulex\LaravelFlowpipe\Contracts\FlowStep;
+
+final class {{ class }} implements FlowStep
+{
+    public function handle(mixed $payload, Closure $next): mixed
+    {
+        // TODO: Add your logic here
+
+        return $next($payload);
+    }
+}

src/LaravelFlowpipeServiceProvider.php

@@ -24,5 +24,8 @@ public function boot(): void
     public function register(): void
     {
         $this->mergeConfigFrom(__DIR__.'/Config/flowpipe.php', 'flowpipe');
+        $this->commands([
+            Console\Commands\FlowpipeMakeStepCommand::class,
+        ]);
     }
 }

src/Registry/FlowDefinitionRegistry.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Grazulex\LaravelFlowpipe\Registry;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\File;
+use RuntimeException;
+use Symfony\Component\Yaml\Yaml;
+
+final class FlowDefinitionRegistry
+{
+    private string $path;
+
+    public function __construct(?string $path = null)
+    {
+        $this->path = base_path(config('flowpipe.definitions_path', 'flow_definitions'));
+    }
+
+    public function list(): Collection
+    {
+        return collect(File::files($this->path))
+            ->filter(fn ($f) => str_ends_with($f->getFilename(), '.yaml'))
+            ->map(fn ($f) => $f->getFilenameWithoutExtension());
+    }
+
+    public function get(string $name): array
+    {
+        $file = $this->path.'/'.$name.'.yaml';
+
+        if (! file_exists($file)) {
+            throw new RuntimeException("Flow definition [$name] not found.");
+        }
+
+        return Yaml::parseFile($file);
+    }
+}

src/Steps/StepResolver.php

@@ -6,29 +6,40 @@
 
 use Closure;
 use Grazulex\LaravelFlowpipe\Contracts\FlowStep;
+use Illuminate\Support\Str;
 use InvalidArgumentException;
 
 final class StepResolver
 {
     /**
-     * Resolve a step given a Closure, instance, or class name.
+     * Resolve a given step into a FlowStep instance or Closure.
      */
     public static function resolve(FlowStep|Closure|string $step): FlowStep|Closure
     {
+        // Already a usable instance
         if ($step instanceof Closure || $step instanceof FlowStep) {
             return $step;
         }
 
-        if (class_exists($step)) {
-            $instance = app($step);
+        // Try resolving by class name or configured namespace
+        if (is_string($step)) {
+            $class = class_exists($step)
+                ? $step
+                : config('flowpipe.step_namespace', 'App\\Flowpipe\\Steps').'\\'.Str::studly($step);
+
+            if (! class_exists($class)) {
+                throw new InvalidArgumentException("Step class [$class] does not exist.");
+            }
+
+            $instance = app($class);
 
             if (! $instance instanceof FlowStep) {
-                throw new InvalidArgumentException("Resolved class [$step] must implement FlowStep.");
+                throw new InvalidArgumentException("Resolved class [$class] must implement FlowStep.");
             }
 
             return $instance;
         }
 
-        throw new InvalidArgumentException('Invalid step provided: '.gettype($step));
+        throw new InvalidArgumentException('Invalid step type: '.gettype($step));
     }
 }