Entwicklung on wt-modules

CLI-Skripte

Mon, 01 Jan 0001 00:00:00 +0000

Das Modul bringt ausschließlich CLI-Skripte mit. Sie sind geschützt: bei Aufruf über HTTP (das Verzeichnis modules_v4 liegt innerhalb des Web-Roots) antworten sie mit 403 anstatt auszuführen.

Skript	Zweck	Braucht eine webtrees-Installation + DB?
`cli/build-link-index.php [--limit=N] [--tree=<id>] [--rebuild] [--flush]`	baut/aktualisiert den Link-Index für die XREF-Übersicht	ja
`cli/build-uid-index.php [--limit=N] [--tree=<id>] [--rebuild] [--flush] [--force]`	baut/aktualisiert den UID-Index für die UID-Suche	ja
`cli/refresh-wthb-toc.php [--all] [--lang=<list>] [--clear] [--force]`	aktualisiert den WTHB-Inhaltsverzeichnis-Cache (Produktion)	ja
`test-text-tag-collector.php`	eigenständige Unit-Tests für den Text-Tag-Collector	nein
`test-link-classifier.php`	eigenständige Unit-Tests für den Link-Klassifizierer (inkl. Ziel-Extraktion)	nein
`test-uid-tag-collector.php`	eigenständige Unit-Tests für den UID-Tag-Collector	nein
`test-uid-index-service.php`	eigenständige Unit-Tests für den UID-Index-Service	nein
`tests/smoke-text-tag-collector.php [limit]`	scannt Datensätze mit erweiterten Links, gibt jeden erfassten Wert aus	ja
`smoke-migration5.php`	SQLite-Smoke-Test für Migration5 (UID-Index-Schema)	ja
`tests/p1-measure.php [--tree=<id>]`	Read-only-Scaling-Messung für die XREF-Übersicht	ja

Ausführen vom webtrees-Root aus mit der gleichen PHP-Version, mit der die Instanz läuft (webtrees benötigt PHP 8.3+):

Mitwirken

Mon, 01 Jan 0001 00:00:00 +0000

Wenn Sie zu diesem Modul beitragen möchten, großartig! Sie können beitragen, indem Sie:

Code beisteuern — schauen Sie sich die Issues für Dinge an, die Aufmerksamkeit brauchen. Wenn Sie Änderungen vornehmen möchten, die nicht in einem Issue aufgeführt sind, erstellen Sie bitte eines, damit Sie Ihren Pull Request verlinken können.
Testen — derzeit ist alles manuell; bitte erstellen Sie ein Issue für jeden Bug, den Sie finden.

Übersetzung

Sie können zu diesem Projekt auf Codeberg Weblate beitragen. Aktualisierte Übersetzungen werden in der nächsten Version dieses Moduls enthalten sein.

Projektstruktur

Mon, 01 Jan 0001 00:00:00 +0000

Verzeichnislayout

linkenhancer/
├── module.php ← webtrees-Entry-Point
├── autoload.php ← PSR-4-Autoloader
├── cron-jobs.php ← Self-Registration-Manifest für cronjob
├── latest-version.txt ← aktuelle Version (mit LinkEnhancerModule.php synchron)
├── composer.json ← PHP-Abhängigkeiten (wt-shared-libs, phpstan)
├── package.json ← JS-Abhängigkeiten (gulp, rollup, mocha)
├── gulpfile.mjs ← Build-Tasks
├── phpstan.neon ← Konfiguration der statischen Analyse
├── phpstan-bootstrap.php ← PSR-4-Bootstrap für PHPStan
├── phpstan-baseline.neon ← bekannte Probleme
├── src/ ← PHP (PSR-4)
│ ├── LinkEnhancerModule.php
│ ├── LinkEnhancerModuleExt.php
│ ├── LinkEnhancerUtils.php
│ ├── SettingInterface.php
│ ├── CommonMark/ ← CommonMark-Extensionen
│ ├── DataFix/ ← Datenkorrektur-Handler + Dispatcher
│ ├── Factories/ ← CustomMarkdownFactory
│ ├── Http/ ← Request-Handler
│ ├── Schema/ ← Migrations + SeedHelpTable
│ └── Services/ ← Geschäftslogik
├── resources/
│ ├── js/ ← JS-Quellcode (src/) + Build-Ausgabe (bundle-*)
│ ├── css/ ← CSS-Quellcode + Build-Ausgabe
│ ├── lang/ ← .pot / .po / .php (Übersetzungen)
│ ├── views/ ← PHTML-Views
│ └── img/ ← Screenshots
├── cli/ ← CLI-Wartungsskripte
├── tests/ ← Standalone- + Smoke-Tests
└── util/ ← Build-/Wartungs-Shell-Skripte

Abhängigkeiten

PHP (composer.json ):
- bschwede/wt-shared-libs (Path-Repo ../wt-shared-libs)
- phpstan (dev).
- Konflikte mit:
  - webtrees <2.2 und
  - elysch/webtrees-mitalteli-misc-features
JS (package.json ):
- Laufzeit-Abhängigkeit tiny-markdown-editor
- Dev-Tooling — Gulp, Rollup, PostCSS (autoprefixer, cssnano), Mocha + chai + sinon, jsdom

Datenbank-Schema

Das Modul besitzt fünf Tabellen (Präfix le_), die inkrementell durch src/Schema/Migration#.php erstellt werden. Jede Migration ist additiv und idempotent, sodass das Schema bei jedem Modul-Load konvergiert.

Klassenhierarchie

Mon, 01 Jan 0001 00:00:00 +0000

Automatisch generiert durch docs/tools/generate-class-hierarchy.php — nicht manuell bearbeiten.

Modul

LinkEnhancerModule extends AbstractModule implements MiddlewareInterface, ModuleCustomInterface, ModuleGlobalInterface, ModuleConfigInterface, ModuleDataFixInterface, ModuleListInterface, ModuleTabInterface, SettingInterface — LinkEnhancerModule.php
SettingInterface — SettingInterface.php
LinkEnhancerUtils — LinkEnhancerUtils.php
LinkEnhancerModuleExt extends LinkEnhancerModule implements ModuleExtGlobalInterface — LinkEnhancerModuleExt.php

CommonMark (Extensions)

LeImageRenderer (final) implements NodeRendererInterface, XmlNodeRendererInterface, ConfigurationAwareInterface — CommonMark/LeImageRenderer.php
SmartPunctHelper — CommonMark/SmartPunctHelper.php
LeTableOfContentsRenderer (final) implements NodeRendererInterface, XmlNodeRendererInterface — CommonMark/LeTableOfContentsRenderer.php

Factories

CustomMarkdownFactory extends MarkdownFactory — Factories/CustomMarkdownFactory.php

Request-Handler

DataFixBlocksAction implements RequestHandlerInterface — Http/RequestHandlers/DataFixBlocksAction.php
HelpWthbAction implements RequestHandlerInterface — Http/RequestHandlers/HelpWthbAction.php
XrefDetailData (final) implements RequestHandlerInterface — Http/RequestHandlers/XrefDetailData.php
XrefOverviewListData (final) implements RequestHandlerInterface — Http/RequestHandlers/XrefOverviewListData.php
GotoIdTreeAction extends GotoIdAction — Http/RequestHandlers/GotoIdTreeAction.php
GotoUidTreeAction extends GotoUidAction — Http/RequestHandlers/GotoUidTreeAction.php
GotoXrefAction implements RequestHandlerInterface — Http/RequestHandlers/GotoXrefAction.php
DataFixRebuildIndexAction implements RequestHandlerInterface — Http/RequestHandlers/DataFixRebuildIndexAction.php
RenumberActionHandler (final) — Http/RequestHandlers/RenumberActionHandler.php
HelpMdAction implements RequestHandlerInterface — Http/RequestHandlers/HelpMdAction.php
AdminXrefOverviewData (final) implements RequestHandlerInterface — Http/RequestHandlers/AdminXrefOverviewData.php
GotoIdAction extends AbstractGotoAction — Http/RequestHandlers/GotoIdAction.php
HelpWtCoreAction implements RequestHandlerInterface — Http/RequestHandlers/HelpWtCoreAction.php
WthbAdminHandler (final) — Http/RequestHandlers/WthbAdminHandler.php
GotoUidAction extends AbstractGotoAction — Http/RequestHandlers/GotoUidAction.php
AbstractGotoAction (abstract) implements RequestHandlerInterface — Http/RequestHandlers/AbstractGotoAction.php

Schema

SeedHelpTable implements SeedInterface — Schema/SeedHelpTable.php
Migration6 implements MigrationInterface — Schema/Migration6.php
Migration2 implements MigrationInterface — Schema/Migration2.php
Migration7 implements MigrationInterface — Schema/Migration7.php
Migration3 implements MigrationInterface — Schema/Migration3.php
Migration4 implements MigrationInterface — Schema/Migration4.php
Migration1 implements MigrationInterface — Schema/Migration1.php
Migration5 implements MigrationInterface — Schema/Migration5.php
Migration0 implements MigrationInterface — Schema/Migration0.php

Services

AdminSettingsBuilder (final) — Services/AdminSettingsBuilder.php
MarkdownEditorActivationService (final) — Services/MarkdownEditorActivationService.php
IndexRebuildScheduler (final) — Services/IndexRebuildScheduler.php
UidTagCollector (final) — Services/UidTagCollector.php
TextTagCollector (final) — Services/TextTagCollector.php
ContentBuilder (final) — Services/ContentBuilder.php
RenumberWithLinksService (final) — Services/RenumberWithLinksService.php
DataFiles (final) — Services/DataFiles.php
XrefOverviewColumns (final) — Services/XrefOverviewColumns.php
LinkIndexService (final) — Services/LinkIndexService.php
XrefsService (final) — Services/XrefsService.php
XrefDetailService (final) — Services/XrefDetailService.php
WthbService — Services/WthbService.php
IdResolver (final) — Services/IdResolver.php
LinkRenderer (final) — Services/LinkRenderer.php
WthbTocService (final) — Services/WthbTocService.php
UidIndexService (final) — Services/UidIndexService.php

DataFix

FixHandlerInterface — DataFix/FixHandlerInterface.php
DataFixDispatcher — DataFix/DataFixDispatcher.php
TreeLookupTrait — DataFix/TreeLookupTrait.php
DanglingLinksFix (final) implements FixHandlerInterface — DataFix/Handlers/DanglingLinksFix.php
DuplicateUidFix (final) implements FixHandlerInterface — DataFix/Handlers/DuplicateUidFix.php
WtTypeFix (final) implements FixHandlerInterface — DataFix/Handlers/WtTypeFix.php
XrefUidSwapFix (final) implements FixHandlerInterface — DataFix/Handlers/XrefUidSwapFix.php
AmbiguousUidFix (final) implements FixHandlerInterface — DataFix/Handlers/AmbiguousUidFix.php

Entwicklungsumgebung

Mon, 01 Jan 0001 00:00:00 +0000

Was man zum Bauen und Testen des Moduls lokal braucht.

Voraussetzungen

Komponente	Version	Hinweise
PHP	8.3+	dieselbe Version, mit der die webtrees-Instanz läuft
Composer	2.x	installiert `wt-shared-libs` + `phpstan`
Node.js	18+ (LTS)	für Gulp / Rollup / Mocha
webtrees	2.2.x oder 2.3.x	nötig für PHPStan (`app/`-Klassen) und die Smoke-Tests
wt-shared-libs	neueste Version	Schwester-Repo unter `modules_v4/wt-shared-libs` (Composer-Path-Repo)

Lage

Das Modul liegt innerhalb einer webtrees-Installation unter modules_v4/linkenhancer/. Sein composer.json zieht die Schwester-Bibliothek als lokales Path-Repository ein:

Build-System

Mon, 01 Jan 0001 00:00:00 +0000

Bundling, Übersetzungs-Kompilierung und Versionierung werden über Gulp-Tasks in gulpfile.mjs gesteuert, aufgerufen mit npx gulp <task>. Die npm run *-Skripte decken nur das Testing ab — siehe die Seite Testing.

Tasks

Task	Befehl	Wirkung
`build`	`npx gulp build`	`clean` → JS (Rollup) + CSS (PostCSS)
`devbuild`	`npx gulp devbuild`	wie `build`, aber Dev-Mode (kein Minify, SourceMaps)
`updatepo`	`npx gulp updatepo`	führt `update-po-files.sh` aus → `xgettext` über `src/` → `messages.pot`
`po2php`	`npx gulp po2php`	kompiliert `resources/lang/.po` → `resources/lang/.php`
`syncversion`	`npx gulp syncversion`	hält `latest-version.txt` ↔ `LinkEnhancerModule.php` synchron
`bumpversion`	`npx gulp bumpversion`	erfordert einen sauberen git-Tree → Version-Bump → `syncversion`
`archive`	`npx gulp archive`	`build` + `po2php` + `create-archive.sh` (Release-ZIP)
`forgejo:issue-refs`	`npx gulp forgejo:issue-refs[:dry]`	ergänzt Issue-Referenzen in Commit-Messages (braucht `FORGEJO_TOKEN` in `.env`) - wurde nur einmalig angewendet für die Übernahme des Repos von GitHub zu Codeberg

JS / CSS Bundling

build = clean → (parallel) JS + CSS.

Übersetzungs-Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Das Modul bringt seine eigenen Übersetzungen über die Standard-gettext-Kette ein, gehostet auf Codeberg Weblate.

Ablauf

flowchart TB
 subgraph Extraction["1️⃣ Quellcode → POT"]
 direction LR
 PHP["📝 src/*.php"] -->|npx gulp updatepo| POT["📄 messages.pot"]
 end

 subgraph Translation["2️⃣ Übersetzung"]
 direction LR
 WEBLATE["🌐 Weblate"] -->|download| PO["🗝 <lang>.po"]
 end

 subgraph Rendering["3️⃣ Webtrees"]
 direction LR
 PHPARR["📦 lang.php"] -->|I18N| RENDER["✅ Rendering"]
 end

 POT -->|upload| Translation
 PO -->|npx gulp po2php| Rendering

 classDef sourceStyle fill:#e3f2fd,stroke:#1565C0,stroke-width:2px
 classDef fileStyle fill:#e8f5e9,stroke:#2E7D32,stroke-width:2px
 classDef weblateStyle fill:#f3e5f5,stroke:#7B1FA2,stroke-width:2px
 classDef renderStyle fill:#fce4ec,stroke:#C2185B,stroke-width:2px

 class PHP sourceStyle
 class POT,PO,PHPARR fileStyle
 class WEBLATE weblateStyle
 class RENDER renderStyle

Strings extrahieren

update-po-files.sh führt xgettext über jede *.php / *.phtml aus, außer util/, vendor/, node_modules/ und tests/:

WTHB-TOC-Language-Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Überblick

Das Paket linkenhancer-wthb-toc-lang stellt das Inhaltsverzeichnis (TOC) des deutschen webtrees-Handbuchs — samt Übersetzungen — der WTHB-Hilfefunktion zur Verfügung. Die Produktion ist ein Rundlauf, der komplett außerhalb der webtrees-Installation läuft: Er liest das Handbuch von GenWiki, erzeugt das TOC neu, schreibt das Ergebnis als MediaWiki-Template zurück nach GenWiki und — parallel — die strukturierten Daten in ein externes Codeberg-Repo, das Codeberg Pages, Weblate (Übersetzungen) und schließlich das Modul versorgt. Diese Seite dokumentiert die Produktionsseite; die Konsumenten-Seite (Cache, CLI, Rendering) steht auf der WTHB-Funktionsseite und der Seite CLI-Skripte.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Die komplette Kette läuft mit:

npm test

Das führt test:php → analyse:php → test:js aus, wobei jeder Schritt bestehen muss, bevor der nächste läuft.

JavaScript (Mocha + jsdom)

npm run test:js
# mocha 'resources/js/tests/**/*.test.js' --require jsdom-global/register

PHP-Standalone-Unit-Tests

npm run test:php
# führt jedes tests/test-*.php mit dem System-PHP aus — ohne webtrees, ohne DB

Test	Abgedeckt
`test-text-tag-collector.php`	Text-Tag-Collector
`test-link-classifier.php`	Link-Klassifizierer (inkl. Ziel-Extraktion)
`test-uid-tag-collector.php`	UID-Tag-Collector
`test-uid-index-service.php`	UID-Index-Service
`test-i18n-mark.php`	i18n-Marker
`test-wthb-toc-service.php`	WTHB-TOC-Service

PHP-Statische Analyse

npm run analyse:php # oder: composer analyse
# PHPStan Level 6 — siehe die PHPStan-Seite

Smoke-Tests (brauchen webtrees + DB)

Diese üben eine echte Installation und sind nicht Teil von npm test:

PHPStan

Mon, 01 Jan 0001 00:00:00 +0000

Benötigt wird: PHPstan

Die statische Analyse ist über phpstan.neon konfiguriert (Level 6, Baseline in phpstan-baseline.neon).

Ausführen

composer analyse

Die Analyse benötigt eine webtrees-Installation (für die app/-Klassen + vendor/autoload.php). Ausführen vom bind-mounted-Pfad:

cd /path/to/webtrees/modules_v4/linkenhancer
composer analyse

Konfiguration

Level: 6
Baseline: phpstan-baseline.neon (bekannte Probleme)
Bootstrap: phpstan-bootstrap.php registriert die PSR-4-Namespaces direkt (umgeht den versionsgeprüften Autoloader in wt-shared-libs)
Scan-Verzeichnisse: ../../app/ (webtrees-Core-Klassen)
Ausgeschlossene Pfade: LinkEnhancerModuleExt.php (Verwendung im Zusammenhang mit Vesta-Modulen)
Speichergrenze: 1G
Parallel: deaktiviert (Single-Prozess, zuverlässiger in CI)

Wichtige Einstellungen

treatPhpDocTypesAsCertain: false — verhindert False Positives aus @var-Assertions
ignoreErrors für:
- AccessLevel Enum (nur-Klasse in WT 2.3, in der 2.2-Laufzeit nicht verfügbar)
- DB::prefix('') — beabsichtigt (Präfix ohne Identifier holen)

Baseline neu generieren

Nach beabsichtigten Änderungen, die neue (akzeptable) Fehler einführen:

Release

Mon, 01 Jan 0001 00:00:00 +0000

Schritte

# 1. Version erhöhen (erfordert einen sauberen git-Tree)
npx gulp bumpversion

# 2. Build + Übersetzungen kompilieren + Release-Archiv erstellen
npx gulp archive

Was `archive` tut

npx gulp archive führt build → po2php → create-archive.sh aus. Das Skript:

Liest die Version aus latest-version.txt .
rsync das Modul nach dist/linkenhancer/ und schließt alles aus, das nicht ausgeliefert wird (unten).
Erzeugt dist/linkenhancer_v<version>.zip.

Aus dem Archiv ausgeschlossen

create-archive.sh lässt unter anderem aus: node_modules/, .git*, gulpfile.mjs, package*.json, phpstan*, tests/, die util/*-Buildskripte, resources/js/src, resources/js/tests, resources/img/, resources/lang/*.po / *.mo und .env. Ausgeliefert werden nur die gebauten bundle*-JS/CSS, die kompilierten resources/lang/*.php, src/, resources/views/, resources/css/ und die Modul-Entry-Dateien.

Entwicklung on wt-modules

CLI-Skripte

Mitwirken

Übersetzung

Projektstruktur

Verzeichnislayout

Abhängigkeiten

Datenbank-Schema

Klassenhierarchie

Modul

CommonMark (Extensions)

Factories

Request-Handler

Schema

Services

DataFix

Entwicklungsumgebung

Voraussetzungen

Lage

Build-System

Tasks

JS / CSS Bundling

Übersetzungs-Pipeline

Ablauf

Strings extrahieren

WTHB-TOC-Language-Pipeline

Überblick

Testing

JavaScript (Mocha + jsdom)

PHP-Standalone-Unit-Tests

PHP-Statische Analyse

Smoke-Tests (brauchen webtrees + DB)

PHPStan

Ausführen

Konfiguration

Wichtige Einstellungen

Baseline neu generieren

Release

Schritte

Was archive tut

Aus dem Archiv ausgeschlossen

Was `archive` tut