[somethingwithproof]

docs: describe the plugin as it behaves today

Description

Rewrites README.md so each statement matches the default branch as it is now, including the merged get_request_var() change (#58). The old README was a stub: it did not say what to install, which versions are supported, how the import works, which realm to grant, what the plugin stores, or how to run the tests, and it carried a note about a Cancel button that no page of this version draws. Only README.md changes. No code, INFO or manifest.json change, because nothing in them was wrong.

Base: origin/main at 34138d8.

Related issue

None.

Motivation and context

An administrator reading the README could not tell what the plugin needs or what it does to the database. A few facts that matter in practice were nowhere in the repository's documentation: one realm covers viewing, uploading and deleting; the address and name columns are narrow, so IPv6 clients and MySQL's Id: suffix are stored wrongly; the page lifts PHP's limits for every request; uninstalling drops all imported data.

How has this been tested?

Every claim was checked against the code or by running it. The environment was a throwaway Cacti 1.2.x tree (a local branch at 1.2.32) with the plugin from origin/main and MariaDB 11.8.9, PHP 8.4. The commands and results are in the table below. Two statements rest on code or the workflow only and are marked as such.

README statement	Result	Evidence
Needs Cacti 1.2.29 or later in the 1.2 series	confirmed	INFO:8 compat = 1.2.29; the CI workflow clones CACTI: 1.2.x (.github/workflows/plugin-ci-workflow.yml, env). Installed and ran on 1.2.32 here; 1.2.29 itself was not run
PHP: return and nullable types, so 7.1 or later; CI checks syntax on 8.2, 8.3, 8.4	added	function display_version(): void (import_log.php:175), ?string $table_mode (includes/functions.php); matrix php: ['8.2', '8.3', '8.4'] and the "Check PHP Syntax for Plugin" step. Only 8.4 was run here; 7.1 was not run
MariaDB: Aria for the three per-query tables; MySQL: InnoDB	added	includes/database.php:38-45; SELECT table_name, engine FROM information_schema.tables on MariaDB 11.8.9 showed Aria for _details, _details_methods, _details_tables and InnoDB for the rest
Needs Cacti's path_php_binary for uploads	added	slowlog.php:171 and includes/functions.php:1238 start the importer with it; the upload test in the throwaway tree worked with the setting present
No remote poller support	added	INFO:9 remote_collect:0, offline_view:0, offline_mgmt:0
Old note about a Cancel button needing layout.js on Cacti before 1.2.31	removed	grep cactiReturnTo finds one use in the plugin, slowlog_save_button() in slowlog.php, which no code calls. No page of this version draws such a button. (Core did gain the handler in 1.2.31: release/1.2.31:include/layout.js:775.) #60 adds No and Return buttons that use it, so its README change should restore the note
Install with plugin_manage.php --install --enable	confirmed	ran it: "Plugin slowlog installed successfully." and "enabled."; plugin_config row slowlog / 2.6 / status 1
Install creates the eight tables and loads the reserved words	confirmed	SHOW TABLES LIKE 'plugin_slowlog%' listed the eight tables of the README; 776 words in plugin_slowlog_reserved_words; includes/database.php:265 reads docs/keywords.txt
Install registers one realm and gives it to admin	confirmed	plugin_realms row 2 / slowlog / slowlog.php / Plugin -> MySQL Slow Log Viewer; user_auth_realm row for user 1, realm 102; setup.php:59
One realm covers view, upload and delete	confirmed	setup.php:59 is the only api_plugin_register_realm; the upload (form_save) and delete (form_actions) handlers are in slowlog.php, which that realm gates; an upload and the other pages all answered 200 for a user holding only that realm
No settings	confirmed	setup.php:263 slowlog_config_settings() adds an empty array to the Misc tab
Upgrade runs on plugins.php or slowlog.php when the version differs; prunes tombstones, tests/ and phpunit.xml; warns about unlisted files	confirmed	set plugin_config.version to 2.5 and ran slowlog_check_upgrade(): themes/, keywords.txt, tests/ and phpunit.xml were removed, the version went to 2.6, and the Cacti log showed "slowlog upgrade found a file/directory not described in manifest.json: stray.txt (left in place)"; setup.php:362-472
Disable keeps the data	confirmed	--disable: status 4, 8 tables left
Uninstall drops the tables, the realm and the grants	confirmed	--disable then --uninstall: 0 plugin_config rows, 0 tables, 0 realm rows, 0 grants, 0 hooks
Upload form fields and choices	confirmed	form page contained import_file, description, length, table_mode, table_names, and the "Max Upload Filesize / Max Post Size / Max Execution Time / Memory Limit" rows; length choices All, 1024 to 16384 Chars; the three table modes (HTML read back)
Upload runs in the background, staged file removed	confirmed	uploaded a small log by HTTP: record created, status reached 2, "All Tables Processed"; --delete-after in the worker command
Statuses Pre-Processing, Post-Processing, Complete, Bad File Format; refresh every five seconds while queued	confirmed	slowlog.php status labels; refreshMSeconds = 5000 (slowlog.php:1884) when a row has status 0
CLI options	confirmed	php plugins/slowlog/import_log.php --help printed the usage; --table-mode=x gives "Invalid --table-mode value"; --table-mode=reference without names gives "requires --table-names"; options read from the parser (import_log.php). The help text is wrong for --usecacti (it says "The logid ..."); the README describes the behaviour, not that line
--delete-after deletes also for a file that is not a log	changed	import_log.php:149; ran an import of a non-log file with a pre-created record and --delete-after: the record went to status 3 (Bad File Format) and the file was gone afterwards
--length cuts bytes	confirmed	includes/functions.php:1002 substr()
List mode when --table-names is given without --table-mode	confirmed	import_post_process() infers list; imported a log with --table-names='host graph_local' and no mode: only graph_local,host were associated, while the default mode found graph_local,host,settings
MariaDB format imports correctly	confirmed	imported a log with Thread_id, Schema, Rows_affected, Bytes_sent: schema stored as shop, status 2
MySQL 5.7 and 8.0 format imports, but Id: ends up in the address	confirmed	imported ISO-time entries with Id: suffix: addresses stored 127.0.0.1 Id and 192.168.100.100 (cut at 15); includes/functions.php:1069 splits the line on every colon
IPv6 clients are not stored correctly	confirmed	::1 stored as '', 2001:db8::17 stored as 2001; ip_address is varchar(15) (includes/database.php:72)
Names are cut at 20 and table names at 45	confirmed	a 32-character user and a 34-character schema were stored as 20 characters each; a 51-character table name as 45; includes/database.php:70,76,181
Entry times come from SET timestamp= and use PHP's time zone	confirmed	the stored dates followed PHP's date() of that epoch in every import above; the E2E failure of the MySQL 8 import under America/New_York (reproduced locally) comes from the same source. Fixed in #60
Pages and charts	confirmed	requested Summary, By Method, By Table, Details and the import form by HTTP: all 200 with the titles used in the README; methods page contained six bar charts (raw_count, raw_query, raw_examined, raw_sent, raw_affected, raw_bytes) and five box charts (box_query to box_bytes); "Include Max" is in slowlog.php:1538
Limits unlimited for every request	confirmed	slowlog.php:32-33
Memory use of an import	measured	a 200,000-entry, 75 MB log: 480 MB peak PHP memory for the import, 450 MB for table association alone (median of three runs; PHP 8.4 CLI, MariaDB 11.8.9). Same fixture as in #60's performance section
Translations: 21 languages; rebuild with locales/build_gettext.sh	confirmed	ls locales/po/*.po | wc -l = 21, locales/LC_MESSAGES/*.mo = 21; ran the script in a copy: it regenerated the template and all .po/.mo files (needs xgettext, msgmerge, msgfmt, realpath; it also printed a basename usage line on macOS and carried on)
Pest command	confirmed	in a Cacti develop checkout with the plugin at plugins/slowlog and tests/.cacti-version set to develop: include/vendor/bin/pest --configuration=plugins/slowlog/phpunit.xml gave "271 passed, 1 skipped". composer.json of the 1.2.x tree used here has no Pest; develop's has pestphp/pest
Coverage and patch gate commands	confirmed	the --coverage-clover=plugins/slowlog/coverage/clover.xml run passed; php tests/bin/patch-coverage.php <clover> origin/main 100 ran in the git checkout and printed "no measured lines changed" (the README's relative path coverage/clover.xml is the workflow's form)
validate-manifest.php, check-i18n-pot.php origin/main	confirmed	"manifest.json 'expected' matches the plugin tree." and "No translatable-string changes detected"

Not verified: Cacti 1.2.29 and 1.2.30 themselves; PHP 7.1 to 8.1; MySQL (as opposed to MariaDB) as the Cacti database; the SlowLog tab in the Cacti header (the hook is registered in setup.php:56-57 but I did not check its rendering, so the README does not describe it).

Known issues I did not put in the README

The No button on the delete confirmation currently deletes the selected logs (fixed in #60), so the README only says to confirm with Yes. I did not document defects that an open PR fixes.

Types of changes

• Documentation only; no code change

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation. (It is 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