README

Symfony Console commands and formatters for inspecting, validating, and debugging workflow definitions and runs.

Features

• List available workflow definitions from a repository.
• Display workflow details in human-readable text or JSON.
• Inspect workflow inputs, outputs, steps, branches, and step configuration.
• Render workflow graphs as colored two-dimensional text flowcharts, Mermaid, or JSON.
• Render workflow run summaries for CLI diagnostics.
• Extend step registration through a dedicated initializer contract.

Installation

composer require adachsoft/workflow-symfony-cli

Integration

Register AdachSoft\WorkflowSymfonyCli\Command\WorkflowListCommand in the Symfony Console application and provide its constructor dependencies through your service container:

• AdachSoft\Workflow\Contracts\WorkflowDefinitionRepositoryInterface
• AdachSoft\Workflow\Contracts\StepRegistryInterface
• AdachSoft\Workflow\Registry\StepDefinitionResolver (from adachsoft/workflow ^6.0)
• AdachSoft\WorkflowSymfonyCli\Formatter\WorkflowDetailTextFormatter
• AdachSoft\WorkflowSymfonyCli\Formatter\WorkflowDetailJsonFormatter

The command is exposed as workflow:list.

The workflow detail view includes the declared workflow output schema. Text output uses the WORKFLOW OUTPUT SCHEMA section and displays [not declared] when no schema is declared. JSON output includes workflow_output_schema, with null representing an undeclared schema. Branch schemas are resolved from static step configuration; for run_workflow, the on_next schema reflects the child workflow's output_schema when config.workflow_id identifies the child statically. A child selected through config_map cannot be resolved this way. Ensure StepDefinitionResolver is available in the application service container.

Register AdachSoft\WorkflowSymfonyCli\Command\WorkflowGraphCommand as well. It is exposed as workflow:graph and requires the following services:

• AdachSoft\Workflow\Contracts\WorkflowDefinitionRepositoryInterface
• AdachSoft\Workflow\Contracts\StepRegistryInterface
• AdachSoft\WorkflowSymfonyCli\Resolver\WorkflowGraphResolver
• AdachSoft\WorkflowSymfonyCli\Formatter\WorkflowGraphTextFormatter
• AdachSoft\WorkflowSymfonyCli\Formatter\WorkflowGraphMermaidFormatter
• AdachSoft\WorkflowSymfonyCli\Formatter\WorkflowGraphJsonFormatter

An AdachSoft\WorkflowSymfonyCli\Contract\StepRegistryInitializerInterface service is optional.

Usage

# List available workflows in text format.
php bin/console workflow:list

# List available workflows as JSON.
php bin/console workflow:list --format=json

# Display one workflow in text format.
php bin/console workflow:list --workflow-id=example

# Display one workflow as JSON.
php bin/console workflow:list --workflow-id=example --format=json

# Render a workflow graph as text (the default format).
php bin/console workflow:graph example

# Render a workflow graph as Mermaid.
php bin/console workflow:graph example --format=mermaid

# Render a workflow graph as JSON.
php bin/console workflow:graph example --format=json

The default text graph renders boxed steps, with green normal paths, red error paths, and yellow retry paths. Successful and failed terminal outcomes are marked with check and cross icons.

workflow:list returns a non-zero exit status when an unsupported output format is selected or the requested workflow cannot be loaded. workflow:graph returns a non-zero exit status when the format is unsupported or its workflow cannot be loaded.

Workflow debug logging

workflow:debug streams each message emitted by a step through StepContextDto::$logger?->log() as soon as the step writes it. The output includes the source workflow, run, and step identifiers together with the message and JSON-encoded data:

[workflow=<workflow_id> run=<run_id> step=<step_name>] <message> data=<JSON>

Messages are shown at normal verbosity and suppressed in quiet mode. The command does not keep an automatic log history, and steps that do not call the logger contract produce no log messages. A message emitted before a step throws remains visible before the command displays the error.

Data is formatted for readable console output: list order and associative keys are preserved; objects (including JsonSerializable objects) are represented as [object <type>] without calling their serializers, resources as [resource], non-finite floats as [non-finite float], and arrays beyond the supported nesting depth as [depth limit]. If JSON encoding still fails, the data is shown as [unserializable]. Logs may contain sensitive data, so steps should only emit values that are safe to display in the console.

Custom step logger in workflow:debug

WorkflowDebugCommand requires a StepLoggerFactoryInterface service to create the logger for each command execution. The default implementation is ConsoleStepLoggerFactory, which preserves the current output format:

[workflow=<workflow_id> run=<run_id> step=<step_name>] <message> data=<JSON>

An application can provide its own StepLoggerFactoryInterface implementation to customize formatting, for example by adding colors or icons based on $output->isDecorated(). workflow:run does not pass a step logger to the workflow engine; step logging remains available only through workflow:debug.

Register the default factory in Symfony DI with:

AdachSoft\WorkflowSymfonyCli\Contract\StepLoggerFactoryInterface: '@AdachSoft\WorkflowSymfonyCli\Logging\ConsoleStepLoggerFactory'
AdachSoft\WorkflowSymfonyCli\Logging\ConsoleStepLoggerFactory: ~

Migration to 0.6.0

WorkflowDebugCommand now requires a fifth constructor argument implementing StepLoggerFactoryInterface. Use ConsoleStepLoggerFactory to retain the default log format, or provide an application-specific factory.

Extending step registration

Implement AdachSoft\WorkflowSymfonyCli\Contract\StepRegistryInitializerInterface when the application needs to register workflow steps before CLI commands access the workflow registry.

use AdachSoft\Workflow\Contracts\StepRegistryInterface;
use AdachSoft\WorkflowSymfonyCli\Contract\StepRegistryInitializerInterface;

final class ApplicationStepRegistryInitializer implements StepRegistryInitializerInterface
{
    public function initialize(StepRegistryInterface $stepRegistry): void
    {
        // Register application-specific workflow steps here.
    }
}

Documentation examples

• CLI usage
• Symfony Console registration

License

This library is released under the MIT license.