Bug 41651 - Allow plugins to specify additional dependencies
Summary: Allow plugins to specify additional dependencies
Status: Needs Signoff
Alias: None
Product: Koha
Classification: Unclassified
Component: Plugin architecture (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement
Assignee: HKS3 Tadeusz Sośnierz
QA Contact: Testopia
URL:
Keywords:
Depends on:
Blocks: 41720
  Show dependency treegraph
 
Reported: 2026-01-16 14:11 UTC by HKS3 Tadeusz Sośnierz
Modified: 2026-01-27 09:04 UTC (History)
7 users (show)

See Also:
GIT URL:
Initiative type: ---
Sponsorship status: ---
Comma delimited list of Sponsors:
Crowdfunding goal: 0
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
Circulation function:


Attachments
Bug 41651: Allow plugins do specify dependencies, abort installation if unmet (6.61 KB, patch)
2026-01-16 14:14 UTC, HKS3 Tadeusz Sośnierz
Details | Diff | Splinter Review
Bug 41651: Allow plugins do specify dependencies, abort installation if unmet (5.67 KB, patch)
2026-01-19 14:47 UTC, HKS3 Tadeusz Sośnierz
Details | Diff | Splinter Review
Bug 41651: Allow plugins to specify dependencies, abort installation if unmet (5.75 KB, patch)
2026-01-27 08:06 UTC, Martin Renvoize (ashimema)
Details | Diff | Splinter Review
Bug 41651: (QA follow-up) Fix issues in plugin file copy (4.21 KB, patch)
2026-01-27 08:06 UTC, Martin Renvoize (ashimema)
Details | Diff | Splinter Review
Bug 41651: (follow-up) Improve plugin dependency handling (3.71 KB, patch)
2026-01-27 08:06 UTC, Martin Renvoize (ashimema)
Details | Diff | Splinter Review
Bug 41651: (follow-up) Add test coverage for dependency checking (11.40 KB, patch)
2026-01-27 08:06 UTC, Martin Renvoize (ashimema)
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description HKS3 Tadeusz Sośnierz 2026-01-16 14:11:16 UTC
Koha plugins cannot currently declare any dependencies. Not meeting them will occcasionally fail upon installation (if the main plugin class tries to load them at compile time) or runtime (if one of the other packages does, or code cleverly checks if the dependency is met).

Ideally we'd have a way of specifying if a Koha plugin depends on another Perl module, or another Koha plugin. A nice feature of this would be to able be able to declare optional dependencies, which may only be required for a subset of the Plugin's features (like in https://github.com/HKS3/koha-normalize-marc2db/blob/main/Koha/Plugin/HKS3/NormalizeMARC2DB/Jobs/VerifyAll.pm#L34). Those shouldn't prevent installation, but should still warn loudly upon plugin installation, in a way that is hard/impossible to miss (e.g. have an intermitted screen on plugins-upload.pl, with an "are you sure").

Patch incoming.
Comment 1 HKS3 Tadeusz Sośnierz 2026-01-16 14:14:39 UTC
Created attachment 191567 [details] [review]
Bug 41651: Allow plugins do specify dependencies, abort installation if unmet

This approach uses a new $metadata key, to minimize the scope of changes needed.
The downside of that is the fact that if the base plugin package requires
those dependencies in compile-time already, the code (and thus metadata itself)
will fail to load in an unhandled way.

plugins-upload.pl can't know for sure whether it's really the plugin being installed
that doesn't have its dependencies met, which is a limitation to how it currently works.
Comment 2 HKS3 Tadeusz Sośnierz 2026-01-19 14:47:18 UTC
Created attachment 191651 [details] [review]
Bug 41651: Allow plugins do specify dependencies, abort installation if unmet

This unpacks uploaded plugin into a temporary directory where we check
the prerequisites/conflicts in standard CPAN ways, and only continue
with the installation if all the runtime requirements are met.
Comment 3 Martin Renvoize (ashimema) 2026-01-27 08:06:38 UTC
Created attachment 192087 [details] [review]
Bug 41651: Allow plugins to specify dependencies, abort installation if unmet

This unpacks uploaded plugin into a temporary directory where we check
the prerequisites/conflicts in standard CPAN ways, and only continue
with the installation if all the runtime requirements are met.

Signed-off-by: Martin Renvoize <martin.renvoize@openfifth.co.uk>
Comment 4 Martin Renvoize (ashimema) 2026-01-27 08:06:39 UTC
Created attachment 192088 [details] [review]
Bug 41651: (QA follow-up) Fix issues in plugin file copy

We're focusing on reliability and security here, the improvements
include:

- Escape regex metacharacters in path using \Q...\E to prevent
  regex injection issues
- Check copy() return value and collect errors, die if any
  copies fail to prevent silent partial installations
- Make basename filter more specific to only skip cpanfile and
  META.json/META.yml, not files containing "META" anywhere
Comment 5 Martin Renvoize (ashimema) 2026-01-27 08:06:40 UTC
Created attachment 192089 [details] [review]
Bug 41651: (follow-up) Improve plugin dependency handling

The original patch was a great start, but I saw some area's for
improvement including listing all missing dependencies as apposed to
just the first.

- Add POD documentation for the new 'from' parameter in InstallPlugins()
- Normalize staging directory path by removing trailing slashes to
  prevent double-slash issues in destination paths
- Fix path concatenation to avoid double slashes (plugins_dir already
  ends without slash, destdir starts with slash after substitution)
- Report all unmet dependencies at once instead of dying on the first
  one, providing better user feedback
- Add 'last' to break out of metafiles loop once a file is found
Comment 6 Martin Renvoize (ashimema) 2026-01-27 08:06:41 UTC
Created attachment 192090 [details] [review]
Bug 41651: (follow-up) Add test coverage for dependency checking

Tests for _check_dependencies():
- No dependency files present (passes silently)
- cpanfile with satisfied dependencies (passes)
- cpanfile with unmet dependencies (dies with message)
- META.json with satisfied dependencies (passes)
- META.yml with satisfied dependencies (passes)
- META.json with unmet dependencies (dies)
- Multiple unmet dependencies are all reported

Tests for InstallPlugins() with 'from' parameter:
- Files are copied from staging to plugins directory
- cpanfile is NOT copied to plugins directory
- META.json is NOT copied to plugins directory
- META.yml is NOT copied to plugins directory
- Trailing slash in path is handled correctly