Skip to content

Add third-party panel registration API - #468

Merged
TheWitness merged 14 commits into
developfrom
feature/panel-registration-api
Nov 11, 2026
Merged

TheWitness merged 14 commits into
developfrom
feature/panel-registration-api

Conversation

@TheWitness

@TheWitness TheWitness commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds a third-party panel registration API so other Cacti plugins can publish their own Intropage dashboard panels at runtime — without copying a file into Intropage's panellib/ directory.

A foreign plugin guards each call with function_exists() and calls intropage_register_panel() (typically from its config_arrays/install hook). Registered panels behave exactly like the built-in panellib panels: Intropage polls them, users can be granted them and add them to dashboards, and they are automatically removed everywhere when the owning plugin is uninstalled.

What's included

  • New table plugin_intropage_panel_registration storing the owning plugin name, the callback functions (update_func/details_func/trends_func + include_file), the declared request variables and their types (request_vars JSON), and the full panel attribute set. Created on install and via a 4.1.0 upgrade step; dropped on uninstall.
  • includes/registration.php — the public API:
    • intropage_register_panel($panel) — register / fully replace (validates, persists, and immediately publishes an enabled panel into the definition/data tables)
    • intropage_update_panel_registration($panel_id, $fields) — patch selected attributes
    • intropage_enable_panel_registration($panel_id) / intropage_disable_panel_registration($panel_id)
    • intropage_unregister_panel($panel_id) (delete) and intropage_unregister_plugin_panels($plugin)
    • helpers: intropage_get_panel_registration(s)(), intropage_validate_request_vars(), intropage_prune_stale_registrations()
  • Panel-library integration — initialize_panel_library() merges enabled registrations (whose plugin is installed), including their callback file, without clobbering built-in panels.
  • Automatic cleanup — intropage_prune_stale_registrations() runs on every poller cycle and every dashboard view; when a plugin is uninstalled its panels are stripped from all dashboards, data, definitions and permissions. A merely disabled plugin keeps its registration (its panels simply stop rendering via the requires gate).
  • Security — include_file paths are constrained to existing .php files beneath plugins/ (no traversal / arbitrary include); all writes use prepared statements.
  • Docs — README.md gains a "Registering panels from another plugin" section documenting the full schema (every attribute, type, default and options), the request_vars sub-schema and types, every API call, the lifecycle/pruning behavior, and a complete worked example. panellib/README.md cross-references it.
  • Tests — tests/Unit/IntropagePanelRegistrationTest.php covers validation, the request-var spec, defaults, the include-file guard and the row→library mapping.

Version

Bumps INFO to 4.1.0 with a matching CHANGELOG.md entry and an idempotent upgrade migration.

Validation

  • php -l clean on every changed PHP file.
  • Registration validation, request-variable sanitization and library mapping verified with a standalone harness (logic mirrored in the committed Pest unit test). The full Pest suite runs in CI.

Review notes

  • plugin governs installed/uninstalled pruning; requires (defaulting to the owning plugin) governs enabled/disabled runtime gating — mirroring how built-in panels already work.
  • Re-registering an existing panel_id is idempotent, so plugins can safely register on every page load to keep definitions in sync.

Allow other Cacti plugins to publish their own Intropage dashboard panels
at runtime, without copying a file into Intropage's panellib/ directory.

Plugins call intropage_register_panel() (guarded by function_exists) plus the
companion update/enable/disable/unregister calls. Registrations are stored in
the new plugin_intropage_panel_registration table (owning plugin, callback
functions, declared request variables and their types, and the full panel
attribute set), merged into the live panel library by
initialize_panel_library(), and seeded into the definition/data tables so they
poll and render like native panels.

intropage_prune_stale_registrations() runs on every poller cycle and every
dashboard view to remove registrations whose owning plugin is no longer
installed, stripping the panel from all dashboards, data, definitions and
permissions.

The panel schema and every API call are documented in README.md; a focused
unit test covers the validation and mapping helpers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 7, 2026 19:31

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved critical flaws allow registration to bypass panel permissions and overwrite or delete built-in panels.

10 open issues
What changed in this PR

Adds an API for other Cacti plugins to register Intropage dashboard panels without copying files into panellib/.

Changes:

  • Introduces persistent panel registration, lifecycle APIs, callback loading and request-variable validation.
  • Integrates registered panels into the library and adds stale-registration cleanup during polling and dashboard views.
  • Adds API documentation and unit tests, with a registration-table migration and version bump to 4.1.0.
File Description
tests/​Unit/​IntropagePanelRegistrationTest.php Tests registration validation, defaults, path guards and definition mapping.
README.md Documents the API, schema, lifecycle and integration example.
poller_intropage.php Prunes stale registrations before polling.
panellib/​README.md Points third-party plugins to the registration API.
INFO Bumps the plugin version to 4.1.0.
includes/​registration.php Implements registration, publication, cleanup and validation helpers.
includes/​functions.php Loads the API and merges registered panels into the library.
includes/​database.php Adds registration-table installation, migration and removal.
display.php Prunes stale registrations before dashboard rendering.
CHANGELOG.md Records the third-party panel registration feature.

Review effort: Balanced

Comment thread includes/registration.php Resolved
Comment thread includes/registration.php Resolved
Comment thread includes/database.php Resolved
Comment thread includes/functions.php Resolved
Comment thread includes/registration.php Resolved
Comment thread includes/registration.php Resolved
Comment thread includes/registration.php Resolved
Comment thread includes/registration.php Resolved
Comment thread includes/registration.php Resolved
Comment thread includes/registration.php Resolved
The uninstall contract test counted DROP TABLE statements and expected 7;
the new plugin_intropage_panel_registration table makes it 8, so update the
expectation.

Also fix a pre-existing typo in initialize_panel_library()'s auto-unregister
cleanup, which deleted from the non-existent plugin_intropage_definition table
instead of plugin_intropage_panel_definition, leaving a stale definition row
and raising a SQL error whenever a panel's required plugin was uninstalled.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xmacan
xmacan previously approved these changes Nov 7, 2026
The patch-coverage gate requires every changed production line to be exercised.
Cover the database-backed registration functions (register/update/enable/
disable/unregister, prune, load, request-variable validation, admin grant and
permission cleanup) with in-process unit tests driven by the bootstrap stubs.

To make the two hard-to-reach blocks of initialize_panel_library() testable in
isolation, extract them into intropage_unregister_missing_panels() (which now
also owns the intropage_unregister guard, so the call site is unconditional and
always exercised) and intropage_merge_registered_panels(). Make the unit
bootstrap's db_table_exists() stub configurable via $GLOBALS['__test_tables']
(defaulting to false, so existing tests are unaffected) so the
registration-table-guarded paths can run.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
TheWitness and others added 3 commits November 7, 2026 15:01
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Act on the code-review findings on the registration API:

- Reject numeric, over-length, built-in, and cross-plugin panel ids before
  persisting; only the owning plugin may re-register or withdraw its panels
  (intropage_registration_conflict()).
- Resolve the permission-grant target from the configured admin user instead of
  the current session visitor, so registering on an ordinary user's page load
  cannot grant that user panels.
- Expose the API from setup.php (loaded for every enabled plugin at start-up) so
  a foreign plugin's config_arrays hook sees it regardless of plugin order.
- Enforce the requires gate in intropage_reload_panel()/intropage_detail_panel()
  so a panel stops executing callbacks once its plugin is disabled.
- Register a fallback $registry category for loaded registrations so the
  permission editors render their category heading.
- Use FILTER_NULL_ON_FAILURE for boolean request vars and reject non-scalar
  request-variable input instead of coercing it to 'Array'.
- Invalidate initialize_panel_library()'s static cache (not just the session
  snapshot) on every registration mutation.
- Validate registration string lengths against the live panel_definition column
  widths so a published registration never overflows or truncates.

Extend the unit tests to cover every new path.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xmacan
xmacan previously approved these changes Nov 8, 2026
xmacan
xmacan previously approved these changes Nov 9, 2026
@TheWitness

Copy link
Copy Markdown
Member Author

Advice re: rendering third-party cards (card + chart scope)

Following up on the intent here — Intropage presenting any card from any plugin — with a concrete analysis of what a registered panel can actually render.

What the registration delivers today: a panel supplies PHP only (update_func/details_func + include_file); the callbacks return HTML. There is no css/js attribute, so a card can only rely on assets already present on the Intropage page.

The charting pieces the dashboard plugins use (gauges, bullets, usage/stacked bars) are currently pinned per-plugin — .hmibDashGauge*/.hmibBullet*, .apcupsdGauge*/.apcupsdBullet*, .mtdashBar* — each defined in that plugin's own stylesheet. They're structurally identical (triplicated) and JS-free (inline SVG + CSS classes), but CSS-class-dependent.

So: a third-party card using those primitives renders correctly in Intropage only incidentally — if the owning plugin happens to load its content CSS on every page. A plugin that scopes its CSS to its own pages would have its Intropage card render unstyled.

Fix (done in core): Cacti/cacti#8680 now ships a shared, themeable .cc* card-widget library (include/css/card-widgets.css + card_gauge()/card_bar()/card_bullet()/card_stackbar()/card_stat() helpers), loaded globally by the common header. Because Intropage then has the primitives loaded, any card built on them renders correctly with zero per-plugin asset wiring — turning "render any card from any plugin" into a reliable contract for the common rich-card case, and removing the triplication. The dashboard plugins are being converged onto these shared primitives.

Remaining gap for this PR to consider (so the promise fully holds beyond the shared primitives):

  1. Bespoke content CSS — a plugin widget not in the shared set: either inline the styles in the callback HTML, or add an optional css_file attribute Intropage enqueues when the card is present.
  2. JS-driven cards (the "ready function / inline js" case, e.g. a billboard chart) — the hard one. Intropage's strict, nonce-based CSP blocks third-party inline <script>. d3/billboard are in core (available), but the init call isn't. Supporting JS cards needs a nonce-aware channel — a declared js_file Intropage enqueues with its own nonce, or a registered client-init callback Intropage invokes after inserting the card — not raw inline JS. The shared JS-free primitives are exactly what let rich cards avoid JS and side-step this.

Suggestion: keep #468's PHP-callback model, lean on the shared .cc* primitives for rich content, and add optional css_file / nonce-aware js_file attributes to the registration schema for bespoke/JS cards.

TheWitness and others added 6 commits November 11, 2026 13:10
…urce prefixes

Make the registration table the single catalog of every panel (core and
third-party) and read from it instead of rebuilding the library from disk on
every request:

- Poller sync: intropage_sync_core_registrations() stats each panellib/*.php
  file's mtime and, when a file changes (or is added/removed), re-runs its
  register_<basename>() and upserts its panels as Intropage-owned ('intropage')
  core registrations. Runs each poller cycle (cheap when nothing changed) and
  at install/upgrade. A panel's enabled flag is preserved across syncs.

- Enable/Disable: the registration enabled flag now governs the whole library.
  initialize_panel_library() drops disabled panels (core or third-party) so the
  poller, panel picker and is_panel_enabled() skip them and the dashboard render
  loop hides them, all non-destructively (data and placements are retained).

- Management page: Console > Intropage > Panel Library (intropage_panels.php,
  guarded by the new Intropage Panel Library realm) lists every registered panel
  in a filterable, sortable table with a free-text search, a Source (plugin)
  dropdown and Enable/Disable bulk actions. Columns: Panel Name, Source,
  Category, Level, Requires, Refresh, Update Function, Status.

- Source prefixes: panel titles are prefixed by origin wherever the definition
  name is rendered (cards, detail dialog): 'Core - ' for Intropage's own panels
  and the title-cased plugin name for third-party panels.

- The built-in-id conflict guard now lets the reserved 'intropage' owner adopt
  its own built-ins while still blocking foreign plugins from shadowing them.

Covers the new logic with unit tests (source prefixing, disabled filtering,
enable/disable, the mtime sync and withdraw paths, the menu/navigation wiring)
and allowlists the new web entry point for patch coverage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…into feature/panel-registration-api

# Conflicts:
#	CHANGELOG.md
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
SonarCloud flagged the search, source and rows filter controls as inputs
without an associated label (Web:InputWithoutLabelCheck). Wrap each filter
caption in a <label for=...> tied to its control.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Bump the INFO `compat` floor from 1.2.17 to 1.2.29 and update the matching
references in the README requirements, the PHP compatibility test note, the
database upgrade comment and the repository instructions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@sonarqubecloud

Copy link
Copy Markdown

@TheWitness
TheWitness merged commit 4d90a7d into develop Nov 11, 2026
10 checks passed
@TheWitness
TheWitness deleted the feature/panel-registration-api branch November 11, 2026 19:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants