Michael/breznflow
1
1
Fork 0
Code Issues Pull requests Projects Releases 5 Packages Wiki Activity Actions
breznflow/README.de.md
Michael 1b3de37a54 docs: bump version badge to 1.0.3 in READMEs 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-17 13:34:44 +00:00

16 KiB
Raw Blame History

BreznFlow

PHP 8.0+ WordPress 6.0+ License: GPL-2.0 Version

🇬🇧 English version → README.md

BreznFlow ist ein WordPress-Plugin, das n8n-Automations-Workflows als interaktive SVG-Diagramme rendert — direkt in Beiträgen und Seiten. Workflow-JSON einfügen, und das Plugin erzeugt ein zoombares, klickbares Diagramm mit Node-Detail-Panel, automatischer Maskierung sensibler Daten und farbcodierten Node-Icons.

Keine externen Abhängigkeiten. Kein CDN. Kein Tracking. Vanilla JavaScript. Ein Shortcode: [breznflow id="X"].

Warum dieses Plugin existiert

n8n-Workflows sind mächtig, aber visuell teilen ist überraschend schwierig. Screenshots sind statisch und veralten schnell. Den n8n-Editor einzubetten ist unpraktisch. JSON in einen Blogpost kopieren ist unlesbar.

BreznFlow löst das, indem es den rohen JSON-Export in ein interaktives Diagramm verwandelt — die gleichen Nodes, die gleichen Verbindungen, aber als sauberes SVG innerhalb von WordPress gerendert. Leser können zoomen, pannen und jeden Node anklicken, um seine Parameter zu sehen.

Entwickelt in Passau, Bayern — für mifupa.com, einem persönlichen Blog, auf dem regelmäßig n8n-Automationen vorgestellt werden und eine bessere Darstellung brauchten.

Inhaltsverzeichnis

Verzeichnisstruktur

breznflow/
├── breznflow.php                 # Plugin-Header, Konstanten (BREZNFLOW_VERSION, BREZNFLOW_DIR, BREZNFLOW_URL)
├── uninstall.php                 # Aufräumen bei Plugin-Löschung
├── readme.txt                    # WordPress.org Plugin-Readme
├── assets/
│   ├── admin.css                 # Admin-Stylesheet (Wizard, Settings, Listtable)
│   ├── admin.js                  # Admin-JavaScript (Wizard-Schritte, JSON-Validierung)
│   ├── renderer.css              # Frontend SVG-Renderer Styles
│   ├── renderer.js               # Frontend-Renderer (SVG-Engine, Pan/Zoom, Detail-Panel)
│   ├── brezn.css                 # Legacy Brezn-Theme (Kompatibilität)
│   └── themes/
│       ├── dark.css              # Dark-Theme (Standard)
│       ├── light.css             # Light-Theme
│       ├── minimal.css           # Minimal-Theme
│       ├── tech.css              # Tech-Theme
│       └── brezn.css             # Brezn-Theme
├── includes/
│   ├── Core.php                  # Singleton-Bootstrap, lädt alle Abhängigkeiten
│   ├── PostType.php              # CPT breznflow_workflow + Taxonomie breznflow_category
│   ├── Shortcode.php             # [breznflow] Shortcode mit 13 Attributen
│   ├── DownloadHandler.php       # JSON-Download-Endpunkt (?breznflow_download={id})
│   ├── EmbedHandler.php          # Standalone Embed-Seite (?breznflow_embed={id})
│   ├── Admin/
│   │   ├── AdminMenu.php         # Menüstruktur + Dashboard-Render
│   │   ├── SettingsPage.php      # Plugin-Einstellungen (16 Optionen, validiert)
│   │   ├── ThemesPage.php        # Theme-Verwaltung (Import/Löschen eigener Themes)
│   │   ├── WizardPage.php        # 3-Schritt Import-Wizard (Einfügen/Upload → Konfigurieren → Vorschau)
│   │   ├── WorkflowListTable.php # WP_List_Table für Workflow-Verwaltung
│   │   └── views/                # PHP-Templates für alle Admin-Seiten
│   ├── Features/
│   │   ├── NodeTypeRegistry.php  # 86 Node-Typen mit Markenfarben und Icons
│   │   ├── NodeCategorizer.php   # Kategorisiert Nodes (Trigger, Action, Logic, AI, etc.)
│   │   ├── InfoBoxBuilder.php    # „3× HTTP Request, 2× Code" Node-Zusammenfassung
│   │   ├── ViewCounter.php       # View-Zähler pro Workflow
│   │   ├── RelatedWorkflows.php  # Ähnliche Workflows nach gemeinsamen Node-Typen
│   │   ├── ThemeRegistry.php     # 5 Built-in-Themes + Custom-Theme-Support
│   │   └── ThemeImporter.php     # Import/Export von .breznflow.json Theme-Dateien
│   └── Security/
│       ├── MaskingRules.php      # Secret-Erkennung (URL-Parameter, Header, Entropie)
│       ├── WorkflowValidator.php # JSON-Schema-Validierung für n8n-Exporte
│       └── WorkflowSanitizer.php # Zwei-Pass-Sanitierung: Strings + Secret-Maskierung
└── languages/
    ├── breznflow.pot             # Übersetzungsvorlage
    ├── breznflow-de_DE.po        # Deutsche Übersetzung
    └── breznflow-de_DE.mo        # Kompilierte deutsche Übersetzung

Features

Interaktiver SVG-Renderer

Das Herzstück von BreznFlow. Jeder n8n-Node wird zu einem klickbaren SVG-Element mit farbcodierten Icons, Verbindungslinien und Labels. Der Renderer unterstützt:

  • Pan & Zoom — Mausrad zoomt zur Cursorposition, Klick-Drag zum Verschieben
  • Node-Klick — öffnet das Detail-Panel unterhalb des Diagramms mit allen Node-Parametern
  • Auto-Fit — Workflows über einem konfigurierbaren Node-Schwellenwert (Standard: 30) zoomen automatisch zum Trigger-Node beim Laden
  • Minimap — optionales Minimap-Overlay zur Navigation in großen Workflows
  • Vollbild — Portal-basierter Vollbildmodus

Alles wird clientseitig in Vanilla JavaScript gerendert — kein Canvas, kein WebGL, keine externen Bibliotheken.

3-Schritt Import-Wizard

  1. Einfügen oder hochladen — JSON direkt einfügen, .json-Datei hochladen oder von URL abrufen
  2. Konfigurieren — Darstellungsmodus, Theme, Zoom, Titel, Kategorien einstellen
  3. Vorschau — Live-SVG-Vorschau mit Maskierungs-Zusammenfassung vor dem Veröffentlichen

Der Wizard validiert JSON gegen das n8n-Schema, sanitiert alle Strings und maskiert erkannte Geheimnisse. Das Maskierungs-Protokoll zeigt genau, was entfernt wurde und warum.

Import von URL: Ruft Workflow-JSON von beliebigen öffentlichen URLs per wp_remote_get() ab. Anfragen an private/interne Netzwerkadressen (localhost, LAN-Bereiche, Cloud-Metadaten-Endpunkte) werden blockiert.

Node Type Registry

86 vordefinierte Node-Typen mit markengetreuen Farben und 2-Buchstaben-Icons:

Kategorie Beispiele
Trigger Schedule, Webhook, Manual, Form
Kernlogik HTTP Request, Code, IF, Switch, Merge, Filter
Datentransformation HTML, XML, Markdown, Crypto
Datenbanken MySQL, PostgreSQL, Redis, MongoDB, SQLite, Supabase
Kommunikation Slack, Telegram, Discord, Gmail, WhatsApp
Google Sheets, Drive, Calendar, Docs, YouTube
Dev-Tools GitHub, GitLab, Jira, Confluence, Linear, Notion
KI OpenAI, Claude, Gemini, Ollama, Hugging Face, Mistral, LangChain
Speicher FTP, SSH, Airtable, Baserow
CRM/Marketing HubSpot, Salesforce, Mailchimp, Brevo

Unbekannte Node-Typen bekommen einen deterministischen Fallback: 2-Buchstaben-Initialen und eine Farbe aus einem djb2-Hash — der gleiche unbekannte Typ sieht immer gleich aus.

Theme-System

5 Built-in-Themes: Dark (Standard), Light, Minimal, Tech, Brezn.

Eigene Themes können als .breznflow.json-Dateien mit 41 CSS-Farbtokens importiert werden. Custom-Themes werden in wp_options gespeichert und als Inline-CSS-Variablen gerendert.

Themes sind global, pro Workflow oder pro Shortcode wählbar via theme="dark".

Action Bar

Unterhalb des Diagramms (nicht im Compact-Modus) bietet die Action Bar:

Aktion Steuerung Funktion
Share Globale Einstellung Zeigt Artikel-Link + Anker-Link für Hash-Navigation
Embed Global + pro Post Zeigt iframe-Embed-Code für Standalone-Einbettung
Get JSON Globale Einstellung Zeigt formatiertes JSON mit Größe in KB
Download Global + pro Post Lädt sanitiertes JSON als Datei herunter

Jede Aktion ist global in den Einstellungen steuerbar und per Shortcode überschreibbar.

Maskierung sensibler Daten

BreznFlow speichert nie das rohe Workflow-JSON. Vor dem Speichern läuft eine Zwei-Pass-Sanitierung:

Pass 1 — String-Sanitierung: Alle Strings durchlaufen sanitize_text_field(). Ausnahme: jsCode-Felder bleiben erhalten, werden aber mit esc_html() ausgegeben (nie ausgeführt).

Pass 2 — Secret-Erkennung:

  • URL-Parameter: api_key, token, secret, password, access_token, auth, client_secret in Query-Strings → [REDACTED]
  • Header-Werte: Authorization, Bearer, X-API-Key und ähnliche Header-Namen in {name, value}-Paaren → Wert maskiert
  • Hochentropie-Bedingungen: Werte in IF/Switch-Conditions, die UUID-Muster, Groß-/Kleinschreibung+Ziffern oder lange Strings ohne Leerzeichen matchen → per Entropie-Heuristik maskiert

Ein Maskierungs-Protokoll zeichnet jedes maskierte Element mit Grund, Key und Hinweis auf — sichtbar in der Wizard-Vorschau (Schritt 3).

Darstellungsmodi

Modus Was angezeigt wird
visual Vollständiges Diagramm mit Toolbar, Detail-Panel, Action Bar
info Nur Node-Zähler (InfoBox) — kein Diagramm
compact Diagramm ohne Toolbar und Action Bar

Konfigurierbar global, pro Workflow oder pro Shortcode.

Embed-Handler

Liefert eine Standalone-HTML-Seite unter ?breznflow_embed={id} für iframe-Einbettung. Die Seite enthält nur den SVG-Renderer — kein WordPress-Theme, keine Admin-Bar.

Dual-Gate-Sicherheit: Sowohl die globale allow_embed-Einstellung als auch das Per-Post-Meta _breznflow_show_embed müssen aktiviert sein.

URL-Parameter: ?theme={id} und ?minimap=0|1.

HTTP-Header enthalten X-Robots-Tag: noindex, nofollow und entfernen X-Frame-Options für Embedding.

Weitere Features

  • View-Zähler — zählt, wie oft jeder Workflow angezeigt wird
  • Ähnliche Workflows — zeigt verwandte Workflows nach gemeinsamen Node-Typen
  • InfoBox — kompakte Zusammenfassung wie „3× HTTP Request, 2× Code, 1× OpenAI"
  • KI-Erkennung — erkennt und markiert automatisch Workflows mit KI-Nodes
  • Schema.org HowTo — optionale JSON-LD-Strukturdatenausgabe
  • Anker-Navigation — <span id="breznflow-{id}"> für Hash-basiertes Deep-Linking mit 60px Scroll-Offset

Datenspeicherung

WordPress Options (wp_options)

Option-Key Inhalt
breznflow_settings Alle Plugin-Einstellungen (16 Keys, serialisiertes Array)
breznflow_custom_themes Custom-Theme-Definitionen (serialisiertes Array)

Post Meta (wp_postmeta)

Meta-Key Inhalt
_breznflow_raw_json Sanitiertes Workflow-JSON (nie das Roh-Original)
_breznflow_original_name Originaler Workflow-Name aus n8n
_breznflow_node_count Gesamtzahl der Nodes
_breznflow_node_summary Kategorisierte Node-Anzahl (JSON)
_breznflow_has_ai_nodes Ob der Workflow KI-Nodes enthält
_breznflow_ai_node_types Liste der KI-Node-Typen (JSON)
_breznflow_mask_log Maskierte Werte beim Import (JSON)
_breznflow_default_zoom Zoom-Level pro Workflow (10–200)
_breznflow_show_title Titel anzeigen
_breznflow_show_infobox InfoBox anzeigen
_breznflow_show_download Download erlauben
_breznflow_show_embed Einbettung erlauben
_breznflow_show_minimap Minimap anzeigen
_breznflow_default_mode Darstellungsmodus
_breznflow_default_theme Theme-ID

Uninstall-Cleanup

uninstall.php löscht bei Plugin-Deinstallation:

  • Alle breznflow_workflow-Posts und deren Meta
  • Option breznflow_settings
  • Alle breznflow_category-Taxonomie-Terms
  • Alle Transients mit Präfix breznflow_

Sicherheit

Eingabevalidierung

  • Workflow-JSON wird vor dem Import gegen das n8n-Schema validiert
  • Alle $_POST / $_GET-Werte über wp_unslash() + spezifische Sanitizer verarbeitet
  • Alle Ausgaben escaped mit esc_html, esc_attr, esc_url
  • SQL-Queries ausschließlich via $wpdb->prepare()

CSRF-Schutz

Jede Admin-Aktion validiert eine WordPress-Nonce. Capability-Checks erfordern manage_options für Einstellungen und edit_posts für Workflow-Verwaltung.

Download- & Embed-Sicherheit

Beide Endpunkte validieren:

  1. Post existiert, ist Typ breznflow_workflow und Status publish
  2. Die entsprechende Per-Post-Meta-Berechtigung ist aktiviert
  3. Die globale Einstellung ist aktiviert
  4. Das gespeicherte JSON ist valide

Response-Header enthalten X-Content-Type-Options: nosniff. Downloads nutzen Cache-Control: no-store.

Import von URL

Das „Von URL abrufen"-Feature im Wizard blockiert Anfragen an private/interne Netzwerkadressen (localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, Cloud-Metadaten-Endpunkte) zur Verhinderung von SSRF-Angriffen.

Shortcode

[breznflow id="42"]
[breznflow id="42" mode="compact" theme="light" zoom="80"]
[breznflow id="42" show_share="0" show_embed="1" show_minimap="0"]
Attribut Standard Beschreibung
id — Workflow-Post-ID (erforderlich)
mode visual visual, info oder compact
theme dark Theme-ID
zoom 100 Initiales Zoom-Level (10–200)
show_title true Workflow-Titel anzeigen
show_infobox true Node-Zusammenfassung anzeigen
show_minimap true Minimap-Overlay anzeigen
show_download false Download-Button anzeigen
show_share true Share-Aktion anzeigen
show_embed false Embed-Aktion anzeigen
show_get_json false „Get JSON"-Aktion anzeigen
max_code_lines 50 Max. Zeilen in Code-Node-Anzeige

Auflösungs-Hierarchie: Shortcode-Attribut → Post-Meta → Plugin-Einstellungen.

Installation

Via GitHub Release (empfohlen):

  1. breznflow.zip vom neuesten Release herunterladen
  2. In WordPress unter Plugins → Installieren → Plugin hochladen einspielen

Manuell (clone):

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/noschmarrn/breznflow.git
wp plugin activate breznflow

Nach der Aktivierung:

  1. BreznFlow → Workflow hinzufügen
  2. n8n Workflow-JSON einfügen (oder .json-Datei hochladen)
  3. Darstellungseinstellungen konfigurieren und Vorschau prüfen
  4. Veröffentlichen — [breznflow id="X"] in beliebigen Beitrag oder Seite einfügen

Kein Build-Step. Alle Assets sind direkte JS/CSS-Dateien.

Technischer Stack

Komponente Technologie
Backend PHP 8.0+, WordPress Plugin API
Namespace BreznFlow\
Architektur Singleton-Core, Feature-Klassen mit register()
Rendering Vanilla JavaScript SVG-Generierung (kein Canvas, keine Bibliotheken)
Datenbank WordPress Options API + Post Meta
Caching WordPress Transients (Related Workflows)
Frontend Vanilla JS, kein Build-Step, kein externes CDN
I18n .pot-File, Text-Domain breznflow
Coding Standard WordPress PHPCS
Lizenz GPL-2.0-or-later

Lizenz

GPL-2.0-or-later — https://www.gnu.org/licenses/gpl-2.0.html

Copyright (c) 2025–2026 mifupa.com