diff options
Diffstat (limited to 'apps/provisioning_api/lib/Controller/UsersController.php')
| -rw-r--r-- | apps/provisioning_api/lib/Controller/UsersController.php | 183 |
1 files changed, 115 insertions, 68 deletions
diff --git a/apps/provisioning_api/lib/Controller/UsersController.php b/apps/provisioning_api/lib/Controller/UsersController.php index 6ce46087d80..07f651c74fa 100644 --- a/apps/provisioning_api/lib/Controller/UsersController.php +++ b/apps/provisioning_api/lib/Controller/UsersController.php @@ -51,6 +51,7 @@ use libphonenumber\PhoneNumberUtil; use OC\Authentication\Token\RemoteWipe; use OC\KnownUser\KnownUserService; use OC\User\Backend; +use OCA\Provisioning_API\ResponseDefinitions; use OCA\Settings\Mailer\NewUserMailHelper; use OCP\Accounts\IAccountManager; use OCP\Accounts\IAccountProperty; @@ -76,6 +77,9 @@ use OCP\Security\ISecureRandom; use OCP\User\Backend\ISetDisplayNameBackend; use Psr\Log\LoggerInterface; +/** + * @psalm-import-type ProvisioningApiUserDetails from ResponseDefinitions + */ class UsersController extends AUserData { /** @var IURLGenerator */ protected $urlGenerator; @@ -135,12 +139,12 @@ class UsersController extends AUserData { /** * @NoAdminRequired * - * returns a list of users + * Get a list of users * - * @param string $search - * @param int $limit - * @param int $offset - * @return DataResponse + * @param string $search Text to search for + * @param int|null $limit Limit the amount of groups returned + * @param int $offset Offset for searching for groups + * @return DataResponse<Http::STATUS_OK, array{users: string[]}, array{}> */ public function getUsers(string $search = '', int $limit = null, int $offset = 0): DataResponse { $user = $this->userSession->getUser(); @@ -163,6 +167,7 @@ class UsersController extends AUserData { } } + /** @var string[] $users */ $users = array_keys($users); return new DataResponse([ @@ -173,7 +178,12 @@ class UsersController extends AUserData { /** * @NoAdminRequired * - * returns a list of users and their data + * Get a list of users and their details + * + * @param string $search Text to search for + * @param int|null $limit Limit the amount of groups returned + * @param int $offset Offset for searching for groups + * @return DataResponse<Http::STATUS_OK, array{users: array<string, ProvisioningApiUserDetails|array{id: string}>}, array{}> */ public function getUsersDetails(string $search = '', int $limit = null, int $offset = 0): DataResponse { $currentUser = $this->userSession->getUser(); @@ -198,12 +208,13 @@ class UsersController extends AUserData { $users = array_merge(...$users); } + /** @var array<string, ProvisioningApiUserDetails|array{id: string}> $usersDetails */ $usersDetails = []; foreach ($users as $userId) { $userId = (string) $userId; $userData = $this->getUserData($userId); // Do not insert empty entry - if (!empty($userData)) { + if ($userData !== null) { $usersDetails[$userId] = $userData; } else { // Logged user does not have permissions to see this user @@ -222,9 +233,14 @@ class UsersController extends AUserData { * @NoAdminRequired * @NoSubAdminRequired * - * @param string $location - * @param array $search - * @return DataResponse + * Search users by their phone numbers + * + * @param string $location Location of the phone number (for country code) + * @param array<string, string[]> $search Phone numbers to search for + * @return DataResponse<Http::STATUS_OK, array<string, string>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array<empty>, array{}> + * + * 200: Users returned + * 400: Invalid location */ public function searchByPhoneNumbers(string $location, array $search): DataResponse { $phoneUtil = PhoneNumberUtil::getInstance(); @@ -318,16 +334,22 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @NoAdminRequired * - * @param string $userid - * @param string $password - * @param string $displayName - * @param string $email - * @param array $groups - * @param array $subadmin - * @param string $quota - * @param string $language - * @return DataResponse + * Create a new user + * + * @param string $userid ID of the user + * @param string $password Password of the user + * @param string $displayName Display name of the user + * @param string $email Email of the user + * @param string[] $groups Groups of the user + * @param string[] $subadmin Groups where the user is subadmin + * @param string $quota Quota of the user + * @param string $language Language of the user + * @param ?string $manager Manager of the user + * @return DataResponse<Http::STATUS_OK, array{id: string}, array{}> * @throws OCSException + * @throws OCSForbiddenException Missing permissions to make user subadmin + * + * 200: User added successfully */ public function addUser( string $userid, @@ -521,10 +543,10 @@ class UsersController extends AUserData { * @NoAdminRequired * @NoSubAdminRequired * - * gets user info + * Get the details of a user * - * @param string $userId - * @return DataResponse + * @param string $userId ID of the user + * @return DataResponse<Http::STATUS_OK, ProvisioningApiUserDetails, array{}> * @throws OCSException */ public function getUser(string $userId): DataResponse { @@ -535,8 +557,8 @@ class UsersController extends AUserData { } $data = $this->getUserData($userId, $includeScopes); - // getUserData returns empty array if not enough permissions - if (empty($data)) { + // getUserData returns null if not enough permissions + if ($data === null) { throw new OCSException('', OCSController::RESPOND_NOT_FOUND); } return new DataResponse($data); @@ -546,14 +568,15 @@ class UsersController extends AUserData { * @NoAdminRequired * @NoSubAdminRequired * - * gets user info from the currently logged in user + * Get the details of the current user * - * @return DataResponse + * @return DataResponse<Http::STATUS_OK, ProvisioningApiUserDetails, array{}> * @throws OCSException */ public function getCurrentUser(): DataResponse { $user = $this->userSession->getUser(); if ($user) { + /** @var ProvisioningApiUserDetails $data */ $data = $this->getUserData($user->getUID(), true); return new DataResponse($data); } @@ -565,7 +588,9 @@ class UsersController extends AUserData { * @NoAdminRequired * @NoSubAdminRequired * - * @return DataResponse + * Get a list of fields that are editable for the current user + * + * @return DataResponse<Http::STATUS_OK, string[], array{}> * @throws OCSException */ public function getEditableFields(): DataResponse { @@ -581,8 +606,10 @@ class UsersController extends AUserData { * @NoAdminRequired * @NoSubAdminRequired * - * @param string $userId - * @return DataResponse + * Get a list of fields that are editable for a user + * + * @param string $userId ID of the user + * @return DataResponse<Http::STATUS_OK, string[], array{}> * @throws OCSException */ public function getEditableFieldsForUser(string $userId): DataResponse { @@ -642,6 +669,13 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @UserRateThrottle(limit=5, period=60) * + * Update multiple values of the user's details + * + * @param string $userId ID of the user + * @param string $collectionName Collection to update + * @param string $key Key that will be updated + * @param string $value New value for the key + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function editUserMultiValue( @@ -735,12 +769,12 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @UserRateThrottle(limit=50, period=600) * - * edit users + * Update a value of the user's details * - * @param string $userId - * @param string $key - * @param string $value - * @return DataResponse + * @param string $userId ID of the user + * @param string $key Key that will be updated + * @param string $value New value for the key + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function editUser(string $userId, string $key, string $value): DataResponse { @@ -1046,9 +1080,11 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @NoAdminRequired * - * @param string $userId + * Wipe all devices of a user * - * @return DataResponse + * @param string $userId ID of the user + * + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * * @throws OCSException */ @@ -1081,8 +1117,10 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @NoAdminRequired * - * @param string $userId - * @return DataResponse + * Delete a user + * + * @param string $userId ID of the user + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function deleteUser(string $userId): DataResponse { @@ -1116,10 +1154,11 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @NoAdminRequired * - * @param string $userId - * @return DataResponse + * Disable a user + * + * @param string $userId ID of the user + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException - * @throws OCSForbiddenException */ public function disableUser(string $userId): DataResponse { return $this->setEnabled($userId, false); @@ -1129,10 +1168,11 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @NoAdminRequired * - * @param string $userId - * @return DataResponse + * Enable a user + * + * @param string $userId ID of the user + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException - * @throws OCSForbiddenException */ public function enableUser(string $userId): DataResponse { return $this->setEnabled($userId, true); @@ -1141,7 +1181,7 @@ class UsersController extends AUserData { /** * @param string $userId * @param bool $value - * @return DataResponse + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ private function setEnabled(string $userId, bool $value): DataResponse { @@ -1167,8 +1207,10 @@ class UsersController extends AUserData { * @NoAdminRequired * @NoSubAdminRequired * - * @param string $userId - * @return DataResponse + * Get a list of groups the user belongs to + * + * @param string $userId ID of the user + * @return DataResponse<Http::STATUS_OK, array{groups: string[]}, array{}> * @throws OCSException */ public function getUsersGroups(string $userId): DataResponse { @@ -1195,6 +1237,7 @@ class UsersController extends AUserData { foreach ($getSubAdminsGroups as $key => $group) { $getSubAdminsGroups[$key] = $group->getGID(); } + /** @var string[] $groups */ $groups = array_intersect( $getSubAdminsGroups, $this->groupManager->getUserGroupIds($targetUser) @@ -1211,9 +1254,11 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @NoAdminRequired * - * @param string $userId - * @param string $groupid - * @return DataResponse + * Add a user to a group + * + * @param string $userId ID of the user + * @param string $groupid ID of the group + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function addToGroup(string $userId, string $groupid = ''): DataResponse { @@ -1246,9 +1291,11 @@ class UsersController extends AUserData { * @PasswordConfirmationRequired * @NoAdminRequired * - * @param string $userId - * @param string $groupid - * @return DataResponse + * Remove a user from a group + * + * @param string $userId ID of the user + * @param string $groupid ID of the group + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function removeFromGroup(string $userId, string $groupid): DataResponse { @@ -1305,13 +1352,13 @@ class UsersController extends AUserData { } /** - * Creates a subadmin - * * @PasswordConfirmationRequired * - * @param string $userId - * @param string $groupid - * @return DataResponse + * Make a user a subadmin of a group + * + * @param string $userId ID of the user + * @param string $groupid ID of the group + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function addSubAdmin(string $userId, string $groupid): DataResponse { @@ -1343,13 +1390,13 @@ class UsersController extends AUserData { } /** - * Removes a subadmin from a group - * * @PasswordConfirmationRequired * - * @param string $userId - * @param string $groupid - * @return DataResponse + * Remove a user from the subadmins of a group + * + * @param string $userId ID of the user + * @param string $groupid ID of the group + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function removeSubAdmin(string $userId, string $groupid): DataResponse { @@ -1378,8 +1425,8 @@ class UsersController extends AUserData { /** * Get the groups a user is a subadmin of * - * @param string $userId - * @return DataResponse + * @param string $userId ID if the user + * @return DataResponse<Http::STATUS_OK, string[], array{}> * @throws OCSException */ public function getUserSubAdminGroups(string $userId): DataResponse { @@ -1391,10 +1438,10 @@ class UsersController extends AUserData { * @NoAdminRequired * @PasswordConfirmationRequired * - * resend welcome message + * Resend the welcome message * - * @param string $userId - * @return DataResponse + * @param string $userId ID if the user + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> * @throws OCSException */ public function resendWelcomeMessage(string $userId): DataResponse { |