Add VendorModuleService for Composer-based Webtrees modules

[magicsunday]

Add VendorModuleService for Composer-based Webtrees modules

🚀 Feature: Vendor Module Support via Composer (VendorModuleService)

Overview

This PR introduces a new service class, VendorModuleService, that allows Webtrees to seamlessly load modules installed via Composer.

A key part of this feature is the introduction of a new Composer package type: webtrees-module. This package type signals that a Composer package is a Webtrees extension, making it automatically discoverable and loadable by the Webtrees core.

This modernizes module management and brings Webtrees closer in line with practices used by frameworks such as Symfony, Laravel, and TYPO3.

Why?

Currently, Webtrees modules are installed and managed manually in the modules_v4 directory. While functional, this approach has limitations:

• ❌ No standardized distribution format for third-party modules
• ❌ Manual installation and updates are error-prone
• ❌ No integration with Composer’s dependency management

By enabling Composer-managed modules (via webtrees-module), we provide:

• ✅ A standardized installation process (composer require vendor/package)
• ✅ Automatic updates alongside Webtrees itself
• ✅ A cleaner separation of first-party and third-party modules
• ✅ A familiar workflow for PHP developers who already rely on Composer

This makes Webtrees more attractive to external developers and lowers the barrier for creating and sharing extensions.

How It Works

The VendorModuleService leverages Composer’s InstalledVersions API to:

1. Discover installed Composer packages of type webtrees-module
2. Load and validate their module.php entrypoint
3. Register the module within Webtrees’ existing ModuleService
4. Provide meaningful error handling via FlashMessages

Internally:

• Modules are identified by composer.json → "type": "webtrees-module"
• Installed paths are retrieved via Composer’s runtime API
• Modules are assigned unique names based on their package (_mypackage_)

Benefits

• For Developers: Publish Webtrees modules directly on Packagist, making them discoverable and installable with a single command.
• For Administrators: No need to manually upload files; Composer ensures correct versions and resolves dependencies.
• For the Project: Aligns Webtrees with modern PHP ecosystem practices, ensuring sustainability and extensibility.

📦 Example composer.json for a Webtrees Module

{
  "name": "my-vendor/my-webtrees-module",
  "description": "An example Webtrees module distributed via Composer.",
  "type": "webtrees-module",
  "license": "GPL-3.0-or-later",
  "authors": [
    {
      "name": "Your Name",
      "email": "[email protected]"
    }
  ],
  "require": {
    "php": ">=8.1",
    "fisharebest/webtrees": "^2.2"
  },
  "autoload": {
    "psr-4": {
      "MyVendor\\MyWebtreesModule\\": "src/"
    }
  }
}

[magicsunday]

Together with Webtrees 2.2.4 or dev-main, this can currently be tested using the magicsunday/webtrees-fan-chart package, for example. To do this, the WIP branch must be checked out.

composer require magicsunday/webtrees-fan-chart:dev-WIP

[codecov]

Codecov Report

❌ Patch coverage is 5.17241% with 55 lines in your changes missing coverage. Please review.
✅ Project coverage is 34.92%. Comparing base (94920f4) to head (c1d9570).

Files with missing lines	Patch %	Lines
app/Services/Composer/VendorModuleService.php	0.00%	55 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #5227      +/-   ##
============================================
- Coverage     34.96%   34.92%   -0.04%     
- Complexity    11228    11245      +17     
============================================
  Files          1159     1160       +1     
  Lines         48235    48293      +58     
============================================
+ Hits          16865    16868       +3     
- Misses        31370    31425      +55     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[kiwi3685]

I develop modules purely for my own use. I have no need or interest in using composer. I know there are many others doing the same. For us modules_v4 is simple and works well.

So how does this proposal affect us? There is no mention of users like us in this.

[magicsunday]

Thanks for raising this — it’s an important point.

To be clear: this proposal does not remove or break the existing modules_v4 system. If you are developing modules purely for your own use, or you prefer to keep things simple by dropping files into modules_v4, you can continue to do so exactly as you always have. Nothing changes for you.

What this PR does is add an additional option for distributing and installing modules via Composer, using the new webtrees-module package type. This is mainly targeted at:

• Developers who want to publish their modules to Packagist for broader use
• Administrators who prefer dependency management through Composer
• The Webtrees ecosystem as a whole, to provide a standardized, modern way of sharing extensions

So to summarize:

• ✅ Your existing workflow with modules_v4 continues to be fully supported
• ✅ No existing modules will need to be rewritten or migrated
• ✅ Composer-based modules are an extra path, not a replacement

The goal here is to expand possibilities without taking anything away.

[magicsunday]

Hi @fisharebest, I hope you're well. I'd appreciate it if you'd take a look at this PR. If you find any issues, I'm happy to adjust or improve it. Thank you for your time and feedback!

[ekdahl]

Nice work!
As a module developer, what steps are needed to publish a module, more than adding the JSON file like in your example?
Does this add more dependencies (Composer) for webtrees, or is Composer always installed when I have PHP in for example Debian?

[magicsunday]

Thanks for the kind feedback! Let me clarify:

What steps are needed to publish a module?

• You create a composer.json file for your module with "type": "webtrees-module".
• Add your module code (with module.php as the entrypoint).
• Push your code to a public Git repository (e.g. GitHub).
• Submit it to Packagist.org (which is essentially “the Composer directory”) so that users can install it with a simple composer require vendor/package.

That’s it — Composer takes care of the rest (autoloading, versioning, installation path, etc.).

Does this add more dependencies for webtrees?
No new dependencies are introduced in Webtrees itself. Composer support is already bundled with Webtrees’ development workflow.

• If you install Webtrees from the official release .zip, nothing changes — you don’t need Composer at all.
• If you install Webtrees via composer create-project, you already have Composer on your system.
• On platforms like Debian, Composer is not installed automatically with PHP — but admins who want to install Composer-based modules can install Composer once (apt install composer or via the Composer installer).

So in short:

• ✅ No extra requirement for existing users.
• ✅ Composer is only needed if you want to use Composer-based modules.
• ✅ Module developers benefit from the familiar Composer workflow.

[BertKoor]

As I understand it, this approach will complicate things tremendously for site admins that 'simply' want to install or try out a vendor module.

Currently all that's needed is unzip the module source code into a subdirectory of modules_v4 on their server.

With this mechanism they need to clone the webtrees git repo, edit some file, have a local PHP development environment in order to execute composer install and then upload whatever that has produced to their server.

Thus the requirements for using such modules are raised significantly. Or am I missing something?

[kiwi3685]

Hi @BertKoor
I asked a similar question when this was first presented here (see earliest comment above).
For my purposes this was answered very satisfactorily.
But you should review the answer though, as you may be thinking of something I missed.

[BertKoor]

Thanks for pointing that out, @kiwi3685 . I thought I had read the complete discussion, but apparently I had misunderstood some nuances. You addressed concerns from the point of view of a module developer. It was mentioned that this "does not remove or break the existing modules_v4 system" and I understood that as implying only a simple backwards-compatibility guarantee. There was no explicit mention of impact on site administrators.

Now should I understand that "composer"-ised modules can be installed the old way as well? In my experience more options leads to confusion, especially on unknown territory. And I hope that n>1 for this feature, but I have my doubts.

[magicsunday]

• The existing modules_v4 system remains fully supported — you can still just unzip and use modules as before.

• Modules can still be distributed as ZIP files and installed manually; Composer is only needed if you choose to use it.

• Composer support is an additional option, primarily aimed at:

  • Developers who publish their modules on Packagist (like me)
  • Power users or automated environments where dependency management and versioning via Composer are desirable (like me => https://github.com/magicsunday/webtrees-docker/)
    • My NAS doesn't allow me to install additional packages like PHP, etc. Therefore, I've put together a Docker development environment that makes me completely independent of the host OS.
    • With Docker, I package my development environment into a self-contained "box." I can run any PHP or database version I want without touching my NAS/host system. The box is reproducible (everyone gets exactly the same environment with docker compose up), isolated, and can be removed at any time without leaving any residue. This way, I avoid "only runs on me" issues, keep the host clean, and can quickly test or share production-level setups.

@fisharebest
Have you had a chance to take a look at it yet?