Download the PHP package williamundqvist/scheduled-page-reviews without Composer

Scheduled Page Reviews

A WordPress plugin for content freshness reminders: per-page review intervals, assignees, hierarchical rule inheritance, due/overdue tracking, batched email digests, a Gutenberg sidebar, and a React page-tree admin UI.

This is a stand-alone generic WordPress plugin. It does not depend on any specific theme or framework.

Requirements

• PHP 8.1+
• WordPress 6.5+
• Node.js 18+ (build-time only)

Installation (development)

Then activate the plugin in wp-admin → Plugins.

Installation (test / production ZIP)

Releases are built in CI from a tag on main. The ZIP includes vendor/ and dist/; you do not need Node or Composer on the server.

1. Download the ZIP from the GitHub Release for your tag (see RELEASE.md).
2. Plugins → Add New → Upload Plugin and activate.

To build a ZIP locally:

Output: .build/scheduled-page-reviews-<version>.zip

Scripts

See LOCALIZATION.md for the full i18n plan (PHP, emails, admin SPA, editor sidebar).

Architecture (short tour)

Each service constructor self-registers its WordPress hooks. App::boot() wires the object graph; it contains no add_action calls of its own. This keeps the dependency graph explicit and the bootstrap class small.

Data model

Empty rules are deleted from post meta automatically — no orphan rows.

Target model (who to notify)

recipients is a list of Target objects rather than plain ID or email arrays. Every target has the shape { type, value }:

Example rule fragment:

Role targets are expanded at notification time by ReviewScanner, so changing a role's membership in WP (or via a SAML/OIDC sync) is reflected on the very next cron run. Roles that no longer exist simply expand to zero users — no error, no notifications.

Legacy data shapes (plain integer arrays in the old owners field, plain string arrays in recipients) are still accepted by Rule::fromArray() and merged into recipients on load.

Inheritance model (tri-state)

A page's effective value for each field (interval_days, recipients, notify_before) resolves as follows:

1. If the page has a local rule for that field → use it.
2. Otherwise walk ancestors top-down looking for the nearest ancestor with a subtree rule for that field → use it.
3. Otherwise fall back to global settings.

Resolution is lazy: there is no materialized table of effective settings. InheritanceResolver::resolveForPage() does the ancestor walk on demand (cached per request via WpPageHierarchy). InheritanceResolver::walkTree() is the bulk DFS used by cron.

Who sees review status in wp-admin

The Pages list badges ("Review overdue" / "Review due soon"), the dashboard widget, and the REST /dashboard endpoint all use the same visibility rules via RecipientVisibility:

Email-only recipient pages show no badge to any WP user unless a site overview user is viewing.

Override via filters:

• scheduled_page_reviews/can_view_site_overview — grant or revoke site-wide overview per user
• scheduled_page_reviews/post_states/show — per-page override for Pages list badges

REST API

Namespace: scheduled-page-reviews/v1. All endpoints require is_user_logged_in() minimum.

The /pages/<id>/rule GET response also includes last_reviewed_at, last_reviewed_by, next_review_at, and bucket so the editor sidebar renders in a single request.

Public extension API

All actions and filters are namespaced under scheduled_page_reviews/....

Actions

Filters

Example: redirect owner reminders to a Slack webhook instead of email

Example: hide WP default roles from the picker, expose only SAML-imported ones

Example: stop the scanner from touching auto-draft pages

Reminders (email throttling)

Two global settings under General settings → Reminders control repeat digests:

Digest grouping is per recipient per cron run — all eligible pages for that person appear in one email, regardless of review date.

Current cadence model (per page)

_scheduled_page_reviews_last_notified_at is stored on each page. Cadence throttles re-notifying that page, not how often a person receives mail overall.

Implication: if you own many pages that become due on different days, you may receive more than one email per cadence period (e.g. one digest when page A is due, another when page B becomes due a day later). Pages are not lost — they wait for the next eligible cron run.

Possible future change (per recipient) — not implemented

A per-recipient cadence would cap digest mail to at most one email per address every N days and batch all actionable pages into that single mail. That avoids staggered daily digests when someone owns many pages. Tracked as a future improvement; the plugin still uses per-page cadence today.

Scanning & WP-Cron

Three ways to start a scan:

WP-CLI

Server crontab example (sync, daily at 22:00):

If using --background, also run due WP events regularly:

Background tick pipeline

When a scan runs in background mode (scheduled_page_reviews_daily, --background, or legacy tick resume):

1. Acquires a transient lock (6 hours) to prevent overlap.
2. Processes up to cron_batch_size pages per tick (filterable).
3. Persists RunState (cursor, totals) in a transient.
4. If more pages remain, reschedules scheduled_page_reviews_tick (+60 seconds).
5. When complete, fires scheduled_page_reviews/cron/run_completed which the dispatcher consumes.

Important: WP Cron settings in the Schedule tab register the daily event — they do not execute it. Something must run due scheduled events (page loads with WP-Cron enabled, or wp cron event run --due-now from server crontab).

On deactivation the daily event, any pending tick events, and run-state transients are cleared.

Permission layers

The plugin separates three independent concerns. They must not be conflated — a user can hold one, two, or all three.

Editor workflow (content owners only): dashboard widget, Pages list badges, Gutenberg sidebar, row actions, and email digests. None of these require the settings SPA. Links to the settings page are shown only to users who pass scheduled_page_reviews/can_manage_settings.

WordPress page editing (edit_post) is separate from ownership actions. Editors who are not configured recipients can still edit page content in WordPress, but they do not see ownership UI or mark pages reviewed.

Per-page ownership actions (view status, mark reviewed) are gated by PageAuthorization: recipient assignment, site overview, or settings admin. Rule writes (PUT /pages/<id>/rule) require settings admin only.

Site-specific tuning (for example, restrict both overview and settings access to the administrator role while other manage_options users remain content owners only) is done with scheduled_page_reviews/can_view_site_overview and scheduled_page_reviews/can_manage_settings in site code — not by hardcoding roles in the plugin.

The legacy capability config key is still read as a fallback when either dedicated key is missing.

Testing

Domain logic is fully unit-tested with in-memory fakes for RuleSource, PageHierarchy, and NotificationQueueInterface, so the inheritance resolver, cron scanner, and email renderer run without WordPress loaded.

License

GPL-3.0-or-later