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+):

Requirements

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

webtrees 2.2.x (PHP 8.3+)
PHP CLI with proc_open available (standard)
A trigger: classic cron, a systemd timer, a Windows Task Scheduler task, or the built-in watch daemon (no OS timer needed — see “Trigger installation”)

Requirements

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

This module requires webtrees version 2.2 or 2.3. This module has the same requirements as webtrees#system-requirements.

It was initially created for version 2.2.4; since linkenhancer 1.6.1 it should also work with webtrees 2.3. Tests were usually run with built-in themes and some other custom modules.

Tip: It’s recommended installing the Cronjob module as well. This makes it easy to run the CLI scripts for maintaining the indexes.

Service API

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

Neighboring modules query the module’s state through a stable, read-only facade (CronjobService) instead of its internal services. Check availability first - the module may not be installed, and the class is only autoloadable when its module.php has been loaded:

<?php
use Schwendinger\Webtrees\Module\Cronjob\Services\CronjobService;

if (class_exists(CronjobService::class) && CronjobService::isFunctional()) {
 $status = CronjobService::jobStatus('mymodule:backup'); // null = unknown job
 $age = CronjobService::lastTickAge(); // seconds since last tick
 $listened = CronjobService::listenedEvents(); // event name => job names
}

Question	Method(s)
Is the service functional?	`isFunctional()`, `problems()` (codes: `module_disabled`, `not_migrated`, `cron_library_missing`, `tick_stale`)
Which features are enabled?	`features()` (`watch`, `pseudo_events`, `route_events`), `watchStatus()`
When did the last tick run?	`lastTick()` / `lastTickAge()` - both trigger types (marker file `data/cronjob/tick.last`)
Is a job enabled / when did it last run?	`isJobEnabled($name)`, `jobStatus($name)`, `lastRun($name)` - job names are namespaced (`<module>:<name>`)
Which events are listened for?	`listenedEvents()`, `listenersFor($event)`; catalogs: `eventCatalog()`, `pseudoEvents()`, `routeEvents()`
Actions (the only two)	`runJobNow($name)` (queued at the next tick), `pushEvent($name, $payload)` (event queue)

Contract: read-only methods never throw when the schema is missing (safe defaults), descriptions are source strings (never pre-translated), and lastRun() deliberately excludes the job output, which may contain personal data.

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.

Installation

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

Copy the module folder to modules_v4/cronjob/ (ZIP install works too). The cron library ships inside the module — nothing to fetch.
Open webtrees once (any page as an admin) so the module’s boot() creates its tables.
Install the trigger (classic cron, systemd timer, or Windows Task Scheduler — the module’s admin page generates the block for your OS with the paths of this installation already filled in).
Trigger installation (once) — see below.
Create your first job in the admin UI or configure and activate registered jobs.

Trigger installation (once)

Installation

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

Via Custom Module Manager (recommended)

Install and use Custom Module Manager for an easy and convenient installation of webtrees custom modules.
Open the Custom Module Manager view in webtrees, select “linkenhancer”, and click on the “Install Module” button.

Manual installation

Download the latest release of the module.
Upload the downloaded file to your web server.
Unzip the package into your modules_v4 directory.
Rename the folder to linkenhancer

If everything was successful, you should see a subdirectory linkenhancer with the unpacked content in the modules_v4 directory.

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.

Pseudo-events

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

webtrees has no event bus, so core actions (logins, failed logins, logouts, record edits, errors, searches) are detected by polling the webtrees log table (app/Log.php, table log) and firing an event per new matching log entry. It is off by default: nothing runs until you enable the offered cronjob:pseudo-events job.

Built-in events (one cj_event per new log row, payload = the row):

Event	Log filter (log_type, message prefix)	Fires when
`cronjob:log-auth-failed`	`auth`, `Login failed`	a login attempt failed (wrong password, unknown user, unverified, not approved, no session cookies)
`cronjob:log-auth-login`	`auth`, `Login:`	a user logged in
`cronjob:log-auth-logout`	`auth`, `Logout:`	a user logged out
`cronjob:log-error`	`error`, –	an exception was caught and logged (the message is the trace)
`cronjob:log-edit-update`	`edit`, `Update:`	a record was updated (`GedcomRecord::updateRecord()`)
`cronjob:log-edit-delete`	`edit`, `Delete:`	a record was deleted (`GedcomRecord::deleteRecord()`)
`cronjob:log-search`	`search`, –	a search ran (one log row per searched tree)

Payload: log_id, log_time, log_message (truncated to 250 characters, UTF-8-safe) plus gedcom_id / user_id when the log row carries them. The message prefixes are the hard-coded English strings of the current core; a core update that changes them silently stops the matching event (no fallback by design) — the event catalog descriptions and the test-pseudo-events suite pin the current mapping.

Self-registration

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

Other modules can advertise their scheduled jobs so they show up in the admin UI without manual registry editing. Two ways (a module may use both); both are discovered automatically on each tick, only for enabled modules:

Marker method

getCronJobs(): array on the module’s module.php class, returning the same shape. Equivalent: getModuleEvents(): array, getModuleCommands(): array.

Manifest file (recommended)

modules_v4/<module>/cron-jobs.php that returns an array of job specs:

<?php
// modules_v4/linkenhancer/cron-jobs.php
declare(strict_types=1);

return [
 [
 'name' => 'link-index',
 'title' => 'Update the link index',
 'triggers' => [
 ['type' => 'time', 'cron' => '*/30 * * * *'],
 ],
 'command_type' => 'module',
 'command' => 'modules_v4/linkenhancer/cli/build-link-index.php',
 'args' => '--limit=5000',
 ],
];

Translatable title / description literals in a manifest should be wrapped in MoreI18N::translate() (identity marker) so xgettext picks them up - translation happens at render time, never at manifest load.

Admin settings

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

Since this is a service module, the only way to access its functions is through the module settings page. Strictly speaking, the only settings available are:

the optional path to the PHP CLI binary (if it is not automatically detected) and
the option to enable additional debug logging in the error log.

Event catalog

The admin page (Events section) and the job form’s event-name suggestions are fed by an event inventory (cj_event_catalog, synced by the tick like the job registry). It merges, in this priority order:

Admin settings

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

At the top of the admin page, you can access the administrative Cross-Reference Overview and the Renumber xref_IDs (with references) function.
You can also enable or disable the basic features:

When the first four basic features are enabled, more detailed settings can be configured further down. There are also two global settings for debug output in the browser’s JavaScript console and the web server error log file, and you can choose whether links should always open in a new browser tab (it’s also possible to set different options for each core feature).

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

Route events

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

A complementary, immediate detection mechanism: instead of polling state on a schedule, the module observes the HTTP request itself. When a request to a mapped mutating route has been handled successfully (2xx/3xx), it queues the matching event into the same cj_event queue — a listening event job then reacts at the next tick (~60 s), with no polling latency.

Which routes are mapped — two rules, both derived from the live webtrees route table. Common prerequisites: path starts with /tree/{tree}/, the handler is in webtrees’ request-handler namespace (RequestHandlers in 2.2.6, Controllers in 2.3), and the request is a POST mutation. In 2.2.6 this is enforced at map time (GET page routes are not mapped); in 2.3 the route carries no HTTP method, so the POST check happens at fire-time and the GET form-load of the same route is ignored.

Usage

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

Creating a job

Control panel → Cron Job Scheduler → New Job:

Field	Meaning
Name (slug)	technical identifier, `a-z 0-9 _ -`. Read-only for module-offered jobs (their `<module>:<name>` key is fixed); editable for jobs you create yourself.
Title	human readable name
Triggers	one or more time triggers (cron schedules) and/or event triggers — the job fires when any trigger fires. At least one is required.
Cron expression	(time trigger) standard 5-field cron or a macro (`@daily`, `@weekly`, …). Times are UTC.
Event name	(event trigger) the event this job reacts to. Slug or `<domain>:slug`, max 64 chars.
Command	a `modules_v4/<module>/cli/<script>.php` path or an allowlisted core command.
Arguments	plain options/values only (e.g. `--limit=5000`), max 10 tokens
Timeout	30 - 3600 s
Notify on failure	opt-in: alert the administrator accounts when this job fails

Available event names and commands are provided as datalists to make data entry easier.

Markdown Image Support

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

This feature allows you to easily embed images from GEDCOM media records (which reside behind the media firewall) or from the public directory into notes. If restriction rules apply to the record, instead of the image, a message is displayed.

Syntax:

![alternate text for gedcom object](#@id=@M1@)
![alternate text for picture in public folder](#@public=webtrees.png "title")
![picture with defined height, width and additional css class](#@id=@M1@&h=200&w=200&cname=float-right)

Technically the images are packed into a div container together with an image subtitle — which is also a link to the media data set for GEDCOM objects. The display can be customized as required using the standard CSS classes or per-image additional CSS classes (e.g. float-start or float-end from webtrees vendor.css).

Markdown Editor

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

You can enable a visual markdown editor (mde) for note textareas. Under the hood the project TinyMDE - A tiny, dependency-free embeddable HTML/JavaScript Markdown editor is used.

Besides syntax highlighting it ships with an icon bar for common format commands, a help popup and line numbering.

Note: Unfortunately, the on-screen keyboard does NOT work as before with the previous text input field. The selected characters end up as an intermediate step in the small text field below the Markdown editor and then must be copied manually to the desired position.

Markdown Extensions

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

Warning: Please keep in mind when using these extensions, you are deviating from the smallest common markdown dialect set. If the library used to render markdown in HTML needs to be changed for any reason, there is a possibility that not all of the extended markup used here will be supported (see also #32). Since the markup is not intrusive, the impact should not be serious — of course, it’s a minor drawback.

The Tick

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

The tick is the heart of the module: once a minute it looks at every enabled job, decides what is due, and runs it. Neither the webtrees core nor the operating system does any scheduling itself — they only start tick.php .

flowchart TD
 subgraph Triggers["`⏱ Triggers *(once per minute)*`"]
 CRON["`🕑 OS cron / systemd<br/>*every minute*`"]
 WATCH["`👁 watch daemon<br/>*(in-module)*`"]
 end

 subgraph Guard["🛡 Guard"]
 TP["`📄 cli/tick.php · **cron:tick**<br/>*guard(): 403 over HTTP*`"]
 OFF{"`⚠ site offline?<br/>*data/offline.txt*`"}
 BOOT["`🚀 boot()<br/>*webtrees + DB*`"]
 end

 subgraph Selection["🔎 Select work"]
 TIME["`📅 time-based jobs<br/>**next_run_at due** *(UTC)*`"]
 CE[("`📦 cj_event<br/>*event queue*`")]
 DRAIN["`🧮 drain queue<br/>*coalesced · 60 s budget*`"]
 end

 subgraph Execution["`⚙ Execution *(isolated child)*`"]
 RUN["`🧪 JobRunner<br/>**proc_open**`"]
 LIM["`⏲ timeout 30–3600 s<br/>last **64 KB** · exit code`"]
 end

 subgraph Storage["💾 Storage"]
 CJRUN[("`cj_run<br/>*run history*`")]
 MARK["`🏷 tick.last<br/>*stale > 300 s → tick_stale*`"]
 end

 CRON --> Guard
 WATCH --> Guard
 TP --> OFF
 OFF -->|"offline"| SKIP["⏭ skip tick"]
 OFF -->|"online"| BOOT
 BOOT --> TIME
 BOOT --> DRAIN
 CE --> DRAIN
 TIME --> Execution
 DRAIN --> Execution
 RUN --> LIM
 LIM --> CJRUN
 BOOT --> MARK

 classDef sourceStyle fill:#e3f2fd,stroke:#1565C0,stroke-width:2px
 classDef queueStyle fill:#fff3e0,stroke:#E65100,stroke-width:2px
 classDef tickStyle fill:#e8f5e9,stroke:#2E7D32,stroke-width:2px
 classDef execStyle fill:#fce4ec,stroke:#C2185B,stroke-width:2px
 classDef storageStyle fill:#f5f5f5,stroke:#616161,stroke-width:1px

 class CRON,WATCH sourceStyle
 class OFF,CE queueStyle
 class TP,TIME,DRAIN tickStyle
 class RUN,LIM execStyle
 class CJRUN,MARK,SKIP storageStyle

What starts a tick

Pick one trigger (once):

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:

German webtrees manual (WTHB)

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

A context sensitive help link to the German webtrees manual can be added to the small navigation menu. Context links are also available for components on pages provided by custom extensions (e.g. on the individuals page, the start page or items in the main menu) — these can be identified by the i symbols in a circle.

To ensure that this function is also available in the admin backend, a modified version of views/layouts/administration.phtml must be registered. This module attempts to use the custom module vesta_common (if installed and enabled) or its own version of the view layout file. Alternatively, patch P002 could also be applied to the core code.

Table cell height control

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

For longer markdown note texts it’s sometimes a pain to scroll through if you are interested in the next facts beneath them at the moment. This feature should come in handy here: By activating the checkbox in the top right corner of the title cell (first table column), the maximum height of the content cell with the long note is set to about 80% of the viewport height. This makes the content itself scrollable.

Home Link

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

The site title can be a link to the tree homepage or the user my page. The webmaster can also set a user-defined URL.

Dynamic CSS styles can be applied to match the current theme, ensuring that the display contrasts well. Of course it is not limited to the home link use case - for details see Admin settings.

CLI Scripts

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

Scripts

php modules_v4/cronjob/cli/tick.php # run all due jobs
php modules_v4/cronjob/cli/tick.php --dry-run # show what would run
php modules_v4/cronjob/cli/tick.php --job=<name> # run one specific job now
php modules_v4/cronjob/cli/tick.php --strict # exit 1 if any job failed
php modules_v4/cronjob/cli/tick.php --full-output # echo full job output (debugging!)
php modules_v4/cronjob/cli/watch.php # run the resident watch daemon

Exit codes: 0 = tick ran (job failures are recorded in the DB), 1 = environment problem or (with --strict) at least one job failed.

Cross-Reference Overview

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

There are three types of overviews:

overview about all data for the admin (admin overview),
to one tree limited overview (user overview), and
record-specific overview on the record details view (record overview, as tab or modal).

The admin overview (Control panel → LinkEnhancer → Cross-reference overview) is a server-side paginated DataTable. It lists all records that contain classic @XREF@ cross-references or linkenhancer links, with a per-record link inventory.

Optional filters:

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.

Renumber XREFs (with links)

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

The standard webtrees renumbering (Control panel Manage family trees → [Family tree] → Renumber XREFs) resolves cross-tree XREF collisions but does not update linkenhancer or classic links. This module provides an extended renumber that repairs all affected links in one step.

Access: Control panel → LinkEnhancer → Renumber XREFs (with links)

Workflow:

Select the tree that has XREF collisions (duplicate XREFs with other trees).
The page shows each conflicting XREF, its record type, and the number of inbound linkenhancer references from the link index.
On submit, each conflicting XREF is:
- renamed in the GEDCOM core tables (same as the standard renumber)
- all wt=@XREF@ / id=@XREF@ links in notes and blocks are updated
- the link index (le_link_index) and UID index (le_uid_index) are repaired inline or deferred to cron
Each renumbered record is logged in the edit log (Admin → Changes log), e.g. Renumbered @I456@ → @I457@ (INDI, 3 core rows, 2 links).
If the PHP time limit is reached, the run stops with partial progress — the remaining conflicts are renumbered on the next run.

Note: The standard webtrees renumber (without links) remains available and is unaffected. Use this module’s renumber when your notes or blocks contain linkenhancer links. See also: fisharebest/webtrees#5156

Security

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

No shell, ever. Commands are executed via proc_open with an argv array.
Command whitelist. Module scripts must match modules_v4/<module>/cli/<script>.php, exist, and resolve inside a modules_v4/<module>/cli/ directory. Core commands are limited to the read-only/export allowlist.
Argument validation. Every argument token must be a plain option or value — no shell metacharacters, no spaces inside tokens, max 10 tokens.
Working directories. Module scripts run from the webtrees root; core commands run from data/.
No sensitive data in stdout. The tick echoes summary lines only; full output stays in the admin-only run history.
UI actions are all named *Admin* (admin-only, CSRF-protected).
Kill switch: disable the module — the tick then does nothing.
The tick is single-instance (flock), and a job’s child process is hard-killed after its timeout (SIGKILL).
Event-queue coalescing. A flood of identical events cannot amplify into one job run per queued row.
Webhook token header-only. Send the token exclusively in the X-Cronjob-Token header.

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.

Data Fixes

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

The module provides a set of data-fix handlers accessible from the webtrees data-fix interface (Control panel → Data fixes → LinkEnhancer). Each handler addresses a specific link integrity issue:

Fix	What it does
XREF ⇄ UID reference swap	Converts linkenhancer link targets between XREF and UID form. Direction is selectable (XREF→UID or UID→XREF). Requires the UID index to be built.
Fix `wt=` type letter	Sets, repairs, or removes the legacy type letter in `wt=<type>@REF@` links. Modes: set (add missing type), repair (fix wrong type), remove (strip type letter).
Report dangling link targets	Report-only: lists linkenhancer links whose target record no longer exists. No changes are made.
Report ambiguous UID targets	Report-only: lists links whose UID target resolves to more than one record. No changes are made.
Report duplicate UIDs in index	Report-only: lists UIDs assigned to multiple records in the UID index. No changes are made.

Each fix follows the webtrees data-fix workflow: select fix type → preview → apply. The data-fix page also shows the current status of the link and UID indexes, and whether index updates will be deferred to the cron job.

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:

UID Lookup

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

A UID (_UID in GEDCOM 5.5.1, UID in GEDCOM 7.0) is a persistent identifier assigned to a record. The UID survives XREF renumbering and tree migrations, making it a stable reference point.

This feature allows navigating directly to a record by its UID. The URL pattern is:

/tree/{tree}/goto-uid/{uid} — scoped to one tree
/goto-uid/{uid} — global (searches all trees)

Behavior:

0 hits → 404
1 visible hit → redirect to the record
>1 visible hit → selection list (case-variant UIDs or the same UID in multiple records)

UID comparison is case-insensitive (GEDCOM specs do not define UID as case-sensitive). The stored value is verbatim; matching is done case-insensitively so that case-variant UIDs return a selection list rather than a possibly-wrong single redirect.

Patches

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

The patches can be applied additionally — the module also works without them!

The util subfolder contains minor patches for the webtrees core. These are diff-files that can be easily applied or removed using shell from within the installed module folder (necessary for auto-detecting webtrees sources):

Usage: util/wt-patch.sh [-R] [FILTER]
 -R undo Patch (patch -R)
 FILTER '*' for all or specific (e.g. '01')

Don’t forget to reapply the patches after updating webtrees.

These are minor bug fixes or functional enhancements — usually in a single file — that are intended to bridge the gap until they are officially fixed/implemented in the webtrees core.

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.

Search Results

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

Website information

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

Site built with Docsy v0.18.0

wt-modules

CLI Scripts

Requirements

Requirements

Service API

Contributing

Translation

Installation

Trigger installation (once)

Installation

Via Custom Module Manager (recommended)

Manual installation

Project Structure

Directory layout

Dependencies

Database schema

Pseudo-events

Self-registration

Marker method

Manifest file (recommended)

Admin settings

Event catalog

Admin settings

Class Hierarchy

Module

CommonMark (Extensions)

Factories

Request Handlers

Schema

Services

DataFix

Route events

Usage

Creating a job

Markdown Image Support

Markdown Editor

Markdown Extensions

The Tick

What starts a tick

Development Environment

Requirements

Location

German webtrees manual (WTHB)

Table cell height control

Home Link

CLI Scripts

Scripts

Cross-Reference Overview

Build System

Tasks

JS / CSS bundling

Renumber XREFs (with links)

Security

Translation Pipeline

Flow

Extracting strings

WTHB TOC Language Pipeline

Overview

Data Fixes

Testing

JavaScript (Mocha + jsdom)

PHP standalone unit tests

PHP static analysis

Smoke tests (need webtrees + DB)

PHPStan

Run

Configuration

Key settings

Regenerating the baseline

UID Lookup

Patches

Releasing

Steps

What archive does

Excluded from the archive

Search Results

Website information

Build information

What `archive` does