README

Contao-5-Erweiterung zum webhook-gesteuerten Import von Inhalten aus externen Quellen in Artikel, News und (perspektivisch) Kalender.

Der erste Importer liest Markdown aus Git-Repositories (Shallow Fetch), mappt Frontmatter und CommonMark auf Contao-Datensätze und unterstützt Assets, interne Links sowie gezielten Re-Import bei Push-Webhooks.

Paket: lindesbs/sourcerer-bundle
Autor: Stefan Lindecke
Lizenz: MIT

Funktionsumfang (Stand)

Bereich	Funktion
Importer	Git/Markdown → Artikel oder News
Webhook	`POST/GET /sourcerer/webhook/{uniqueKey}` (Forgejo, Generic)
Backend	Importer verwalten, manueller Test-Import (Modal), Log-Viewer
Git	HTTPS oder SSH (Private Key), Branch- und Verzeichnis-Auswahl aus Remote
Inhalte	Frontmatter, CommonMark, Bilder/Downloads, interne Markdown-Links
Robustheit	Import-Timeout, Ziel-Verifikation (gelöschte Artikel werden neu angelegt)
Benachrichtigung	E-Mail und Gotify bei Fehler/`partial`
Logging	Rotierende Logfiles unter `var/log/sourcerer/{importerId}/`

Geplant u. a. RSS/Atom, IMAP/POP3, Kalender — siehe ROADMAP.md. Ideen für spätere Versionen: WISHLIST.md.

Voraussetzungen

PHP 8.3+
Contao 5.3+ (contao/core-bundle, contao/news-bundle)
Git CLI auf dem Server (für Shallow Fetch)
Optional: Contao-Vault für Credentials (Git, Webhook-Secret, Gotify)

Installation

Als Composer-Paket (Contao-Projekt)

Path-Repository oder VCS in der Contao-Installation:

{
  "repositories": [
    {
      "type": "path",
      "url": "../entwicklung/sourcerer"
    }
  ],
  "require": {
    "lindesbs/sourcerer-bundle": "@dev"
  }
}

composer update lindesbs/sourcerer-bundle
php bin/console contao:migrate
php bin/console cache:clear

Backend

Unter System → Sourcerer Importer anlegen, Ziel (Seite/Archiv + Ersteller) und Git-Zugang konfigurieren. Die Webhook-URL wird beim ersten Speichern einmalig erzeugt.

Konfiguration (Auszug)

Einstellung	Beschreibung
`repositoryProtocol`	`https` oder `ssh`
`repositoryUrl`	Remote-URL
`credentialRef`	Vault-Referenz oder direkter Wert (Token bzw. SSH-Key)
`branch`	Branch aus Remote-Auswahl
`contentPath`	Unterverzeichnis mit Markdown (aus Repo-Struktur)
`author`	Contao-Benutzer als Ersteller aller importierten Inhalte
`importTimeout`	Max. Laufzeit in Sekunden (`0` = Standard 300)

Globaler Standard-Timeout in der Contao-Installation:

# config/services.yaml
parameters:
  lindesbs_sourcerer.import_timeout: 600

Entwicklung

Repository klonen, Abhängigkeiten installieren:

composer install

Qualitätssicherung

composer cs          # Easy Coding Standard (PSR-12, Symfony, Clean Code)
composer cs:fix      # ECS mit Auto-Fix
composer phpstan     # Statische Analyse (Level 5)
composer test        # PHPUnit
composer qa          # cs + phpstan + test

Konfiguration: ecs.php (PSR-12/Symfony/Clean-Code, angelehnt an Contao-Stil), phpstan.neon.dist

Tests

40 PHPUnit-Tests decken u. a. Git-Credentials, Webhook-Payloads, Markdown-Parsing und Import-Logik ab.

Architektur (Kurz)

Webhook / Backend  →  ImportRunner  →  GitMarkdownImporter
                           ↓
              Artikel / News + tl_content + tl_files
                           ↓
              tl_sourcerer_external_ref (Upsert-Tracking)

Synchroner Import im HTTP-Request — keine Queue. Details, Datenmodell und Phasenplan: ROADMAP.md.

Entwicklungsweise & Transparenz

Dieses Projekt entsteht in enger menschlich geführter Entwicklung mit Unterstützung durch LLMs (z. B. Cursor). Die KI wird bewusst eingesetzt für:

Debugging und Fehleranalyse
Mockups und UI-/Ablauf-Skizzen und natürlich CSS (!!!)
Durchspielen von Abläufen vor der Implementierung
Code-Review und Konsistenzprüfungen
Planung (Roadmap, Architektur, Wishlist)

Architektur-Entscheidungen, Review und Freigabe liegen beim Autor. Automatisierte Checks (ECS, PHPStan, PHPUnit) sichern den Code zusätzlich ab.

Weitere Dokumentation

Datei	Inhalt
ROADMAP.md	Architektur, Phasen, Datenmodell
WISHLIST.md	Geplante Features (z. B. Autor-Mapping)

Lizenz

MIT — siehe Composer-Paketmetadaten.

lindesbs/sourcerer-bundle

包简介

README 文档