← Adorn Reports  /  Documentation

Documentation.

Everything you need to install, configure and use the Adorn Reports plugin. 

01 — Installation.

Adorn Reports installs like any standard WordPress plugin. Minimum requirements: WordPress 6.0+, PHP 7.4+, and write access to wp-content/uploads/ for PDF generation.

Method 1: WordPress Admin Upload (recommended)

  1. Download the latest .zip from the plugin page.
  2. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
  3. Choose the downloaded adorn-reports-X.X.X.zip and click Install Now.
  4. Click Activate Plugin.

Method 2: Manual FTP/SFTP Upload

  1. Unzip the plugin archive locally.
  2. Upload the adorn-reports/ folder to /wp-content/plugins/ on your server.
  3. In WordPress admin, click Activate next to Adorn Reports.

Method 3: Auto-update from existing installation

If an earlier version is already installed, the plugin checks for updates every 3 hours. New versions appear in Dashboard → Updates — click Update Now.

02 — First steps after activation.

The plugin is designed to start working immediately. On activation it creates everything it needs and begins capturing events from WordPress hooks — no configuration required.

What activation does

  • Creates the wp_adorn_reports_log table (event entries with user, IP, severity, JSON details)
  • Creates the wp_adorn_reports_data table (saved reports with period, status and report payload)
  • Stores the adorn_reports_settings option with sensible defaults (90-day retention, monthly schedule, IP collection on, accent #FF007C)
  • Schedules the adorn_reports_cron_cleanup daily cron event for log purging
  • Adds the Adorn Reports entry to the WP admin sidebar
  • Begins listening on 30+ WordPress hooks and recording events as they happen

First five minutes — recommended setup

Reports work out of the box, but a few quick choices in Settings make them feel like yours:

  1. Upload your logo from the WP Media library — appears top-left of every PDF
  2. Pick your accent colour — the plugin auto-derives a light tint and a dark shade for headings and tiles
  3. Set Company Name, Tagline and Website URL
  4. Set the TM Contract Renewal Date — appears on the PDF and switches to an urgent orange box within 60 days of expiry
  5. Decide on IP collection (default on) and Auto-anonymise on user delete (default on) to match your privacy stance
  6. Set the Log Retention period (default 90 days)

03 — Dashboard tour.

Adorn Reports lives at WP Admin → Adorn Reports. The interface is split into 5 tabs.

Dashboard

Four KPI tiles for the last 30 days — Total Events, Updates, Security Events, Reports Generated. Below: Recent Activity (last 10 audit-log entries), the Environment card (WordPress, PHP, active theme, plugin count) and a single Generate Report quick-action plus an Email Report shortcut.

Reports

Saved reports list with date range, brand, status and per-row actions — Export PDF, Email (sends the PDF as an attachment), Delete. New Report opens the report builder. Empty state shown when no reports exist yet.

Activity Log

The full audit trail. Search across event types, users, IPs and details (debounced 400 ms). Combinable filters: group, event type, user, date-from, date-to. Click a row to open the detail modal with full JSON metadata. Export the filtered view to CSV. Clear Filters resets all at once. Pagination at 25 entries per page.

Security

Vulnerability Scanner powered by the WPScan CVE database. Four severity tiles (Critical, High, Medium, Low) and a per-item table listing every installed plugin and theme that has a known CVE with the title, severity badge, fixed-in version (if any) and a link to the advisory. A daily cron refreshes results automatically; the Rescan Now button forces an immediate re-scan. Requires a free WPScan API token (set in Settings).

Settings

Branding, contract renewal date, email defaults, WPScan token, privacy preferences, retention policy and a Check for Updates button. Settings save via AJAX with success/error feedback.

04 — Settings & Configuration.

All settings are stored in a single WordPress option (adorn_reports_settings) and saved via AJAX with nonce verification.

Report Branding

  • Logo (logo_id) — upload via the WP Media library. SVG or PNG with transparent background recommended. Falls back to the bundled brand SVG if not set.
  • Accent Colour (accent_color) — any hex via the WP colour picker. Light tint (KPI backgrounds) is auto-mixed at 88% with white; dark shade (headings, dividers) is auto-darkened by 55%.
  • Company Name, Tagline, Website URL, Email

TM Contract Renewal

Set the date your maintenance contract expires (renewal_date). The PDF prints a calm reminder when more than 60 days out, switches to an urgent orange box at 60 days, and shows an “expired” message after the date passes.

Report Schedule

Cadence reference for your own scheduling: weekly, biweekly, or monthly (default). The plugin doesn’t auto-send reports yet — this drives the next-TM date printed on the PDF.

Email Defaults

Pre-fill values for the Email Report modal (added in v1.10).

  • Enable email delivery (email_enabled) — flips the master switch. SMTP transport is whatever WordPress is configured with (WP Mail SMTP, FluentSMTP, etc).
  • Default recipients (email_recipients) — comma-/whitespace-separated. Pre-fills the modal.
  • Sender name & email — email_sender_name / email_sender_address. Both optional. Falls back through: explicit value → company_name / company_email → WP admin email.
  • Subject and body templates — email_subject + email_body. Placeholders: {site_name}, {site_url}, {period}, {from}, {to}, {company}.

Security Scanning

Added in v1.11. Paste a free WPScan API token (wpscan.com/register) into the WPScan API token field (wpscan_token). The Security tab activates as soon as a token is configured. The free tier covers 25 requests/day — enough for most sites; per-item responses are cached for 12 hours to soften the limit. A daily cron (adorn_reports_cron_vuln_scan) keeps results fresh.

Privacy & Data

  • Collect IP addresses (collect_ip) — default on. Toggle off for stricter POPIA/GDPR posture.
  • Auto-anonymise on user delete (anonymize_on_delete) — clears IPs and replaces user references when a WP user is deleted (default on)
  • Log retention (log_retention) — in days. Default 90. Daily cron deletes anything older.
  • PDF reports enabled (default on); Email reports — live since v1.10.

05 — Activity Log.

The Activity Log captures every meaningful event on the site by listening to WordPress hooks. Each entry stores: event_type, group, user_id, object_type, object_name, JSON details, IP address, timestamp.

Tracked events

Security: login_success, login_failed, logout

Users: user_created, user_deleted, role_changed, profile_updated (email, password, display name, first/last name)

Content: post_created, post_updated, post_published, post_trashed; menu_created, menu_updated, menu_deleted; term_created, term_edited, term_deleted

Comments: comment_created, comment_approved, comment_unapproved, comment_spam, comment_trashed, comment_deleted, comment_edited

Media: media_uploaded, media_updated, media_deleted

Updates: plugin_activated, plugin_deactivated, plugin_updated, plugin_installed, plugin_deleted, theme_switched, theme_updated, theme_installed, core_updated

Settings: option_updated (16 watched WP options including blogname, siteurl, admin_email, permalink_structure, users_can_register, default_role, timezone_string), widget_updated

Severity classification

Severity is derived from the event type, not stored as a column. The four levels and their UI colours:

  • Critical (red) — failed login, user deleted, plugin deleted, core updated
  • High (amber) — role changed, post trashed, plugin/theme deactivated, comment trashed/deleted, term/menu deleted, option_updated
  • Medium (blue) — user created, post published, profile updated, plugin/theme activated/installed/updated, comment approved/unapproved/spam, widget updated
  • Low (grey) — login success, logout, post create/update, comment create/edit, media upload/update, menu create/update, term create/edit

IP collection

If Collect IP is on (default), the plugin reads CF-CONNECTING-IP → X-FORWARDED-FOR → REMOTE_ADDR. Toggle off in Settings for stricter privacy — the IP column simply records empty.

Searching, filtering, exporting

  • Search bar (debounced 400 ms) matches event names, users, IPs and details JSON
  • Filters (combinable): group, event_type, user, date-from, date-to
  • Click a row for the detail modal with the full metadata payload, severity badge, user role and IP
  • Pagination at 25 entries per page
  • CSV export downloads the currently filtered set as a spreadsheet
  • Clear Filters resets everything in one click

Retention & cleanup

The adorn_reports_cron_cleanup daily cron event deletes any entry older than the configured retention window (default 90 days). Tables persist through plugin updates and reactivation. Uninstall does not drop the tables — your audit trail survives a delete/reinstall cycle.

06 — Generating Reports.

From the Dashboard or the Reports tab, click Generate Report (or New Report) to open the report builder modal.

Section toggles

From v1.11.8, three toggles control which blocks appear in the PDF:

  • Updates & Plugin / Theme Status — Update Summary KPIs + Plugin/Theme Updates tables + Plugin/Theme Status tables.
  • Site Content — Posts / Pages / Comments KPI tile row.
  • Server & Environment — the full Server info table.

Header, Site Info, TM Renewal box, sign-off and footer always render — they’re structural. The selection is stored in meta.sections_included on the report record, so re-exporting the same report’s PDF honours the original toggles.

Modal options

  • Date range — From and To dates, default last 30 days
  • Generate Report — saves a record to wp_adorn_reports_data with status completed and the full report payload as JSON
  • Generate & Export PDF — saves the report and immediately returns a signed download URL for the branded PDF

Email Report

Live since v1.10. Click Email Report on the dashboard Quick Actions, or the per-row send icon in the Reports tab.

  • Recipients (comma-/whitespace-separated, pre-filled from Settings defaults)
  • Subject and HTML body (placeholders {site_name}, {site_url}, {period}, {from}, {to}, {company})
  • Sends via wp_mail() with the generated PDF attached — any SMTP plugin already installed handles transport
  • Triggers a report_emailed audit event recording the recipients and subject
  • If no saved report is selected, the plugin generates a fresh 30-day report on the fly before sending

Saved reports

Saved reports appear in the Reports tab with their date range and status. Re-export a PDF at any time using the Export PDF action; the PDF is regenerated from the stored report data with the original section toggles applied.

07 — PDF output structure.

PDFs are rendered by Dompdf, A4 portrait, 15 mm side / 12 mm bottom margins. Helvetica is used by default; DejaVu Sans is loaded for Unicode arrows. A typical full report runs 5–8 pages depending on plugin/theme count.

Section order

  1. Header — logo on the left, “Website Maintenance Report” + date on the right, 3 px accent-colour divider
  2. Site Info — client, website URL, WordPress version, reporting period, maintenance date
  3. Update Summary KPIs — 4 tiles: Total Updates, Core, Plugin, Theme
  4. Plugin Updates — table with name, previous → updated-to, date (or “no plugin updates this period”)
  5. Theme Updates — same shape
  6. Page break
  7. Plugin Status — full list with Active/Inactive badges and an “Update available” badge where applicable
  8. Theme Status — full list with the active theme highlighted
  9. Site Content KPIs — 3 tiles: Posts Added, Pages Added, Comments Added
  10. Server — architecture, web server, PHP version + SAPI, MySQL, memory limit, time limit, upload max, post max, cURL, Imagick, pretty permalinks, SSL, debug mode
  11. TM Contract Renewal (if a renewal date is set):
    • Calm box if more than 60 days out
    • Orange urgent box at 60 days or fewer
    • “Your maintenance contract has expired” message after the date passes
  12. Sign-off paragraph
  13. Footer — centred company name + tagline, then small grey “Powered by Adorn Reports — Adorn Media Studio” attribution (locked)

Logo fallback chain

The PDF picks the first available logo: (1) the uploaded logo_id from settings → (2) the bundled assets/images/logo.svg → (3) the bundled media-logo.png → (4) the company name rendered as text.

08 — White-label branding.

Adorn Reports is white-label by design. The default branding shows Adorn Media Studio, but you can replace every visible element with your own.

Configurable branding fields

  • Logo (logo_id) — PDF header on every page
  • Accent colour (accent_color) — headings, KPI tile backgrounds, table headers, the 3 px divider line
  • Company Name (company_name), Tagline (company_tagline), Website URL (company_website)

Auto-derived colours

You only pick one accent colour — the plugin computes the supporting palette automatically:

  • hex_to_light() — mixes accent with white at 88%, used for KPI tile backgrounds and subtle highlights
  • hex_to_dark() — multiplies accent by 0.55, used for h1/h2 headings, dividers and dark table headers

What can’t be removed

The PDF footer always shows “Powered by Adorn Reports — Adorn Media Studio” in small grey text. The plugin author and copyright references in the WP admin and update modal are also fixed. Everything client-facing on the PDF is yours; the small attribution is the licence price.

09 — Privacy & POPIA/GDPR.

Adorn Reports is built with POPIA (South Africa) and GDPR (EU) compliance in mind. The plugin only logs WordPress user actions — not visitor activity. There is no front-end tracking, no analytics scripts, no third-party calls.

WordPress privacy tools integration

Plays cleanly with Tools → Export Personal Data and Tools → Erase Personal Data:

  • Hooks into wp_privacy_personal_data_exporters — returns audit-log entries for the requested user (paginated 100 per batch)
  • Hooks into wp_privacy_personal_data_erasers — anonymises log entries by clearing the user_id, IP, and replacing object_name with “[Deleted User]”
  • Updates wp_adorn_reports_data.created_by to 0 for any reports authored by the deleted user

Auto-anonymise on user delete

When a WordPress user is deleted, the delete_user hook applies the same anonymisation as the data eraser — controlled by the Auto-anonymise setting (default on). Toggle off if you need to preserve historical user references for compliance audits.

Optional IP collection

The Collect IP setting is on by default. When off, the plugin records an empty string for IP — the column still exists for schema stability, but no addresses are stored. Useful for stricter POPIA/GDPR postures or visitor-anonymous setups behind a CDN.

Configurable retention

Retention is in days, default 90. The daily adorn_reports_cron_cleanup cron event deletes anything older than the configured window. Common values: 30, 60, 90, 180, 365.

Privacy policy text

Adorn Reports registers a privacy policy snippet via wp_add_privacy_policy_content() — visit Settings → Privacy → Policy Guide to copy suggested wording into your site’s privacy policy. It covers what data is collected, why (legitimate interest under Article 6(1)(f) GDPR / Section 11(1)(f) POPIA), retention, and user rights.

10 — REST API reference.

Adorn Reports exposes a REST API for external integrations and dashboards.

Namespace & base URL

https://your-site.com/wp-json/adorn-reports/v1/

Authentication

All endpoints require the manage_options capability (admin-only). Authenticate with the WordPress nonce on the same site, or with Application Passwords via the Authorization: Basic header from external clients.

Endpoints

  • GET /reports — paginated saved reports. Query: page (default 1), per_page (default 10, max 50). Response: items, total, total_pages, page.
  • GET /reports/<id> — single report with report_data JSON decoded into nested fields.
  • POST /reports/generate — create a new report. Body: from_date, to_date (Y-m-d), brand (optional). Response: report_id, message.
  • GET /stats — KPI snapshot. Query: days (default 30). Response: total_events, updates, security_events, content_changes, failed_logins, by_group, recent, reports_generated.
  • GET /log — paginated activity entries. Query: event_group, event_type, page, per_page (default 25, max 100).
  • GET /environment — one-shot site environment snapshot: wp_version, php_version, mysql_version, site_url, site_name, active_theme, ssl, memory_limit, debug_mode, timezone, plugin_count.

Compatible with the Model Context Protocol — reports and stats can be wired into MCP clients for dashboards or AI workflows.

11 — Self-hosted updates.

Adorn Reports is not on the WordPress.org directory. It uses a self-hosted update system that integrates with WordPress’s standard update flow.

How it works

  1. Your site queries a metadata endpoint via the pre_set_site_transient_update_plugins filter
  2. Results are cached in a transient for 3 hours to keep load off the update server
  3. If a newer version is found, it appears in Dashboard → Updates with the standard “Update Now” button
  4. WordPress downloads, swaps and reactivates the plugin like any other update

Force-checking

Two ways to force a fresh check before the 3-hour cache expires:

  • Settings → Check for Updates button (uses the adorn_force_update nonce-protected action and clears the transient)
  • WordPress Dashboard → Updates → Check Again

Security

The updater performs a same-origin check on the download URL: it parses the host of the metadata response and rejects any package whose download_url points to a different domain. This prevents a hijacked update server from serving malicious payloads from third-party hosts.

Update modal fields

The plugin update modal renders the metadata WordPress-style: name, version, requires WP/PHP, tested, description tab, installation tab, changelog tab, banner image. Supported metadata fields include version, download_url, tested, requires, requires_php, last_updated, homepage, icons, banners, description, installation, changelog, downloaded.

12 — Troubleshooting.

Check that wp-content/uploads/ is writeable and your PHP memory_limit is at least 128M. Dompdf errors land in the standard PHP error log.

Dompdf can’t fetch from external domains. Logos must come from the WP Media Library (same domain). The bundled SVG falls back automatically if logo_id is empty.

The version cache is 3 hours. Click Settings → Check for Updates, or Dashboard → Updates → Check Again, to force a fresh check.

Deactivate and reactivate the plugin to re-run the schema check. Then trigger an event (log out, edit a post) and refresh.

Fixed in v1.5.1 by loading DejaVu Sans for Unicode support. If you’re seeing this, you’re on an older build — update.

Reduced from 25 mm to 15 mm sides / 12 mm bottom in v1.9.0. Dompdf ignores @page margins, so the plugin uses body padding instead.

From v1.3.1 onwards, tables persist through delete/reinstall cycles. If you really need a clean slate, drop wp_adorn_reports_log and wp_adorn_reports_data manually from the database.

All endpoints require manage_options capability. Use Application Passwords (Profile → Application Passwords) and pass them via the Authorization: Basic header.

13 — Changelog.

The full changelog lives in CHANGELOG.md, in the WordPress plugin update modal, and on the plugin landing page.

Highlights

v1.11.8 — Report builder section toggles now actually wire through to the PDF. Three working toggles (Updates & Status, Content, Server). meta.sections_included preserves the selection across re-exports.

v1.11.7 — WP “View Details” modal brand assets refreshed: ADORN hexagon-A icon with the Reports blue → pink gradient; banner uses the same gradient backdrop with the adorn.reports wordmark.

v1.11.6 — Dashboard header swapped to just the gradient hexagon-A icon (the sidebar label already carries the wordmark).

v1.11.5 — Sidebar section divider rewritten with WordPress’s native wp-menu-separator pattern (the same hook Crocoblock uses for JetEngine PLUGINS / POST TYPES dividers). Idempotent CSS emit across sibling Adorn plugins.

v1.11.1 – 1.11.4 — Visual sync sweep with adorn.lens: ADORN brand icon in the sidebar with adorn.reports wordmark label, light theme enforced, primary buttons follow the pink-fill / brand-dark-text contrast rule, dashboard wordmark header.

v1.11.0 — Vulnerability Scanner. WPScan API integration, per-item 12h cache, severity normalised to 4 buckets, Security tab with rescan + summary tiles + per-item table, new vulnerability_detected audit event.

v1.10.0 — Email Reports. Full send flow via wp_mail(), recipients/subject/body modal, audit log entry per send, Settings defaults for sender + recipients + templates.

v1.9.1 — New brand identity (logo, hex icon, banner). PDF defaults migrated to brand pink #FF007C / deep-blue #070857.

v1.8.0 — Activity Log overhaul: 30+ event types, severity, search, combinable filters, detail modal, CSV export, working pagination.

v1.7.0 — POPIA & GDPR compliance: optional IP collection, WP privacy tools integration, auto-anonymise on user delete, configurable retention.

v1.6.0 — White-label branding: upload logo, accent colour, company name/tagline/website. Auto-derived light tint and dark shade.

v1.0.0 — Initial release.

14 — Support & Contact.

Stuck on something the docs don’t cover? Adorn Reports is built and maintained by Adorn Media Studio — reach out and we’ll help.

Email Support
Visit adornmedia.co.za

Looking for something?

South Africa’s Protection of Personal Information Act (POPIA) & Cookie Consent

We will not sell, share, or rent your Personal Information to any third party or use your email address for unsolicited mail. Any emails sent by us will only be in connection with the provision of our services and/or the marketing thereof. We use cookies on our website to give you the most relevant experience by remembering your preferences and repeat visits. By continuing in the website you accept the use of cookies.

accept cookies