wip

Author: lam0819

README.md

@@ -8,6 +8,13 @@
 
 Create powerful business workflows with simple, maintainable code.
 
+> ⚠️ **WARNING: DEVELOPMENT STATUS**⚠️ 
+> 
+> This package is currently under active development and is **NOT READY FOR PRODUCTION USE**. 
+> 
+> Features may be incomplete, APIs might change, and there could be breaking changes. Use at your own risk in development environments only.
+
+
 ## ✨ Why Choose This Workflow Engine?
 
 - 🎨 **Simple & Intuitive** - Array-based workflow definitions and fluent WorkflowBuilder API

composer.json

@@ -27,7 +27,7 @@
         "illuminate/database": "^10.0||^11.0||^12.0",
         "illuminate/events": "^10.0||^11.0||^12.0",
         "illuminate/support": "^10.0||^11.0||^12.0",
-        "solution-forest/workflow-engine-core": "^0.0.1-alpha"
+        "solution-forest/workflow-engine-core": "^0.0.2-alpha"
     },
      "conflict": {
         "laravel/framework": "<11.0.0"

docs/advanced-features.md

@@ -131,10 +131,8 @@ Configure automatic retries for unreliable operations:
 
 ```php
 $workflow = WorkflowBuilder::create('robust-workflow')
-    ->step('api-call', ApiCallAction::class)
-        ->retry(attempts: 3, backoff: 'exponential')
-    ->step('database-operation', DatabaseAction::class)
-        ->retry(attempts: 5, backoff: 'linear')
+    ->addStep('api-call', ApiCallAction::class, [], null, 3) // 3 retry attempts
+    ->addStep('database-operation', DatabaseAction::class, [], null, 5) // 5 retry attempts  
     ->build();
 ```
 
@@ -147,7 +145,7 @@ $workflow = WorkflowBuilder::create('robust-workflow')
 ```php
 // Custom backoff function
 $workflow = WorkflowBuilder::create('custom-retry')
-    ->step('operation', MyAction::class)
+    ->addStep('operation', MyAction::class, [], null, 3) // Basic retry with 3 attempts
         ->retry(attempts: 3, backoff: function($attempt) {
             return $attempt * 1000; // 1s, 2s, 3s
         })

docs/api-reference.md

@@ -14,32 +14,29 @@ Creates a new workflow builder instance.
 $builder = WorkflowBuilder::create('my-workflow');
 ```
 
-#### `step(string $id, string $actionClass): self`
+#### `addStep(string $id, string $actionClass, array $config = [], ?int $timeout = null, int $retryAttempts = 0): self`
 
 Adds a custom action step to the workflow.
 
 ```php
-$builder->step('process-payment', ProcessPaymentAction::class);
+$builder->addStep('process-payment', ProcessPaymentAction::class);
+$builder->addStep('process-payment', ProcessPaymentAction::class, ['currency' => 'USD'], 30, 3);
 ```
 
-#### `email(string $template, array $options = []): self`
+#### `email(string $template, string $to, string $subject, array $data = []): self`
 
 Adds an email step to the workflow.
 
 ```php
-$builder->email('welcome-email', [
-    'to' => '{{ user.email }}',
-    'subject' => 'Welcome {{ user.name }}!',
-    'data' => ['welcome_bonus' => 100]
-]);
+$builder->email('welcome-email', '{{ user.email }}', 'Welcome {{ user.name }}!', ['welcome_bonus' => 100]);
 ```
 
-#### `http(string $method, string $url, array $data = []): self`
+#### `http(string $url, string $method = 'GET', array $data = [], array $headers = []): self`
 
 Adds an HTTP request step to the workflow.
 
 ```php
-$builder->http('POST', 'https://api.example.com/webhooks', [
+$builder->http('https://api.example.com/webhooks', 'POST', [
     'event' => 'user_registered',
     'user_id' => '{{ user.id }}'
 ]);
@@ -61,26 +58,24 @@ Adds conditional logic to the workflow.
 
 ```php
 $builder->when('user.age >= 18', function($builder) {
-    $builder->step('verify-identity', VerifyIdentityAction::class);
+    $builder->addStep('verify-identity', VerifyIdentityAction::class);
 });
 ```
 
-#### `retry(int $attempts, string $backoff = 'linear'): self`
+#### `startWith(string $actionClass, array $config = [], ?int $timeout = null, int $retryAttempts = 0): self`
 
-Configures retry behavior for the previous step.
+Adds the first step in a workflow (syntactic sugar for better readability).
 
 ```php
-$builder->step('api-call', ApiCallAction::class)
-    ->retry(attempts: 3, backoff: 'exponential');
+$builder->startWith(ValidateInputAction::class, ['strict' => true]);
 ```
 
-#### `timeout(int $seconds = null, int $minutes = null, int $hours = null): self`
+#### `then(string $actionClass, array $config = [], ?int $timeout = null, int $retryAttempts = 0): self`
 
-Sets a timeout for the previous step.
+Adds a sequential step (syntactic sugar for better readability).
 
 ```php
-$builder->step('long-operation', LongOperationAction::class)
-    ->timeout(minutes: 5);
+$builder->then(ProcessDataAction::class)->then(SaveResultAction::class);
 ```
 
 #### `build(): WorkflowDefinition`

docs/getting-started.md

@@ -53,10 +53,10 @@ use App\Actions\CreateUserProfileAction;
 
 // Create the workflow
 $registrationWorkflow = WorkflowBuilder::create('user-registration')
-    ->step('create-profile', CreateUserProfileAction::class)
-    ->email('welcome-email', to: '{{ user.email }}', subject: 'Welcome!')
+    ->addStep('create-profile', CreateUserProfileAction::class)
+    ->email('welcome-email', '{{ user.email }}', 'Welcome!')
     ->delay(hours: 24)
-    ->email('tips-email', to: '{{ user.email }}', subject: 'Getting Started Tips')
+    ->email('tips-email', '{{ user.email }}', 'Getting Started Tips')
     ->build();
 
 // Start the workflow
@@ -155,9 +155,7 @@ The workflow engine automatically handles errors and provides retry mechanisms:
 
 ```php
 $workflow = WorkflowBuilder::create('robust-workflow')
-    ->step('risky-operation', RiskyAction::class)
-        ->retry(attempts: 3, backoff: 'exponential')
-        ->timeout(seconds: 30)
+    ->addStep('risky-operation', RiskyAction::class, [], 30, 3) // timeout: 30s, retry: 3 attempts
     ->build();
 ```
 

tests/Support/TestActions/CreateUserProfileAction.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace SolutionForest\WorkflowEngine\Laravel\Tests\Support\TestActions;
+
+use SolutionForest\WorkflowEngine\Attributes\Retry;
+use SolutionForest\WorkflowEngine\Attributes\Timeout;
+use SolutionForest\WorkflowEngine\Attributes\WorkflowStep;
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+use SolutionForest\WorkflowEngine\Core\ActionResult;
+use SolutionForest\WorkflowEngine\Core\WorkflowContext;
+
+#[WorkflowStep(
+    id: 'create_profile',
+    name: 'Create User Profile',
+    description: 'Creates a new user profile in the database'
+)]
+#[Timeout(seconds: 30)]
+#[Retry(attempts: 3, backoff: 'exponential')]
+class CreateUserProfileAction implements WorkflowAction
+{
+    public function execute(WorkflowContext $context): ActionResult
+    {
+        $userData = $context->getData('user') ?? [];
+
+        // Mock user profile creation
+        $profile = [
+            'id' => rand(1000, 9999),
+            'user_id' => $userData['id'] ?? null,
+            'name' => $userData['name'] ?? 'Unknown',
+            'email' => $userData['email'] ?? 'unknown@example.com',
+            'created_at' => date('Y-m-d H:i:s'),
+        ];
+
+        return ActionResult::success([
+            'profile_id' => $profile['id'],
+            'profile' => $profile,
+        ]);
+    }
+
+    public function canExecute(WorkflowContext $context): bool
+    {
+        return true; // Always executable for testing
+    }
+
+    public function getName(): string
+    {
+        return 'Create User Profile';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Creates a new user profile in the database';
+    }
+}

tests/Support/TestActions/RiskyAction.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace SolutionForest\WorkflowEngine\Laravel\Tests\Support\TestActions;
+
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+use SolutionForest\WorkflowEngine\Core\ActionResult;
+use SolutionForest\WorkflowEngine\Core\WorkflowContext;
+
+class RiskyAction implements WorkflowAction
+{
+    public function execute(WorkflowContext $context): ActionResult
+    {
+        $config = $context->getConfig();
+        $failureRate = $config['failure_rate'] ?? 0.3; // 30% chance of failure by default
+
+        // Simulate risky operation that sometimes fails
+        if (rand(1, 100) <= ($failureRate * 100)) {
+            throw new \Exception('Simulated failure in risky operation');
+        }
+
+        return ActionResult::success([
+            'operation_id' => 'risky_'.uniqid(),
+            'success' => true,
+            'executed_at' => date('Y-m-d H:i:s'),
+        ]);
+    }
+
+    public function canExecute(WorkflowContext $context): bool
+    {
+        return true; // Always executable for testing
+    }
+
+    public function getName(): string
+    {
+        return 'Risky Operation';
+    }
+
+    public function getDescription(): string
+    {
+        return 'A simulated risky operation that sometimes fails for testing retry logic';
+    }
+}

tests/Support/TestActions/SendWelcomeEmailAction.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace SolutionForest\WorkflowEngine\Laravel\Tests\Support\TestActions;
+
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+use SolutionForest\WorkflowEngine\Core\ActionResult;
+use SolutionForest\WorkflowEngine\Core\WorkflowContext;
+
+class SendWelcomeEmailAction implements WorkflowAction
+{
+    public function execute(WorkflowContext $context): ActionResult
+    {
+        $config = $context->getConfig();
+        $userData = $context->getData('user') ?? [];
+
+        // Mock email sending
+        $emailData = [
+            'id' => 'email_'.uniqid(),
+            'to' => $userData['email'] ?? 'unknown@example.com',
+            'subject' => $config['subject'] ?? 'Welcome!',
+            'template' => $config['template'] ?? 'welcome',
+            'sent_at' => date('Y-m-d H:i:s'),
+        ];
+
+        return ActionResult::success([
+            'email_id' => $emailData['id'],
+            'email_sent' => true,
+            'email_data' => $emailData,
+        ]);
+    }
+
+    public function canExecute(WorkflowContext $context): bool
+    {
+        $userData = $context->getData('user') ?? [];
+
+        return ! empty($userData['email']);
+    }
+
+    public function getName(): string
+    {
+        return 'Send Welcome Email';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Sends a welcome email to the user';
+    }
+}

tests/Support/TestActions/VerifyIdentityAction.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace SolutionForest\WorkflowEngine\Laravel\Tests\Support\TestActions;
+
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+use SolutionForest\WorkflowEngine\Core\ActionResult;
+use SolutionForest\WorkflowEngine\Core\WorkflowContext;
+
+class VerifyIdentityAction implements WorkflowAction
+{
+    public function execute(WorkflowContext $context): ActionResult
+    {
+        $userData = $context->getData('user') ?? [];
+
+        // Mock identity verification
+        $verificationResult = [
+            'verification_id' => 'verify_'.uniqid(),
+            'user_id' => $userData['id'] ?? null,
+            'status' => 'verified',
+            'verified_at' => date('Y-m-d H:i:s'),
+        ];
+
+        return ActionResult::success([
+            'verification' => $verificationResult,
+            'identity_verified' => true,
+        ]);
+    }
+
+    public function canExecute(WorkflowContext $context): bool
+    {
+        $userData = $context->getData('user') ?? [];
+
+        return isset($userData['id']) && ($userData['age'] ?? 0) >= 18;
+    }
+
+    public function getName(): string
+    {
+        return 'Verify Identity';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Verifies user identity for users 18 years and older';
+    }
+}