diff options
Diffstat (limited to 'lib/public/Accounts')
| -rw-r--r-- | lib/public/Accounts/IAccount.php | 149 | ||||
| -rw-r--r-- | lib/public/Accounts/IAccountManager.php | 227 | ||||
| -rw-r--r-- | lib/public/Accounts/IAccountProperty.php | 121 | ||||
| -rw-r--r-- | lib/public/Accounts/IAccountPropertyCollection.php | 81 | ||||
| -rw-r--r-- | lib/public/Accounts/PropertyDoesNotExistException.php | 24 | ||||
| -rw-r--r-- | lib/public/Accounts/UserUpdatedEvent.php | 43 |
6 files changed, 645 insertions, 0 deletions
diff --git a/lib/public/Accounts/IAccount.php b/lib/public/Accounts/IAccount.php new file mode 100644 index 00000000000..f9218f5fdf6 --- /dev/null +++ b/lib/public/Accounts/IAccount.php @@ -0,0 +1,149 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Accounts; + +use Generator; +use OCP\IUser; + +/** + * Interface IAccount + * + * @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 $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, string $verificationData = ''): IAccount; + + /** + * Get a property by its key + * + * @since 15.0.0 + * + * @param string $property Must be one of the PROPERTY_ prefixed constants of \OCP\Accounts\IAccountManager + * @return IAccountProperty + * @throws PropertyDoesNotExistException + */ + public function getProperty(string $property): IAccountProperty; + + /** + * 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 + * @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; + + /** + * Get the related user for the account data + * + * @since 15.0.0 + * + * @return IUser + */ + public function getUser(): IUser; +} diff --git a/lib/public/Accounts/IAccountManager.php b/lib/public/Accounts/IAccountManager.php new file mode 100644 index 00000000000..ae5535ef13b --- /dev/null +++ b/lib/public/Accounts/IAccountManager.php @@ -0,0 +1,227 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Accounts; + +use OCP\IUser; + +/** + * Access user profile information + * + * @since 15.0.0 + * + */ +interface IAccountManager { + /** + * Contact details visible locally only + * + * @since 21.0.1 + */ + public const SCOPE_PRIVATE = 'v2-private'; + + /** + * 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'; + + /** + * Get the account data for a given user + * + * @since 15.0.0 + * + * @param IUser $user + * @return IAccount + */ + 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 - 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 + * + * @since 21.0.0 + */ + public function searchUsers(string $property, array $values): array; +} diff --git a/lib/public/Accounts/IAccountProperty.php b/lib/public/Accounts/IAccountProperty.php new file mode 100644 index 00000000000..c9d05bfb6ca --- /dev/null +++ b/lib/public/Accounts/IAccountProperty.php @@ -0,0 +1,121 @@ +<?php + +declare(strict_types=1); + +/** + * 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 + * + * @since 15.0.0 + * + * @param string $value + * @return IAccountProperty + */ + public function setValue(string $value): IAccountProperty; + + /** + * Set the scope of a property + * + * @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; + + /** + * Set the verification status of a property + * + * @since 15.0.0 + * + * @param string $verified + * @return IAccountProperty + */ + public function setVerified(string $verified): IAccountProperty; + + /** + * Get the name of a property + * + * @since 15.0.0 + * + * @return string + */ + public function getName(): string; + + /** + * Get the value of a property + * + * @since 15.0.0 + * + * @return string + */ + public function getValue(): string; + + /** + * Get the scope of a property + * + * @since 15.0.0 + * + * @return string + * @psalm-return IAccountManager::SCOPE_* + */ + public function getScope(): string; + + /** + * Get the verification status of a property + * + * @since 15.0.0 + * + * @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 new file mode 100644 index 00000000000..1d27ef1df30 --- /dev/null +++ b/lib/public/Accounts/PropertyDoesNotExistException.php @@ -0,0 +1,24 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Accounts; + +/** + * Class PropertyDoesNotExistException + * + * @since 15.0.0 + * + */ +class PropertyDoesNotExistException extends \Exception { + /** + * Constructor + * @param string $msg the error message + * @since 15.0.0 + */ + public function __construct($property) { + parent::__construct('Property ' . $property . ' does not exist.'); + } +} 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; + } +} |