wip

Author: lam0819

README.md

@@ -10,7 +10,8 @@ Create powerful business workflows with simple, maintainable code.
 
 ## ✨ Why Choose This Workflow Engine?
 
-- 🎨 **Simple & Intuitive** - Array-based workflow definitions that are easy to understand
+- 🎨 **Simple & Intuitive** - Array-based workflow definitions and fluent WorkflowBuilder API
+- 🏷️ **Modern PHP 8.3+ Attributes** - Declarative configuration with #[WorkflowStep], #[Retry], #[Timeout] 
 - 🔒 **Type Safety First** - Built with enums, strong typing, and modern PHP features
 - ⚡ **Laravel Native** - Seamless integration with Laravel's ecosystem and helpers
 - 🧩 **Extensible** - Easy to extend with custom actions and storage adapters
@@ -279,6 +280,77 @@ $definition = [
 
 ## 🔧 Core Features
 
+### Modern PHP 8.3+ Attributes
+
+Enhance your workflow actions with declarative attributes for configuration:
+
+```php
+<?php
+
+namespace App\Actions;
+
+use SolutionForest\WorkflowEngine\Attributes\WorkflowStep;
+use SolutionForest\WorkflowEngine\Attributes\Timeout;
+use SolutionForest\WorkflowEngine\Attributes\Retry;
+use SolutionForest\WorkflowEngine\Attributes\Condition;
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+use SolutionForest\WorkflowEngine\Core\ActionResult;
+use SolutionForest\WorkflowEngine\Core\WorkflowContext;
+
+#[WorkflowStep(
+    id: 'send_email',
+    name: 'Send Welcome Email',
+    description: 'Sends a welcome email to new users'
+)]
+#[Timeout(minutes: 5)]
+#[Retry(attempts: 3, backoff: 'exponential')]
+#[Condition('user.email is not null')]
+class SendWelcomeEmailAction implements WorkflowAction
+{
+    public function execute(WorkflowContext $context): ActionResult
+    {
+        $user = $context->getData('user');
+        
+        // Send email logic here
+        Mail::to($user['email'])->send(new WelcomeEmail($user));
+        
+        return ActionResult::success(['email_sent' => true]);
+    }
+}
+```
+
+#### Available Attributes:
+
+- **`#[WorkflowStep]`** - Define step metadata (id, name, description, config)
+- **`#[Timeout]`** - Set execution timeouts (seconds, minutes, hours)  
+- **`#[Retry]`** - Configure retry behavior (attempts, backoff strategy, delays)
+- **`#[Condition]`** - Add conditional execution rules
+
+### WorkflowBuilder Fluent API
+
+Create workflows with an intuitive, chainable API:
+
+```php
+use SolutionForest\WorkflowEngine\Core\WorkflowBuilder;
+
+$workflow = WorkflowBuilder::create('user-onboarding')
+    ->description('Complete user onboarding process')
+    ->addStep('welcome', SendWelcomeEmailAction::class)
+    ->addStep('setup', SetupUserAction::class, ['template' => 'premium'])
+    ->when('user.plan === "premium"', function($builder) {
+        $builder->addStep('premium-setup', PremiumSetupAction::class);
+    })
+    ->email('tips-email', '{{ user.email }}', 'Getting Started Tips')
+    ->delay(hours: 24)
+    ->addStep('complete', CompleteOnboardingAction::class)
+    ->build();
+
+// Start the workflow
+$workflowId = $workflow->start('user-001', [
+    'user' => ['email' => 'john@example.com', 'plan' => 'premium']
+]);
+```
+
 ### Modern PHP 8.3+ Enums
 
 ```php

docs/advanced-features.md

@@ -1,5 +1,128 @@
 # Advanced Features
 
+## PHP 8.3+ Attributes
+
+Use declarative attributes to configure your workflow actions:
+
+### WorkflowStep Attribute
+
+Define step metadata directly on your action classes:
+
+```php
+<?php
+
+namespace App\Actions;
+
+use SolutionForest\WorkflowEngine\Attributes\WorkflowStep;
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+
+#[WorkflowStep(
+    id: 'send_email',
+    name: 'Send Welcome Email',
+    description: 'Sends a welcome email to new users',
+    config: ['template' => 'welcome', 'async' => true],
+    required: true,
+    order: 1
+)]
+class SendWelcomeEmailAction implements WorkflowAction
+{
+    // Action implementation...
+}
+```
+
+### Timeout Attribute
+
+Set execution timeouts for your actions:
+
+```php
+use SolutionForest\WorkflowEngine\Attributes\Timeout;
+
+// Single time unit
+#[Timeout(seconds: 30)]
+#[Timeout(minutes: 5)]
+#[Timeout(hours: 1)]
+
+// Combined time units
+#[Timeout(minutes: 5, seconds: 30)] // 5 minutes 30 seconds
+class LongRunningAction implements WorkflowAction
+{
+    // Action will timeout after specified duration
+}
+```
+
+### Retry Attribute
+
+Configure automatic retry behavior:
+
+```php
+use SolutionForest\WorkflowEngine\Attributes\Retry;
+
+// Basic retry configuration
+#[Retry(attempts: 3)]
+
+// With backoff strategy
+#[Retry(attempts: 5, backoff: 'exponential')]
+#[Retry(attempts: 3, backoff: 'linear', delay: 1000)]
+
+// Maximum delay cap
+#[Retry(attempts: 5, backoff: 'exponential', delay: 1000, maxDelay: 30000)]
+class UnreliableApiAction implements WorkflowAction
+{
+    // Will automatically retry on failure
+}
+```
+
+Available backoff strategies:
+- `linear` - Fixed delay between retries
+- `exponential` - Exponentially increasing delay  
+- `fixed` - Same delay for all retries
+
+### Condition Attribute
+
+Add conditional execution rules:
+
+```php
+use SolutionForest\WorkflowEngine\Attributes\Condition;
+
+// Single condition
+#[Condition('user.email is not null')]
+
+// Multiple conditions (repeatable attribute)
+#[Condition('user.email is not null')]
+#[Condition('order.amount > 100')]
+#[Condition('user.premium = true', operator: 'or')]
+class ConditionalAction implements WorkflowAction
+{
+    // Only executes if conditions are met
+}
+```
+
+Condition expressions support:
+- Property access: `user.email`, `order.amount`
+- Comparisons: `>`, `<`, `>=`, `<=`, `=`, `!=`
+- Null checks: `is null`, `is not null`
+- Operators: `and`, `or`
+
+### Combining Attributes
+
+You can use multiple attributes together:
+
+```php
+#[WorkflowStep(
+    id: 'process_payment',
+    name: 'Process Payment',
+    description: 'Processes customer payment'
+)]
+#[Timeout(minutes: 2)]
+#[Retry(attempts: 3, backoff: 'exponential')]
+#[Condition('order.amount > 0')]
+#[Condition('payment.method is not null')]
+class ProcessPaymentAction implements WorkflowAction
+{
+    // Robust payment processing with timeout, retries, and conditions
+}
+```
+
 ## Error Handling and Retries
 
 ### Automatic Retries

docs/getting-started.md

@@ -99,6 +99,41 @@ class CreateUserProfileAction implements WorkflowAction
 }
 ```
 
+### Enhanced Actions with Attributes
+
+Use PHP 8.3+ attributes to add configuration directly to your action classes:
+
+```php
+<?php
+
+namespace App\Actions;
+
+use SolutionForest\WorkflowEngine\Attributes\WorkflowStep;
+use SolutionForest\WorkflowEngine\Attributes\Timeout;
+use SolutionForest\WorkflowEngine\Attributes\Retry;
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+use SolutionForest\WorkflowEngine\Core\WorkflowContext;
+use SolutionForest\WorkflowEngine\Core\ActionResult;
+
+#[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
+    {
+        // Same implementation as above
+        // Now with automatic timeout and retry handling
+    }
+}
+```
+
+See the [Advanced Features](advanced-features.md) guide for more details on attributes.
+
 ## Workflow States
 
 Workflows have built-in states that you can monitor: