Jerome Wincek

Tag: vchs-plugin-series

  • 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.

  • Managing shelter programs with WordPress and The Events Calendar

    The Venango County Humane Society runs weekly programs. Bingo every Tuesday and Saturday night. A feline spay and
    neuter clinic every Tuesday morning. Adoption events, fundraisers, volunteer orientations, education sessions — most of them recurring, most of them indefinite, all of them needing to appear on a public calendar so donors, volunteers, and community members know when and where to show up.

    The shelter already used The Events Calendar for its public calendar view — it’s the most popular event plugin in WordPress, well-maintained, and the free version handles everything you’d expect from an event display. Except for one thing: recurring events. That feature is paywalled behind The Events Calendar Pro,
    which starts at around $100 a year. For a shelter with a strict
    operating budget, that’s a real decision — and for a pattern as simple as “bingo every Tuesday and Saturday, forever,” it’s a lot of money to spend on a calendar.

    The natural workaround is The Events Calendar’s CSV import. You can build a spreadsheet with one row per event instance, upload it, and TEC will create the events. This works. It also means that every quarter, the front desk manager has to open a spreadsheet, duplicate last week’s bingo row thirteen more times, fix the dates, re-upload, and hope nothing went wrong. A recurring service generates 100+ events a year, and the import file has to be maintained as a rolling document. It’s not hard, exactly. It’s just constant, and it’s the kind of maintenance work that has no upside — it just has to get done.

    This post is about the plugin I built to make that go away. It’s at
    wp-content/plugins/vcpahumane-shelter-events-wrapper/ in the site’s tree, available as a GPL project at
    github.com/jwincek/vcpahumane-shelter-events-wrapper,
    and it went live on vcpahumane.org about two weeks ago. Currently two people edit events with it: me and the shelter’s front desk manager.

    The plugin is a thin authoring layer on top of The Events Calendar.
    You define a program once (“Bingo, every Tuesday and Saturday, 5 PM to 9 PM, at the shelter”), and the plugin generates individual TEC events for each occurrence on a rolling schedule. TEC continues to handle the public calendar display — this plugin doesn’t touch the front-end — but the authoring experience is now “describe the pattern” instead of “maintain a spreadsheet.” That’s the entire pitch.

    Is it a wrapper or an extension?

    The plugin is called “shelter-events-wrapper,” but reading the code I’d actually describe it as an extension alongside TEC, not a
    literal wrapper. The admin doesn’t stop using TEC’s interface — they still see TEC’s events list, still click into individual event posts
    to edit them when needed, still use TEC’s categories and calendar
    views on the front end. The plugin adds a second authoring surface (the Programs CPT) that generates TEC events but doesn’t replace TEC’s own editing.

    This matters because the plugin inherits TEC’s strengths for free.
    Every TEC extension in the ecosystem — integrations with booking
    systems, email marketing, social media sharing — keeps working. The calendar views, archive pages, and single-event templates remain TEC’s, which means they get TEC’s updates and accessibility improvements without anyone having to backport anything.

    It also means the plugin has a narrower responsibility: authoring
    recurring programs. It doesn’t try to be a better calendar. It just
    tries to be a better admin experience for the specific case of
    defining recurring services that run indefinitely.

    Decision 1: programs as a custom post type, events as the output

    The centerpiece is a custom post type called shelter_program. Each program has the fields you’d expect — title, description, recurrence pattern, start and end times, timezone, venue, organizer, cost — plus a few nonprofit-specific additions: a contact email, an “appointments required” flag, age restrictions, a “variable pricing” checkbox for services like the spay/neuter clinic where cost depends on the animal, and a blackout dates list.

    A program is not an event. It’s a description of a recurring service.
    When the cron runs, or when an admin clicks “Generate Events” on a dedicated page, the plugin walks forward through the calendar and creates individual TEC events for each occurrence that matches the program’s pattern. Those events are stored in TEC’s native tribe_events post type using TEC’s PHP ORM:

    ```php
$event = tribe_events()
    ->set_args( [
        'title'          => 'BINGO Night — Tuesday, April 15, 2025',
        'description'    => $program['description'],
        'start_date'     => $start,
        'end_date'       => $end,
        'timezone'       => $program['timezone'],
        'venue'          => $venue_id,
        'organizer'      => $organizer_id,
        'cost'           => $program['cost'],
        'featured'       => $program['featured'],
    ] )
    ->create();

    No direct database writes. No template overrides. No wrestling with TEC’s internals. The ORM exists precisely for this use case and it works well. The plugin’s contribution is the authoring UX and the automation; TEC’s contribution is everything else.

    The rolling window is eight weeks by default, configurable in config/events.json. Each daily cron run extends the window forward, creating new events as needed. Nothing is generated indefinitely into the future — just enough for visitors browsing the next two months to see what’s upcoming.

    Decision 2: deterministic hashes for duplicate prevention

    Cron runs, and it runs again, and sometimes it runs a third time because a stale job didn’t get cleaned up properly, and suddenly you have three copies of next Tuesday’s bingo on your calendar. This is the classic failure mode of “generate events from a schedule,” and the standard fix is to make event creation idempotent: running the generator twice should produce the same result as running it once.

    The plugin does this with a SHA-256 hash of the program slug plus the event date, stored as post meta on each generated event:

    private static function make_hash( string $slug, string $date ): string {
    return hash( 'sha256', $slug . '|' . $date );
}

private static function event_exists( string $meta_key, string $hash ): bool {
    global $wpdb;
    $exists = $wpdb->get_var(
        $wpdb->prepare(
            "SELECT COUNT(*) FROM {$wpdb->postmeta}
             WHERE meta_key = %s AND meta_value = %s",
            $meta_key,
            $hash
        )
    );
    return (int) $exists > 0;
}

    Before creating an event for a given program on a given date, the generator hashes the pair and checks whether an event with that hash already exists. If yes, skip. If no, create and stamp the hash onto the new post.

    This is simple enough that it sounds almost beneath mention, but the alternatives are worse: a unique compound meta key requires custom table creation; a title-based check breaks the moment you change a program’s name; a “last generated” timestamp on the program doesn’t handle partial runs. The hash approach is idempotent, storage-efficient, and fails safely — if somehow an event does get duplicated, the worst that happens is you delete one manually and the check prevents the next cron run from recreating it.

    Decision 3: the Replace workflow

    This is the decision I’m most pleased with, because it came directly from a problem I didn’t anticipate.

    Here’s the problem: programs run forever, but reality intervenes. “Bingo is cancelled this week because of the holiday.” “This month’s Feline Clinic is being replaced with a special shots-only session.” “Tuesday’s event is happening in a different venue because we’re renovating the main hall.” The recurring definition is still correct — bingo will resume next week — but one specific occurrence needs to change or be replaced.

    A naive solution is to let the admin edit the individual generated event in TEC’s interface. That works until the next cron run overwrites the edit, because the syncer sees a program-linked event that’s out of sync with its program definition and “corrects” it.

    The plugin solves this with an explicit Replace workflow. From the Generate Events admin page, each upcoming event gets a “Replace” action that does three things:

    1. Cancels the original event. It’s not deleted — the post stays in place with [CANCELLED] prepended to the title and a _shelter_cancelled meta flag set. This preserves a historical record and keeps the cross-references intact.
    2. Creates a brand-new draft event. The new event is pre-populated with the original’s date, time, venue, and organizer, but it’s otherwise a blank slate — the admin has full creative freedom to change the title, description, featured image, category, and anything else.
    3. Stores cross-references. The original gets a _shelter_replaced_by meta pointing to the new event’s ID; the new event gets a _shelter_replaces_event meta pointing back to the original. The Event Syncer respects this linkage — it will never re-sync a replaced event from the program definition, so the creative edits are safe from future updates.

    After clicking Replace, the admin is kicked into TEC’s native block editor for the new event. They can use TEC’s categories, meta, and content tools normally — nothing in the replacement workflow is proprietary to this plugin. When they publish, the new event appears on the calendar in place of the cancelled one. Two weeks later, the regular Tuesday bingo resumes without any further intervention.

    This is the feature that turns “a better way to create recurring events” into “a real tool for managing a recurring program.” Anyone building event tooling for a nonprofit will eventually run into “this week is different,” and having a thoughtful answer to that question is the difference between a demo and a production tool.

    Decision 4: weekly recurrence only (and why that’s probably wrong)

    Let me flag a real limitation honestly. The plugin only supports weekly day-of-week recurrence — “every Tuesday and Saturday” — and nothing more complex. It doesn’t handle “second Saturday of the month,” “last Friday of every month,” “every other Tuesday,” “alternating Mondays and Wednesdays,” or any other pattern that can’t be expressed as a fixed set of weekdays repeating every week.

    For VCHS’s current programs this is fine. Bingo is every Tuesday and Saturday; the clinic is every Tuesday. None of the shelter’s programs need anything more sophisticated right now.

    But I already know this won’t last. The moment the shelter adds a monthly fundraiser or a “second Saturday of the month” volunteer orientation, the plugin will fall over and I’ll have to extend it. The cleanest way to handle this is probably to adopt RFC 5545 RRULE syntax — the same standard iCalendar uses — which supports all of those patterns cleanly and has battle-tested PHP libraries. But that’s a nontrivial refactor of the metabox, the generator, and the UI, so I’ve punted on it for now.

    Worth knowing if you clone the plugin and your use case is more complex than “specific weekdays every week.” You’ll hit this wall faster than I did.

    Decision 5: the small UX details that matter for non-technical users

    One of the two editors using this plugin is the shelter’s front desk manager, who is not a developer and didn’t ask to be one. This shaped several small UX decisions that are worth noting because they’re the kind of thing that doesn’t make it into most technical posts.

    Day-of-week chips instead of a text field. The recurrence pattern is set by clicking toggle buttons for each weekday. Not a comma-separated list, not a dropdown, not an RRULE string — visual pill buttons that say “Mon Tue Wed Thu Fri Sat Sun” and light up when clicked. Anyone can understand this without explanation.

    “Dry run” preview on the generate page. Before actually creating events, admins can click “Generate (dry run)” to see a preview of what would be created. This makes the generator feel safe to experiment with. Running it accidentally doesn’t break anything; it just shows you a list.

    “Also update past events” checkbox, off by default. When you change a program — say, you correct a typo in the description, or change the venue — by default only future events are updated. Past events are frozen as historical record. The opt-in checkbox lets you override that when you actually want to retroactively fix past events, but it’s not the default because the default should preserve history.

    Cancelled events stay visible, with a badge. When an event is cancelled (either individually or via Replace), it isn’t deleted — it stays on the calendar with a “Cancelled” badge. This way anyone looking at the calendar retrospectively can see “yes, bingo was supposed to happen on March 5th, and it was cancelled, not missed.” For a recurring community program, that matters.

    The Staff Guide, rendered from README.md inside WordPress admin. There’s a dashboard page under Events → Staff Guide & Help that renders the plugin’s README.md as HTML. The parser is hand-rolled (it handles the specific Markdown subset the README uses — headings, lists, tables, code blocks, emphasis, links — nothing fancier) and has no external dependencies. The front desk manager can find help without leaving WordPress, without visiting GitHub, without knowing that GitHub exists. For a plugin with two users, one of whom is not technical, this matters more than any code-level architectural decision.

    None of these are flashy. None of them are “WordPress 6.9 Abilities API” or “Block Bindings” or any of the novel-sounding things. But they’re the decisions that determine whether the front desk manager actually uses the plugin or reverts to the spreadsheet. Technical sophistication without UX thoughtfulness is just a more elaborate spreadsheet.

    A warning about get_posts() and TEC venues

    This is a “small gift to the next developer” section, same spirit as the edit.asset.php gotcha from the companion plugin post.

    When creating TEC events from a program, the plugin needs to reuse existing venues and organizers if they already exist with the same name — otherwise every sync creates duplicate venues, and you end up with forty-seven “Venango County Humane Society” entries in the venues list.

    The natural way to look up a venue by name is:

    $existing = get_posts( [
    'post_type' => 'tribe_venue',
    'post_title' => $venue_name,
    'post_status' => [ 'publish', 'draft' ],
    'posts_per_page' => 1,
] );

    This does not work. get_posts() silently ignores the post_title parameter — it’s not a supported WP_Query argument, despite looking like it should be. get_posts() will return the first venue it finds regardless of title, and if there are no venues at all it’ll return an empty array. You won’t get an error. You won’t get a warning. You’ll just get the wrong result, and your plugin will quietly create duplicate venues every sync.

    The fix is a direct $wpdb query:

    $existing_id = $wpdb->get_var(
    $wpdb->prepare(
        "SELECT ID FROM {$wpdb->posts}
         WHERE post_type = 'tribe_venue'
           AND post_title = %s
           AND post_status IN ('publish', 'draft')
         LIMIT 1",
        $venue_name
    )
);

    This is one of those “WordPress quirk” things that’s well-known if you’ve dealt with it before and completely invisible if you haven’t. I lost real time to this during development. If you’re writing any plugin that looks up posts by title, always go through $wpdb directly, not get_posts() or WP_Query — they quietly don’t support title filtering even though the documentation makes it look like they do.

    (As a bonus, the plugin’s title-match query also promotes any matching draft venues to publish status when they’re reused. This avoids a subtle bug where a venue created manually but left as a draft would stay invisible on the calendar even though events were being assigned to it.)

    What’s still open

    Features I haven’t built yet, in rough order of how likely I am to actually need them:

    1. Monthly and more complex recurrence patterns. The weekly-only limitation will bite eventually. RFC 5545 RRULE is the right answer; doing the refactor well is the hard part. If you have experience with RRULE parsing libraries for PHP, I’d love help with this.
    2. A proper date picker for blackout dates. Currently blackout dates are entered as a textarea with one date per line in YYYY-MM-DD format. It works. A calendar widget would be kinder to the non-technical user.
    3. Bulk actions on programs. If you want to pause five programs at once (say, during a facility renovation), you currently have to edit each one individually. A bulk action on the programs list table would be a small, useful addition.
    4. Time-of-day differences within a recurrence pattern. Currently a program has one start time and one end time, so “Bingo is 5 PM on Tuesdays but 7 PM on Saturdays” requires two separate programs. That’s fine for now but it’s a papercut.
    5. An iCal export endpoint. TEC already provides this for its own events, so it’s probably already covered, but worth verifying. If TEC’s iCal doesn’t include shelter-program-generated events correctly, a custom export would be useful.
    6. An optional “import from TEC CSV” migration path for shelters already using CSV imports. It should be possible to detect repeating patterns in an existing CSV file and offer to convert them into program definitions. Not built yet.

    None of these are blocking anyone. The plugin is doing its job for VCHS’s current programs, and the absent features are nice-to-haves rather than dealbreakers. But if you’re a developer who wants to contribute and any of these sound interesting, the repo is open and I’d be happy to pair on design.

    How other shelters could use this

    This is a case study more than a pitch, but I want to say something honest about portability.

    The plugin is written for a specific shelter with specific programs, and the seed data in config/events.json reflects that — it creates bingo and the spay/neuter clinic as starter programs on first activation. For another shelter to use the plugin, the first thing they’d need to do is delete those seed programs and create their own.

    The category taxonomy (Fundraiser, Clinic, Adoption, Education, Volunteer) was chosen for VCHS’s programming but is generic enough that most shelters would find it applicable. Categories are editable from the WordPress admin like any normal taxonomy, so a shelter with different needs can add their own without touching code.

    The plugin’s text domain is shelter-events (not vcpahumane-*) because I wanted it to feel generic enough to apply elsewhere. The UI strings, the field labels, the help text — none of them reference VCHS specifically. A shelter in Idaho could install this plugin and use it without seeing “Venango County” anywhere.

    That said, I haven’t actually tested it at another shelter. If you run a small nonprofit that manages recurring programs and you’re currently wrestling with TEC’s CSV import, I’d love to hear whether this plugin would work for you, and what would need to change to make it usable. Open an issue, send an email, whatever works.

    The repo: github.com/jwincek/vcpahumane-shelter-events-wrapper

    License: GPL

    Requires: WordPress 6.4+, The Events Calendar (free), PHP 8.1+

    Status: Live on vcpahumane.org as of two weeks ago. Two active users. Currently managing two recurring programs generating several events a week; tested at smaller scale than it would ideally support, but no known issues.

    If you’re building similar tools for other nonprofits, I’d love to compare notes. And if you’re a nonprofit and you’d like to try this plugin, I’d love even more to hear whether it actually helps.

  • 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.