[somethingwithproof]

Title

Bring the README in line with the code on the default branch

Description

The README was short and several statements no longer matched the code. This PR rewrites it against origin/develop (13159fc) and checks each statement by reading the code or running the command. No PHP, JavaScript or SQL is touched.

• README.md: requirements, optional plugins, install, upgrade and uninstall as they behave now, realms and who gets which panels, dashboards and sharing, favorite graphs, settings with defaults and values, the poller script and its options, the panel list, the tables, how to add a panel library, translations, and the development and test commands. The old bullet list of panels is replaced by the real list. The 2018 screenshot is replaced by a current one (images/intropage-dashboard.png, taken on Cacti 1.2.32 with demo devices).
• panellib/README.md: the description of how to write a panel followed keys that do not exist (interval) and said trend functions were not implemented. It now documents the keys the code reads, with an example that was run on both cores.
• INFO: deverlopers@cacti.net is a typo of developers@cacti.net (the address used in the plugin's translation template). Nothing else in INFO or manifest.json was wrong.

Statements in the old README that were wrong or incomplete, and what replaces them:

• Installing: "Enable plugin" is not enough; the plugin has to be installed first, and it stays disabled (status 4) until it is enabled.
• The user permission page is under Console > Configuration > Users, not "Console > Users".
• The panels "will not start rendering until at least one user has access to a Panel" is not what the code does. The poller refreshes every stored panel row; system panel rows exist from the installation.
• Favorite graphs are "rendered in SVG format only": graph_image.php uses the image format of the graph (PNG or SVG).
• "Copy one of the existing directories" for a new panel library: the libraries are files, and a plugin cannot supply one from its own directory.
• Upgrade: removing the old directory also removes any panel library file added to panellib, and the upgrade removes tests/ and phpunit.xml; both are now stated.

Found while checking and left alone because this PR does not change code:

• The settings "How often analyze DB", "How often check NTP" and "How often check DNS" are never read by any code. The README says so.
• --force of poller_intropage.php is parsed and listed in the help but the variable is never used.
• The description of the admin alert setting says HTML tags are allowed; the panel escapes the text.
• intropage_add_panel() and intropage_remove_panel() still exist and fail (see the table). A separate PR deals with them.
• tests/Security/PhpCompatibilityTest.php says Cacti 1.2 fails to start below PHP 8.0; Cacti 1.2.32 checks for PHP 8.2 (include/vendor/composer/platform_check.php:7).
• locales/po/ka-GE.po has no compiled locales/LC_MESSAGES/ka-GE.mo.
• locales/build_gettext.sh prints cat: include/cacti_version: No such file or directory in a plugin checkout and then works.

Related Issue

No tracking issue.

Motivation and Context

Someone installing or upgrading the plugin, or writing a panel, should be able to follow the README. Following the old panellib/README.md example produced PHP warnings and a fatal TypeError (run below).

How Has This Been Tested?

Environment: Cacti 1.2.32 (the 1.2.x branch, cloned) and the Cacti development branch (1.3.0 dev), PHP 8.3, MariaDB 11.8.9, in Docker; plugin from this branch's parent (origin/develop). Both cores were used for every command unless one is named. Not available here: Cacti 1.2.17 itself, PHP 8.0 to 8.2 and 8.4, a web browser. The three files changed here have no tests of their own; the repository's checks still pass (72 passed, 1 skipped, 1 warning as on origin/develop; validate-manifest.php and check-i18n-pot.php pass).

Verification table. "Ran" means the command was executed and the result is given; otherwise the evidence is the file and line on origin/develop.

README statement	Result	Evidence
Cacti 1.2.17 or later	Confirmed as declared, not run on 1.2.17	INFO:29 compat = 1.2.17; 1.2.32 and development ran
Tested in CI against 1.2.x	Confirmed	.github/workflows/plugin-ci-workflow.yml CACTI: 1.2.x
Installs, enables and polls on development	Confirmed	Ran: plugin_manage.php --plugin=intropage --install --enable, then poller_intropage.php --debug, exit 0
PHP 8.0 or later for the code	Confirmed	tests/Security/PhpCompatibilityTest.php (no post-8.0 functions); str_contains used in includes/functions.php
Cacti 1.2.32 needs PHP 8.2, development 8.3	Confirmed	include/vendor/composer/platform_check.php:7 in each tree (PHP_VERSION_ID >= 80200 / 80300)
Poller script started after each cycle with the PHP Binary Path, php if empty	Confirmed	setup.php:530-544 (poller_bottom, path_php_binary); setting is on the Paths tab (include/global_settings.php, 'path' array)
Data Source Statistics (Settings > Data) for the Busiest panels and Analyze DS stats	Confirmed	panellib/busiest.php:204 and eleven more, panellib/analyze.php:1194; setting dsstats_enable is in the 'data' array
PHP sockets for the NTP check, listed as required by Cacti	Confirmed	includes/functions.php:2258 socket_create; Cacti lib/utility.php:2523 lists sockets
thold panels: Last Threshold Events, Threshold, 24 Hour Extremes	Confirmed	panellib/thold.php:91,109, panellib/system.php:134 (requires)
syslog (3), mactrack (2), maint, webseer, servcheck panels	Confirmed	panellib/syslog.php:61,79,97, mactrack.php:61,79, misc.php:79,97,115
Analyze Cacti Objects uses monitor and thold	Confirmed	panellib/analyze.php:1033 (monitor), :810 (thold, log-only thresholds)
Panels hidden until the plugin is installed; message when installed but not enabled	Confirmed	Ran: initialize_panel_library() returns 29 panels with no other plugin, 40 is the count with all in the source; includes/functions.php:1525-1560; e.g. panellib/mactrack.php:114
Maint panel first on the first dashboard when the setting is not "Never warn"	Confirmed (for a user who has the panel)	display.php:541-551
"Automatically Uninstall Panels" removes stored panels of a missing plugin	Confirmed	includes/functions.php:1503-1520
Install then enable; not active until enabled	Confirmed	Ran on both cores: after --install plugin_config.status is 4, after --enable 1; 7 tables, 20 hooks (2 enabled until enabling), realms 2 and 3
Command line install and enable	Confirmed	Ran: php cli/plugin_manage.php --plugin=intropage --install --enable
Settings under Console > Configuration > Settings > Intropage	Confirmed	includes/settings.php:54
Permissions under Console > Configuration > Users (and User Groups) > Intropage tab	Fixed (old text said "Console > Users")	Cacti include/global_arrays.php:1046-1049 (1.2) and :1135-1138 (development); includes/settings.php:155-195 adds the tabs
Only the admin user has the realms after install	Confirmed	Ran: user_auth_realm has rows only for user 1 (realms 102 and 103)
Realms and roles	Confirmed	setup.php:85-86, :190-191; display.php:407 (Reload Panel Definitions), includes/functions.php intropage_action_settings (admin realm)
The installing user gets every panel; CLI install gives it to the admin user	Confirmed	includes/database.php:57-70, :171-182; Ran: user 1 had 29 panels after a CLI install
New and copied users get all user level panels and Favorite Graphs, no system panels	Confirmed	Ran intropage_new_user_permission(99): 17 panels, 0 system panels, favourite_graph on; includes/settings.php:665-703
Existing users see an empty dashboard until they get panels	Confirmed	display.php:494-531 ("Welcome to Intropage!")
Upgrade: replace files, then enable or open the dashboard	Confirmed	Ran on both cores: stored version 4.0.4 with the height columns dropped; --enable set version 4.0.5 and added the columns; includes/database.php:208-402; Cacti calls check_config on install and enable (lib/plugins.php api_plugin_check_config, api_plugin_enable)
The upgrade removes include/, themes/, tests/, phpunit.xml, and logs other unknown top-level entries	Confirmed	Ran: a stray file was left and logged not described in manifest.json: stray-file.txt; tests/ and an include/ directory were gone afterwards; setup.php:321-437, manifest.json:2-5
Old directory removal also removes added panel libraries	Confirmed by the previous row (the directory is replaced)	includes/functions.php:1525 loads only panellib/*.php
Uninstall drops the 7 tables, hooks, realms, intropage_* settings, resets the login option	Confirmed	Ran on both cores: 0 tables, 0 hooks, 0 realms, 0 settings left; user_auth.login_opts 4 became 1; includes/database.php:34-44
settings_user rows are kept	Confirmed	Ran: one intropage_autorefresh row remained after uninstall
Up to 9 dashboards, the first cannot be removed	Confirmed	display.php:300, :304
Panels list, cog, Actions list, timespan list, move/resize/reload/disable	Confirmed by reading	display.php:270-480, includes/intropage.js, includes/cards/cards.js; not seen in a browser
Sharing: copies panels and data, permission checked on open, empty dashboard cannot be shared	Confirmed	includes/functions.php case 'useshared', display.php:439-477 (:452), display.php:119-154
Login placement labels	Confirmed	display.php:410-425
Eye icon adds a favorite graph; not for a custom timespan; needs the Favorite Graphs panel	Confirmed	includes/functions.php:2338-2371
Image format of the graph, not SVG only	Fixed (old text said SVG only)	graph_image.php:54-77 in both Cacti trees
Settings table (names, defaults, values)	Confirmed	Ran: values printed from includes/variables.php after loading it in Cacti; defaults and options copied from that output
Three *_interval settings are not read	Confirmed	grep for ntp_interval, dns_interval, analyse_db_interval over all PHP and JS: only includes/variables.php:125,158,176
Admin alert is plain text, shown on the first dashboard when longer than 3 characters	Confirmed	panellib/system.php:354 (html_escape), display.php:555
Poller options --debug, --version, --help; --force has no effect	Confirmed	Ran all three; poller_intropage.php:45,71-72,171,183 ($force is set and declared but never read)
One copy at a time, second start ends quietly	Confirmed	poller_intropage.php:99-105
Moves the plugin first in the plugin order on each run	Confirmed	poller_intropage.php:107-108,134-155
Trend values kept 2 days	Confirmed	poller_intropage.php:306-314
Panel list by group, level and needs	Confirmed	Ran: the 29 panels with their level, class and requires printed from the registered definitions; the other 11 from the requires lines above
Seven tables	Confirmed	Ran: SHOW TABLES LIKE 'plugin_intropage%' returned 7; includes/database.php:57-194
Panel library: files in panellib, register_<name>(), $registry, unique ids	Confirmed	includes/functions.php:1525-1536; Ran: the example in README.md and panellib/README.md registered and stored its data on both cores
Following the old panellib/README.md example	Wrong, now fixed	Ran: PHP warnings for class, refresh, trefresh and a fatal TypeError in intropage_readable_interval() on both cores
Reload Panel Definitions after adding a file	Confirmed	includes/functions.php case 'forcereload', update_registered_panels() at :1612
A plugin cannot add a panel from its own directory	Confirmed	only plugins/intropage/panellib/*.php is globbed
intropage_add_panel() does not work	Confirmed	Ran on both cores: returns DB Exec Failed ... Unknown column 'file', no definition row; setup.php:577-587, :604 (DROP ?)
Text domain intropage, files in locales/LC_MESSAGES/<language>.mo	Confirmed	Cacti include/global_languages.php:111-124,255
sh locales/build_gettext.sh, sh locales/build_mo.sh	Confirmed	Ran in a Debian container with gettext installed, from a copy of the tree: build_gettext.sh exit 0 (rewrote cacti.pot, merged 22 .po, wrote .mo), build_mo.sh exit 0
Language list, ka-GE without .mo	Confirmed	ls locales/po locales/LC_MESSAGES
include/vendor/bin/pest --configuration=plugins/intropage/phpunit.xml	Confirmed	Ran from the Cacti directory on both cores: 72 passed, 1 skipped, 1 warning, with tests/.cacti-version set to 1.2.x and to develop
tests/.cacti-version 1.2.x accepts any release	Confirmed	tests/bootstrap-unit.php check; Ran with 1.2.x on the development branch
--coverage-clover=plugins/intropage/coverage/clover.xml	Confirmed	Ran with Xdebug; file written
php tests/bin/validate-manifest.php, check-i18n-pot.php origin/develop, patch-coverage.php coverage/clover.xml origin/develop 100	Confirmed	Ran from the plugin directory: all exit 0 (patch coverage reports "no measured lines changed" because the diff has no PHP)
CI workflow description	Confirmed	.github/workflows/plugin-ci-workflow.yml
docs.cacti.net link, GitHub issues link	Confirmed	curl returned 200 for each
Forum link	Not verified	curl returned 403 (it blocks scripts); kept
Screenshot shows the current page	Confirmed	images/intropage-dashboard.png was captured from Intropage 4.0.5 on Cacti 1.2.32 with nine panels; the old external image is no longer linked

Rollback

Revert the merge commit. Documentation only, plus one character fix in the INFO address.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation repository accordingly.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud