Jerome Wincek

Tag: WooCommerce

  • Simple Spam Shield: a lightweight, cloud-free WordPress anti-spam plugin

    This is the last post in a series about plugins I’ve built for the Venango County Humane Society. The previous five posts covered shelter-specific WordPress work — adoptable pet listings, a Petstablished sync engine, a donations platform, a recurring events manager. All of them are specialized for nonprofit use cases; none of them would make sense outside of that context.

    This post is about the one plugin in the stack that has nothing to do with animals, donations, or shelters. It’s a spam plugin. It’s called Simple Spam Shield, and the only connection to the shelter is that it was born from a shelter problem.

    Here’s the problem. Within weeks of being posted, the shelter’s volunteer application form — built using Jetpack’s Contact Form blocks — started receiving thousands of fake submissions. Casino spam, pharma spam, SEO link dumps, the usual. So many that I had to wade through hundreds of pages of garbage to find real volunteer applications. We were using WordPress blacklisted terms at the time.

    The obvious answer was Akismet. It’s the default WordPress spam
    solution, it’s free for personal sites, and it works well. But it sends every form submission to Akismet’s cloud service for analysis, which means every volunteer applicant’s name, email address, and personal information passes through a third-party server. For a nonprofit that handles sensitive community data, that felt wrong. The alternative — installing a commercial anti-spam plugin with a $50/year license — felt like the same paywall dynamic I’d been building around in the other plugins.

    So I built a spam shield. No cloud. No API keys. No external
    dependencies. Everything runs locally on the WordPress server. It
    protects comments, WooCommerce product reviews, and Jetpack Contact Forms using a small bundle of proven mechanisms that don’t require phoning home. It’s been running on vcpahumane.org for a few weeks as the site’s only spam protection.

    The repo is at github.com/jwincek/simple-spam-shield. GPL, zero-config out of the box, designed to be useful to any WordPress site that wants spam protection without a cloud dependency.

    What “simple” means

    The name is deliberate. “Simple” doesn’t mean the code is a single
    file — it’s a few thousand lines of PHP with config-driven guard
    definitions, a normalized data pipeline, and per-surface integration classes. “Simple” means the feature selection is small and focused: seven spam-detection mechanisms, three protected surfaces, one settings page, one log viewer. No machine learning, no remote API, no cloud dashboard, no premium tier.

    The thesis is that a handful of well-implemented local checks —
    honeypot fields, time gates, duplicate detection, nonce validation, link counting, keyword matching, and optional behavioral scoring — catch the vast majority of automated spam without needing to send user data off-server. They don’t catch everything. A determined human spammer will get through. But for the kind of automated form-crawling that floods small sites, they’re effective and they preserve privacy.

    The guard pipeline

    The plugin’s core is a weighted, short-circuit pipeline called the
    Guard_Runner. Seven guards are defined in config/guards.json, each with a weight that determines execution order. The runner sorts guards by weight (highest first), initializes them, and runs them sequentially against the submission data. The first guard that fails blocks the submission — no further guards run.

    GuardWeightDefaultWhat it does
    Honeypot100OnHidden form field that bots fill in, humans don’t
    Duplicate95OnMD5 hash of content + author + email + IP, checked against a 60-second transient window
    Time Gate90OnRejects submissions faster than 3 seconds after page load
    Nonce80OnStandard WordPress nonce verification
    Link Limit70OnRejects submissions with more than 3 URLs
    Keyword Block60OnCase-insensitive matching against a blocklist
    Behavioral55OffScores mouse movements, clicks, and time on page

    The weight ordering is intentional: cheap checks run first. The
    honeypot is a single empty-field check — essentially free. The
    duplicate guard is a transient lookup. The time gate is arithmetic.
    By the time the runner reaches keyword matching (which involves
    string operations against a list), most bot submissions have already been caught and rejected by a faster check.

    All seven guards implement a shared Guard_Interface and extend Abstract_Guard, so adding an eighth guard is a matter of writing one class and adding an entry to guards.json. The pipeline doesn’t need to know about the new guard’s internals — just its weight and whether it’s enabled.

    Three surfaces, one normalized layer

    The plugin protects three different form systems, each with its own submission lifecycle:

    • WordPress comments — intercepted via the preprocess_comment filter at priority 1
    • WooCommerce product reviews — intercepted via
      woocommerce_new_comment (reviews are stored as comments but go through WC’s own flow)
    • Jetpack Contact Forms — intercepted via
      jetpack_contact_form_is_spam filter

    Each surface has a thin integration class in includes/integrations/ whose only job is to normalize the submission data into a common format — content, author, email, plus any JS-injected fields (honeypot value, nonce, timestamp) — and pass it to the Guard_Runner. The guards never need to know which surface the data came from.

    This is the same pattern as the Petstablished sync plugin’s abilities layer: a normalized interface between the outside world and the core logic, so the core logic stays clean and testable regardless of how many input surfaces you add. If someone wanted to add protection for Gravity Forms or WPForms, they’d write one integration class, normalize the data, and the existing seven guards would apply automatically.

    The Jetpack problem (and the two-phase workaround)

    Jetpack Contact Forms are the hardest surface to protect, and the reason is worth documenting because other plugin developers will run into the same wall.

    When a Jetpack form is submitted, Jetpack’s processor recognizes only the fields defined in the form’s configuration. Any extra fields that the plugin injects — the honeypot field, the nonce, the timestamp, the behavioral data — are silently stripped
    from $_POST before Jetpack’s spam filter fires. By the time the
    plugin’s jetpack_contact_form_is_spam filter runs, the JS-injected guard data is gone.

    The solution is a two-phase pipeline:

    Phase 1 runs before Jetpack processes the form. At this point,
    raw $_POST still contains the injected fields, so JS-dependent
    guards (honeypot, nonce, time gate, behavioral) can check their
    data and set a rejection flag.

    Phase 2 runs during Jetpack’s own spam filter. If Phase 1 already flagged the submission, it returns immediately. Otherwise, it runs content-based guards (keyword block, link limit, duplicate) against Jetpack’s structured form data — which is available at this
    point even though the JS fields aren’t.

    The guards themselves handle the edge case gracefully: if a guard expects a field that’s missing (because Jetpack stripped it), it skips rather than hard-failing. This means even if Phase 1 doesn’t fire for some reason, the content-based guards still protect the form. Defense in depth, with graceful degradation.

    This is the kind of integration problem that doesn’t show up in
    documentation or tutorials. Jetpack’s field-stripping behavior is
    undocumented and invisible until you try to inject custom fields
    into a form submission and watch them disappear. If you’re building any plugin that needs to intercept Jetpack form data, plan for this.

    The keyword list problem

    Let me be honest about the plugin’s current biggest weakness: the default keyword blocklist has seven entries.

    ‘casino, poker, viagra, cialis, crypto airdrop, free money, click here now’

    Seven words. That’s the out-of-the-box protection against
    keyword-based spam. The other six guards (honeypot, time gate,
    nonce, duplicate, link limit, behavioral) don’t depend on keywords
    and work fine, but keyword blocking is the guard that catches
    content-aware spam — the submissions that are crafted to look
    human-like but contain telltale phrases. Seven keywords is not
    enough for that.

    The reason it’s seven is that I’ve been cautious about false
    positives. Every keyword added to the default list is a keyword
    that could block a legitimate submission on someone’s site I’ve
    never seen. “Casino” is safe — no legitimate volunteer application
    mentions casinos. But “free” alone would block real content. “Buy”
    would block WooCommerce review discussions. The default list needs to be universally safe, which means it needs to be conservative, which means it’s small.

    This is the single most useful contribution someone could make to this plugin right now: a curated, well-tested default keyword
    list that’s aggressive enough to catch common spam patterns but
    conservative enough to avoid false positives on typical WordPress
    sites. If you maintain a WordPress site and have access to your
    spam folder, the phrases in there are exactly what this list needs.
    Open an issue, paste the patterns, and I’ll merge them.

    The admin can add site-specific keywords from the settings page
    (it’s a textarea, one keyword per line), but the defaults should
    be good enough that most sites don’t need to touch them.

    Allowlisting and the privacy model

    Before any guard runs, the pipeline checks the submitter’s IP
    and email against an allowlist. The allowlist supports exact IPs,
    CIDR ranges (e.g., 10.0.0.0/8), exact email addresses, and
    domain patterns (e.g., @trusted.org). Allowlisted submissions
    bypass all guards entirely.

    The broader privacy model is simple: no data leaves the server.
    Form submissions are checked locally. Blocked attempts are logged to a custom database table on the site’s own database. The log captures the guard that triggered, the reason, a content excerpt, the IP, and the user agent — enough to diagnose false positives, not enough to build a surveillance profile.

    The log can be disabled entirely from the settings page, and
    uninstall.php drops the log table and deletes all plugin options and transients. A clean uninstall leaves no orphaned data behind.

    This is the part of the plugin I feel most strongly about. Spam
    protection and privacy should not be in tension. The reason cloud-based spam services exist is that they can aggregate data across millions of sites to build better models — and that’s genuinely effective. But for a small nonprofit handling volunteer applications and donation forms, the tradeoff of sending that data to a third party isn’t worth it. A local-only approach is good enough for the threat model, and it respects the people filling out the forms.

    What’s still open

    Features that would make the plugin meaningfully better, in rough
    order of impact:

    1. A larger, better-curated default keyword list. I said this above but it bears repeating: this is the highest-leverage contribution anyone can make. The plugin’s architecture is solid; its vocabulary is anemic. If you have a collection of spam phrases from your own site, please share them.

    2. A “block this” button in the log viewer. Currently, if an admin sees a blocked submission and wants to add the offending
    phrase to the keyword list, they have to copy it, navigate to
    settings, paste it into the textarea, and save. A one-click “add to blocklist” action from the log viewer would close that loop.

    3. A “whitelist this” button in the log viewer. Same idea: if a legitimate submission was blocked, the admin should be able
    to allowlist the IP or email directly from the log entry.

    4. Gravity Forms / WPForms / CF7 integrations. The normalized
    data layer makes this straightforward — one integration class per
    form plugin. I’ve only built the three surfaces I needed (comments, WC, Jetpack). If you use a different form plugin and want to contribute an integration, the architecture is ready for it.

    5. A community-maintained blocklist. The most ambitious
    version of item 1: a shared, versioned keyword list that sites can
    subscribe to (via a simple GitHub-hosted JSON file, not a cloud
    service). Sites would pull keyword updates on a schedule without
    sending any data back. This preserves the no-cloud model while
    benefiting from collective intelligence. Not built yet, but the
    architecture would support it cleanly.

    Why this is the last post in the series

    This series started with a post about a pet adoption plugin — the kind of thing that only makes sense if you know about the Venango County Humane Society specifically. It ends with a spam
    plugin that has nothing to do with animals, shelters, or
    northwestern Pennsylvania.

    That’s the arc I want to name explicitly, because I think it
    generalizes.

    When you start building for a specific organization — especially
    a small nonprofit doing cost-critical work that shouldn’t need to buy solutions off the shelf — you build the specific things first. A pet sync engine. A donation platform. An events manager. Each one is tailored to one organization’s needs, and each one is useful to other organizations with similar needs. The circle of relevance is small but real.

    But along the way you inevitably build generic things too. A spam
    plugin. A caching pattern. A config-driven registration framework.
    An edit.asset.php file that you document in a blog post so the
    next developer doesn’t lose an hour to the same gotcha. These are the by-products of specific work that turn out to be useful to
    everyone.

    I think this is how open-source nonprofit infrastructure actually
    gets built. Not by someone deciding to build “a platform for
    nonprofits” in the abstract, but by someone solving real problems
    for a real organization, publishing the solutions, and discovering
    that the specific and the generic are interleaved in ways you
    can’t predict in advance.

    Six plugins, six posts, one shelter. If any of them are useful to
    you — whether you run a shelter, a nonprofit, a small business, or
    just a WordPress site that gets too much spam — I’m glad. And if
    you want to help make any of them better, the repos are all open
    and I’ll be here.

    The repos:

    All GPL. All welcome contributions of any size.

    Thank you for reading this series. If you’d like to start from the beginning, the first post is here.

  • Building an open-source donations plugin for small nonprofits (without the paywall)

    If you’ve ever helped a small nonprofit pick a WordPress donation plugin, you already know the shape of the problem. There are several reputable options — GiveWP, Charitable, WooCommerce’s own donation extensions — and all of them follow the same business model: a free version that handles basic one-time donations, and a paid tier that unlocks the features the
    nonprofit actually needs. Recurring donations: paid. Custom fields: paid. Campaign progress bars: paid. Donor management: paid. Tax receipts: paid. The paid tiers usually start around $200 a year and climb from there.

    For a well-funded nonprofit, $200 a year is a rounding error. For a
    small no-kill shelter that runs on community donations / memberships and operates on a tight budget, it’s a real expense — and worse, it’s an expense that scales the wrong way: the more your nonprofit grows, the more features you need, the more you pay. You end up paying a software vendor for permission to accept your own donations.

    This post is about a plugin I built to refuse that bargain. It’s called
    vcpahumane-wc-donations (still named starter-shelter internally — more on that in a moment), and it’s a WordPress plugin that turns WooCommerce into a real donations platform without locking the useful features behind a paywall. It powers the donations system at Venango County Humane Society, a small no-kill shelter in northwestern Pennsylvania that I’ve been doing development work for since early 2025.

    The plugin went live on the production site last week. As of this writing it’s deployed, integrated, and ready. Writing this now feels like the right moment: while the design decisions are fresh and before the inevitable post-launch reality has forced me to revise them.

    The repo is at github.com/jwincek/vcpahumane-wc-donations. It’s GPL, the issues tracker is open, and developer collaboration is the primary reason this post exists.

    A note about the name

    The plugin’s GitHub repo and the post title both call it
    vcpahumane-wc-donations, but if you clone the repo and look inside, the main file is starter-shelter.php, the namespace is Starter_Shelter\, and the text domain is starter-shelter. That’s residual from earlier iterations — the plugin started as a “shelter donations starter template” intended to be reusable across different shelter sites, then got specific to VCHS, then I started thinking about it as a generic starter again. A rename is planned but hasn’t happened yet.

    I’m mentioning this up front because it’s exactly the kind of thing
    that will confuse a developer cloning the repo for the first time, and I’d rather acknowledge the inconsistency than pretend it isn’t there. Everything in this post that says “vcpahumane-wc-donations” you can read as “the plugin formerly known as starter-shelter, currently being renamed in place.” If you contribute a PR before the rename is done, you’ll see both names floating around, and that’s expected.

    What this plugin does, briefly

    It accepts donations, memberships, and in-memoriam tributes through WooCommerce’s checkout. It stores those records as custom post types that the shelter can query, report on, and display however they want. It ships with about ten Gutenberg blocks for donation forms, memberships, memorial walls, campaign progress, and donor stats. It has an admin UI for managing everything. It’s all GPL.

    It does not (yet) support recurring donations, donor self-service
    accounts, tax receipt PDFs, or employer matching. Those are real gaps and I’ll talk about them at the end. The plugin is intentionally a starting point, not a finished product.

    What it does have, that I think is architecturally interesting:

    1. A pattern for syncing custom post types with WooCommerce variable products that lets you treat donations as first-class data instead of as a side effect of e-commerce orders
    2. A JSON-driven input mapping system that converts WooCommerce order data into structured donation records without writing any custom processing code per donation type
    3. A memorial wall block that solves a real maintenance problem the shelter was facing
    4. WordPress 6.9 Abilities API integration that gives the plugin the same single-source-of-truth architecture I wrote about for the Petstablished sync plugin

    Decision 1: CPTs over WooCommerce as the source of truth

    The first and biggest decision. Most WordPress donation plugins do one of two things:

    • Build their own checkout, payment gateway integration, and order storage from scratch (this is what GiveWP does)
    • Treat donations as WooCommerce orders and store everything in the WooCommerce order tables (this is what most WC-based donation plugins do)

    The first approach means rebuilding everything WooCommerce already does. The second approach means your donation data lives in tables designed for selling t-shirts, not for tracking philanthropic giving — and querying “how much did this donor give in 2025, and to which programs” requires joining wp_wc_orders to wp_wc_order_itemmeta to figure out what the line items meant.

    This plugin takes a third approach. WooCommerce handles the transaction, custom post types are the source of truth for the donation data. When a customer completes an order containing donation items, the plugin processes the order, extracts the donation-relevant data, and creates new posts in custom post types:

    • sd_donation — one record per donation transaction
    • sd_membership — one record per active membership
    • sd_memorial — one record per memorial tribute
    • sd_donor — one record per unique donor (deduplicated by email)

    The WooCommerce order remains as the transaction log, but it’s not where queries go. When the admin asks “show me all donations from November 2025 grouped by donor,” the query runs against sd_donation posts (which are indexed and meta-cached normally), not against the WooCommerce order tables.

    This has several practical benefits:

    Reporting is fast and natural. A WP_Query against
    post_type => 'sd_donation' with date and donor filters is the kind of query WordPress is designed for. Joining order tables for the same question requires custom SQL.

    Donations have their own permalinks, taxonomies, and meta. A
    donation can be tagged to a campaign, attached to a memorial, marked anonymous, given a public-facing display name distinct from the billing name, and so on — all using WordPress’s native meta and taxonomy systems.

    The plugin can evolve independently of WooCommerce. If WooCommerce changes its order table structure (and it has, recently), the donation data is unaffected. The integration layer is small and the data layer is decoupled.

    Migrations and exports are easy. Exporting “all donations” is a
    post export, not a WooCommerce order export with a filter applied.

    The cost is that the plugin has to maintain the sync from orders to
    posts, which is the next decision.

    Decision 2: a config-driven input mapping DSL

    When a WooCommerce order completes, the plugin needs to know which items are donations, which are memberships, which are memorial tributes — and for each one, how to extract the relevant fields from the order’s line items, custom checkout fields, product variations, and order meta. Hardcoding that logic per product type would mean a PHP function per donation type, and adding a new donation type would require code changes.

    Instead, the entire mapping lives in config/products.json:

    
```json
{
  "shelter-donations": {
    "ability": "shelter-donations/create",
    "input_mapping": {
      "amount": { "source": "item_total" },
      "allocation": {
        "source": "attribute",
        "key": "preferred-allocation",
        "transform": "normalize_allocation",
        "default": "general-fund"
      },
      "dedication": { "source": "order_meta", "key": "_sd_dedication" },
      "is_anonymous": {
        "source": "order_meta",
        "key": "_sd_is_anonymous",
        "transform": "boolean",
        "default": false
      },
      "campaign_id": { "source": "order_meta", "key": "_sd_campaign_id" }
    }
  },
  "shelter-memorials": {
    "ability": "shelter-memorials/create",
    "input_mapping": {
      "honoree_name": { "source": "order_meta", "key": "_sd_honoree_name" },
      "memorial_type": {
        "source": "attribute",
        "key": "in-memoriam-type"
      },
      "tribute_message": {
        "source": "order_meta",
        "key": "_sd_tribute_message"
      },
      "notify_family": {
        "source": "composite",
        "fields": {
          "enabled": { "source": "order_meta", "key": "_sd_notify_family_enabled" },
          "name": { "source": "order_meta", "key": "_sd_notify_family_name" },
          "email": { "source": "order_meta", "key": "_sd_notify_family_email" }
        }
      }
    }
  }
}

    The Product_Mapper class reads this config and turns it into the input array passed to the corresponding ability. It supports several “source” types — item_total, attribute, order_meta, order_field, item_meta, product_meta, static, and composite (for nested fields like the family notification block) — plus optional transform functions and default values.

    The win here isn’t that the input mapping system is unusual — it’s that adding a new donation type is a JSON edit, not a code change. Want to add a “wishlist item purchase” donation type that maps to a specific allocation? Add an entry to products.json, point it at an existing or new ability, and the order processor handles the rest. The plugin doesn’t need to learn about the new product type at the PHP level.

    I’ll be honest: this is the kind of pattern that’s easy to over-engineer. For a plugin with three product types I could have just written three PHP functions and called them from a switch statement. I went with the config-driven approach because (a) I expect to add more product types over time, and (b) I’d already built the same pattern for the Petstablished sync plugin and was happy with how it scaled. The cost of the abstraction is low; the benefit compounds with each new type.

    Decision 3: the memorial wall

    I want to spend some time on this section because it’s the feature that has the clearest non-technical story, and it’s the second-most important thing the plugin does after actually accepting donations.

    The Venango County Humane Society receives around 300 memorial donations a year. Most of those are “in memory of” tributes — someone loses a beloved pet or family member and makes a donation to the shelter in their memory. The shelter’s previous practice was to maintain a flat list / spreadsheet of memorials on their website, manually, by hand. As you can imagine, this was a real pain to keep up: every memorial meant editing a static page, every typo meant re-editing it, and it scaled badly with volume.

    The shelter would have accepted the same flat list / spreadsheet. What they got instead is the memorial wall block: a paginated, searchable, year-filterable grid of all public memorial tributes, with each card showing the honoree’s name, the tribute message, the donor’s name (unless they chose to be anonymous), and the date. The block uses the WordPress 6.9 Interactivity API for client-side pagination — search and filter without page reloads, with bookmarkable URL state via query parameters.

    <!-- wp:vcpa/memorial-wall {
    "columns": 3,
    "perPage": 12,
    "showSearch": true,
    "showYearFilter": true,
    "paginationStyle": "numbered"
} /-->

    The data flows like this: a memorial donation is placed via the memorial form block in the donation flow; it goes through WooCommerce checkout; the order processor extracts the honoree name, message, and donor info; a new sd_memorial post is created; and the memorial wall block displays it on the next page render. End to end, the only “manual” step is the donor filling out the form. The shelter staff doesn’t touch anything.

    Three things about this section worth knowing:

    The memorial wall grew out of a separate plugin. I originally built in-memoriam-donations-manager as a standalone plugin and later folded its functionality into the donations plugin. The separate plugin still exists in the same parent directory but it’s deprecated. The lesson: when two plugins are doing related work for the same nonprofit, fold them together early. The architectural overhead of maintaining two plugins for one shelter is real and not worth it.

    Anonymous donors are first-class. The form has an “anonymous” checkbox; when it’s checked, the donor name is replaced with “Anonymous” on the wall but the donation itself is still recorded under the donor’s account in the database. The display layer respects the privacy choice; the data layer doesn’t lose information.

    The donor name is denormalized into the memorial post. When the memorial is created, the donor’s display name is copied into a _sd_donor_display_name meta field on the memorial post. This is unusual — the “right” way would be to look up the donor by ID at display time. The reason for the denormalization is search: the memorial wall has a search box, and searching across memorials by donor name without N+1’ing into the donor table requires the donor name to be on the memorial post itself. This is a deliberate performance decision that I’m noting here because it’s the kind of thing that looks wrong on first read.

    Decision 4: Abilities API as the action layer

    Same pattern as the Petstablished sync plugin (which I wrote about in a previous post in this series), so I’ll keep this section short. Every action the plugin can take is registered as a WordPress 6.9 Ability with a name, an input schema, a permission callback, and an execute function:

    • shelter-donations/create — create a new donation record
    • shelter-donations/list — list donations with filters
    • shelter-memorials/create — create a new memorial
    • shelter-memorials/list — list memorials with filters
    • shelter-memberships/create — create a new membership
    • shelter-donors/get — get a donor by email
    • shelter-donors/upsert — create or update a donor
    • shelter-reports/summary — aggregate reporting
    • … and several more

    When a WooCommerce order completes, the order processor doesn’t write to the database directly — it executes abilities. When the memorial wall block fetches data, it executes the shelter-memorials/list ability. When the admin reports page generates a summary, it executes the shelter-reports/summary ability.

    The benefit, as in the Petstablished plugin, is that there’s one implementation of “create a donation” in the entire codebase, and the order processor, the REST API, the import/export tools, and the internal data integrity checks all share it. If I change how donations are stored, the change happens in one place.

    The Abilities API also gives me a clean permission model. Most abilities are declared as internal (only callable from the plugin itself) or admin_only. The few that need front-end access — for the memorial wall block, the donor stats block, the donation form’s campaign list — go through a thin REST wrapper, the same pattern I documented in the Petstablished sync post.

    Decision 5: standard WooCommerce variable products with custom prices

    The plugin doesn’t define a custom WooCommerce product type. Donations, memberships, and memorials are all standard variable products with specific attributes:

    • shelter-donations (product) → variations for “General Fund,” “Medical Care,” “Food & Supplies,” etc., via the preferred-allocation attribute
    • shelter-memberships (product) → variations for tier names (“Single $10,” “Family $25,” “Contributing $50”) via the membership-level attribute
    • shelter-donations-in-memoriam (product) → “Person” or “Pet” variations via the in-memoriam-type attribute

    All of these products are created automatically on plugin activation by an Activator class. They’re marked virtual (no shipping), no inventory tracking, and tax-exempt. The product images are inline SVGs generated at activation time.

    The clever part is that these are variable products with dynamic prices. WooCommerce normally requires variations to have fixed prices, but the donation forms let the donor enter any amount. The plugin uses the woocommerce_before_calculate_totals hook to override the line item price before the cart total is calculated:

    add_action(
    'woocommerce_before_calculate_totals',
    function ( $cart ) {
        foreach ( $cart->get_cart() as $cart_item_key => $cart_item ) {
            if ( isset( $cart_item['sd_custom_amount'] ) ) {
                $cart_item['data']->set_price( $cart_item['sd_custom_amount'] );
            }
        }
    }
);

    This works, and it’s the standard way to do “name your own price” products in WooCommerce, but it’s the kind of thing that would be nice to formalize. A custom product type might be cleaner long-term; for now, the standard variable product approach has the benefit of working with every WooCommerce extension out of the box.

    What’s still open

    Five features I haven’t built yet, in rough order of how often they get requested by nonprofits:

    1. Recurring donations. This is the single biggest gap. Monthly donors are roughly five to ten times more valuable to a nonprofit over their lifetime than one-time donors, and every commercial donation plugin paywalls recurring giving as their flagship premium feature. WooCommerce Subscriptions is a natural fit and the plugin’s order processor already has a hook for woocommerce_subscription_renewal_payment_complete — the missing work is the membership-renewal-handling logic, the donor-facing UI for managing recurring donations, and the failure handling for declined renewals. This is the feature I most want help building, and the one most likely to make this plugin an actual replacement for paid alternatives.

    2. Donor accounts and a self-serve donor portal. Currently, donors have no way to log in, see their giving history, update their contact info, or change a recurring donation. WooCommerce’s “My Account” page is registered but it’s mostly empty for donor-specific use cases. I’m planning to pick this up next.

    3. Tax receipts. Year-end donor summaries (PDF, optionally emailed) and individual donation receipts are useful for both donors and shelter staff. The shelter currently handles this manually, which is the kind of work that scales badly with donor count. There’s a stub donation-receipt email template in the plugin but no PDF generation behind it.

    4. Employer matching support. Many corporate donors check “is this match-eligible?” before giving. A simple “your employer matches donations” question on the donation form, plus a list of known match-eligible employers that the shelter can maintain, would unlock a meaningful slice of corporate giving without requiring full matching automation.

    5. Business sponsor logo display. The plugin already collects business sponsor logos at checkout (with admin moderation) but doesn’t have the front-end blocks to actually display them anywhere. Picking this up alongside donor accounts.

    If any of those sound interesting and you’d like to take a swing, the repo welcomes issues and pull requests. The codebase has good separation of concerns, the abilities pattern means most new features can be added without touching unrelated code, and I’m happy to pair on design decisions before anyone starts implementing.

    A few smaller things worth knowing

    The plugin requires WordPress 6.9 and WooCommerce. The 6.9 requirement comes from the Abilities API; the WooCommerce requirement is obvious. This is a meaningful constraint — some smaller shelters don’t have 6.9 yet — but it’s the right constraint, because the plugin’s architecture wouldn’t work without abilities.

    There are no automated tests yet. Same admission as the companion plugin and the sync plugin. The donation flow in particular would benefit from end-to-end tests, and the order processor is the right candidate for a unit-testable harness. If you want to contribute a test setup, this is the most valuable kind of contribution you can make.

    Performance is decent but not benchmarked. The plugin uses an Entity Hydrator pattern with N+1 prevention (same approach as the Petstablished sync plugin), but I haven’t actually measured page load times under realistic donation volumes. If you’re using this on a site with thousands of memorials, please open an issue with your numbers — even “no problems noticed” is useful data.

    There’s a legacy data migration tool for shelters coming from other donation plugins. It’s currently scoped to the specific predecessor I wrote (shelter-donations-wc-simple) but the framework is general — if you’re moving from GiveWP, Charitable, or another WC-based plugin, it should be possible to write an importer module.

    Why I built this

    I want to close on something I’ve been thinking about a lot, both for this plugin and for the others in this series of posts.

    Nonprofit software has a particular flavor of business model that’s worth naming explicitly. Most commercial nonprofit tools — donation platforms, donor management CRMs, email marketing systems, event management — operate on the principle that the most important features should cost money, and that nonprofits will pay for them because they have to. This is a perfectly rational business model. It’s also, collectively, a tax on the entire nonprofit sector. Money that could be spent on programs is instead spent on software vendors.

    Open source has historically been bad at addressing this. The free WordPress donation plugins exist, but they’re free because they’re deliberately limited, with the expectation that serious nonprofits will upgrade. The premium tiers are not “for the very largest nonprofits with complex needs” — they’re for anyone who actually wants to run a donation program. The pricing is not designed to reflect cost; it’s designed to capture value from organizations that can’t afford to negotiate.

    A genuinely open-source alternative is uncomfortable for everyone involved. It threatens the commercial vendors’ business model, it asks nonprofits to use software that doesn’t have a 24/7 support hotline, and it puts the burden of maintenance on developers who have to find some other way to fund their time. It is not obviously sustainable. I am building this on a small monthly stipend from a shelter that has fewer than sixty animals at a time, and the math of “how does this scale to other shelters” is genuinely unclear to me.

    But I think it’s worth doing anyway, for three reasons:

    1. The technical foundations have gotten dramatically better. WordPress 6.9’s Abilities API, WooCommerce’s maturity as a payments platform, the Block Editor’s evolution into a real content management surface, the Interactivity API — these are the building blocks that make a serious open-source donation plugin tractable for one developer to build. Five years ago this would have been a much bigger project.
    2. The collective value is much larger than the per-shelter value. A plugin that saves one shelter $200 a year in software fees is not interesting. A plugin that saves a thousand shelters $200 a year each is $200,000 a year of recovered nonprofit budget. The marginal cost of a shelter adopting an existing plugin is nearly zero; the marginal value is real.
    3. Someone has to start. Open-source nonprofit infrastructure doesn’t exist by default. It exists because individual developers decide to build it and then maintain it. I am one such developer building one such piece of infrastructure for one such nonprofit, and I’m publishing it openly in the hope that others will find it useful.

    If you work for or with a nonprofit and you’d consider trying this plugin, I’d love to hear from you. If you’re a developer who’s frustrated by the same paywalled-features dynamic and you want to help, even better.

    The repo is at github.com/jwincek/vcpahumane-wc-donations. Issues, PRs, and emails are welcome.