bbPatreon for phpBB 3.3

Patreon integration for phpBB — link patron accounts via OAuth and automatically manage forum group membership based on pledge tiers. Developed and maintained by Avathar.be.

Version

1.3.0

Support

• Support forum

Requirements

• phpBB 3.3.0 or higher
• PHP 8.1 or higher
• PHP curl extension

Features

Account linking

• Users link their Patreon account from the UCP via OAuth 2.0
• Unlink from UCP with immediate group demotion

Tier-based group sync

• Automatic phpBB group assignment based on Patreon pledge tier
• Tier-to-group mapping configured in the ACP with "Fetch Tiers" button (no manual ID lookup)
• Grace period option: delay group removal after a patron cancels or payment fails

Real-time and scheduled sync

• Real-time sync via Patreon webhooks (pledge create, update, delete)
• Nightly cron task for full reconciliation against the Patreon members API
• Manual "Sync Now" button in the ACP for on-demand reconciliation
• "Refresh my status" button in UCP so users can trigger an immediate re-sync (rate-limited to once per 5 minutes)

UCP patron dashboard

• Tier name, pledge status (color-coded), pledge amount, assigned forum group, and last sync time
• Human-readable status labels (Active Patron, Payment Declined, Former Patron, Pending)

Public supporters page

• Public page at /patreon/supporters listing opted-in active patrons
• Shows avatar, username (coloured), rank, group (coloured), tier name, and optionally pledge amount
• ACP master switch to enable/disable the page and the pledge amount column
• UCP opt-in checkboxes: "Show me as a supporter" and "Show my pledge amount" — both default off
• Link in the navbar sandwich menu when enabled
• Patreon tier badge on the "The Team" page for active patrons

Administration

• "Fetch Campaign ID" button in the ACP (auto-detects from the API)
• Webhook management: register via API or manually via the Patreon portal, with "Check Status" and "Test Ping" buttons
• Notification to admins and moderators when a user links their Patreon account
• Linked users overview in the ACP showing coloured usernames, tier, status, pledge amount, and sync timestamps
• Creator access token auto-refresh on expiry
• Collapsible help text throughout the ACP explaining how each section works

Languages supported

• Dutch, English, French, German, Portuguese, Spanish

Changelog

• 1.3.0

  • [FIX] "Fetch Tiers" only ever inserted/updated tiers Patreon's API currently returns — a tier deleted then recreated on Patreon (even at the same price) left the old tier stuck in the ACP mapping list and public tier catalogue forever. Tiers missing from a fresh fetch are now marked unpublished, same as a tier retired on Patreon directly.
  • [FIX] An active patron landing on a tier with no group mapping configured yet (e.g. right after the tier above is recreated) was silently demoted from all patron groups. Their groups are now left untouched and a LOG_PATREON_TIER_UNMAPPED admin-log entry is added instead, so the admin notices and can re-map the tier.
  • [FIX] The ACP "bbAccounts Integration" tab was always visible, even with bbAccounts not installed, where it just showed an errorbox explaining that. The tab itself is now hidden until bbAccounts is installed and enabled.
  • [FIX] Free ($0) tier patrons were never assigned to their tier's phpBB group and stayed stuck at "pending link" indefinitely — Patreon reports a null patron_status for members whose only entitlement is a free tier, which was incorrectly treated as "not a patron". Now normalized to active_patron whenever a currently-entitled tier is present. (#23)
  • [FIX] ACP "Linked Users" table loaded every Patreon-linked member in one unbounded query; paginated at 25 per page using phpBB's core pagination service. (#22)
  • [NEW] New ACP "Patron Stats" page: active/declined patron counts, total monthly pledge amount, and an active-patron breakdown per tier — computed live, no need to visit Patreon's own dashboard. (#4)
  • [NEW] Public avathar.bbpatreon.service.patron_data_provider service exposing opted-in supporter data, so other extensions can read it without querying phpbb_patreon_sync directly. Two new template events, avathar_bbpatreon_supporters_body_before/_after, let other extensions inject markup on the supporters page. (#2)
  • [NEW] Public avathar.bbpatreon.service.tier_data_provider service exposing the published tier catalogue (label, description, formatted amount, Patreon subscribe URL) for building a "Membership Tiers" page. New avathar.bbpatreon.tiers_updated event fires when the ACP "Fetch Tiers" action refreshes the catalogue. (#10)

• 1.2.4

  • [NEW] bbAccounts integration: active patrons get monthly journal-entry credits via admin-configured rules in ACP → bbPatreon → bbAccounts Integration. Nightly cron + manual "Run credit now" button. Outbox-pattern idempotency via the new bbpatreon_credit_log table. Soft-coupled: works fine when bbAccounts is not installed. (#18)
  • [NEW] New permission u_patreon_notify gates who receives "X linked their Patreon account" notifications. Default-granted to ROLE_ADMIN_FULL only; admins can extend to moderator roles or specific groups via ACP → Permissions. (#19)
  • [NEW] Optional "set tier group as default" ACP toggle (default OFF). When enabled, promoting a patron to a tier-mapped group also sets it as their default phpBB group (username adopts the group colour and rank); demotion reverts to Registered users. (#20)
  • [FIX] Notification body now shows the human-readable tier name (e.g. "Tier: Bronze Supporter") instead of the raw Patreon tier ID. (#21)
  • [FIX] Notification type lang key now matches phpBB's expected dotted format — UCP → Notifications → Notification Options shows a proper label instead of the raw placeholder. (#16)

• 1.0.0

  • [CHG] "Show me as a supporter" option now only available to paying patrons (free-tier users cannot opt in)
  • [CHG] Clarified explain text in all 6 languages: option is reserved for paying patrons
  • [FIX] Purging extension data now cleans up orphan OAuth links from the core oauth_accounts table

• 1.0.0-RC4

  • [FIX] Fatal error when rendering "Patreon linked" notifications — missing user_loader injection (#14)
  • [FIX] Fatal error when disabling extension with unread notification rows — orphaned notifications now purged on disable (#15)

• 1.0.0-RC3

  • [NEW] Public supporters page at /patreon/supporters with avatar, rank, coloured group, tier (#2)
  • [NEW] Optional pledge amount column on supporters page, gated by ACP toggle + UCP opt-in (#2)
  • [NEW] Patreon tier badge on "The Team" page for active patrons (#2)
  • [NEW] Supporters page link in navbar sandwich menu (#2)
  • [CHG] ACP: coloured usernames in linked users table
  • [NEW] UCP: "Refresh my status" re-sync button with 5-minute rate limit (#3)
  • [NEW] UCP: show assigned forum group, human-readable status labels, last sync time (#3)
  • [NEW] UCP: color-coded pledge status (active/declined/former/pending) (#3)
  • [NEW] UCP: "Show me as a supporter" and "Show my pledge amount" opt-in checkboxes (#2)
  • [NEW] Migrations: show_public, show_pledge_public columns, supporters page config keys
  • [NEW] CI: PHPUnit 9.x on PHP 8.1-8.4 with MySQL, PostgreSQL, and Windows

• 1.0.0-dev

  • [NEW] Initial release
  • [NEW] OAuth 2.0 account linking via custom PHPoAuthLib service (works with auth_method = db)
  • [NEW] Patreon API v2 client with creator token auto-refresh
  • [NEW] Tier-to-group mapper with grace period support
  • [NEW] Dedicated patreon_tiers table for tier metadata and group mapping
  • [NEW] Webhook receiver with HMAC-MD5 signature validation
  • [NEW] Nightly cron reconciliation task
  • [NEW] ACP: API credentials, webhook management, tier mapping, linked users table
  • [NEW] UCP: link/unlink Patreon account, view tier and pledge status
  • [NEW] Notification type for admin/moderator alerts on account linking
  • [NEW] GitHub Actions CI (PHP 8.1-8.4) and EPV validation

Installation

1. Download the latest release and unzip it.
2. Copy the entire contents from the unzipped folder to /ext/avathar/bbpatreon/.
3. Navigate in the ACP to Customise -> Manage extensions.
4. Find bbPatreon under "Disabled Extensions" and click Enable.

Configuration

1. Navigate to ACP -> Extensions -> Patreon Integration -> Settings.
2. Enter your Patreon API credentials (Client ID, Client Secret, Creator tokens).
3. Click Fetch next to Campaign ID to auto-detect it.
4. Click Fetch Tiers and assign a phpBB group to each Patreon tier, then click Submit.
5. Register a webhook via the Patreon portal or the API button, and paste the secret.
6. Tell your members to visit UCP -> Patreon and click "Link your Patreon Account".

Testing

See contrib/TESTING.md for details on running the test suite.

Uninstallation

1. Navigate in the ACP to Customise -> Manage extensions.
2. Click the Disable link for bbPatreon.
3. To permanently uninstall, click Delete Data, then delete the bbpatreon folder from /ext/avathar/.

License

GNU General Public License v2

© 2026 - Avathar.be (Andy Vandenberghe)