Download the PHP package sofyco/workflow without Composer

Sofyco Workflow

A PHP library for building artifact-based workflow graphs — not linear prompt chains, but directed graphs where nodes consume and produce typed files.

Use it to orchestrate multimodal pipelines: LLM prompts, text-to-speech, image generation, video rendering, conditional branches, parallel fan-out/fan-in, and chained workflows.

Features

• Graph execution engine — schedules all ready nodes in parallel, supports fan-in and fan-out
• Artifact-first model — text, JSON, images, audio, and video are stored as files with MIME types
• Immutable execution history — every node attempt creates a new NodeExecution; results are never overwritten
• Typed ports — connect nodes through named input/output ports with artifact type and MIME validation
• Safe conditions — edge conditions use a small DSL, not arbitrary code
• Pluggable providers — swap LLM, TTS, image, and video backends via interfaces
• Framework-friendly — pure PHP core with optional Symfony Messenger integration
• PHP 8.5+ — enums, readonly classes, strict types throughout

Requirements

• PHP ^8.5

No framework is required. Symfony Messenger and Doctrine adapters are provided as integration stubs.

Installation

Core concepts

Workflow graph

A workflow is a directed graph made of:

Artifacts

An artifact is always a physical file (or a reference to one in object storage). Format is determined by mimeType, not by a separate “text vs JSON” type.

Examples:

Rules:

1. Nodes never return raw strings — they create artifacts.
2. Artifacts are immutable once written.
3. Retries create new NodeExecution records with a new attempt number.
4. MongoDB (or any DB) stores metadata only; file content lives in object storage.

Node readiness

A node runs when:

1. It is reachable from the start node.
2. All required input ports have compatible artifacts.
3. Incoming edge conditions are satisfied.
4. It is not already running or completed.
5. Retry limits have not been exceeded.

After one node finishes, the scheduler finds all ready nodes — not just the next one — enabling natural parallelism.

Architecture

Runtime services

Node runners

Register runners in NodeRunnerRegistry:

Quick start

The example below runs a workflow synchronously using in-memory repositories and local file storage. See tests/Support/WorkflowTestHarness.php for a complete wiring reference.

Input artifact format

When starting a run, pass input artifacts as an associative array:

Idempotency

Each node execution uses a unique key:

If Messenger redelivers a message, an already-completed execution is returned without re-running.

Building a workflow graph

Prompt templates

PromptRenderer replaces {{ dotted.path }} placeholders using the runtime context:

Template example:

Edge conditions

Conditions use a safe DSL — no user PHP:

Supported operators: equals, not_equals, greater_than, less_than, contains, exists.

Extending the library

LLM gateway

Used by PromptNodeRunner to generate text or JSON artifacts.

TTS gateway

Register providers in TtsGatewayRegistry. Example node settings for ElevenLabs:

Image generator

ImageGenerationNodeRunner can read a text prompt or extract a field from a JSON artifact:

Video renderer

VideoRenderNodeRunner expects audio and subtitles input ports and produces a video/mp4 artifact.

Artifact storage

LocalArtifactStorage is included for development. Implement S3ArtifactStorage for production object storage.

Recommended storage paths:

Async execution (Symfony Messenger)

For production, dispatch one message per node instead of calling process() synchronously:

The handler runs the node and calls WorkflowScheduler::scheduleReadyNodes() again.

Example workflows

The test suite includes three end-to-end workflow examples:

1. Video content production

Fixture: tests/Fixtures/VideoContentWorkflowFixture.php
Test: tests/Integration/VideoContentWorkflowTest.php

2. Website posts parsing

Fixture: tests/Fixtures/WebsitePostsParsingWorkflowFixture.php
Test: tests/Integration/WebsitePostsParsingWorkflowTest.php

3. Blog post generation (chained workflow)

Takes a post from the parsing workflow and generates a full site post in parallel:

Fixture: tests/Fixtures/BlogPostGenerationWorkflowFixture.php
Test: tests/Integration/BlogPostGenerationWorkflowTest.php

The blog post test demonstrates workflow chaining: it runs the parsing workflow first, extracts the first post artifact, and feeds it into the generation workflow.

Symfony integration (optional)

The library ships stubs for Symfony Messenger and Doctrine repositories:

Wire these in your Symfony app via service configuration. The core engine has no Symfony dependency. HTTP endpoints for a workflow builder UI belong in your application layer, not in this library.

Development

Clone the repository and run tests with Docker:

Or without Docker:

Project structure (tests)

Design principles

1. Nodes produce artifacts, not strings.
2. Text and JSON are File artifacts with the appropriate MIME type.
3. WorkflowVersion is immutable — runs always execute against the version they started with.
4. Parallelism is native — the scheduler runs every ready node, not just one.
5. Retries are new attempts — history is preserved for auditing and debugging.
6. Conditions are safe — limited DSL, no eval or user code.
7. Loops must be bounded — configure maxTotalNodeExecutions and maxAttemptsPerNode on the workflow version.

Roadmap

• [ ] WorkflowService — create, edit, and publish workflow drafts
• [ ] WorkflowValidator — graph validation before publish
• [ ] Doctrine MongoDB repository implementations
• [ ] S3 / object storage adapter
• [ ] Condition, validator, transform, and merge node runners
• [ ] Human review and webhook nodes
• [ ] Sub-workflows

License

This package is open-source software licensed under the MIT license.

Author

Sofiia Korzhova — [email protected]