aboutsummaryrefslogtreecommitdiffstats
path: root/lib/public/SystemTag
diff options
context:
space:
mode:
Diffstat (limited to 'lib/public/SystemTag')
-rw-r--r--lib/public/SystemTag/ISystemTag.php40
-rw-r--r--lib/public/SystemTag/ISystemTagManager.php64
-rw-r--r--lib/public/SystemTag/ISystemTagManagerFactory.php23
-rw-r--r--lib/public/SystemTag/ISystemTagObjectMapper.php61
-rw-r--r--lib/public/SystemTag/ManagerEvent.php26
-rw-r--r--lib/public/SystemTag/MapperEvent.php41
-rw-r--r--lib/public/SystemTag/SystemTagsEntityEvent.php31
-rw-r--r--lib/public/SystemTag/TagAlreadyExistsException.php23
-rw-r--r--lib/public/SystemTag/TagCreationForbiddenException.php18
-rw-r--r--lib/public/SystemTag/TagNotFoundException.php25
-rw-r--r--lib/public/SystemTag/TagUpdateForbiddenException.php18
11 files changed, 160 insertions, 210 deletions
diff --git a/lib/public/SystemTag/ISystemTag.php b/lib/public/SystemTag/ISystemTag.php
index 6f6fce07585..4fd93831955 100644
--- a/lib/public/SystemTag/ISystemTag.php
+++ b/lib/public/SystemTag/ISystemTag.php
@@ -1,28 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Johannes Leuker <j.leuker@hosting.de>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- * @author Vincent Petry <vincent@nextcloud.com>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
@@ -98,4 +80,20 @@ interface ISystemTag {
* @since 22.0.0
*/
public function getAccessLevel(): int;
+
+ /**
+ * Returns the ETag of the tag
+ * The ETag is a unique identifier for the tag and should change whenever the tag changes
+ * or whenever elements gets added or removed from the tag.
+ *
+ * @since 31.0.0
+ */
+ public function getETag(): ?string;
+
+ /**
+ * Returns the color of the tag
+ *
+ * @since 31.0.0
+ */
+ public function getColor(): ?string;
}
diff --git a/lib/public/SystemTag/ISystemTagManager.php b/lib/public/SystemTag/ISystemTagManager.php
index 0f5c373c49f..96e775d6401 100644
--- a/lib/public/SystemTag/ISystemTagManager.php
+++ b/lib/public/SystemTag/ISystemTagManager.php
@@ -1,28 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Joas Schilling <coding@schilljs.com>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- * @author Vincent Petry <vincent@nextcloud.com>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
@@ -44,7 +26,7 @@ interface ISystemTagManager {
*
* @throws \InvalidArgumentException if at least one given tag ids is invalid (string instead of integer, etc.)
* @throws TagNotFoundException if at least one given tag ids did no exist
- * The message contains a json_encoded array of the ids that could not be found
+ * The message contains a json_encoded array of the ids that could not be found
*
* @since 9.0.0, optional parameter $user added in 28.0.0
*/
@@ -75,8 +57,10 @@ interface ISystemTagManager {
* @return ISystemTag system tag
*
* @throws TagAlreadyExistsException if tag already exists
+ * @throws TagCreationForbiddenException if user doesn't have the right to create a new tag
*
* @since 9.0.0
+ * @since 31.0.0 Can throw TagCreationForbiddenExceptionif user doesn't have the right to create a new tag
*/
public function createTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag;
@@ -99,14 +83,16 @@ interface ISystemTagManager {
* @param string $newName the new tag name
* @param bool $userVisible whether the tag is visible by users
* @param bool $userAssignable whether the tag is assignable by users
+ * @param string $color color
*
* @throws TagNotFoundException if tag with the given id does not exist
* @throws TagAlreadyExistsException if there is already another tag
- * with the same attributes
+ * with the same attributes
*
* @since 9.0.0
+ * @since 31.0.0 `$color` parameter added
*/
- public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable);
+ public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable, ?string $color);
/**
* Delete the given tags from the database and all their relationships.
@@ -124,25 +110,47 @@ interface ISystemTagManager {
* given id.
*
* @param ISystemTag $tag tag to check permission for
- * @param IUser $user user to check permission for
+ * @param IUser|null $user user to check permission for
*
* @return bool true if the user is allowed to assign/unassign the tag, false otherwise
*
* @since 9.1.0
+ * @since 31.0.0 `$user` can be null to check anonymous permissions
+ */
+ public function canUserAssignTag(ISystemTag $tag, ?IUser $user): bool;
+
+ /**
+ * Checks whether the given user is allowed to create new tags
+ *
+ * @param IUser|null $user user to check permission for
+ * @return bool true if the user is allowed to create a new tag, false otherwise
+ *
+ * @since 31.0.0
+ */
+ public function canUserCreateTag(?IUser $user): bool;
+
+ /**
+ * Checks whether the given user is allowed to update tags
+ *
+ * @param IUser|null $user user to check permission for
+ * @return bool true if the user is allowed to update a tag, false otherwise
+ *
+ * @since 31.0.0
*/
- public function canUserAssignTag(ISystemTag $tag, IUser $user): bool;
+ public function canUserUpdateTag(?IUser $user): bool;
/**
* Checks whether the given user is allowed to see the tag with the given id.
*
* @param ISystemTag $tag tag to check permission for
- * @param IUser $user user to check permission for
+ * @param IUser|null $user user to check permission for
*
* @return bool true if the user can see the tag, false otherwise
*
* @since 9.1.0
+ * @since 31.0.0 `$user` can be null to check anonymous permissions
*/
- public function canUserSeeTag(ISystemTag $tag, IUser $user): bool;
+ public function canUserSeeTag(ISystemTag $tag, ?IUser $user): bool;
/**
* Set groups that can assign a given tag.
diff --git a/lib/public/SystemTag/ISystemTagManagerFactory.php b/lib/public/SystemTag/ISystemTagManagerFactory.php
index 2028128d6a0..e6c10568d16 100644
--- a/lib/public/SystemTag/ISystemTagManagerFactory.php
+++ b/lib/public/SystemTag/ISystemTagManagerFactory.php
@@ -1,27 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- * @author Vincent Petry <vincent@nextcloud.com>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
diff --git a/lib/public/SystemTag/ISystemTagObjectMapper.php b/lib/public/SystemTag/ISystemTagObjectMapper.php
index 07a542c6794..c604fa93c58 100644
--- a/lib/public/SystemTag/ISystemTagObjectMapper.php
+++ b/lib/public/SystemTag/ISystemTagObjectMapper.php
@@ -1,28 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Joas Schilling <coding@schilljs.com>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- * @author Vincent Petry <vincent@nextcloud.com>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
@@ -49,7 +31,7 @@ interface ISystemTagObjectMapper {
* @param string $objectType object type
*
* @return array with object id as key and an array
- * of tag ids as value
+ * of tag ids as value
*
* @since 9.0.0
*/
@@ -66,9 +48,9 @@ interface ISystemTagObjectMapper {
* @return string[] array of object ids or empty array if none found
*
* @throws TagNotFoundException if at least one of the
- * given tags does not exist
+ * given tags does not exist
* @throws \InvalidArgumentException When a limit is specified together with
- * multiple tag ids
+ * multiple tag ids
*
* @since 9.0.0
*/
@@ -87,7 +69,7 @@ interface ISystemTagObjectMapper {
* @param string|array $tagIds tag id or array of tag ids to assign
*
* @throws TagNotFoundException if at least one of the
- * given tags does not exist
+ * given tags does not exist
*
* @since 9.0.0
*/
@@ -106,7 +88,7 @@ interface ISystemTagObjectMapper {
* @param string|array $tagIds tag id or array of tag ids to unassign
*
* @throws TagNotFoundException if at least one of the
- * given tags does not exist
+ * given tags does not exist
*
* @since 9.0.0
*/
@@ -119,14 +101,37 @@ interface ISystemTagObjectMapper {
* @param string $objectType object type
* @param string $tagId tag id to check
* @param bool $all true to check that ALL objects have the tag assigned,
- * false to check that at least ONE object has the tag.
+ * false to check that at least ONE object has the tag.
*
* @return bool true if the condition set by $all is matched, false
- * otherwise
+ * otherwise
*
* @throws TagNotFoundException if the tag does not exist
*
* @since 9.0.0
*/
public function haveTag($objIds, string $objectType, string $tagId, bool $all = true): bool;
+
+
+ /**
+ * Get the list of object types that have objects assigned to them.
+ *
+ * @return string[] list of object types
+ *
+ * @since 31.0.0
+ */
+ public function getAvailableObjectTypes(): array;
+
+ /**
+ * Set the list of object ids for the given tag.
+ * This will replace the current list of object ids.
+ *
+ * @param string $tagId tag id
+ * @param string $objectType object type
+ * @param string[] $objectIds list of object ids
+ *
+ * @throws TagNotFoundException if the tag does not exist
+ * @since 31.0.0
+ */
+ public function setObjectIdsForTag(string $tagId, string $objectType, array $objectIds): void;
}
diff --git a/lib/public/SystemTag/ManagerEvent.php b/lib/public/SystemTag/ManagerEvent.php
index 802b690038a..adfe64f8658 100644
--- a/lib/public/SystemTag/ManagerEvent.php
+++ b/lib/public/SystemTag/ManagerEvent.php
@@ -1,30 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Joas Schilling <coding@schilljs.com>
- * @author Lukas Reschke <lukas@statuscode.ch>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
diff --git a/lib/public/SystemTag/MapperEvent.php b/lib/public/SystemTag/MapperEvent.php
index cbd1b2ff2db..821d1b5dc5e 100644
--- a/lib/public/SystemTag/MapperEvent.php
+++ b/lib/public/SystemTag/MapperEvent.php
@@ -1,40 +1,22 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Joas Schilling <coding@schilljs.com>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
use OCP\EventDispatcher\Event;
+use OCP\EventDispatcher\IWebhookCompatibleEvent;
/**
* Class MapperEvent
*
* @since 9.0.0
*/
-class MapperEvent extends Event {
+class MapperEvent extends Event implements IWebhookCompatibleEvent {
/**
* @since 9.0.0
* @deprecated 22.0.0
@@ -103,4 +85,17 @@ class MapperEvent extends Event {
public function getTags(): array {
return $this->tags;
}
+
+ /**
+ * @return array
+ * @since 32.0.0
+ */
+ public function getWebhookSerializable(): array {
+ return [
+ 'eventType' => $this->getEvent(),
+ 'objectType' => $this->getObjectType(),
+ 'objectId' => $this->getObjectId(),
+ 'tagIds' => $this->getTags(),
+ ];
+ }
}
diff --git a/lib/public/SystemTag/SystemTagsEntityEvent.php b/lib/public/SystemTag/SystemTagsEntityEvent.php
index 252029e6ba2..d8f391d0dba 100644
--- a/lib/public/SystemTag/SystemTagsEntityEvent.php
+++ b/lib/public/SystemTag/SystemTagsEntityEvent.php
@@ -1,29 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Joas Schilling <coding@schilljs.com>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
@@ -56,9 +37,9 @@ class SystemTagsEntityEvent extends Event {
/**
* @param string $name
* @param \Closure $entityExistsFunction The closure should take one
- * argument, which is the id of the entity, that tags
- * should be handled for. The return should then be bool,
- * depending on whether tags are allowed (true) or not.
+ * argument, which is the id of the entity, that tags
+ * should be handled for. The return should then be bool,
+ * depending on whether tags are allowed (true) or not.
* @throws \OutOfBoundsException when the entity name is already taken
* @since 9.1.0
*/
diff --git a/lib/public/SystemTag/TagAlreadyExistsException.php b/lib/public/SystemTag/TagAlreadyExistsException.php
index 23c36a376f6..9db94bc4124 100644
--- a/lib/public/SystemTag/TagAlreadyExistsException.php
+++ b/lib/public/SystemTag/TagAlreadyExistsException.php
@@ -1,27 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Vincent Petry <vincent@nextcloud.com>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
diff --git a/lib/public/SystemTag/TagCreationForbiddenException.php b/lib/public/SystemTag/TagCreationForbiddenException.php
new file mode 100644
index 00000000000..eeae38e31f7
--- /dev/null
+++ b/lib/public/SystemTag/TagCreationForbiddenException.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\SystemTag;
+
+/**
+ * Exception when a user doesn't have the right to create a tag
+ *
+ * @since 31.0.0
+ */
+class TagCreationForbiddenException extends \RuntimeException {
+}
diff --git a/lib/public/SystemTag/TagNotFoundException.php b/lib/public/SystemTag/TagNotFoundException.php
index 8f5442bb145..8a143422fff 100644
--- a/lib/public/SystemTag/TagNotFoundException.php
+++ b/lib/public/SystemTag/TagNotFoundException.php
@@ -1,29 +1,10 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Joas Schilling <coding@schilljs.com>
- * @author Lukas Reschke <lukas@statuscode.ch>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- * @author Vincent Petry <vincent@nextcloud.com>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
*/
namespace OCP\SystemTag;
diff --git a/lib/public/SystemTag/TagUpdateForbiddenException.php b/lib/public/SystemTag/TagUpdateForbiddenException.php
new file mode 100644
index 00000000000..e5c1e76f6fe
--- /dev/null
+++ b/lib/public/SystemTag/TagUpdateForbiddenException.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\SystemTag;
+
+/**
+ * Exception when a user doesn't have the right to create a tag
+ *
+ * @since 31.0.1
+ */
+class TagUpdateForbiddenException extends \RuntimeException {
+}
generated by cgit v1.2.3 (git 2.39.1) at 2025-08-15 05:34:57 +0000