Form Collections Developer Guide

Form Collections — Developer Guide

Shipped in 2.2.0. A collection groups the submissions of several forms under one name — Staff Survey 2026, an audit round, an onboarding wave. Optional: most forms belong to none. Several forms may share a collection; a form belongs to at most one.

The user-facing description lives on Forms. This page is the reasoning a change to the code has to respect.

The one decision everything else follows from

There are two collection_id columns, and they are allowed to disagree.

Column	Means	Written when
forms.collection_id	where new submissions of this form go	somebody pairs the form
form_submissions.collection_id	which collection this submission was part of	once, at submit time

The second is a snapshot and is never read live again. Reading a submission's collection through its form would let re-pairing rewrite history: unpair a form and last year's 340 responses stop belonging to anything; move it and they defect to the new collection. For a feature whose entire job is an audit trail, that is the one failure that makes it worthless.

form_submissions.approver_id has been snapshotted for the same reason since #928, and is the precedent to point at.

Consequences to preserve:

• The collection view selects on the stamp, never by joining through the form. A submission made while a form was a member stays in the collection after the form moves; one made before it joined never appears.
• Unlinking a form from a collection must not unstamp its submissions.
• createVersion() carries collection_id forward. A form is a chain of rows and the catalogue lists leaves, so a new version that dropped it would unpair the form the moment somebody pressed Save — exactly how approval gating was lost before #95, a warning written at that very call site.
• saveForm() only touches the column when the caller sends it, so an adapter that knows nothing about collections cannot unpair a form by saving its title.

Closing never writes to a form

What closing does is an operator setting, forms_collection_close_effect, because organisations mean different things by "closed":

Value	Effect
reporting_only	nothing stops; the label says the exercise is over
stop_submissions (default)	submitForm() refuses, naming the collection
stop_and_hide	as above, and the portal catalogue does not offer the forms

🔴 Whichever is chosen, setCollectionClosed() writes to form_collections and nothing else. If closing stamped is_portal_visible = 0 onto the forms, reopening would switch all of them back on — including one deliberately kept off the portal. The question is asked at the moment it matters, by submissionsBlockedBy() and portalCatalogueFilter(), so reopening restores exactly what was there.

A form's own is_active stays independent — two separate reasons a form may be shut, neither overwriting the other. The collection guard sits after the is_active check, so a form that is both reports being inactive, which is its own state and the one an analyst can act on.

Refusal is enforced in FormsService::submitForm(), not in the page, so a bookmarked URL cannot walk around it.

Deleting

A collection holding submissions is closable but not deletable — said in a sentence by deleteCollection() and enforced by a foreign key with no delete rule behind it. Deleting one with no submissions simply unpairs any forms pointing at it (ON DELETE SET NULL on forms.collection_id). The Delete button is disabled with the reason as its tooltip, so the rule is not something you discover by pressing it.

Two ways to pair, one column

Membership can be edited from either end and both write the same column through the service, so they cannot drift:

• Per form — the folder icon on the forms list, beside portal visibility and approval, which is where every other per-form property already lives.
• Per collection — a tick list in Forms → Settings → Collections, via setCollectionForms().

⚠️ A form belongs to one collection, so ticking one already in another moves it. The picker shows where each form currently lives and warns before you tick; the save names what was taken and from where. Frozen (non-leaf) versions are ignored rather than linked — a collection on a snapshot nobody can submit against is not a membership.

Before Database Verification

Every read and write is behind FormsService::collectionsAvailable(), which checks the table and both columns — all three, because two of three is a half-migrated database where the feature would write stamps nothing can read. It caches per request: it is an information_schema query and the forms list would otherwise run it once per form.

With it false, the module is exactly the one that shipped before. get_forms.php and the portal catalogue build their SQL without naming the column, submissions still save, and the Collections tab says to run Database Verification rather than showing an empty list that looks like a working feature nobody has used.

🔴 Testing this needs a cold process. The probe caches its answer, so dropping the columns in a run that has already answered true hides the very fault you are looking for.

Where the code is

File	What
includes/services/forms.php	every rule above — the write path for both UI and API
includes/db_verify_schema.php, database/freeitsm.sql	the table and the two columns; these must agree
api/forms/get_collections.php	the list, with counts and the close-effect setting
api/forms/save_collection.php, delete_collection.php, set_collection_closed.php	create / rename / delete / close
api/forms/save_collection_forms.php, get_collection_form_picker.php	membership from the collection's side
api/forms/get_collection_submissions.php	submissions across a collection's forms, with each form's fields
forms/settings/index.php	the Collections tab (capability forms.collections)
forms/collection.php	the submissions view
assets/js/form-pdf.js	the shared document builder — see Submission PDF Export

Counting

The form count is over leaves only. A form's history is a chain of rows all carrying collection_id, so counting rows would report "Staff Survey 2026 — 4 forms" for one form edited three times. The submission count deliberately is not filtered that way: every one of those is a real submission, whichever version produced it.

RBAC

Collections have their own capability, forms.collections, rather than sharing the layout one: closing a collection can stop several forms accepting submissions, which is a different order of thing from choosing where a logo sits.

🔑 The capability registry derives from forms/settings/manifest.php, so adding the tab entry registered the capability, put its tick-box in the Roles picker, and made the forms.manage umbrella expand to include it. There is no second list to keep in step.

See also

• Forms — the module
• Submission PDF Export — Developer Guide
• Database Verification — Developer Guide
• Service Layer