Donations for WooCommerce Companion WP Registry grade A-. Low-severity findings · 1 findingWP RegistryLow-severity findings · 1 findingOpen the reportA-

The modern donor-facing form pattern — three side-by-side options for One-time, Monthly, and Annually with separate preset amount tiers per interval — built on top of the Donation for WooCommerce parent plugin without modifying it.

┌───────────────────────────────────────────────────────────────┐
│  ○ One-time      ● Monthly       ○ Annually                   │
│ ─────────────────────────────────────────────────────────     │
│  ○ $10           ○ $25 [Most popular]  ○ $50                  │
│       ○ Custom: $ ___________                                 │
│                                                               │
│  Provides school supplies for one student                     │
│                                                               │
│        [ Donate $25/month ]                                   │
└───────────────────────────────────────────────────────────────┘

The companion plugin feeds the parent plugin's existing AJAX pipeline with the right parameters, so all downstream wiring (cart, order, subscription, emails, reports, PDF receipts) keeps working untouched. Recurring billing is handled by either WooCommerce Subscriptions (paid) or Subscriptions for WooCommerce by WPS (free) — auto-detected.

Why this exists

Donation for WooCommerce supports recurring donations technically, but only via a single legacy "Make this recurring" checkbox plus period/interval/length dropdowns. There's no built-in way to offer the modern donor pattern that nonprofits like Charity:Water, NPR, and Wikipedia have made standard. This companion adds it without forking the parent plugin — the parent keeps receiving auto-updates; the companion attaches to its 47+ documented action and filter hooks.

What's in v1.1.0

Full changelog: readme.txt. Per-release notes: .release-notes.md.

Requirements

The companion is HPOS-compatible (High-Performance Order Storage) and Cart/Checkout-Block-compatible.

Install

From a release zip (recommended)

1. Download the latest zip from the Releases page.
2. WordPress admin → Plugins → Add New → Upload Plugin → activate.
3. Visit WooCommerce → Donations Companion → Diagnostics to verify the install.

From source

git clone https://github.com/f8l124/donations-for-woocommerce-companion.git
cd donations-for-woocommerce-companion
composer install     # dev tooling only — runtime ships without vendor/
npm install          # Playwright + wp-env

Then symlink or copy the directory into your site's wp-content/plugins/.

Once it's available on WordPress.org

Plugins → Add New → search for "Donations for WooCommerce Companion" (planned post-v1.1.0).

Usage in 60 seconds

1. Edit a campaign → fill in the "Interval-First Donation Form" meta box: enable the intervals you want, set preset amounts, set min/max for custom amounts.
2. Place the form wherever donors should see it — three options:
   • Auto-augment: the companion automatically wraps parent's existing form rendering on campaign permalinks, the parent's [wc_woo_donation] shortcode, and the parent's widget. No further action needed.
   • Shortcode: [dfwc_recurring_donation campaign_id="123"]
   • Gutenberg block: search for "Recurring Donation" in the inserter
3. Test the donor flow in the live admin preview pane below the meta box. Toggle viewport / engine / language / currency to verify how the form behaves under each.

For multi-campaign sites, define a template once at Donations Companion → Templates, then apply via the campaign meta box or via bulk actions on the campaign list screen.

Full walkthrough: docs/getting-started.md.

Documentation

For nonprofit admins

• docs/getting-started.md — onboarding from fresh install through first campaign
• docs/advanced-intervals.md — weekly / quarterly / semi-annually / custom cadences
• docs/multi-currency.md — WCML / WCPay / Aelia integration
• docs/troubleshooting.md — diagnostics walkthrough; common issues
• docs/privacy.md — what the plugin stores, what it doesn't, GDPR posture

For developers

• docs/event-hooks.md — six action hooks + GA4 / FluentCRM / webhook recipes
• docs/architecture/current-state.md — module structure, save flow, render flow
• docs/architecture/parent-contract.md — every line range we attach to in the parent plugin
• docs/architecture/compatibility-matrix.md — what's tested where
• CONTRIBUTING.md — local setup, code style, PR flow
• docs/release-process.md — how to cut a release

For maintainers

• SECURITY.md — vulnerability reporting
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1
• docs/release-readiness.md — wp.org submission checklist

Architecture

The plugin is small (~5,000 LOC PHP+JS+CSS, well under the wp.org soft limit) and intentionally low-magic:

• Hand-rolled PSR-4-ish autoloader — no Composer in the runtime. Composer is dev-only.
• No custom database tables — all per-campaign config in post meta on wc-donation posts; templates in a single wp_options row.
• All persistence via update_post_meta / WP_Query — zero direct SQL outside $wpdb->prepare (in uninstall.php for the transient sweep).
• No remote runtime fetches — no analytics, no telemetry, no external dependencies at runtime.
• Auto-augmentation, not replacement — the donor sees parent's full form (cause selector, gift aid, processing fee, tributes, donor wall) with our interval-first UI mounted into parent's amount-block position via CSS / JS.
• Defense in depth on submit — three layers (server-side guard, JS short-circuit, disabled HTML) prevent preview HTML from ever submitting a real donation.

Full architectural overview: docs/architecture/current-state.md.

Testing

Run all gates locally:

composer check            # PHPCS + PHPStan + PHPUnit
composer test:contract    # parent-contract watcher
npm run test:e2e          # Playwright (requires tests/donation-for-woocommerce.zip)

Compatibility & status

This is a community-maintained companion. The parent plugin (Donation for WooCommerce by WPExperts) is not affiliated — the companion attaches via documented hooks rather than forking. A built-in self-check probe runs on every admin page load and surfaces an admin notice if any parent plugin update breaks a contract the companion depends on. A weekly CI watcher catches parent updates the moment they ship.

WPML compatibility certification is planned for post-WordPress.org acceptance — see plans/v2/AA-wpml-integration.md (gitignored locally; spec lives there).

Contributing

Bug reports, feature requests, and pull requests welcome. See:

• CONTRIBUTING.md for setup + PR flow
• SECURITY.md for vulnerability reporting
• .github/ISSUE_TEMPLATE/ for issue templates
• Pinned roadmap issue for scope discussion

License

GPL-2.0-or-later — same as the parent plugin and WordPress core. Compatible with the WordPress.org plugin directory's licensing requirements.

Copyright (c) 2026 David Stells.