WPHammer
Log in

Monthly Reports

WPHammer generates monthly reports that summarize everything that happened on a WordPress site during a given period. Reports are created as drafts, reviewed and optionally annotated, then published for clients to view.

Report generation

Reports are generated via the GenerateSiteReportAction, which:

  1. Calls AggregateReportDataAction to collect data across the report period
  2. Determines which sections contain meaningful data
  3. Creates a SiteReport record with the aggregated data cached as JSON

The GenerateMonthlyReportsCommand (reports:generate-monthly) automates this for all eligible sites at the start of each month. It accepts --team, --site, and --locale options for targeted generation.

A report is only generated if:

  • The team has reports_enabled set to true
  • The site has reports_enabled set to true
  • No report already exists for the same period

Report data

The AggregateReportDataAction pulls data from multiple sources for the reporting period:

Section Data source Key metrics
Summary Aggregated from all sections Uptime percentage, update count, security status, backups completed
Updates Activity logs (WordPress source) Plugin, theme, and core updates with details
Security Security scans and findings Scans completed, findings resolved, abuse blocked
Uptime UptimeDailySummary and UptimeIncident Availability percentage, avg response time, incidents, total downtime
Backups Backup records Total, successful, failed counts, success rate, total size
Canary Canary checks Checks completed, alerts triggered, current status
Activity Activity logs Recent activity items (up to 100)

Report sections

Each report includes a configurable set of sections controlled by the ReportSection enum:

  • Summary — high-level metrics at a glance
  • Updates — WordPress core, plugin, and theme updates applied
  • Security — scan results and resolved findings
  • Uptime — availability and response time data
  • Backups — backup completion statistics
  • Canary — visual check alerts and status
  • Activity — chronological activity log
  • Notes — custom notes added by the team

When generating a report, sections are auto-selected based on which ones have meaningful data. You can override this selection when creating a report manually.

Draft and publish workflow

Reports follow a two-stage lifecycle:

  1. Draft — the report is created with published_at set to null. You can edit custom notes and adjust sections while in draft.
  2. Published — calling PublishSiteReportAction re-aggregates fresh data for the period, updates the cached data, and sets published_at. The report becomes publicly accessible.

To unpublish a report, UnpublishSiteReportAction clears published_at, returning it to draft status.

Custom notes

Each report supports a custom_notes field for adding client-facing commentary — maintenance summaries, recommendations, or context about the reporting period. When notes are present, the Notes section is automatically included.

Localization

Reports support multiple locales. The locale field (defaulting to en) determines the language used for section labels and UI text. The GenerateMonthlyReportsCommand accepts a --locale option, and the SiteReportFactory includes a french() state for fr locale.

Related