aboutsummaryrefslogtreecommitdiffstats
path: root/lib/public/Notification
diff options
context:
space:
mode:
Diffstat (limited to 'lib/public/Notification')
-rw-r--r--lib/public/Notification/AlreadyProcessedException.php27
-rw-r--r--lib/public/Notification/IAction.php40
-rw-r--r--lib/public/Notification/IApp.php33
-rw-r--r--lib/public/Notification/IDeferrableApp.php29
-rw-r--r--lib/public/Notification/IDismissableNotifier.php33
-rw-r--r--lib/public/Notification/IManager.php41
-rw-r--r--lib/public/Notification/INotification.php97
-rw-r--r--lib/public/Notification/INotifier.php41
-rw-r--r--lib/public/Notification/IPreloadableNotifier.php31
-rw-r--r--lib/public/Notification/IncompleteNotificationException.php27
-rw-r--r--lib/public/Notification/IncompleteParsedNotificationException.php30
-rw-r--r--lib/public/Notification/InvalidValueException.php32
-rw-r--r--lib/public/Notification/UnknownNotificationException.php16
13 files changed, 260 insertions, 217 deletions
diff --git a/lib/public/Notification/AlreadyProcessedException.php b/lib/public/Notification/AlreadyProcessedException.php
index bc200eb71bd..162abd81864 100644
--- a/lib/public/Notification/AlreadyProcessedException.php
+++ b/lib/public/Notification/AlreadyProcessedException.php
@@ -3,31 +3,14 @@
declare(strict_types=1);
/**
- * @copyright Copyright (c) 2019 Joas Schilling <coding@schilljs.com>
- *
- * @author Joas Schilling <coding@schilljs.com>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * 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
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace OCP\Notification;
-/**
- * @since 17.0.0
- */
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '17.0.0')]
class AlreadyProcessedException extends \RuntimeException {
/**
* @since 17.0.0
diff --git a/lib/public/Notification/IAction.php b/lib/public/Notification/IAction.php
index bcd013f08bc..722dac72826 100644
--- a/lib/public/Notification/IAction.php
+++ b/lib/public/Notification/IAction.php
@@ -1,34 +1,16 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Joas Schilling <coding@schilljs.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\Notification;
-/**
- * Interface IAction
- *
- * @since 9.0.0
- */
+use OCP\AppFramework\Attribute\Consumable;
+
+#[Consumable(since: '9.0.0')]
interface IAction {
/**
* @since 17.0.0
@@ -54,8 +36,9 @@ interface IAction {
/**
* @param string $label
* @return $this
- * @throws \InvalidArgumentException if the label is invalid
+ * @throws InvalidValueException if the label is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setLabel(string $label): IAction;
@@ -68,8 +51,9 @@ interface IAction {
/**
* @param string $label
* @return $this
- * @throws \InvalidArgumentException if the label is invalid
+ * @throws InvalidValueException if the label is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setParsedLabel(string $label): IAction;
@@ -82,7 +66,6 @@ interface IAction {
/**
* @param bool $primary
* @return $this
- * @throws \InvalidArgumentException if $primary is invalid
* @since 9.0.0
*/
public function setPrimary(bool $primary): IAction;
@@ -97,8 +80,9 @@ interface IAction {
* @param string $link
* @param string $requestType
* @return $this
- * @throws \InvalidArgumentException if the link is invalid
+ * @throws InvalidValueException if the link is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setLink(string $link, string $requestType): IAction;
diff --git a/lib/public/Notification/IApp.php b/lib/public/Notification/IApp.php
index 6abb9a823e5..37c352d44cd 100644
--- a/lib/public/Notification/IApp.php
+++ b/lib/public/Notification/IApp.php
@@ -1,39 +1,22 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Joas Schilling <coding@schilljs.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\Notification;
-/**
- * Interface IApp
- *
- * @since 9.0.0
- */
+use OCP\AppFramework\Attribute\Implementable;
+
+#[Implementable(since: '9.0.0')]
interface IApp {
/**
* @param INotification $notification
- * @throws \InvalidArgumentException When the notification is not valid
+ * @throws IncompleteNotificationException When the notification does not have all required fields set
* @since 9.0.0
+ * @since 30.0.0 throws {@see IncompleteNotificationException} instead of \InvalidArgumentException
*/
public function notify(INotification $notification): void;
diff --git a/lib/public/Notification/IDeferrableApp.php b/lib/public/Notification/IDeferrableApp.php
index dad2828cdbd..00c7d691b10 100644
--- a/lib/public/Notification/IDeferrableApp.php
+++ b/lib/public/Notification/IDeferrableApp.php
@@ -3,33 +3,14 @@
declare(strict_types=1);
/**
- * @copyright Copyright (c) 2020, Joas Schilling <coding@schilljs.com>
- *
- * @author Joas Schilling <coding@schilljs.com>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * 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
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace OCP\Notification;
-/**
- * Interface IDeferrableApp
- *
- * @since 20.0.0
- */
+use OCP\AppFramework\Attribute\Implementable;
+
+#[Implementable(since: '20.0.0')]
interface IDeferrableApp extends IApp {
/**
* Start deferring notifications until `flush()` is called
diff --git a/lib/public/Notification/IDismissableNotifier.php b/lib/public/Notification/IDismissableNotifier.php
index c13e880a4a6..d2f649b45a1 100644
--- a/lib/public/Notification/IDismissableNotifier.php
+++ b/lib/public/Notification/IDismissableNotifier.php
@@ -3,43 +3,30 @@
declare(strict_types=1);
/**
- * @copyright Copyright (c) 2019, Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * 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
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace OCP\Notification;
+use OCP\AppFramework\Attribute\Implementable;
+
/**
* Interface INotifier classes should implement if they want to process notifications
* that are dismissed by the user.
*
* This can be useful if dismissing the notification will leave it in an incomplete
- * state. The handler can chose to for example do some default action.
- *
- * @since 18.0.0
+ * state. The handler can choose to for example do some default action.
*/
+#[Implementable(since: '18.0.0')]
interface IDismissableNotifier extends INotifier {
/**
* @param INotification $notification
- * @throws \InvalidArgumentException In case the handler can't handle the notification
+ * @throws UnknownNotificationException when the notifier is not in charge of the notification
*
* @since 18.0.0
+ * @since 30.0.0 Notifiers should throw {@see UnknownNotificationException} instead of \InvalidArgumentException
+ * when they did not handle the notification. Throwing \InvalidArgumentException directly is deprecated and will
+ * be logged as an error in Nextcloud 39.
*/
public function dismissNotification(INotification $notification): void;
}
diff --git a/lib/public/Notification/IManager.php b/lib/public/Notification/IManager.php
index 82f0ced07ed..207a89344b0 100644
--- a/lib/public/Notification/IManager.php
+++ b/lib/public/Notification/IManager.php
@@ -1,39 +1,20 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @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\Notification;
-/**
- * Interface IManager
- *
- * @since 9.0.0
- */
-interface IManager extends IApp, INotifier {
+use OCP\AppFramework\Attribute\Consumable;
+
+#[Consumable(since: '9.0.0')]
+interface IManager extends IApp, IPreloadableNotifier {
/**
* @param string $appClass The service must implement IApp, otherwise a
- * \InvalidArgumentException is thrown later
+ * \InvalidArgumentException is thrown later
* @since 17.0.0
*/
public function registerApp(string $appClass): void;
@@ -41,8 +22,8 @@ interface IManager extends IApp, INotifier {
/**
* @param \Closure $service The service must implement INotifier, otherwise a
* \InvalidArgumentException is thrown later
- * @param \Closure $info An array with the keys 'id' and 'name' containing
- * the app id and the app name
+ * @param \Closure $info An array with the keys 'id' and 'name' containing
+ * the app id and the app name
* @deprecated 17.0.0 use registerNotifierService instead.
* @since 8.2.0 - Parameter $info was added in 9.0.0
*/
@@ -50,7 +31,7 @@ interface IManager extends IApp, INotifier {
/**
* @param string $notifierService The service must implement INotifier, otherwise a
- * \InvalidArgumentException is thrown later
+ * \InvalidArgumentException is thrown later
* @since 17.0.0
* @deprecated 22.0.0 use the IBootStrap registration context
*/
diff --git a/lib/public/Notification/INotification.php b/lib/public/Notification/INotification.php
index 0c6625e346d..a740678376f 100644
--- a/lib/public/Notification/INotification.php
+++ b/lib/public/Notification/INotification.php
@@ -1,41 +1,23 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @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\Notification;
-/**
- * Interface INotification
- *
- * @since 9.0.0
- */
+use OCP\AppFramework\Attribute\Consumable;
+
+#[Consumable(since: '9.0.0')]
interface INotification {
/**
* @param string $app
* @return $this
- * @throws \InvalidArgumentException if the app id is invalid
+ * @throws InvalidValueException if the app id is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setApp(string $app): INotification;
@@ -48,8 +30,9 @@ interface INotification {
/**
* @param string $user
* @return $this
- * @throws \InvalidArgumentException if the user id is invalid
+ * @throws InvalidValueException if the user id is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setUser(string $user): INotification;
@@ -62,8 +45,9 @@ interface INotification {
/**
* @param \DateTime $dateTime
* @return $this
- * @throws \InvalidArgumentException if the $dateTime is invalid
+ * @throws InvalidValueException if the $dateTime is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setDateTime(\DateTime $dateTime): INotification;
@@ -77,8 +61,9 @@ interface INotification {
* @param string $type
* @param string $id
* @return $this
- * @throws \InvalidArgumentException if the object type or id is invalid
+ * @throws InvalidValueException if the object type or id is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setObject(string $type, string $id): INotification;
@@ -98,8 +83,9 @@ interface INotification {
* @param string $subject
* @param array $parameters
* @return $this
- * @throws \InvalidArgumentException if the subject or parameters are invalid
+ * @throws InvalidValueException if the subject or parameters are invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setSubject(string $subject, array $parameters = []): INotification;
@@ -127,8 +113,9 @@ interface INotification {
*
* @param string $subject
* @return $this
- * @throws \InvalidArgumentException if the subject is invalid
+ * @throws InvalidValueException if the subject is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setParsedSubject(string $subject): INotification;
@@ -148,10 +135,11 @@ interface INotification {
* See https://github.com/nextcloud/server/issues/1706 for more information.
*
* @param string $subject
- * @param array $parameters
+ * @param array<string, array<string, string>> $parameters
* @return $this
- * @throws \InvalidArgumentException if the subject or parameters are invalid
+ * @throws InvalidValueException if the subject or parameters are invalid
* @since 11.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setRichSubject(string $subject, array $parameters = []): INotification;
@@ -171,8 +159,9 @@ interface INotification {
* @param string $message
* @param array $parameters
* @return $this
- * @throws \InvalidArgumentException if the message or parameters are invalid
+ * @throws InvalidValueException if the message or parameters are invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setMessage(string $message, array $parameters = []): INotification;
@@ -200,8 +189,9 @@ interface INotification {
*
* @param string $message
* @return $this
- * @throws \InvalidArgumentException if the message is invalid
+ * @throws InvalidValueException if the message is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setParsedMessage(string $message): INotification;
@@ -221,10 +211,11 @@ interface INotification {
* See https://github.com/nextcloud/server/issues/1706 for more information.
*
* @param string $message
- * @param array $parameters
+ * @param array<string, array<string, string>> $parameters
* @return $this
- * @throws \InvalidArgumentException if the message or parameters are invalid
+ * @throws InvalidValueException if the message or parameters are invalid
* @since 11.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setRichMessage(string $message, array $parameters = []): INotification;
@@ -243,8 +234,9 @@ interface INotification {
/**
* @param string $link
* @return $this
- * @throws \InvalidArgumentException if the link is invalid
+ * @throws InvalidValueException if the link is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setLink(string $link): INotification;
@@ -255,20 +247,41 @@ interface INotification {
public function getLink(): string;
/**
+ * Set the absolute url for the icon (should be colored black or not have a color)
+ *
+ * It's automatically color inverted by clients when needed
+ *
* @param string $icon
* @return $this
- * @throws \InvalidArgumentException if the icon is invalid
+ * @throws InvalidValueException if the icon is invalid
* @since 11.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function setIcon(string $icon): INotification;
/**
+ * Get the absolute url for the icon (should be colored black or not have a color)
+ *
+ * It's automatically color inverted by clients when needed
+ *
* @return string
* @since 11.0.0
*/
public function getIcon(): string;
/**
+ * @return $this
+ * @throws InvalidValueException if the app is not allowed to send priority notifications
+ * @since 31.0.0
+ */
+ public function setPriorityNotification(bool $priorityNotification): INotification;
+
+ /**
+ * @since 31.0.0
+ */
+ public function isPriorityNotification(): bool;
+
+ /**
* @return IAction
* @since 9.0.0
*/
@@ -277,8 +290,9 @@ interface INotification {
/**
* @param IAction $action
* @return $this
- * @throws \InvalidArgumentException if the action is invalid
+ * @throws InvalidValueException if the action is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function addAction(IAction $action): INotification;
@@ -291,8 +305,9 @@ interface INotification {
/**
* @param IAction $action
* @return $this
- * @throws \InvalidArgumentException if the action is invalid
+ * @throws InvalidValueException if the action is invalid
* @since 9.0.0
+ * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
*/
public function addParsedAction(IAction $action): INotification;
diff --git a/lib/public/Notification/INotifier.php b/lib/public/Notification/INotifier.php
index ba43cc04cf6..b6851e3dfb3 100644
--- a/lib/public/Notification/INotifier.php
+++ b/lib/public/Notification/INotifier.php
@@ -1,34 +1,21 @@
<?php
declare(strict_types=1);
-
/**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Joas Schilling <coding@schilljs.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\Notification;
+use OCP\AppFramework\Attribute\Implementable;
+
/**
- * Interface INotifier
- *
- * @since 9.0.0
+ * Please consider implementing {@see IPreloadableNotifier} to improve performance. It allows to
+ * preload and cache data for many notifications at once instead of loading the data for each
+ * prepared notification separately.
*/
+#[Implementable(since: '9.0.0')]
interface INotifier {
/**
* Identifier of the notifier, only use [a-z0-9_]
@@ -39,7 +26,7 @@ interface INotifier {
public function getID(): string;
/**
- * Human readable name describing the notifier
+ * Human-readable name describing the notifier
*
* @return string
* @since 17.0.0
@@ -50,9 +37,15 @@ interface INotifier {
* @param INotification $notification
* @param string $languageCode The code of the language that should be used to prepare the notification
* @return INotification
- * @throws \InvalidArgumentException When the notification was not prepared by a notifier
+ * @throws UnknownNotificationException When the notification was not prepared by a notifier
* @throws AlreadyProcessedException When the notification is not needed anymore and should be deleted
+ * @throws IncompleteParsedNotificationException Only to be thrown by the {@see IManager}
* @since 9.0.0
+ * @since 30.0.0 Notifiers should throw {@see UnknownNotificationException} instead of \InvalidArgumentException
+ * when they did not handle the notification. Throwing \InvalidArgumentException directly is deprecated and will
+ * be logged as an error in Nextcloud 39.
+ * @since 30.0.0 Throws {@see IncompleteParsedNotificationException} when not all required fields
+ * are set at the end of the manager or after a INotifier that claimed to have parsed the notification.
*/
public function prepare(INotification $notification, string $languageCode): INotification;
}
diff --git a/lib/public/Notification/IPreloadableNotifier.php b/lib/public/Notification/IPreloadableNotifier.php
new file mode 100644
index 00000000000..2bdcd84d254
--- /dev/null
+++ b/lib/public/Notification/IPreloadableNotifier.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Implementable;
+
+/**
+ * Allow notifier implementations to preload and cache data for many notifications at once to
+ * improve performance by, for example, bundling SQL queries.
+ */
+#[Implementable(since: '32.0.0')]
+interface IPreloadableNotifier extends INotifier {
+ /**
+ * This method provides a way for notifier implementations to preload and cache data for many
+ * notifications. The data is meant to be consumed later in the {@see INotifier::prepare()}
+ * method to improve performance.
+ *
+ * @since 32.0.0
+ *
+ * @param INotification[] $notifications The notifications which are about to be prepared in the next step.
+ * @param string $languageCode The code of the language that should be used to prepare the notification.
+ */
+ public function preloadDataForParsing(array $notifications, string $languageCode): void;
+}
diff --git a/lib/public/Notification/IncompleteNotificationException.php b/lib/public/Notification/IncompleteNotificationException.php
new file mode 100644
index 00000000000..49d388ebee6
--- /dev/null
+++ b/lib/public/Notification/IncompleteNotificationException.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Catchable;
+
+/**
+ * Thrown when {@see \OCP\Notification\IManager::notify()} is called with a notification
+ * that does not have all required fields set:
+ *
+ * - app
+ * - user
+ * - dateTime
+ * - objectType
+ * - objectId
+ * - subject
+ */
+#[Catchable(since: '30.0.0')]
+class IncompleteNotificationException extends \InvalidArgumentException {
+}
diff --git a/lib/public/Notification/IncompleteParsedNotificationException.php b/lib/public/Notification/IncompleteParsedNotificationException.php
new file mode 100644
index 00000000000..c31ab129fd4
--- /dev/null
+++ b/lib/public/Notification/IncompleteParsedNotificationException.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Catchable;
+
+/**
+ * Thrown when {@see \OCP\Notification\IManager::prepare()} is called with a notification
+ * that does not have all required fields set at the end of the manager or after a INotifier
+ * that claimed to have parsed the notification.
+ *
+ * Required fields are:
+ *
+ * - app
+ * - user
+ * - dateTime
+ * - objectType
+ * - objectId
+ * - parsedSubject
+ */
+#[Catchable(since: '30.0.0')]
+class IncompleteParsedNotificationException extends \InvalidArgumentException {
+}
diff --git a/lib/public/Notification/InvalidValueException.php b/lib/public/Notification/InvalidValueException.php
new file mode 100644
index 00000000000..ec52381ee3c
--- /dev/null
+++ b/lib/public/Notification/InvalidValueException.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Catchable;
+
+#[Catchable(since: '30.0.0')]
+class InvalidValueException extends \InvalidArgumentException {
+ /**
+ * @since 30.0.0
+ */
+ public function __construct(
+ protected string $field,
+ ?\Throwable $previous = null,
+ ) {
+ parent::__construct('Value provided for ' . $field . ' is not valid', previous: $previous);
+ }
+
+ /**
+ * @since 30.0.0
+ */
+ public function getFieldIdentifier(): string {
+ return $this->field;
+ }
+}
diff --git a/lib/public/Notification/UnknownNotificationException.php b/lib/public/Notification/UnknownNotificationException.php
new file mode 100644
index 00000000000..976d9179592
--- /dev/null
+++ b/lib/public/Notification/UnknownNotificationException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '30.0.0')]
+class UnknownNotificationException extends \InvalidArgumentException {
+}
generated by cgit v1.2.3 (git 2.39.1) at 2025-08-16 04:49:44 +0000