magicsunday/webtrees-statistics

This module provides SVG-based statistics for the [webtrees](https://www.webtrees.net) genealogy application.

1.2.0 2026-05-29 09:39 UTC

Requires

• php: 8.3 - 8.5
• ext-dom: *
• ext-json: *
• fisharebest/webtrees: ~2.2.0
• magicsunday/webtrees-module-base: ^2.5
• magicsunday/webtrees-module-installer-plugin: ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.50
• overtrue/phplint: ^9.0
• phpat/phpat: ^0.12.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.0 || ^13.0
• rector/rector: ^2.0

GPL-3.0-or-later

• Rico Sonntag

• module
• chart
• statistic
• webtrees

README

• Statistics
  • Installation
    • Manual installation
    • Using Composer
    • Using Git
  • Update
  • Configuration
  • Usage
  • Troubleshooting
  • Development

Statistics

This module provides a six-tab statistics dashboard for the webtrees genealogy application. Above the tabs a dark hero strip carries the tree title and six headline metrics; the tabs themselves group cards thematically per topic (Overview, Names, Tree health, Life span, Family, Places) and render their data through donut / line / bar / stacked / diverging / chord / sankey / stream / world-map / name-bubbles / month-radial / mirror-histogram / gauge widgets from the shared @magicsunday/webtrees-chart-lib.

Installation

Requires webtrees 2.2 and PHP 8.3 or later.

Manual installation

Important

Download the right .zip file. Each GitHub release page lists two kinds of archive:

• ✅ webtrees-statistics.zip — listed under Assets at the bottom of the release. This is the install-ready archive: it bundles the required vendor/ dependencies (such as webtrees-module-base).
• ❌ "Source code (zip)" / webtrees-statistics-<version>.zip — auto-generated by GitHub from the tag. This is the raw source without bundled dependencies. Uploading it to modules_v4/ will fail with Interface "MagicSunday\Webtrees\ModuleBase\…" not found.

Always pick the asset zip, never "Source code (zip)".

Important

If a previous version of this module is already installed: delete the entire modules_v4/webtrees-statistics folder before extracting the new ZIP. Extracting on top of an existing folder leaves stale files behind that can clash with the new release — a common cause of Interface … not found errors right after an update.

1. Open the latest release page.
2. Under Assets, download webtrees-statistics.zip.
3. Upload the .zip file to your web server.
4. Unzip the package into your modules_v4 directory.
5. Rename the folder to webtrees-statistics.

You should now see a modules_v4/webtrees-statistics directory containing the module files.

Using Composer

Run the following command from the root of your webtrees installation:

composer require magicsunday/webtrees-statistics --update-no-dev

The module will automatically install into the modules_v4 directory.

To remove the module:

composer remove magicsunday/webtrees-statistics --update-no-dev

If you are using the development version of webtrees (main branch):

composer require magicsunday/webtrees-statistics:dev-main --update-no-dev

Using Git

Clone the repository directly into your modules_v4 directory:

git clone https://github.com/magicsunday/webtrees-statistics.git modules_v4/webtrees-statistics

Update

To update to the latest version:

• Manual installation: From the latest release Assets section, download webtrees-statistics.zip (not "Source code (zip)"), delete the old modules_v4/webtrees-statistics folder, and extract the new one.
• Composer: Run composer update magicsunday/webtrees-statistics --update-no-dev.
• Git: Run git pull inside the modules_v4/webtrees-statistics directory.

Configuration

1. Go to the Control Panel (admin section) of your webtrees installation.
2. Scroll down to the Modules section and click on Charts (under Genealogy).
3. Enable the Statistics module. Optionally disable the built-in statistics chart to avoid the menu carrying both.
4. Click Save.

Usage

Open the Charts menu on any tree page and select Statistics.

The module renders six tabs that aggregate tree-wide data into widget cards:

Tab	What it shows
Overview	Demographics (sex / living / marital donuts), tree-records hall-of-fame, top occupations and religions, cumulative tree growth over time
Names	Surname / male / female name bubbles, given-name popularity stream graph, surname × surname marriage chord matrix
Tree health	Source-citation coverage (tree-wide + per birth century), pedigree completeness, average generation length, missing-event gaps, generation-depth distribution, known-ancestors distribution, endogamy rate
Life span	Age-at-death histogram + boxplot per century, living life-stages, lifespan by sex × century, top-10 oldest deceased and living, death causes, child mortality + peak century, births by decade (adaptive bin-collapse), births by century / month / zodiac, deaths by century / month, winter-peak score
Family	Age at marriage M+F, marriage duration, couple age gap, weddings by century and month, age at first child, first children by month, children per family, sibling age gap, family-size distribution by decade, average family size, top-10 largest families, divorce cohort rate, divorces by century / month, age at divorce M+F
Places	Birth / residence / death countries with top-10 list and choropleth world map, birth → death migration sankey, geographic dispersion and distinct-places-per-individual metrics

The marital-status donut counts each living individual exactly once — precedence follows the same per-family decision order webtrees core uses in \Fisharebest\Webtrees\Census\AbstractCensusColumnCondition: an active divorce tag classes the survivor as divorced, a deceased partner as widowed, an active marriage with a living partner as current. Anything else falls into single.

The dashboard ships with light- and dark-mode visuals; the module reads data-bs-theme on the <html> element, so themes that toggle dark mode automatically style the charts too.

Troubleshooting

Fatal error after a manual installation or update: Interface "MagicSunday\Webtrees\ModuleBase\…" not found

• You probably downloaded the GitHub-generated "Source code (zip)" instead of the install-ready asset webtrees-statistics.zip. The asset bundles the required vendor/ dependencies; the source zip does not. Open the latest release, scroll to Assets, download webtrees-statistics.zip, and re-extract.
• If you used the asset zip, make sure you deleted the previous modules_v4/webtrees-statistics folder before extracting. Stale files from an older version can shadow the new bundled vendor code and produce the same error.

The Statistics menu entry is missing

• Make sure the module is enabled in the Control Panel under Modules > Charts.
• Check that your PHP version is 8.3 or later.

Charts do not render / tabs are empty

• Clear your browser cache and reload the page.
• Open the browser developer console — a missing widget bundle usually surfaces as a MIME type or 404 error on /index.php?route=…&module=…&asset=js/statistics-<version>.min.js.

The world map shows every country in the empty colour

• Make sure the tree's place data uses recognisable country names — the world-map widget matches free-text country labels to ISO-3166-1 alpha-2 codes across nine pre-seeded locales plus the active webtrees language; unmatched labels fall back to the empty fill.

Development

This section is for developers who want to contribute to the module.

Building JavaScript

Using Docker (no local Node.js required):

make install
make build

Using local Node.js:

npm install
npm run prepare

Running tests

# JavaScript tests
npm test

# Full PHP + JS quality check
composer update
composer ci:test