v1.0.0-beta1

Donation Campaigns — Release Notes

1.0.0-beta1

Status: First public beta of the new, frontend-based management
architecture — campaign and donation management happen on the topic, under
forum-scoped moderator permissions, rather than in the ACP. See Known
limitations and the release-blocking item below before deploying to a
production board.

Requires phpBB 3.3.16 or later (below 4.0). prosilver only. PHP 8.2 or newer.

---

What the extension does

An administrator, or an authorised forum moderator, attaches a fundraising
campaign to a topic. The topic then shows a box above its first post with a
title, an optional description, a target amount, the amount collected, a
progress bar, and — optionally — the donation count and the names of donors who
agreed to be listed.

The extension records confirmed donations; it does not process payments. The
public total is the sum of donation records entered by hand after money actually
arrived. An optional button links to wherever a board chooses to take payment
(PayPal, a bank-details page, another topic); the extension integrates with no
provider.

---

Headline change — management moved from the ACP to the topic

Campaigns and donations are now managed from the topic, not the ACP. The
topic-tools Donation campaign entry opens a management landing
(/app.php/donationcampaigns/topic/{topic_id}) that resolves state on arrival:
the create form when there is no campaign yet, otherwise a campaign summary plus
only the actions the viewer is authorised for. The service layer and the
Repository → Service core are unchanged; the ACP module's write paths were
replaced by thin frontend controllers. See ADR-015 in DEVELOPERS.md.

Three permissions

Grouped under a dedicated Donation Campaigns permission category:

• a_donationcampaigns — administrator, global. Full ACP access, the
  admin-only maintenance, and an override for every frontend action on every
  forum. Granted to the admin roles on install.
• m_donationcampaigns_manage — moderator, forum-scoped. Manage the
  campaign shell on topics in that forum: create, edit, enable/disable, delete
  an empty campaign. Does not grant donation management.
• m_donationcampaigns_donations — moderator, forum-scoped. Manage the
  donation ledger: add, edit, delete confirmed donations.

The two m_ permissions are independent; a_donationcampaigns overrides both.

⚠️ m_donationcampaigns_donations exposes personal data — donor names,
private donor identities and confirmed amounts. Grant it only to people
trusted with that information.

⚠️ Granting either m_ permission makes the grantee a forum moderator.
phpBB treats anyone holding an m_ permission on a forum as a moderator of
it, so the grantee appears in that forum's Moderator list and gains moderator
standing there. This is inherent to phpBB and is a real (if limited)
promotion, not a hidden grant.

Deletion policy — split by surface

• From the topic, only an empty campaign can be deleted; a non-empty one
  is refused (disable it, or ask an administrator).
• From the ACP, an administrator may hard-delete a non-empty campaign,
  cascading its donations, behind a confirmation that names the campaign and its
  donation count.

Donations are deleted individually from the topic behind a confirmation naming
the amount and donor. All deletion is permanent; totals are always recomputed
from the donation rows.

Audit by surface

Frontend actions (campaign create/edit/enable/disable/delete; donation
add/edit/delete) are written to the moderator log, scoped to the forum and
topic, and read in the MCP. ACP actions (hard-delete, recalculate, settings) are
written to the administrator log. The log an entry lands in tells you where
the action was performed.

The ACP is now read-only oversight plus admin maintenance

ACP → Donation campaigns keeps Settings, a read-only Campaigns list and a
read-only Donations list. Its former create/edit forms are gone; the list rows
link out to the frontend routes on the topic. It retains admin-only maintenance:
Recalculate total and campaign hard-delete, both requiring
a_donationcampaigns.

---

Localisation

The extension ships English and German language packs (language/en and
language/de), kept at parity by a test.

---

Major architectural decisions

Recorded in full in DEVELOPERS.md; summarized here.

ADR	Decision
001	Target phpBB 3.3.x only
002	Money as integer minor units; one board-wide currency
003	The collected total is denormalised but always recalculated from SUM(), never delta-adjusted
004	Donors are free text, not references to forum users
005	Two services and two repositories; business logic in services, persistence in repositories
006	Public box renders at the viewtopic_body_poll_before template event
007	Two deletion listeners feed one unified cleanup operation
008	A single a_donationcampaigns permission (superseded by ADR-015)
009	The concurrent-write race is accepted and mitigated operationally (unique index is authoritative)
010	No JavaScript is required for any essential function
011	Policy and coding-standard violations fail the commit that introduces them
012	Every shared-namespace identifier carries the package machine name
013	Version 1.0 officially supports prosilver only
014	Campaigns are created only from their topic; the ACP resolves state at request time (superseded by ADR-015)
015	Frontend-primary management with forum-scoped moderator permissions; ACP becomes read-only oversight plus admin maintenance

The layering (Repository → Service → Controller / Listener / ACP Module) is
unchanged. The extension never modifies phpBB core and adds no public write
route.

---

Known limitations

These are deliberate boundaries of the scope, not defects.

• prosilver only. A style that does not provide the
  viewtopic_topic_tools_after template event offers no way to manage a
  campaign, because that is the only management entry point (ADR-013 / 015).
• No payment processing and no provider integration, by design. The button
  links out; nothing is charged, and no transaction data is stored.
• No public donation form. Every entry is made from the topic by an
  administrator or an authorised forum moderator.
• A campaign cannot be moved to another topic once created.
• One campaign per topic, enforced by a unique index.
• Donation dates are date-only, stored as UTC midnight; the board timezone
  is not applied to them.
• No bulk deletion of donations.
• Campaigns can attach to a soft-deleted or unapproved topic. The box simply
  does not render until the topic is visible.

---

Known issue — RELEASE-BLOCKING before 1.0 final

Merging topics, or splitting every post out of a topic, deletes that topic —
and with it its campaign and every confirmed donation record.

phpBB empties the source topic during a merge or full split, then removes it via
delete_topics() (functions_admin.php:2058), which fires
core.delete_topics_before_query — the event this extension's cascade listens
to. The cleanup then removes the campaign and its donation rows.

The deletion is silent and irreversible, and it can be triggered by a
moderator who does not hold any donation permission. These are records of money
actually received.

The cascade itself is correct in isolation — an orphaned campaign pointing at a
dead topic would be worse. The fix belongs at the level of distinguishing a
topic being destroyed from a topic being emptied into another, and must be
designed rather than patched. Documented for administrators in
docs/ADMIN_GUIDE.md and for developers, with the verified call chain, in
DEVELOPERS.md.

---

Upgrade / migration

A new migration adds the two forum-scoped moderator permissions,
m_donationcampaigns_manage and m_donationcampaigns_donations. Neither is
granted to anyone on install. Existing a_donationcampaigns access is
unchanged, so upgrading administrators keep working exactly as before, and no
moderator gains any access until a board owner explicitly grants the opt-in
permissions on the forums they should manage.

Existing campaigns and donations continue to work with no data step.

---

Why beta

The management architecture is new — a frontend surface, new controllers, and a
new permission model — so this release is a beta, to gather real-world
verification of that surface before a final 1.0. The reasoning is recorded in
full as ADR-015 in DEVELOPERS.md.

Donation Campaigns 1.0.0 RC1

Highlights

• First public Release Candidate of the Donation Campaigns extension.
• Donation campaigns attached directly to topics.
• Manual donation tracking — the extension records confirmed donations only and processes no payments.
• Progress bar and campaign box shown above the first post.
• Localised currency formatting.
• German and English language packs.
• Comprehensive automated test suite.
• GitHub Actions CI (coding standard, unit tests, PHP lint, EPV).

Installation

Extract the attached uflagmey_donationcampaigns_1.0.0-rc1.zip into your board so that it lands at:

ext/uflagmey/donationcampaigns

Then enable it in the ACP: Customise → Extensions → Donation Campaigns → Enable.

Requires phpBB 3.3.16 or later (below 4.0) and PHP 7.2–8.x. See the extension README for full documentation.

Feedback

This is an RC build intended for testing and feedback before the final 1.0 release. Please report anything you find on the issue tracker.