Gestión del estado

Aprende a pasar datos a lo largo del flujo de trabajo

En términos generales, el propósito de un flujo de trabajo es tomar un estado inicial como entrada, permitir que los nodos manipulen este estado durante la ejecución y devolver el estado final cuando el flujo de trabajo se complete.

Entrada/Salida del flujo de trabajo

El valor de retorno final del propio flujo de trabajo es una instancia del estado del flujo de trabajo. Así que, si necesitas recopilar el resultado de la ejecución del flujo de trabajo, los nodos deben poder escribir y leer del estado hasta que el flujo de trabajo termine y devolver el estado final al script padre.

También puedes proporcionar un estado inicial al flujo de trabajo para introducir valores de entrada.

// 1. Proporciona un estado inicial como entrada del flujo de trabajo para introducir algunos datos
$workflow = Workflow::make(state: new WorkflowState(['query' => '¡Hola!']))
        ->addNode(new InitialNode())
        ->addNode(...)
        ->addNode(...);

// 2. Ejecuta el flujo de trabajo y obtén el estado final
$finalState = $workflow->init()->run();

// 3. Usa los datos del estado final
echo $finalState->get('message');

Uso del estado en los nodos

En nuestros ejemplos hasta ahora, hemos pasado datos de un nodo a otro usando propiedades de eventos personalizados. Esta es una forma poderosa de pasar datos, pero tiene limitaciones. Por ejemplo, si quieres pasar datos entre pasos que no están directamente conectados, necesitas pasar los datos a través de todos los nodos intermedios. Esto puede hacer que tu código sea más difícil de leer y mantener.

Por esta razón tenemos el WorkflowState objeto disponible para cada nodo en el flujo de trabajo. Para usarlo, el flujo de trabajo inyecta la instancia de WorkflowState como segundo argumento del nodo.

namespace App\Neuron;

use NeuronAI\Workflow\Node;
use NeuronAI\Workflow\StartEvent;
use NeuronAI\Workflow\StopEvent;
use NeuronAI\Workflow\WorkflowState;

class InitialNode extends Node
{
    public function __invoke(StartEvent $event, WorkflowState $state): StopEvent
    {
        $state->set('message', '¡Hola mundo!');
        
        return new StopEvent();
    }
}

Estado personalizado

La WorkflowState class es un contenedor para transportar datos durante la ejecución del flujo de trabajo. Puede ser útil crear una clase de estado personalizada para definir propiedades fuertemente tipadas para una mejor autocompletación de código en tus nodos, validación de datos y depuración general.

Crea una CustomState class para introducir propiedades personalizadas:

use App\Models\User;
use NeuronAI\Workflow\WorkflowState;

class CustomState extends WorkflowState
{
    protected User $user;
    
    public function setUser(User $user): CustomState
    {
        $this->user = $user;
        return $this;
    }
    
    public function getUser(): User
    {
        return $this->user;
    }
}

Los nodos pueden aceptar una instancia de CustomState en lugar de la clase predeterminada WorkflowState:

class ExampleNode extends Node 
{
    public function __invoke(StartEvent $event, CustomState $state): StopEvent
    {
        // Usa las propiedades del estado en tus nodos
        if ($state->getUser()->isAdmin()) {
            //...
        }
        
        return new StopEvent();
    }
}

Inyecta el CustomState en la creación del flujo de trabajo:

$state = new CustomState();
$state->setUser($user);

$workflow = MyWorkflow::make(state: $state);

$finalState = $workflow->init()->run();
echo $finalState->getUser()->email;