Download the PHP package wazum/php-dag without Composer

php-dag

Render directed acyclic graphs (DAGs) as ASCII/Unicode art in pure PHP — pipelines, workflows, dependency trees and state machines drawn right in your terminal, CI logs, or Markdown. No image files to open, nothing to install beyond Composer. It also reads and writes Graphviz DOT, so it slots into tools that already emit that format, and it handles cycles and self-loops too.

Already have a DOT file from another tool? Render it straight to text:

Requirements

• PHP 8.2+ (tested on 8.2, 8.3, 8.4, and 8.5)
• ext-mbstring

Installation

Quick Start

Output:

Building Graphs

For simple graphs you do not need explicit Node and Edge objects. Graph::fromEdges() takes a map of titles and a list of edge pairs:

Or build it step by step with connect(). It creates any node that does not exist yet (the title defaults to the id):

The full addNode(new Node(...)) / addEdge(new Edge(...)) API is still there when you need titles, bodies, styles, labels, colors, or weights.

The graph also answers questions about its structure, so you do not have to build your own indexes:

successors() and predecessors() list each neighbour once, even with parallel edges. outgoingEdges() and incomingEdges() keep every edge. Self-loops are separate, through selfLoops().

Examples

Fan-Out

Diamond (Branch and Merge)

Border Styles

Multi-Line Content and Badges

Edge Stroke Styles

Edge Labels

Left-to-Right Flow

Path Highlighting

Make one route stand out with a different stroke style:

ANSI Colors

Color a path and render with the ANSI formatter for the terminal:

When a colored path shares cells with plain edges (a shared trunk or a crossing), the colored edge wins. The highlighted route stays unbroken from start to end.

Groups (Clusters)

Draw a labelled box around a set of nodes:

Edges that enter the group pass through the top border as ╪. Edges that cross a side border show as ╫. Nodes that are not members but land inside the group's rows are pushed out, so the border wraps members only. Groups also work in left-to-right flow. Nested groups are not supported yet.

Graphviz DOT Import and Export

Read DOT from terraform graph, Symfony's workflow:dump, or any other tool:

The parser reads the common DOT that real tools emit: strict digraph, subgraphs, clusters (imported as groups), default attributes, quoted identifiers, numeric values (negatives included), HTML-like labels (tags removed), multi-line labels (\n), and comments. Unknown attributes are ignored. strict graphs merge repeated edges; non-strict graphs keep parallel edges. Self-loops are kept and drawn. Control characters in labels are stripped, so an untrusted file cannot inject terminal escape sequences. PhpDag\Dot\DotParser::flowDirection() reports the rankdir.

It is a pragmatic subset of the DOT grammar, not a full implementation: subgraphs used as edge endpoints ({a b} -> c) and quoted-string concatenation with + are not supported.

toDot() is a Graphviz visualization export, not a full serializer. Node titles and multi-line content, edges, edge labels, edge stroke styles, and groups (including their ids and labels) round-trip through toDot()/fromDot(). Presentation and layout hints that DOT export does not carry — ANSI colors, node styles, edge weights, minLength, badges, and label positions — are dropped. Use it to hand a graph to Graphviz or another DOT tool, not as a save/load format.

Command Line

The package ships a php-dag binary. It reads a DOT file, or DOT from stdin:

The rankdir from the file is used automatically; --direction=tb|lr overrides it. Colors are auto-detected (--ansi / --no-ansi to force). --node-spacing, --rank-spacing, and --quality map to the options below. Run php-dag --help for the full list. Syntax errors go to stderr with the line and column and a non-zero exit code.

Symfony Workflow

Symfony's workflow:dump command prints a workflow as Graphviz DOT. Pipe it to php-dag to see the diagram right in the terminal, with no Graphviz install:

The dump sets rankdir="LR", so php-dag draws it left to right:

Places and transitions both become boxes. Add --ascii for plain output, or --direction=tb to force top-to-bottom.

Spacing

Set the gap between sibling boxes and between layers:

The CLI has the same options: --node-spacing=N and --rank-spacing=N.

Layout Quality

Trade layout effort for speed on large graphs:

• Standard (the default) and Quality place nodes in layers with network simplex, the method Graphviz dot uses. It keeps edges short, so the drawing is compact. Quality spends extra passes on tangled graphs.
• Fast uses simpler longest-path layering and fewer passes. Use it for very large graphs where the better layout is not worth the cost.

On the CLI: --quality=fast|standard|quality.

ASCII-Only Output

For places without Unicode support (logs, old terminals, plain-text email), render with plain ASCII characters:

Customizing the Layout Pipeline

The layout engine is a chain of processors. Take the default chain, change it, and pass it back:

insertBefore(), insertAfter(), replace(), and remove() each match the first processor of the given class and throw if none is found.

Cycles

Cycles are handled for you: back edges are reversed for layout and drawn dashed. Use $graph->isCyclic() to check first.

Reusing a Layout and Streaming Output

render() is a shortcut. For more control, layout() computes the drawing once and returns an immutable LayoutResult. You can render, measure, or stream it many times without computing again:

For large diagrams, renderTo() writes the output line by line to any writable resource, so the whole string never sits in memory at once:

renderTo() writes exactly the same bytes that render() returns.

Performance

php-dag stays fast on large graphs. It uses the same algorithms as Graphviz dot and dagre, kept close to linear time:

• Layering with network simplex (the dot method); each exchange recomputes cut values in one O(V + E) pass, and the number of exchanges is bounded.
• Cycle breaking with a greedy heuristic and incremental degree updates, O((V + E) log V).
• Crossing minimization scores each swap from the two nodes' own edges, not a full layer recount.
• Batched mutations: dummy nodes and edge changes rebuild the indexes once per phase, not per edge.
• Fan-aware rendering paints a shared trunk once, so it stays linear in the trunk length, not quadratic in the fan width.
• Compact cells store a few scalars per cell, not one object per edge.

For very large graphs, LayoutQuality::Fast trades layout effort for speed (see Layout Quality).

How It Works

The library runs the Sugiyama algorithm as a three-stage pipeline:

Stage 1: Graph (Domain Model)

The public API. Build a graph with nodes and edges:

Stage 2: Layout Engine (Sugiyama Pipeline)

Turns the graph into coordinates. Each processor changes one mutable LayoutGraph:

Left-to-right flow uses its own positioning, compaction, label, and routing processors, but the stages stay the same.

Stage 3: Renderer (Canvas-Based)

Draws the positioned nodes and edges onto a sparse 2D character buffer:

Prior Art & Inspiration

php-dag stands on established graph-drawing work:

• Graphviz dot (C) — the layered pipeline and the algorithms reimplemented here: network-simplex ranking, the weighted-median crossing heuristic, and Brandes–Köpf coordinate assignment.
• dagre (JavaScript) — a practical blueprint for network-simplex ranking outside a C codebase.
• ELK (Eclipse Layout Kernel) (Java) — the processor-pipeline architecture: layout as a chain of small, swappable phases rather than one monolith.
• Ratatui (Rust) — the styled cell-buffer model behind Canvas, where each cell carries a glyph, direction bits, and style.

Support

Bug reports, questions, and feature ideas → the issue tracker.

License

Released under the MIT License.

Made with love for the PHP community by Wolfgang Klinger.