From c4406c4592c1c3aeb139e7851ae05060e4399dea Mon Sep 17 00:00:00 2001 From: Thomas Vincent Date: Tue, 17 Nov 2026 20:38:08 -0800 Subject: [PATCH 1/5] docs: align README with source and published releases Signed-off-by: Thomas Vincent --- CHANGELOG.md | 3 +++ README.md | 49 +++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e23ac2..f80eff0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ # ChangeLog +Documentation update (unreleased): Refresh README release/source compatibility, +installation guidance and source-checked behavior. + --- develop --- * dev: Run the CI poller with the shared runner group so RRD files and structured directories pass permission verification diff --git a/README.md b/README.md index b234dd5..90b4b9d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,28 @@ # ReportIt +ReportIt creates tabular reports from RRD data using configurable templates, +measurands and reporting periods. The 3.0 development branch uses Cacti’s report +queue for scheduled execution and notification delivery, including notification +lists, direct email recipients and BCC. + +## Versions and compatibility + +This README describes the `develop` source branch. + +| Code | Plugin version | Minimum Cacti declared in `INFO` | +| --- | --- | --- | +| [Source branch](INFO) | 3.0 | 1.3.0 | +| [Published v1.1.4](https://github.com/Cacti/plugin_reportit/releases/tag/v1.1.4) | 1.1.4 | 1.2.27 | + +Use the published release’s assets and tagged documentation when installing that +package. Branch code can include later changes, even when its version number +matches the release. Cacti’s own PHP and database requirements also apply. + +Install this plugin in **`/plugins/reportit`**, using the directory +name `reportit` rather than `plugin_reportit`. + +See [CHANGELOG.md](CHANGELOG.md) for the version history. + ## Developers * Andreas Braun (aka browniebraun) @@ -8,12 +31,16 @@ * Larry Adams (aka TheWitness) -## Purpose +## Features -This plugin creates tabular reports from RRDfile data which will be archived and -optionally Emailed to a user or users. +Templates, data items, work schedules, time zones, SI-prefix formatting and +scheduled reporting are provided by this branch. The list below also records +legacy 1.x capabilities. Version 3.0 removes the earlier automatic archive/export +workflow in favor of Cacti’s report log; existing legacy archive/export helpers +do not establish that the old workflow is supported in 3.0. See the changelog +and the tagged README for the published 1.1.4 package. -## Features +### Legacy feature list * Definition of individual report templates by using measurands and variables in a mathematical way @@ -46,9 +73,14 @@ optionally Emailed to a user or users. Before you install "ReportIt", check the following requirements: -* Cacti 1.2.27 or higher. +* **This 3.0 source branch: Cacti 1.3.0 or later**, as declared in `INFO`. +* **Published 1.1.4: Cacti 1.2.27 or later**, as declared in its release tag. -To upgrade "ReportIt" release 0.4.0 or higher is required. +The following 0.x migration notes describe legacy versions, not a verified +direct upgrade path to the 3.0 development branch. Back up the database and +existing reports before planning a migration. + +To upgrade the legacy release, ReportIt 0.4.0 or higher is required. A prior version (0.1, 0.2, 0.3.0, 0.3.1, 0.3.2 or 0.4.0a) has to be completely uninstalled (mysql tables as well)! @@ -94,6 +126,11 @@ The Installation of ReportIt is similar to other plugins: ## Upgrade +**Legacy 1.x procedure:** the following instructions refer to the older +archive/export layout. For 3.0, review the development changelog and Cacti’s +report-log workflow before migration. Preserve existing archive/export data. + + To upgrade an existing version of ReportIt please ensure that its release number is v0.4.0 or above. It's strongly recommended to make a backup of your cacti database and your ReportIt folder before! If you're using the default archive From 119a967fcb483adad29fc667eee9c43e8146ee14 Mon Sep 17 00:00:00 2001 From: Thomas Vincent Date: Tue, 17 Nov 2026 20:47:37 -0800 Subject: [PATCH 2/5] style: fix template wizard switch labels Signed-off-by: Thomas Vincent --- CHANGELOG.md | 1 + templates.php | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f80eff0..805f45f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ installation guidance and source-checked behavior. --- develop --- +* dev: Correct template-wizard switch-label spacing to pass the PHP formatting check * dev: Run the CI poller with the shared runner group so RRD files and structured directories pass permission verification * security: Move the plugin's remaining inline event handlers to CSP-safe bindings so the pages no longer trip Cacti's Content-Security-Policy script-src-attr directive: the confirmation-page Cancel buttons use the `cactiReturnTo` class, the filter rows selects are bound via change() in their ready blocks, and the template calc-syntax links use a delegated `reportitAddCalc` handler * dev: Measure CI coverage with xdebug instead of pcov so the plugin's own sources are instrumented (pcov auto-scopes to the Composer root and skipped cacti/plugins/, leaving the patch-coverage gate with nothing to measure) diff --git a/templates.php b/templates.php index a707aa5..6e406d7 100644 --- a/templates.php +++ b/templates.php @@ -100,11 +100,11 @@ template_wizard('export'); break; - case 'template_import_wizard' : + case 'template_import_wizard': template_wizard('import'); break; - case 'template_upload_wizard' : + case 'template_upload_wizard': template_wizard('upload'); break; From 4222266b426770b00da86342ff5463d0c2c14d76 Mon Sep 17 00:00:00 2001 From: Thomas Vincent Date: Tue, 17 Nov 2026 20:56:58 -0800 Subject: [PATCH 3/5] docs: correct remaining setup and compatibility guidance Signed-off-by: Thomas Vincent --- README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 90b4b9d..d867f19 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,9 @@ Before you install "ReportIt", check the following requirements: * **This 3.0 source branch: Cacti 1.3.0 or later**, as declared in `INFO`. * **Published 1.1.4: Cacti 1.2.27 or later**, as declared in its release tag. +* **This source branch: PHP 8.3 or later**, as required by + [composer.json](composer.json). Cacti's own extension and database + requirements also apply. The following 0.x migration notes describe legacy versions, not a verified direct upgrade path to the 3.0 development branch. Back up the database and @@ -82,10 +85,10 @@ existing reports before planning a migration. To upgrade the legacy release, ReportIt 0.4.0 or higher is required. -A prior version (0.1, 0.2, 0.3.0, 0.3.1, 0.3.2 or 0.4.0a) has to be completely -uninstalled (mysql tables as well)! - -Therefore you can use uninstall.php. +Versions before 0.4.0 used a different migration procedure. The old +`uninstall.php` helper is not included in this branch. Preserve a database and +report archive backup, and use the source release's migration instructions +instead of treating an uninstall as a current upgrade step. Optional: To use the full set of ReportIt's functionalities additional extensions are required From 1d4b5fa10b4ef1de0677bf496b3a1832af535d62 Mon Sep 17 00:00:00 2001 From: Thomas Vincent Date: Wed, 18 Nov 2026 01:11:11 -0800 Subject: [PATCH 4/5] docs: correct remaining claims against the plugin code Re-checked the documentation against INFO, setup.php, the settings arrays, registered realms and CLI usage text, and fixed the statements that did not match. Adds the realms, settings and command line tools the README did not mention. Signed-off-by: Thomas Vincent --- README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d867f19..18410f7 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,8 @@ and the tagged README for the published 1.1.4 package. * Provides rounding with binary or decimal SI-Prefixes -* Export to CSV, SML and XML +* Export to CSV, SML, XML and JSON, and to YAML when the PHP 'yaml' extension + is loaded * Different ways of connecting RRDtool @@ -63,8 +64,6 @@ and the tagged README for the published 1.1.4 package. * Automatic dispatch of scheduled reports via email -* Generation of top 10 charts - * Report history * Report per email * Autoexport to a dedicated folder @@ -90,10 +89,8 @@ Versions before 0.4.0 used a different migration procedure. The old report archive backup, and use the source release's migration instructions instead of treating an uninstall as a current upgrade step. -Optional: To use the full set of ReportIt's functionalities additional -extensions are required - -* Fast report generation: PHP extension 'php_rrdtool' +Optional: The YAML export format is offered only when the PHP 'yaml' extension +is loaded. ## Cacti compatibility @@ -154,11 +151,19 @@ Console > Configuration > Settings > Reports. ## How to use -Console > Templates > Reports - create report template, enable publish, disable locked -Console > Management > Reports - create report from your template. Don't forget use "Add data items" +Console > Templates > ReportIt - create report template, enable publish, disable locked +Console > Management > ReportIt Reports - create report from your template. Don't forget use "Add data items" Use ReportIT tab Manual is in file MANUAL.PDF +## Permissions + +The plugin registers three realms that can be assigned to users or groups: + +* ReportIt - Report Viewing +* ReportIt - Create Reports +* ReportIt - Manage Reports + ## Authors ReportIt was created and written by Andreas Braun (browniebraun) with numerous From aa640996832a2e3781c53d09d4c662cedd30e13c Mon Sep 17 00:00:00 2001 From: Thomas Vincent Date: Wed, 18 Nov 2026 16:50:26 -0800 Subject: [PATCH 5/5] docs: use absolute links in README and CHANGELOG Plugin Management renders README.md and CHANGELOG.md from the release tag in a dialog, so relative links resolve against the Cacti server and return 404. Signed-off-by: Thomas Vincent --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 18410f7..c3841dc 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ This README describes the `develop` source branch. | Code | Plugin version | Minimum Cacti declared in `INFO` | | --- | --- | --- | -| [Source branch](INFO) | 3.0 | 1.3.0 | +| [Source branch](https://github.com/Cacti/plugin_reportit/blob/develop/INFO) | 3.0 | 1.3.0 | | [Published v1.1.4](https://github.com/Cacti/plugin_reportit/releases/tag/v1.1.4) | 1.1.4 | 1.2.27 | Use the published release’s assets and tagged documentation when installing that @@ -21,7 +21,7 @@ matches the release. Cacti’s own PHP and database requirements also apply. Install this plugin in **`/plugins/reportit`**, using the directory name `reportit` rather than `plugin_reportit`. -See [CHANGELOG.md](CHANGELOG.md) for the version history. +See [CHANGELOG.md](https://github.com/Cacti/plugin_reportit/blob/develop/CHANGELOG.md) for the version history. ## Developers @@ -75,7 +75,7 @@ Before you install "ReportIt", check the following requirements: * **This 3.0 source branch: Cacti 1.3.0 or later**, as declared in `INFO`. * **Published 1.1.4: Cacti 1.2.27 or later**, as declared in its release tag. * **This source branch: PHP 8.3 or later**, as required by - [composer.json](composer.json). Cacti's own extension and database + [composer.json](https://github.com/Cacti/plugin_reportit/blob/develop/composer.json). Cacti's own extension and database requirements also apply. The following 0.x migration notes describe legacy versions, not a verified