Developer on wt-modules

CLI Scripts

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

The module ships CLI-only scripts. They are guarded: requested over HTTP (the modules_v4 directory is inside the web root) they answer 403 instead of running.

Script	Purpose	Needs a webtrees install + DB?
`cli/build-link-index.php [--limit=N] [--tree=<id>] [--rebuild] [--flush]`	build/update the link index for the XREF overview	yes
`cli/build-uid-index.php [--limit=N] [--tree=<id>] [--rebuild] [--flush] [--force]`	build/update the UID index for UID lookup	yes
`cli/refresh-wthb-toc.php [--all] [--lang=<list>] [--clear] [--force]`	refresh the WTHB table of contents cache (production)	yes
`test-text-tag-collector.php`	standalone unit tests for the text-tag collector	no
`test-link-classifier.php`	standalone unit tests for the link classifier (incl. target extraction)	no
`test-uid-tag-collector.php`	standalone unit tests for the UID tag collector	no
`test-uid-index-service.php`	standalone unit tests for the UID index service	no
`tests/smoke-text-tag-collector.php [limit]`	scan records containing enhanced links, print every captured value	yes
`smoke-migration5.php`	SQLite smoke test for Migration5 (UID index schema)	yes
`tests/p1-measure.php [--tree=<id>]`	read-only scaling measurement for the XREF overview	yes

Run them from the webtrees root with the same PHP version the instance runs on (webtrees requires PHP 8.3+):

Contributing

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

If you’d like to contribute to this module, great! You can contribute by:

Contributing code — check out the issues for things that need attention. If you have changes you want to make not listed in an issue, please create one, then you can link your pull request.
Testing — it’s all manual currently, please create an issue for any bugs you find.

Translation

You can contribute to this project on Codeberg Weblate. Updated translations will be included in the next release of this module.

Project Structure

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

Directory layout

linkenhancer/
├── module.php ← webtrees entry point
├── autoload.php ← PSR-4 autoloader
├── cron-jobs.php ← cronjob self-registration manifest
├── latest-version.txt ← current version (synced to LinkEnhancerModule.php)
├── composer.json ← PHP deps (wt-shared-libs, phpstan)
├── package.json ← JS deps (gulp, rollup, mocha)
├── gulpfile.mjs ← build tasks
├── phpstan.neon ← static analysis config
├── phpstan-bootstrap.php ← PSR-4 bootstrap for PHPStan
├── phpstan-baseline.neon ← known issues
├── src/ ← PHP (PSR-4)
│ ├── LinkEnhancerModule.php
│ ├── LinkEnhancerModuleExt.php
│ ├── LinkEnhancerUtils.php
│ ├── SettingInterface.php
│ ├── CommonMark/ ← CommonMark extensions
│ ├── DataFix/ ← data-fix handlers + dispatcher
│ ├── Factories/ ← CustomMarkdownFactory
│ ├── Http/ ← request handlers
│ ├── Schema/ ← Migrations + SeedHelpTable
│ └── Services/ ← business logic
├── resources/
│ ├── js/ ← JS source (src/) + build output (bundle-*)
│ ├── css/ ← CSS source + build output
│ ├── lang/ ← .pot / .po / .php (translations)
│ ├── views/ ← PHTML views
│ └── img/ ← screenshots
├── cli/ ← CLI maintenance scripts
├── tests/ ← standalone + smoke tests
└── util/ ← build/maintenance shell scripts

Dependencies

PHP (composer.json ):
- bschwede/wt-shared-libs (path repo ../wt-shared-libs) and
- phpstan (dev).
- Conflicts with:
  - webtrees <2.2 and
  - elysch/webtrees-mitalteli-misc-features
JS (package.json ):
- runtime dependency tiny-markdown-editor
- dev tooling — Gulp, Rollup, PostCSS (autoprefixer, cssnano), Mocha + chai + sinon, jsdom.

Database schema

The module owns five tables (prefix le_), created incrementally by src/Schema/Migration#.php. Every migration is additive and idempotent, so the schema converges on each module load.

Class Hierarchy

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

Auto-generated by docs/tools/generate-class-hierarchy.php — do not edit manually.

Module

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 Handlers

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

Development Environment

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

What you need to build and test the module locally.

Requirements

Component	Version	Notes
PHP	8.3+	same version the webtrees instance runs on
Composer	2.x	installs `wt-shared-libs` + `phpstan`
Node.js	18+ (LTS)	for Gulp / Rollup / Mocha
webtrees	2.2.x or 2.3.x	needed for PHPStan (`app/` classes) and the smoke tests
wt-shared-libs	newest version	sibling repo at `modules_v4/wt-shared-libs` (composer path repo)

Location

The module lives inside a webtrees installation at modules_v4/linkenhancer/. Its composer.json pulls in the sibling shared library as a local path repository:

Build System

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

Bundling, translation compilation and versioning are driven by Gulp tasks in gulpfile.mjs , invoked with npx gulp <task>. The npm run * scripts cover testing only — see the Testing page.

Tasks

Task	Command	What it does
`build`	`npx gulp build`	`clean` → JS (Rollup) + CSS (PostCSS)
`devbuild`	`npx gulp devbuild`	like `build`, but Dev-Mode (no minify, source maps)
`updatepo`	`npx gulp updatepo`	runs `update-po-files.sh` → `xgettext` over `src/` → `messages.pot`
`po2php`	`npx gulp po2php`	compiles `resources/lang/.po` → `resources/lang/.php`
`syncversion`	`npx gulp syncversion`	keeps `latest-version.txt` ↔ `LinkEnhancerModule.php` in sync
`bumpversion`	`npx gulp bumpversion`	requires a clean 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]`	adds issue refs to commit messages (needs `FORGEJO_TOKEN` in `.env`) - was used only once to migrate the repo from GitHub to Codeberg

JS / CSS bundling

build = clean → (in parallel) JS + CSS.

Translation Pipeline

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

The module ships its own translations through the standard gettext chain, hosted on Codeberg Weblate.

Flow

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

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

 subgraph Rendering["3️⃣ Webtrees"]
 direction LR
 PHPARR["📦 lang.php"] -->|I18N| RENDER["✅ Render"]
 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

Extracting strings

update-po-files.sh runs xgettext over every *.php / *.phtml except util/, vendor/, node_modules/ and tests/:

WTHB TOC Language Pipeline

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

Overview

The linkenhancer-wthb-toc-lang package delivers the table of contents (TOC) of the German webtrees manual — and its translations — to the WTHB help feature. Its production is a round trip that lives entirely outside the webtrees install: it reads the manual from GenWiki, regenerates the TOC, writes the result back to GenWiki as a MediaWiki template, and — in parallel — ships the structured data to an external Codeberg repo that feeds Codeberg Pages, Weblate (translations) and, finally, the module. This page documents the production side; the consumer side (cache, CLI, rendering) is covered on the WTHB feature page and the CLI scripts page.

Testing

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

The full chain runs with:

npm test

which executes test:php → analyse:php → test:js, each step required to pass before the next runs.

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
# runs every tests/test-*.php with the system PHP — no webtrees install, no DB

Test	Covers
`test-text-tag-collector.php`	text-tag collector
`test-link-classifier.php`	link classifier (incl. target extraction)
`test-uid-tag-collector.php`	UID tag collector
`test-uid-index-service.php`	UID index service
`test-i18n-mark.php`	i18n markers
`test-wthb-toc-service.php`	WTHB TOC service

PHP static analysis

npm run analyse:php # or: composer analyse
# PHPStan Level 6 — see the PHPStan page

Smoke tests (need webtrees + DB)

These exercise a real installation and are not part of npm test:

PHPStan

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

Required: PHPstan

Static analysis is configured via phpstan.neon (Level 6, baseline in phpstan-baseline.neon).

Run

composer analyse

The analysis requires a webtrees installation (for app/ classes + vendor/autoload.php). Run it from the bind-mounted path:

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

Configuration

Level: 6
Baseline: phpstan-baseline.neon (known issues)
Bootstrap: phpstan-bootstrap.php registers PSR-4 namespaces directly (bypasses the version-gated autoloader in wt-shared-libs)
Scan directories: ../../app/ (webtrees core classes)
Exclude paths: LinkEnhancerModuleExt.php (use in conjunction with Vesta modules)
Memory limit: 1G
Parallel: disabled (single process, more reliable in CI)

Key settings

treatPhpDocTypesAsCertain: false — prevents false positives from @var assertions
ignoreErrors for:
- AccessLevel Enum (WT 2.3-only class, not available in 2.2 runtime)
- DB::prefix('') — intentional (getting prefix without identifier)

Regenerating the baseline

After intentional changes that introduce new (acceptable) errors:

Releasing

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

Steps

# 1. Bump the version (requires a clean git tree)
npx gulp bumpversion

# 2. Build + compile translations + create the release archive
npx gulp archive

What `archive` does

npx gulp archive runs build → po2php → create-archive.sh . The script:

Reads the version from latest-version.txt .
rsyncs the module into dist/linkenhancer/, excluding everything that is not shipped (below).
Zips it to dist/linkenhancer_v<version>.zip.

Excluded from the archive

create-archive.sh drops, among others: node_modules/, .git*, gulpfile.mjs, package*.json, phpstan*, tests/, the util/* build scripts, resources/js/src, resources/js/tests, resources/img/, resources/lang/*.po / *.mo, and .env. Only the built bundle* JS/CSS, the compiled resources/lang/*.php, src/, resources/views/, resources/css/ and the module entry files are shipped.

Developer on wt-modules

CLI Scripts

Contributing

Translation

Project Structure

Directory layout

Dependencies

Database schema

Class Hierarchy

Module

CommonMark (Extensions)

Factories

Request Handlers

Schema

Services

DataFix

Development Environment

Requirements

Location

Build System

Tasks

JS / CSS bundling

Translation Pipeline

Flow

Extracting strings

WTHB TOC Language Pipeline

Overview

Testing

JavaScript (Mocha + jsdom)

PHP standalone unit tests

PHP static analysis

Smoke tests (need webtrees + DB)

PHPStan

Run

Configuration

Key settings

Regenerating the baseline

Releasing

Steps

What archive does

Excluded from the archive

What `archive` does