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/FormsMigrator.php

@@ -148,6 +148,7 @@ public function import(IUser $user, IImportSource $importSource, OutputInterface
 				$form->setSubmitMultiple($formData['submitMultiple']);
 				$form->setAllowEditSubmissions($formData['allowEditSubmissions']);
 				$form->setShowExpiration($formData['showExpiration']);
+				$form->setMaxSubmissions($formData['maxSubmissions'] ?? null);
 
 				$this->formMapper->insert($form);
 

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;

lib/Service/SubmissionService.php

@@ -517,6 +517,9 @@ public function validateSubmission(array $questions, array $answers, string $for
 
 			// Check if all answers are within the possible options
 			if (in_array($question['type'], Constants::ANSWER_TYPES_PREDEFINED) && empty($question['extraSettings']['allowOtherAnswer'])) {
+				// Normalize option IDs once for consistent comparison (DB may return ints, request may send strings)
+				$optionIds = array_map('intval', array_column($question['options'] ?? [], 'id'));
+
 				foreach ($answers[$questionId] as $answer) {
 					// Handle linear scale questions
 					if ($question['type'] === Constants::ANSWER_TYPE_LINEARSCALE) {
@@ -527,8 +530,18 @@ public function validateSubmission(array $questions, array $answers, string $for
 						}
 					}
 					// Search corresponding option, return false if non-existent
-					elseif (!in_array($answer, array_column($question['options'], 'id'))) {
-						throw new \InvalidArgumentException(sprintf('Answer "%s" for question "%s" is not a valid option.', $answer, $question['text']));
+					else {
+						// Accept numeric strings like "46" from JSON payloads reliably (e.g. with hardening extensions enabled)
+						$answerId = is_int($answer) ? $answer : (is_string($answer) ? intval(trim($answer)) : null);
+
+						// Reject non-numeric / malformed values early
+						if ($answerId === null || (string)$answerId !== (string)intval($answerId)) {
+							throw new \InvalidArgumentException(sprintf('Answer "%s" for question "%s" is not a valid option.', is_scalar($answer) ? (string)$answer : gettype($answer), $question['text']));
+						}
+
+						if (!in_array($answerId, $optionIds, true)) {
+							throw new \InvalidArgumentException(sprintf('Answer "%s" for question "%s" is not a valid option.', $answer, $question['text']));
+						}
 					}
 				}
 			}

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
                     }
                 }
             },