wip

Author: lam0819

src/Actions/EmailAction.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace SolutionForest\WorkflowEngine\Actions;
+
+use SolutionForest\WorkflowEngine\Contracts\WorkflowAction;
+use SolutionForest\WorkflowEngine\Core\ActionResult;
+use SolutionForest\WorkflowEngine\Core\WorkflowContext;
+
+class EmailAction implements WorkflowAction
+{
+    public function execute(WorkflowContext $context): ActionResult
+    {
+        $template = $context->getConfig('template', 'default');
+        $to = $context->getConfig('to', '');
+        $subject = $context->getConfig('subject', '');
+        $data = $context->getConfig('data', []);
+
+        // Mock email sending - in real implementation this would send actual emails
+        $emailData = [
+            'template' => $template,
+            'to' => $to,
+            'subject' => $subject,
+            'data' => $data,
+            'sent_at' => date('Y-m-d H:i:s'),
+            'status' => 'sent',
+        ];
+
+        return ActionResult::success(['email_sent' => $emailData]);
+    }
+
+    public function canExecute(WorkflowContext $context): bool
+    {
+        return ! empty($context->getConfig('to'));
+    }
+
+    public function getName(): string
+    {
+        return 'Send Email';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Sends an email using the specified template and configuration';
+    }
+}

src/Core/WorkflowBuilder.php

@@ -167,7 +167,7 @@ public function addStep(
         string $id,
         string|WorkflowAction $action,
         array $config = [],
-        ?int $timeout = null,
+        string|int|null $timeout = null,
         int $retryAttempts = 0
     ): self {
         if (empty(trim($id))) {
@@ -178,8 +178,19 @@ public function addStep(
             throw InvalidWorkflowDefinitionException::invalidRetryAttempts($retryAttempts);
         }
 
-        if ($timeout !== null && $timeout <= 0) {
-            throw InvalidWorkflowDefinitionException::invalidTimeout($timeout);
+        // Validate timeout format if provided
+        if ($timeout !== null) {
+            if (is_string($timeout)) {
+                // Validate the string format and convert to ensure it's valid
+                $timeoutSeconds = $this->parseTimeoutString($timeout);
+                if ($timeoutSeconds <= 0) {
+                    throw InvalidWorkflowDefinitionException::invalidTimeout($timeout);
+                }
+            } else {
+                if ($timeout <= 0) {
+                    throw InvalidWorkflowDefinitionException::invalidTimeout($timeout);
+                }
+            }
         }
 
         // Check for duplicate step IDs
@@ -193,7 +204,7 @@ public function addStep(
             'id' => $id,
             'action' => is_string($action) ? $action : $action::class,
             'config' => $config,
-            'timeout' => $timeout,
+            'timeout' => $timeout, // Store original format, not converted
             'retry_attempts' => $retryAttempts,
         ];
 
@@ -217,7 +228,7 @@ public function addStep(
     public function startWith(
         string|WorkflowAction $action,
         array $config = [],
-        ?int $timeout = null,
+        string|int|null $timeout = null,
         int $retryAttempts = 0
     ): self {
         $stepId = 'step_'.(count($this->steps) + 1);
@@ -242,7 +253,7 @@ public function startWith(
     public function then(
         string|WorkflowAction $action,
         array $config = [],
-        ?int $timeout = null,
+        string|int|null $timeout = null,
         int $retryAttempts = 0
     ): self {
         $stepId = 'step_'.(count($this->steps) + 1);
@@ -459,11 +470,21 @@ public function build(): WorkflowDefinition
         // Convert builder format to Step objects
         $steps = [];
         foreach ($this->steps as $stepData) {
+            // Convert timeout to string format for Step object - keep original format if string, convert integer to string
+            $timeoutString = null;
+            if ($stepData['timeout'] !== null) {
+                if (is_string($stepData['timeout'])) {
+                    $timeoutString = $stepData['timeout']; // Keep original string format
+                } else {
+                    $timeoutString = (string) $stepData['timeout']; // Convert integer to string
+                }
+            }
+
             $steps[] = new Step(
                 id: $stepData['id'],
                 actionClass: $stepData['action'],
                 config: $stepData['config'],
-                timeout: $stepData['timeout'] ? (string) $stepData['timeout'] : null,
+                timeout: $timeoutString,
                 retryAttempts: $stepData['retry_attempts'],
                 conditions: isset($stepData['condition']) ? [$stepData['condition']] : []
             );
@@ -498,6 +519,31 @@ public static function quick(): QuickWorkflowBuilder
     {
         return new QuickWorkflowBuilder;
     }
+
+    /**
+     * Convert timeout string to seconds.
+     *
+     * @param string $timeout Timeout string like '30s', '5m', '2h', '1d'
+     * @return int Timeout in seconds
+     *
+     * @throws InvalidWorkflowDefinitionException If format is invalid
+     */
+    private function parseTimeoutString(string $timeout): int
+    {
+        if (! preg_match('/^(\d+)([smhd])$/', $timeout, $matches)) {
+            throw InvalidWorkflowDefinitionException::invalidTimeout($timeout);
+        }
+
+        $value = (int) $matches[1];
+        $unit = $matches[2];
+
+        return match ($unit) {
+            's' => $value,
+            'm' => $value * 60,
+            'h' => $value * 3600,
+            'd' => $value * 86400,
+        };
+    }
 }
 
 /**

src/Core/WorkflowContext.php

@@ -88,13 +88,30 @@ public function getStepId(): string
     }
 
     /**
-     * Get all workflow execution data.
+     * Get workflow execution data.
      *
-     * @return array<string, mixed> Complete data array
+     * When called without parameters, returns all data.
+     * When called with a key parameter, returns the specific data value (supports dot notation).
+     *
+     * @param string|null $key Data key (supports dot notation for nested access), or null for all data
+     * @param mixed $default Default value to return if key doesn't exist
+     * @return mixed Complete data array when key is null, or specific value when key is provided
+     *
+     * @example
+     * ```php
+     * $allData = $context->getData();
+     * $user = $context->getData('user');
+     * $userName = $context->getData('user.name');
+     * $email = $context->getData('user.email', 'unknown@example.com');
+     * ```
      */
-    public function getData(): array
+    public function getData(?string $key = null, mixed $default = null): mixed
     {
-        return $this->data;
+        if ($key === null) {
+            return $this->data;
+        }
+
+        return data_get($this->data, $key, $default);
     }
 
     /**

src/Exceptions/InvalidWorkflowDefinitionException.php

@@ -148,15 +148,17 @@ public static function invalidRetryAttempts(int $attempts): static
     /**
      * Create exception for invalid timeout.
      *
-     * @param int|null $timeout The invalid timeout value
+     * @param string|int|null $timeout The invalid timeout value
      */
-    public static function invalidTimeout(?int $timeout): static
+    public static function invalidTimeout(mixed $timeout): static
     {
+        $timeoutStr = $timeout === null ? 'null' : (string) $timeout;
         return new self(
-            message: "Invalid timeout: {$timeout}. Timeout must be a positive integer or null.",
+            message: "Invalid timeout: {$timeoutStr}. Timeout must be a positive integer, valid time string (e.g., '30s', '5m'), or null.",
             definition: ['provided_timeout' => $timeout],
             validationErrors: [
                 'Use a positive integer for timeout in seconds',
+                'Use a valid time string format: number followed by s/m/h/d (e.g., "30s", "5m", "2h", "1d")',
                 'Use null for no timeout limit',
                 'Consider reasonable timeouts: 30s for quick operations, 300s for complex tasks',
             ]