diff options
Diffstat (limited to 'lib/public/Accounts')
| -rw-r--r-- | lib/public/Accounts/IAccount.php | 113 | ||||
| -rw-r--r-- | lib/public/Accounts/IAccountManager.php | 203 | ||||
| -rw-r--r-- | lib/public/Accounts/IAccountProperty.php | 62 | ||||
| -rw-r--r-- | lib/public/Accounts/IAccountPropertyCollection.php | 81 | ||||
| -rw-r--r-- | lib/public/Accounts/PropertyDoesNotExistException.php | 25 | ||||
| -rw-r--r-- | lib/public/Accounts/UserUpdatedEvent.php | 43 |
6 files changed, 429 insertions, 98 deletions
diff --git a/lib/public/Accounts/IAccount.php b/lib/public/Accounts/IAccount.php index 3f8c86cbc1a..f9218f5fdf6 100644 --- a/lib/public/Accounts/IAccount.php +++ b/lib/public/Accounts/IAccount.php @@ -3,29 +3,12 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2018 Julius Härtl <jus@bitgrid.net> - * - * @author Julius Härtl <jus@bitgrid.net> - * - * @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: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Accounts; +use Generator; use OCP\IUser; /** @@ -34,19 +17,19 @@ use OCP\IUser; * @since 15.0.0 */ interface IAccount extends \JsonSerializable { - /** * Set a property with data * * @since 15.0.0 * - * @param string $property Must be one of the PROPERTY_ prefixed constants of \OCP\Accounts\IAccountManager + * @param string $property Must be one of the PROPERTY_ prefixed constants of \OCP\Accounts\IAccountManager * @param string $value * @param string $scope Must be one of the VISIBILITY_ prefixed constants of \OCP\Accounts\IAccountManager * @param string $verified \OCP\Accounts\IAccountManager::NOT_VERIFIED | \OCP\Accounts\IAccountManager::VERIFICATION_IN_PROGRESS | \OCP\Accounts\IAccountManager::VERIFIED + * @param string $verificationData Optional, defaults to empty string. Since @22.0.0. * @return IAccount */ - public function setProperty(string $property, string $value, string $scope, string $verified): IAccount; + public function setProperty(string $property, string $value, string $scope, string $verified, string $verificationData = ''): IAccount; /** * Get a property by its key @@ -60,24 +43,100 @@ interface IAccount extends \JsonSerializable { public function getProperty(string $property): IAccountProperty; /** - * Get all properties of an account + * Get all properties of an account. Array indices are property names. + * Values from IAccountPropertyCollections are not included in the return + * array. * * @since 15.0.0 - * - * @return IAccountProperty[] + * @deprecated 22.0.0 use getAllProperties() */ public function getProperties(): array; /** + * Set all properties of an account + * + * @param array<string, array<string, string>>|array<string, array<int, array<string, string>>> $properties + * + * e.g. `[ + * 'displayname' => [ + * 'name' => 'displayname', + * 'value' => 'Jonathan Smith', + * 'scope' => 'v2-federated', + * 'verified' => '0', + * 'verificationData' => '', + * ], + * 'email' => [ + * 'name' => 'email', + * 'value' => 'jonathan@example.org', + * 'scope' => 'v2-federated', + * 'verified' => '0', + * 'verificationData' => '', + * ], + * // ... + * 'additional_mail' => [ + * [ + * 'name' => 'additional_mail', + * 'value' => 'jon@example.org', + * 'scope' => 'v2-local', + * 'verified' => '0', + * 'verificationData' => '', + * ], + * [ + * 'name' => 'additional_mail', + * 'value' => 'jon@earth.org', + * 'scope' => 'v2-local', + * 'verified' => '0', + * 'verificationData' => '', + * ], + * ], + * ]` + * + * @since 24.0.0 + */ + public function setAllPropertiesFromJson(array $properties): IAccount; + + /** + * Get all properties of an account. Array indices are numeric. To get + * the property name, call getName() against the value. + * + * IAccountPropertyCollections are being flattened into an IAccountProperty + * for each value. + * + * @since 22.0.0 + * + * @return Generator<int, IAccountProperty> + */ + public function getAllProperties(): Generator; + + /** + * Set a property collection (multi-value properties) + * + * @since 22.0.0 + */ + public function setPropertyCollection(IAccountPropertyCollection $propertyCollection): IAccount; + + /** + * Returns the requested property collection (multi-value properties) + * + * @throws PropertyDoesNotExistException against invalid collection name + * @since 22.0.0 + */ + public function getPropertyCollection(string $propertyCollectionName): IAccountPropertyCollection; + + /** * Get all properties that match the provided filters for scope and verification status * + * Since 22.0.0 values from IAccountPropertyCollection are included, but also + * as IAccountProperty instances. They for properties of IAccountPropertyCollection are + * suffixed incrementally, i.e. #0, #1 ... #n – the numbers have no further meaning. + * * @since 15.0.0 * * @param string $scope Must be one of the VISIBILITY_ prefixed constants of \OCP\Accounts\IAccountManager * @param string $verified \OCP\Accounts\IAccountManager::NOT_VERIFIED | \OCP\Accounts\IAccountManager::VERIFICATION_IN_PROGRESS | \OCP\Accounts\IAccountManager::VERIFIED * @return IAccountProperty[] */ - public function getFilteredProperties(string $scope = null, string $verified = null): array; + public function getFilteredProperties(?string $scope = null, ?string $verified = null): array; /** * Get the related user for the account data diff --git a/lib/public/Accounts/IAccountManager.php b/lib/public/Accounts/IAccountManager.php index ae70d8963b4..ae5535ef13b 100644 --- a/lib/public/Accounts/IAccountManager.php +++ b/lib/public/Accounts/IAccountManager.php @@ -3,27 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2018 Julius Härtl <jus@bitgrid.net> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Joas Schilling <coding@schilljs.com> - * @author Julius Härtl <jus@bitgrid.net> - * - * @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: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Accounts; @@ -37,24 +18,177 @@ use OCP\IUser; * */ interface IAccountManager { + /** + * Contact details visible locally only + * + * @since 21.0.1 + */ + public const SCOPE_PRIVATE = 'v2-private'; - /** nobody can see my account details */ - public const VISIBILITY_PRIVATE = 'private'; - /** only contacts, especially trusted servers can see my contact details */ - public const VISIBILITY_CONTACTS_ONLY = 'contacts'; - /** every body ca see my contact detail, will be published to the lookup server */ - public const VISIBILITY_PUBLIC = 'public'; + /** + * Contact details visible locally and through public link access on local instance + * + * @since 21.0.1 + */ + public const SCOPE_LOCAL = 'v2-local'; + /** + * Contact details visible locally, through public link access and on trusted federated servers. + * + * @since 21.0.1 + */ + public const SCOPE_FEDERATED = 'v2-federated'; + + /** + * Contact details visible locally, through public link access, on trusted federated servers + * and published to the public lookup server. + * + * @since 21.0.1 + */ + public const SCOPE_PUBLISHED = 'v2-published'; + + /** + * The list of allowed scopes + * + * @since 25.0.0 + */ + public const ALLOWED_SCOPES = [ + self::SCOPE_PRIVATE, + self::SCOPE_LOCAL, + self::SCOPE_FEDERATED, + self::SCOPE_PUBLISHED, + ]; + + /** + * @since 15.0.0 + */ public const PROPERTY_AVATAR = 'avatar'; + + /** + * @since 15.0.0 + */ public const PROPERTY_DISPLAYNAME = 'displayname'; + + /** + * @since 27.0.0 + * @deprecated 27.0.0 only added for backwards compatibility with provisioning_api UsersController::getCurrentUser + */ + public const PROPERTY_DISPLAYNAME_LEGACY = 'display-name'; + + /** + * @since 15.0.0 + */ public const PROPERTY_PHONE = 'phone'; + + /** + * @since 15.0.0 + */ public const PROPERTY_EMAIL = 'email'; + + /** + * @since 15.0.0 + */ public const PROPERTY_WEBSITE = 'website'; + + /** + * @since 15.0.0 + */ public const PROPERTY_ADDRESS = 'address'; + + /** + * @since 15.0.0 + * @deprecated 32.0.0 + */ public const PROPERTY_TWITTER = 'twitter'; + /** + * @since 32.0.0 + */ + public const PROPERTY_BLUESKY = 'bluesky'; + + /** + * @since 26.0.0 + */ + public const PROPERTY_FEDIVERSE = 'fediverse'; + + /** + * @since 23.0.0 + */ + public const PROPERTY_ORGANISATION = 'organisation'; + + /** + * @since 23.0.0 + */ + public const PROPERTY_ROLE = 'role'; + + /** + * @since 23.0.0 + */ + public const PROPERTY_HEADLINE = 'headline'; + + /** + * @since 23.0.0 + */ + public const PROPERTY_BIOGRAPHY = 'biography'; + + /** + * @since 23.0.0 + */ + public const PROPERTY_PROFILE_ENABLED = 'profile_enabled'; + + /** + * @since 30.0.0 + */ + public const PROPERTY_BIRTHDATE = 'birthdate'; + + /** + * @since 31.0.0 + */ + public const PROPERTY_PRONOUNS = 'pronouns'; + + /** + * The list of allowed properties + * + * @since 25.0.0 + */ + public const ALLOWED_PROPERTIES = [ + self::PROPERTY_ADDRESS, + self::PROPERTY_AVATAR, + self::PROPERTY_BIOGRAPHY, + self::PROPERTY_BIRTHDATE, + self::PROPERTY_DISPLAYNAME, + self::PROPERTY_EMAIL, + self::PROPERTY_FEDIVERSE, + self::PROPERTY_HEADLINE, + self::PROPERTY_ORGANISATION, + self::PROPERTY_PHONE, + self::PROPERTY_PROFILE_ENABLED, + self::PROPERTY_PRONOUNS, + self::PROPERTY_ROLE, + self::PROPERTY_TWITTER, + self::PROPERTY_BLUESKY, + self::PROPERTY_WEBSITE, + ]; + + + /** + * @since 22.0.0 + */ + public const COLLECTION_EMAIL = 'additional_mail'; + + /** + * @since 15.0.0 + */ public const NOT_VERIFIED = '0'; + + /** + * @since 15.0.0 + */ public const VERIFICATION_IN_PROGRESS = '1'; + + /** + * @since 15.0.0 + */ public const VERIFIED = '2'; /** @@ -68,9 +202,22 @@ interface IAccountManager { public function getAccount(IUser $user): IAccount; /** + * Update the account data with for the user + * + * @since 21.0.1 + * + * @param IAccount $account + * @throws \InvalidArgumentException Message is the property that was invalid + */ + public function updateAccount(IAccount $account): void; + + /** * Search for users based on account data * - * @param string $property + * @param string $property - property or property collection name – since + * NC 22 the implementation MAY add a fitting property collection into the + * search even if a property name was given e.g. email property and email + * collection) * @param string[] $values * @return array * diff --git a/lib/public/Accounts/IAccountProperty.php b/lib/public/Accounts/IAccountProperty.php index 657121a27e8..c9d05bfb6ca 100644 --- a/lib/public/Accounts/IAccountProperty.php +++ b/lib/public/Accounts/IAccountProperty.php @@ -3,36 +3,19 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2018 Julius Härtl <jus@bitgrid.net> - * - * @author Julius Härtl <jus@bitgrid.net> - * - * @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: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Accounts; +use InvalidArgumentException; + /** * Interface IAccountProperty * * @since 15.0.0 */ interface IAccountProperty extends \JsonSerializable { - /** * Set the value of a property * @@ -49,7 +32,9 @@ interface IAccountProperty extends \JsonSerializable { * @since 15.0.0 * * @param string $scope + * @psalm-param IAccountManager::SCOPE_* $scope * @return IAccountProperty + * @throws InvalidArgumentException (since 22.0.0) */ public function setScope(string $scope): IAccountProperty; @@ -87,6 +72,7 @@ interface IAccountProperty extends \JsonSerializable { * @since 15.0.0 * * @return string + * @psalm-return IAccountManager::SCOPE_* */ public function getScope(): string; @@ -98,4 +84,38 @@ interface IAccountProperty extends \JsonSerializable { * @return string */ public function getVerified(): string; + + /** + * Sets data for verification purposes. + * + * @since 22.0.0 + */ + public function setVerificationData(string $verificationData): IAccountProperty; + + /** + * Retrieves data for verification purposes. + * + * @since 22.0.0 + */ + public function getVerificationData(): string; + + /** + * Set the instance-based verification status of a property + * + * @since 23.0.0 + * + * @param string $verified must be one of the verification constants of IAccountManager + * @return IAccountProperty + * @throws InvalidArgumentException + */ + public function setLocallyVerified(string $verified): IAccountProperty; + + /** + * Get the instance-based verification status of a property + * + * @since 23.0.0 + * + * @return string + */ + public function getLocallyVerified(): string; } diff --git a/lib/public/Accounts/IAccountPropertyCollection.php b/lib/public/Accounts/IAccountPropertyCollection.php new file mode 100644 index 00000000000..8fde9781d1f --- /dev/null +++ b/lib/public/Accounts/IAccountPropertyCollection.php @@ -0,0 +1,81 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Accounts; + +use InvalidArgumentException; +use JsonSerializable; + +/** + * Interface IAccountPropertyCollection + * + * @package OCP\Accounts + * + * @since 22.0.0 + */ +interface IAccountPropertyCollection extends JsonSerializable { + /** + * returns the collection name + * + * @since 22.0.0 + */ + public function getName(): string; + + /** + * set properties of this collection + * + * @param IAccountProperty[] $properties + * @throws InvalidArgumentException + * @since 22.0.0 + */ + public function setProperties(array $properties): IAccountPropertyCollection; + + /** + * @return IAccountProperty[] + * @since 22.0.0 + */ + public function getProperties(): array; + + /** + * adds a property to this collection + * + * @throws InvalidArgumentException + * @since 22.0.0 + */ + public function addProperty(IAccountProperty $property): IAccountPropertyCollection; + + /** + * adds a property to this collection with only specifying the value + * + * @throws InvalidArgumentException + * @since 22.0.0 + */ + public function addPropertyWithDefaults(string $value): IAccountPropertyCollection; + + /** + * removes a property of this collection + * + * @since 22.0.0 + */ + public function removeProperty(IAccountProperty $property): IAccountPropertyCollection; + + /** + * removes a property identified by its value + * + * @since 22.0.0 + */ + public function removePropertyByValue(string $value): IAccountPropertyCollection; + + /** + * retrieves a property identified by its value. null, if none was found. + * + * Returns only the first property if there are more with the same value. + * + * @since 23.0.0 + */ + public function getPropertyByValue(string $value): ?IAccountProperty; +} diff --git a/lib/public/Accounts/PropertyDoesNotExistException.php b/lib/public/Accounts/PropertyDoesNotExistException.php index c38487ea928..1d27ef1df30 100644 --- a/lib/public/Accounts/PropertyDoesNotExistException.php +++ b/lib/public/Accounts/PropertyDoesNotExistException.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2018 Julius Härtl <jus@bitgrid.net> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Julius Härtl <jus@bitgrid.net> - * - * @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: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Accounts; /** @@ -31,7 +13,6 @@ namespace OCP\Accounts; * */ class PropertyDoesNotExistException extends \Exception { - /** * Constructor * @param string $msg the error message diff --git a/lib/public/Accounts/UserUpdatedEvent.php b/lib/public/Accounts/UserUpdatedEvent.php new file mode 100644 index 00000000000..fe9ea62a302 --- /dev/null +++ b/lib/public/Accounts/UserUpdatedEvent.php @@ -0,0 +1,43 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Accounts; + +use OCP\EventDispatcher\Event; +use OCP\IUser; + +/** + * This event is triggered when the account data of a user was updated. + * + * @since 28.0.0 + */ +class UserUpdatedEvent extends Event { + /** + * @since 28.0.0 + */ + public function __construct( + protected IUser $user, + protected array $data, + ) { + parent::__construct(); + } + + /** + * @since 28.0.0 + */ + public function getUser(): IUser { + return $this->user; + } + + /** + * @since 28.0.0 + */ + public function getData(): array { + return $this->data; + } +} |