feat: add maximum submissions limit for forms

Add the ability to limit the number of responses a form can receive.
When the limit is reached, the form is automatically closed and displays
a dedicated message instead of accepting new submissions.

- Add max_submissions column to forms_v2_forms table (migration)
- Add maxSubmissions property to Form entity
- Check submission limit in FormsService::canSubmit()
- Add limit enforcement in ApiController::newSubmission()
- Add isMaxSubmissionsReached flag in form API response
- Update FormsForm psalm type in ResponseDefinitions
- Add limit settings UI in SettingsSidebarTab
- Display dedicated 'Form is full' message in Submit view
- Update openapi.json
- Update unit and integration tests

Closes #596

Signed-off-by: lafricain79 <lafricain79@gmail.com>

Author: lafricain79

lib/Controller/ApiController.php

@@ -1375,6 +1375,12 @@ public function newSubmission(int $formId, array $answers, string $shareHash = '
 			throw new OCSForbiddenException('Already submitted');
 		}
 
+		// Check if max submissions limit is reached
+		$maxSubmissions = $form->getMaxSubmissions();
+		if ($maxSubmissions > 0 && $this->submissionMapper->countSubmissions($formId) >= $maxSubmissions) {
+			throw new OCSForbiddenException('Maximum number of submissions reached');
+		}
+
 		// Insert new submission
 		$this->submissionMapper->insert($submission);
 

lib/Db/Form.php

@@ -50,6 +50,8 @@
  * @method string getLockedBy()
  * @method void setLockedBy(string|null $value)
  * @method int getLockedUntil()
+ * @method int|null getMaxSubmissions()
+ * @method void setMaxSubmissions(int|null $value)
  * @method void setLockedUntil(int|null $value)
  */
 class Form extends Entity {
@@ -71,6 +73,7 @@ class Form extends Entity {
 	protected $state;
 	protected $lockedBy;
 	protected $lockedUntil;
+	protected $maxSubmissions;
 
 	/**
 	 * Form constructor.
@@ -86,6 +89,7 @@ public function __construct() {
 		$this->addType('state', 'integer');
 		$this->addType('lockedBy', 'string');
 		$this->addType('lockedUntil', 'integer');
+		$this->addType('maxSubmissions', 'integer');
 	}
 
 	// JSON-Decoding of access-column.
@@ -159,6 +163,7 @@ public function setAccess(array $access): void {
 	 *   state: 0|1|2,
 	 *   lockedBy: ?string,
 	 *   lockedUntil: ?int,
+	 *   maxSubmissions: ?int,
 	 *  }
 	 */
 	public function read() {
@@ -182,6 +187,7 @@ public function read() {
 			'state' => $this->getState(),
 			'lockedBy' => $this->getLockedBy(),
 			'lockedUntil' => $this->getLockedUntil(),
+			'maxSubmissions' => $this->getMaxSubmissions(),
 		];
 	}
 }

lib/Migration/Version050300Date20260303000000.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Forms\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+class Version050300Date20260303000000 extends SimpleMigrationStep {
+
+	/**
+	 * @param IOutput $output
+	 * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+		$table = $schema->getTable('forms_v2_forms');
+
+		if (!$table->hasColumn('max_submissions')) {
+			$table->addColumn('max_submissions', Types::INTEGER, [
+				'notnull' => false,
+				'default' => null,
+				'comment' => 'Maximum number of submissions, null means unlimited',
+			]);
+		}
+
+		return $schema;
+	}
+}

lib/ResponseDefinitions.php

@@ -110,6 +110,7 @@
  *   state: int,
  *   lockedBy: ?string,
  *   lockedUntil: ?int,
+ *   maxSubmissions: ?int,
  * }
  *
  * @psalm-type FormsForm = array{
@@ -125,6 +126,7 @@
  *   fileId: ?int,
  *   filePath?: ?string,
  *   isAnonymous: bool,
+ *   isMaxSubmissionsReached: bool,
  *   lastUpdated: int,
  *   submitMultiple: bool,
  *   allowEditSubmissions: bool,
@@ -135,6 +137,7 @@
  *   state: 0|1|2,
  *   lockedBy: ?string,
  *   lockedUntil: ?int,
+ *   maxSubmissions: ?int,
  *   shares: list<FormsShare>,
  *   submissionCount?: int,
  *   submissionMessage: ?string,

lib/Service/FormsService.php

@@ -204,6 +204,10 @@ public function getForm(Form $form): array {
 		$result['permissions'] = $this->getPermissions($form);
 		// Append canSubmit, to be able to show proper EmptyContent on internal view.
 		$result['canSubmit'] = $this->canSubmit($form);
+		// Append isMaxSubmissionsReached to show proper message on submit view.
+		$maxSubmissions = $form->getMaxSubmissions();
+		$result['isMaxSubmissionsReached'] = $maxSubmissions !== null
+			&& $this->submissionMapper->countSubmissions($form->getId()) >= $maxSubmissions;
 
 		// Append submissionCount if currentUser has permissions to see results
 		if (in_array(Constants::PERMISSION_RESULTS, $result['permissions'])) {
@@ -484,6 +488,12 @@ public function canDeleteResults(Form $form): bool {
 	 * @return boolean
 	 */
 	public function canSubmit(Form $form): bool {
+		// Check if max submissions limit is reached
+		$maxSubmissions = $form->getMaxSubmissions();
+		if ($maxSubmissions !== null && $this->submissionMapper->countSubmissions($form->getId()) >= $maxSubmissions) {
+			return false;
+		}
+
 		// We cannot control how many time users can submit if public link available
 		if ($this->hasPublicLink($form)) {
 			return true;

openapi.json

@@ -106,6 +106,7 @@
                     "fileFormat",
                     "fileId",
                     "isAnonymous",
+                    "isMaxSubmissionsReached",
                     "lastUpdated",
                     "submitMultiple",
                     "allowEditSubmissions",
@@ -116,6 +117,7 @@
                     "state",
                     "lockedBy",
                     "lockedUntil",
+                    "maxSubmissions",
                     "shares",
                     "submissionMessage"
                 ],
@@ -163,6 +165,9 @@
                     "isAnonymous": {
                         "type": "boolean"
                     },
+                    "isMaxSubmissionsReached": {
+                        "type": "boolean"
+                    },
                     "lastUpdated": {
                         "type": "integer",
                         "format": "int64"
@@ -209,6 +214,11 @@
                         "format": "int64",
                         "nullable": true
                     },
+                    "maxSubmissions": {
+                        "type": "integer",
+                        "format": "int64",
+                        "nullable": true
+                    },
                     "shares": {
                         "type": "array",
                         "items": {
@@ -307,7 +317,8 @@
                     "partial",
                     "state",
                     "lockedBy",
-                    "lockedUntil"
+                    "lockedUntil",
+                    "maxSubmissions"
                 ],
                 "properties": {
                     "id": {
@@ -348,6 +359,11 @@
                         "type": "integer",
                         "format": "int64",
                         "nullable": true
+                    },
+                    "maxSubmissions": {
+                        "type": "integer",
+                        "format": "int64",
+                        "nullable": true
                     }
                 }
             },

src/components/SidebarTabs/SettingsSidebarTab.vue

@@ -78,6 +78,32 @@
 				{{ t('forms', 'Show expiration date on form') }}
 			</NcCheckboxRadioSwitch>
 		</div>
+		<NcCheckboxRadioSwitch
+			:model-value="hasMaxSubmissions"
+			:disabled="formArchived || locked"
+			type="switch"
+			@update:model-value="onMaxSubmissionsChange">
+			{{ t('forms', 'Limit number of responses') }}
+		</NcCheckboxRadioSwitch>
+		<div
+			v-show="hasMaxSubmissions && !formArchived"
+			class="settings-div--indent">
+			<NcInputField
+				v-model="maxSubmissionsValue"
+				type="number"
+				:min="1"
+				:disabled="locked"
+				:label="t('forms', 'Maximum number of responses')"
+				@update:model-value="onMaxSubmissionsValueChange" />
+			<p class="settings-hint">
+				{{
+					t(
+						'forms',
+						'Form will be closed automatically when the limit is reached.',
+					)
+				}}
+			</p>
+		</div>
 		<NcCheckboxRadioSwitch
 			:model-value="formClosed"
 			:disabled="formArchived || locked"
@@ -184,6 +210,7 @@ import NcButton from '@nextcloud/vue/components/NcButton'
 import NcCheckboxRadioSwitch from '@nextcloud/vue/components/NcCheckboxRadioSwitch'
 import NcDateTimePicker from '@nextcloud/vue/components/NcDateTimePicker'
 import NcIconSvgWrapper from '@nextcloud/vue/components/NcIconSvgWrapper'
+import NcInputField from '@nextcloud/vue/components/NcInputField'
 import NcNoteCard from '@nextcloud/vue/components/NcNoteCard'
 import TransferOwnership from './TransferOwnership.vue'
 import svgLockOpen from '../../../img/lock_open.svg?raw'
@@ -193,6 +220,7 @@ import { FormState } from '../../models/Constants.ts'
 export default {
 	components: {
 		NcButton,
+		NcInputField,
 		NcCheckboxRadioSwitch,
 		NcDateTimePicker,
 		NcIconSvgWrapper,
@@ -302,6 +330,23 @@ export default {
 			return this.form.state !== FormState.FormActive
 		},
 
+		hasMaxSubmissions() {
+			return (
+				this.form.maxSubmissions !== null
+				&& this.form.maxSubmissions !== undefined
+			)
+		},
+
+		maxSubmissionsValue: {
+			get() {
+				return this.form.maxSubmissions ?? 1
+			},
+
+			set(value) {
+				this.$emit('update:form-prop', 'maxSubmissions', value)
+			},
+		},
+
 		isExpired() {
 			return this.form.expires && moment().unix() > this.form.expires
 		},
@@ -365,6 +410,17 @@ export default {
 			)
 		},
 
+		onMaxSubmissionsChange(checked) {
+			this.$emit('update:form-prop', 'maxSubmissions', checked ? 1 : null)
+		},
+
+		onMaxSubmissionsValueChange(event) {
+			const value = parseInt(event.target.value)
+			if (value > 0) {
+				this.$emit('update:form-prop', 'maxSubmissions', value)
+			}
+		},
+
 		onFormClosedChange(isClosed) {
 			this.$emit(
 				'update:form-prop',

src/views/Submit.vue

@@ -58,7 +58,7 @@
 				</template>
 			</NcEmptyContent>
 			<NcEmptyContent
-				v-else-if="success || !form.canSubmit"
+				v-else-if="success || (!form.canSubmit && !isMaxSubmissionsReached)"
 				class="forms-emptycontent"
 				:name="
 					form.submissionMessage
@@ -74,6 +74,17 @@
 					<p class="submission-message" v-html="submissionMessageHTML" />
 				</template>
 			</NcEmptyContent>
+			<NcEmptyContent
+				v-else-if="isMaxSubmissionsReached"
+				class="forms-emptycontent"
+				:name="t('forms', 'Form is full')"
+				:description="
+					t('forms', 'This form has reached the maximum number of answers')
+				">
+				<template #icon>
+					<NcIconSvgWrapper :svg="IconCheckSvg" size="64" />
+				</template>
+			</NcEmptyContent>
 			<NcEmptyContent
 				v-else-if="isExpired"
 				class="forms-emptycontent"
@@ -360,6 +371,10 @@ export default {
 			return this.form.state === FormState.FormClosed
 		},
 
+		isMaxSubmissionsReached() {
+			return this.form.isMaxSubmissionsReached === true
+		},
+
 		/**
 		 * Checks if the current state is active.
 		 *

tests/Integration/Api/ApiV3Test.php

@@ -394,6 +394,8 @@ public function dataGetNewForm() {
 					'submissionMessage' => null,
 					'fileId' => null,
 					'fileFormat' => null,
+					'maxSubmissions' => null,
+					'isMaxSubmissionsReached' => false,
 				]
 			]
 		];
@@ -525,6 +527,8 @@ public function dataGetFullForm() {
 					'submissionCount' => 3,
 					'fileId' => null,
 					'fileFormat' => null,
+					'maxSubmissions' => null,
+					'isMaxSubmissionsReached' => false,
 				]
 			]
 		];

tests/Integration/Api/RespectAdminSettingsTest.php

@@ -143,6 +143,8 @@ private static function sharedTestForms(): array {
 				],
 				'canSubmit' => true,
 				'submissionCount' => 0,
+				'maxSubmissions' => null,
+				'isMaxSubmissionsReached' => false,
 			],
 		];
 	}