fix(psalm): Fix array syntaxes

Signed-off-by: provokateurin <[email protected]>
nextcloud · Oct 30, 2024 · ac50461 · ac50461
1 parent 1c5a871
commit ac50461
Show file tree

Hide file tree

Showing 8 changed files with 106 additions and 43 deletions.
diff --git a/lib/Capabilities.php b/lib/Capabilities.php
@@ -35,7 +35,7 @@ public function __construct(
 	/**
 	 * Provide App Capabilities
 	 * @inheritdoc
-	 * @return array{forms: array{version: string, apiVersions: array<string>}}
+	 * @return array{forms: array{version: string, apiVersions: list<string>}}
 	 */
 	public function getCapabilities() {
 		return [

diff --git a/lib/Controller/ApiController.php b/lib/Controller/ApiController.php
@@ -130,7 +130,7 @@ public function preflightedCors() {
 	 *                     Possible values:
 	 *                     - `owned`: Forms owned by the user.
 	 *                     - `shared`: Forms shared with the user.
-	 * @return DataResponse<Http::STATUS_OK, array<FormsPartialForm>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<FormsPartialForm>, array{}>
 	 * @throws OCSBadRequestException wrong form type supplied
 	 *
 	 * 200: Array containing the partial owned or shared forms
@@ -238,7 +238,7 @@ public function newForm(?int $fromId = null): DataResponse {
 	 * Read all information to edit a Form (form, questions, options, except submissions/answers)
 	 *
 	 * @param int $formId Id of the form
-	 * @return DataResponse<Http::STATUS_OK, array<FormsForm>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, FormsForm, array{}>
 	 * @throws OCSBadRequestException Could not find form
 	 * @throws OCSForbiddenException User has no permissions to get this form
 	 *
@@ -385,7 +385,7 @@ public function deleteForm(int $formId): DataResponse {
 	 * Read all questions (including options)
 	 *
 	 * @param int $formId the form id
-	 * @return DataResponse<Http::STATUS_OK, array<FormsQuestion>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<FormsQuestion>, array{}>
 	 * @throws OCSForbiddenException User has no permissions to get this form
 	 * @throws OCSNotFoundException Could not find form
 	 *
@@ -812,8 +812,8 @@ public function reorderQuestions(int $formId, array $newOrder): DataResponse {
 	 *
 	 * @param int $formId id of the form
 	 * @param int $questionId id of the question
-	 * @param array<string> $optionTexts the new option text
-	 * @return DataResponse<Http::STATUS_CREATED, array<FormsOption>, array{}> Returns a DataResponse containing the added options
+	 * @param list<string> $optionTexts the new option text
+	 * @return DataResponse<Http::STATUS_CREATED, list<FormsOption>, array{}> Returns a DataResponse containing the added options
 	 * @throws OCSBadRequestException This question is not part ot the given form
 	 * @throws OCSForbiddenException This form is archived and can not be modified
 	 * @throws OCSForbiddenException Current user has no permission to edit
@@ -1223,7 +1223,7 @@ public function deleteAllSubmissions(int $formId): DataResponse {
 	 * Process a new submission
 	 *
 	 * @param int $formId the form id
-	 * @param array<string, array<string>> $answers [question_id => arrayOfString]
+	 * @param array<string, list<string>> $answers [question_id => arrayOfString]
 	 * @param string $shareHash public share-hash -> Necessary to submit on public link-shares.
 	 * @return DataResponse<Http::STATUS_CREATED, null, array{}>
 	 * @throws OCSBadRequestException At least one submitted answer is not valid

diff --git a/lib/Controller/ShareApiController.php b/lib/Controller/ShareApiController.php
@@ -95,7 +95,7 @@ public function __construct(
 	 *                                  - `submit` user can submit
 	 *                                  - `results` user can see the results
 	 *                                  - `results_delete` user can see and delete results
-	 * @return DataResponse<Http::STATUS_CREATED, array<FormsShare>, array{}>
+	 * @return DataResponse<Http::STATUS_CREATED, FormsShare, array{}>
 	 * @throws OCSBadRequestException Invalid shareType
 	 * @throws OCSBadRequestException Invalid permission given
 	 * @throws OCSBadRequestException Invalid user to share with

diff --git a/lib/Db/Form.php b/lib/Db/Form.php
@@ -29,9 +29,11 @@
 namespace OCA\Forms\Db;
 
 use OCA\Forms\Constants;
+use OCA\Forms\ResponseDefinitions;
 use OCP\AppFramework\Db\Entity;
 
 /**
+ * @psalm-import-type FormsAccess from ResponseDefinitions
  * @method string getHash()
  * @method void setHash(string $value)
  * @method string getTitle()
@@ -44,8 +46,6 @@
  * @method void setFileId(int|null $value)
  * @method string|null getFileFormat()
  * @method void setFileFormat(string|null $value)
- * @method array getAccess()
- * @method void setAccess(array $value)
  * @method int getCreated()
  * @method void setCreated(int $value)
  * @method int getExpires()
@@ -58,10 +58,12 @@
  * @method void setShowExpiration(bool $value)
  * @method int getLastUpdated()
  * @method void setLastUpdated(int $value)
- * @method ?string getSubmissionMessage()
- * @method void setSubmissionMessage(?string $value)
+ * @method string|null getSubmissionMessage()
+ * @method void setSubmissionMessage(string|null $value)
  * @method int getState()
- * @method void setState(?int $value)
+ * @psalm-method 0|1|2 getState()
+ * @method void setState(int|null $value)
+ * @psalm-method void setState(0|1|2|null $value)
  */
 class Form extends Entity {
 	protected $hash;
@@ -94,6 +96,10 @@ public function __construct() {
 	}
 
 	// JSON-Decoding of access-column.
+
+	/**
+	 * @return FormsAccess
+	 */
 	public function getAccess(): array {
 		$accessEnum = $this->getAccessEnum();
 		$access = [];
@@ -117,6 +123,10 @@ public function getAccess(): array {
 	}
 
 	// JSON-Encoding of access-column.
+
+	/**
+	 * @param FormsAccess $access
+	 */
 	public function setAccess(array $access) {
 		// No further permissions -> 0
 		// Permit all users, but don't show in navigation -> 1
@@ -131,11 +141,30 @@ public function setAccess(array $access) {
 			// only permit all but not shown to all
 			$value = Constants::FORM_ACCESS_PERMITALLUSERS;
 		}
-		
+
 		$this->setAccessEnum($value);
 	}
 
-	// Read full form
+	/**
+	 * @return array{
+	 *   id: int,
+	 *   hash: string,
+	 *   title: string,
+	 *   description: string,
+	 *   ownerId: string,
+	 *   fileId: ?int,
+	 *   fileFormat: ?string,
+	 *   created: int,
+	 *   access: FormsAccess,
+	 *   expires: int,
+	 *   isAnonymous: bool,
+	 *   submitMultiple: bool,
+	 *   showExpiration: bool,
+	 *   lastUpdated: int,
+	 *   submissionMessage: ?string,
+	 *   state: 0|1|2,
+	 *  }
+	 */
 	public function read() {
 		return [
 			'id' => $this->getId(),

diff --git a/lib/Db/Share.php b/lib/Db/Share.php
@@ -27,9 +27,11 @@
 namespace OCA\Forms\Db;
 
 use OCA\Forms\Constants;
+use OCA\Forms\ResponseDefinitions;
 use OCP\AppFramework\Db\Entity;
 
 /**
+ * @psalm-import-type FormsPermission from ResponseDefinitions
  * @method int getFormId()
  * @method void setFormId(integer $value)
  * @method int getShareType()
@@ -56,21 +58,33 @@ public function __construct() {
 		$this->addType('shareWith', 'string');
 	}
 
+	/**
+	 * @return list<FormsPermission>
+	 */
 	public function getPermissions(): array {
 		// Fallback to submit permission
 		return json_decode($this->getPermissionsJson() ?: 'null') ?? [ Constants::PERMISSION_SUBMIT ];
 	}
 
 	/**
-	 * @param array $permissions
+	 * @param list<FormsPermission> $permissions
 	 */
 	public function setPermissions(array $permissions) {
 		$this->setPermissionsJson(
 			// Make sure to only encode array values as the indices might be non consecutively so it would be encoded as a json object
-			json_encode(array_values($permissions))
+			json_encode($permissions)
 		);
 	}
 
+	/**
+	 * @return array{
+	 *   id: int,
+	 *   formId: int,
+	 *   shareType: int,
+	 *   shareWith: string,
+	 *   permissions: list<FormsPermission>,
+	 * }
+	 */
 	public function read(): array {
 		return [
 			'id' => $this->getId(),

diff --git a/lib/ResponseDefinitions.php b/lib/ResponseDefinitions.php
@@ -87,8 +87,8 @@
  * }
  *
  * @psalm-type FormsAccess = array{
- *   permitAllUsers: bool,
- *   showToAllUsers: bool
+ *   permitAllUsers?: bool,
+ *   showToAllUsers?: bool
  * }
  *
  * @psalm-type FormsPermission = "edit"|"results"|"results_delete"|"submit"|"embed"
@@ -121,15 +121,20 @@
  *   created: int,
  *   access: FormsAccess,
  *   expires: int,
+ *   fileFormat: ?string,
+ *   fileId: ?int,
+ *   filePath?: ?string,
  *   isAnonymous: bool,
+ *   lastUpdated: int,
  *   submitMultiple: bool,
  *   showExpiration: bool,
  *   canSubmit: bool,
  *   permissions: list<FormsPermission>,
  *   questions: list<FormsQuestion>,
  *   state: 0|1|2,
- *   shares: list<string>,
- *   submissions: list<FormsSubmission>,
+ *   shares: list<FormsShare>,
+ *   submissionCount?: int,
+ *   submissionMessage: ?string,
  * }
  *
  * @psalm-type FormsUploadedFile = array{

diff --git a/lib/Service/FormsService.php b/lib/Service/FormsService.php
@@ -56,6 +56,9 @@
  * Trait for getting forms information in a service
  * @psalm-import-type FormsQuestion from ResponseDefinitions
  * @psalm-import-type FormsOption from ResponseDefinitions
+ * @psalm-import-type FormsForm from ResponseDefinitions
+ * @psalm-import-type FormsPermission from ResponseDefinitions
+ * @psalm-import-type FormsShare from ResponseDefinitions
  */
 class FormsService {
 	private ?IUser $currentUser;
@@ -188,7 +191,7 @@ public function getQuestion(int $questionId): ?array {
 	 * Load shares corresponding to form
 	 *
 	 * @param integer $formId
-	 * @return array
+	 * @return list<FormsShare>
 	 */
 	public function getShares(int $formId): array {
 		$shareList = [];
@@ -207,7 +210,7 @@ public function getShares(int $formId): array {
 	 * Get a form data
 	 *
 	 * @param Form $form
-	 * @return array
+	 * @return FormsForm
 	 * @throws IMapperException
 	 */
 	public function getForm(Form $form): array {
@@ -289,7 +292,7 @@ public function getPublicForm(Form $form): array {
 	 * Get current users permissions on a form
 	 *
 	 * @param Form $form
-	 * @return array
+	 * @return list<FormsPermission>
 	 */
 	public function getPermissions(Form $form): array {
 		if (!$this->currentUser) {

diff --git a/openapi.json b/openapi.json
@@ -22,10 +22,6 @@
         "schemas": {
             "Access": {
                 "type": "object",
-                "required": [
-                    "permitAllUsers",
-                    "showToAllUsers"
-                ],
                 "properties": {
                     "permitAllUsers": {
                         "type": "boolean"
@@ -104,15 +100,18 @@
                     "created",
                     "access",
                     "expires",
+                    "fileFormat",
+                    "fileId",
                     "isAnonymous",
+                    "lastUpdated",
                     "submitMultiple",
                     "showExpiration",
                     "canSubmit",
                     "permissions",
                     "questions",
                     "state",
                     "shares",
-                    "submissions"
+                    "submissionMessage"
                 ],
                 "properties": {
                     "id": {
@@ -142,9 +141,26 @@
                         "type": "integer",
                         "format": "int64"
                     },
+                    "fileFormat": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "fileId": {
+                        "type": "integer",
+                        "format": "int64",
+                        "nullable": true
+                    },
+                    "filePath": {
+                        "type": "string",
+                        "nullable": true
+                    },
                     "isAnonymous": {
                         "type": "boolean"
                     },
+                    "lastUpdated": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
                     "submitMultiple": {
                         "type": "boolean"
                     },
@@ -178,14 +194,16 @@
                     "shares": {
                         "type": "array",
                         "items": {
-                            "type": "string"
+                            "$ref": "#/components/schemas/Share"
                         }
                     },
-                    "submissions": {
-                        "type": "array",
-                        "items": {
-                            "$ref": "#/components/schemas/Submission"
-                        }
+                    "submissionCount": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "submissionMessage": {
+                        "type": "string",
+                        "nullable": true
                     }
                 }
             },
@@ -820,10 +838,7 @@
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
                                                 "data": {
-                                                    "type": "array",
-                                                    "items": {
-                                                        "$ref": "#/components/schemas/Form"
-                                                    }
+                                                    "$ref": "#/components/schemas/Form"
                                                 }
                                             }
                                         }
@@ -3960,10 +3975,7 @@
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
                                                 "data": {
-                                                    "type": "array",
-                                                    "items": {
-                                                        "$ref": "#/components/schemas/Share"
-                                                    }
+                                                    "$ref": "#/components/schemas/Share"
                                                 }
                                             }
                                         }