aboutsummaryrefslogtreecommitdiffstats
path: root/apps/provisioning_api/lib/Controller/GroupsController.php
diff options
context:
space:
mode:
Diffstat (limited to 'apps/provisioning_api/lib/Controller/GroupsController.php')
-rw-r--r--apps/provisioning_api/lib/Controller/GroupsController.php102
1 files changed, 62 insertions, 40 deletions
diff --git a/apps/provisioning_api/lib/Controller/GroupsController.php b/apps/provisioning_api/lib/Controller/GroupsController.php
index 46de5395a65..5404f47efc2 100644
--- a/apps/provisioning_api/lib/Controller/GroupsController.php
+++ b/apps/provisioning_api/lib/Controller/GroupsController.php
@@ -14,6 +14,7 @@ declare(strict_types=1);
* @author Robin Appelman <robin@icewind.nl>
* @author Roeland Jago Douma <roeland@famdouma.nl>
* @author Tom Needham <tom@owncloud.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
*
* @license AGPL-3.0
*
@@ -32,7 +33,9 @@ declare(strict_types=1);
*/
namespace OCA\Provisioning_API\Controller;
+use OCA\Provisioning_API\ResponseDefinitions;
use OCP\Accounts\IAccountManager;
+use OCP\AppFramework\Http;
use OCP\AppFramework\Http\DataResponse;
use OCP\AppFramework\OCS\OCSException;
use OCP\AppFramework\OCS\OCSForbiddenException;
@@ -48,6 +51,10 @@ use OCP\IUserSession;
use OCP\L10N\IFactory;
use Psr\Log\LoggerInterface;
+/**
+ * @psalm-import-type ProvisioningApiGroupDetails from ResponseDefinitions
+ * @psalm-import-type ProvisioningApiUserDetails from ResponseDefinitions
+ */
class GroupsController extends AUserData {
/** @var LoggerInterface */
@@ -76,16 +83,16 @@ class GroupsController extends AUserData {
}
/**
- * returns a list of groups
- *
* @NoAdminRequired
*
- * @param string $search
- * @param int $limit
- * @param int $offset
- * @return DataResponse
+ * Get a list of groups
+ *
+ * @param string $search Text to search for
+ * @param ?int $limit Limit the amount of groups returned
+ * @param int $offset Offset for searching for groups
+ * @return DataResponse<Http::STATUS_OK, array{groups: string[]}, array{}>
*/
- public function getGroups(string $search = '', int $limit = null, int $offset = 0): DataResponse {
+ public function getGroups(string $search = '', ?int $limit = null, int $offset = 0): DataResponse {
$groups = $this->groupManager->search($search, $limit, $offset);
$groups = array_map(function ($group) {
/** @var IGroup $group */
@@ -96,15 +103,15 @@ class GroupsController extends AUserData {
}
/**
- * Returns a list of groups details with ids and displaynames
- *
* @NoAdminRequired
* @AuthorizedAdminSetting(settings=OCA\Settings\Settings\Admin\Sharing)
*
- * @param string $search
- * @param int $limit
- * @param int $offset
- * @return DataResponse
+ * Get a list of groups details
+ *
+ * @param string $search Text to search for
+ * @param ?int $limit Limit the amount of groups returned
+ * @param int $offset Offset for searching for groups
+ * @return DataResponse<Http::STATUS_OK, array{groups: ProvisioningApiGroupDetails[]}, array{}>
*/
public function getGroupsDetails(string $search = '', int $limit = null, int $offset = 0): DataResponse {
$groups = $this->groupManager->search($search, $limit, $offset);
@@ -126,8 +133,10 @@ class GroupsController extends AUserData {
/**
* @NoAdminRequired
*
- * @param string $groupId
- * @return DataResponse
+ * Get a list of users in the specified group
+ *
+ * @param string $groupId ID of the group
+ * @return DataResponse<Http::STATUS_OK, array{users: string[]}, array{}>
* @throws OCSException
*
* @deprecated 14 Use getGroupUsers
@@ -137,13 +146,17 @@ class GroupsController extends AUserData {
}
/**
- * returns an array of users in the specified group
- *
* @NoAdminRequired
*
- * @param string $groupId
- * @return DataResponse
+ * Get a list of users in the specified group
+ *
+ * @param string $groupId ID of the group
+ * @return DataResponse<Http::STATUS_OK, array{users: string[]}, array{}>
* @throws OCSException
+ * @throws OCSNotFoundException Group not found
+ * @throws OCSForbiddenException Missing permissions to get users in the group
+ *
+ * 200: User IDs returned
*/
public function getGroupUsers(string $groupId): DataResponse {
$groupId = urldecode($groupId);
@@ -167,6 +180,7 @@ class GroupsController extends AUserData {
/** @var IUser $user */
return $user->getUID();
}, $users);
+ /** @var string[] $users */
$users = array_values($users);
return new DataResponse(['users' => $users]);
}
@@ -175,15 +189,16 @@ class GroupsController extends AUserData {
}
/**
- * returns an array of users details in the specified group
- *
* @NoAdminRequired
*
- * @param string $groupId
- * @param string $search
- * @param int $limit
- * @param int $offset
- * @return DataResponse
+ * Get a list of users details in the specified group
+ *
+ * @param string $groupId ID of the group
+ * @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{}>
* @throws OCSException
*/
public function getGroupUsersDetails(string $groupId, string $search = '', int $limit = null, int $offset = 0): DataResponse {
@@ -210,7 +225,7 @@ class GroupsController extends AUserData {
$userId = (string)$user->getUID();
$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
@@ -228,13 +243,13 @@ class GroupsController extends AUserData {
}
/**
- * creates a new group
- *
* @PasswordConfirmationRequired
*
- * @param string $groupid
- * @param string $displayname
- * @return DataResponse
+ * Create a new group
+ *
+ * @param string $groupid ID of the group
+ * @param string $displayname Display name of the group
+ * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function addGroup(string $groupid, string $displayname = ''): DataResponse {
@@ -260,10 +275,12 @@ class GroupsController extends AUserData {
/**
* @PasswordConfirmationRequired
*
- * @param string $groupId
- * @param string $key
- * @param string $value
- * @return DataResponse
+ * Update a group
+ *
+ * @param string $groupId ID of the group
+ * @param string $key Key to update, only 'displayname'
+ * @param string $value New value for the key
+ * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function updateGroup(string $groupId, string $key, string $value): DataResponse {
@@ -287,8 +304,10 @@ class GroupsController extends AUserData {
/**
* @PasswordConfirmationRequired
*
- * @param string $groupId
- * @return DataResponse
+ * Delete a group
+ *
+ * @param string $groupId ID of the group
+ * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function deleteGroup(string $groupId): DataResponse {
@@ -306,8 +325,10 @@ class GroupsController extends AUserData {
}
/**
- * @param string $groupId
- * @return DataResponse
+ * Get the list of user IDs that are a subadmin of the group
+ *
+ * @param string $groupId ID of the group
+ * @return DataResponse<Http::STATUS_OK, string[], array{}>
* @throws OCSException
*/
public function getSubAdminsOfGroup(string $groupId): DataResponse {
@@ -320,6 +341,7 @@ class GroupsController extends AUserData {
/** @var IUser[] $subadmins */
$subadmins = $this->groupManager->getSubAdmin()->getGroupsSubAdmins($targetGroup);
// New class returns IUser[] so convert back
+ /** @var string[] $uids */
$uids = [];
foreach ($subadmins as $user) {
$uids[] = $user->getUID();
generated by cgit v1.2.3 (git 2.39.1) at 2025-05-03 22:12:10 +0000