Implement new user back end API

lib/private/User/Backend.php

@@ -29,6 +29,7 @@
 /**
  * Abstract base class for user management. Provides methods for querying backend
  * capabilities.
+ * @deprecated 21.0.0 use \OCP\Public\User\Backend\AbstractUserBackEnd instead
  */
 abstract class Backend implements UserInterface {
 	/**

lib/public/IUserBackend.php

@@ -36,13 +36,15 @@
  * Interface IUserBackend
  *
  * @since 8.0.0
+ * @deprecated 21.0.0 use \OCP\Public\User\Backend\AbstractUserBackEnd instead
  */
 interface IUserBackend {
 
 	/**
 	 * Backend name to be shown in user management
 	 * @return string the name of the backend to be shown
 	 * @since 8.0.0
+	 * @deprecated 21.0.0 use \OCP\Public\User\Backend\IUserBackEnd instead
 	 */
 	public function getBackendName();
 }

lib/public/User/Backend/ABackend.php

@@ -33,6 +33,7 @@
 
 /**
  * @since 14.0.0
+ * @deprecated 21.0.0 use \OCP\Public\User\Backend\AbstractUserBackEnd instead
  */
 abstract class ABackend implements IUserBackend, UserInterface {
 

lib/public/User/Backend/AbstractUserBackend.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2020, Alexey Abel <dev@abelonline.de>
+ *
+ * @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/>.
+ *
+ */
+
+namespace OCP\User\Backend;
+
+/**
+ * Class AbstractUserBackend should be used as a base for all user back ends, e.g. implemented by apps.
+ * Additionally implement any number of interfaces in OCP\User\Backend\Action.
+ *
+ * @package OCP\User\Backend
+ * @since 21.0.0
+ */
+class AbstractUserBackend {
+
+	/** @var string */
+	private $backEndName;
+
+	public function __construct(string $backEndName) {
+		$this->backEndName = $backEndName;
+	}
+
+	public function getName(): string {
+		return $this->backEndName;
+	}
+}

lib/public/User/Backend/Action/ICheckPassword.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2020, Alexey Abel <dev@abelonline.de>
+ *
+ * @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/>.
+ *
+ */
+
+namespace OCP\User\Backend\Action;
+
+use OCP\User\Backend\Exception\ActionNotAvailableException;
+use OCP\User\Backend\Exception\UserDoesNotExistInBackEndException;
+
+
+/**
+ * @since 21.0.0
+ */
+interface ICheckPassword {
+	/**
+	 * @return bool whether the implementing user back end has the ability to check a password at this time
+	 * or with the current configuration
+	 */
+	public function canCheckPassword() : bool;
+
+	/**
+	 * Returns whether the supplied password is correct for the supplied user.
+	 *
+	 * Before using this method, you must call `can...Currently()` of this interface to ensure that the user
+	 * backend can perform this action at his time or with the current configuration, since this can change
+	 * during runtime. The implementing user back end will throw an ActionNotAvailableException if it doesn't.
+	 *
+	 * @param string $username the username of the checked user
+	 * @param string $password the password of the user to check
+	 * @return bool true if password is correct, false otherwise
+	 * @throws ActionNotAvailableException if this action is not supported at this time
+	 * @throws UserDoesNotExistInBackEndException if specified username doesn't exist in the user back end
+	 */
+	public function checkPassword(string $username, string $password): bool;
+}

lib/public/User/Backend/Action/ICountUsers.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2020, Alexey Abel <dev@abelonline.de>
+ *
+ * @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/>.
+ *
+ */
+
+namespace OCP\User\Backend\Action;
+
+use OCP\User\Backend\Exception\ActionNotAvailableException;
+
+
+/**
+ * @since 21.0.0
+ */
+interface ICountUsers {
+	/**
+	 * @return bool whether the implementing user back end has the ability to count users at this time
+	 * or with the current configuration
+	 */
+	public function canCountUsers() : bool;
+
+	/**
+	 * Returns the number of users present in this user backend.
+	 *
+	 * Before using this method, you must call `can...Currently()` of this interface to ensure that the user
+	 * backend can perform this action at his time or with the current configuration, since this can change
+	 * during runtime. The implementing user back end will throw an ActionNotAvailableException if it doesn't.
+	 *
+	 * @return int the number of users present in this user backend
+	 * @throws ActionNotAvailableException if this action is not supported at this time
+	 */
+	public function countUsers(): int;
+}

lib/public/User/Backend/Action/ICreateUser.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2020, Alexey Abel <dev@abelonline.de>
+ *
+ * @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/>.
+ *
+ */
+
+namespace OCP\User\Backend\Action;
+
+use OCP\User\Backend\Exception\ActionNotAvailableException;
+use OCP\User\Backend\Exception\UserAlreadyExistsException;
+
+
+/**
+ * @since 21.0.0
+ */
+interface ICreateUser {
+	/**
+	 * @return bool whether the implementing user back end has the ability to create a user at this time
+	 * or with the current configuration
+	 */
+	public function canCreateUser(): bool;
+
+	/**
+	 * Creates a new user.
+	 *
+	 * Before using this method, you must call `can...Currently()` of this interface to ensure that the user
+	 * backend can perform this action at his time or with the current configuration, since this can change
+	 * during runtime. The implementing user back end will throw an ActionNotAvailableException if it doesn't.
+	 *
+	 * @param string $username the username of the new user
+	 * @param string $password the password of the new user
+	 * @throws ActionNotAvailableException if this action is not supported at this time
+	 * @throws UserAlreadyExistsException if a user with provided username already exists
+	 */
+	public function createUser(string $username, string $password): void;
+}

lib/public/User/Backend/Action/IDeleteUser.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2020, Alexey Abel <dev@abelonline.de>
+ *
+ * @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/>.
+ *
+ */
+
+namespace OCP\User\Backend\Action;
+
+use OCP\User\Backend\Exception\ActionNotAvailableException;
+use OCP\User\Backend\Exception\UserDoesNotExistInBackEndException;
+
+
+/**
+ * @since 21.0.0
+ */
+interface IDeleteUser {
+	/**
+	 * @return bool whether the implementing user back end has the ability to create a user at this time
+	 * or with the current configuration
+	 */
+	public function canDeleteUser() : bool;
+
+	/**
+	 * Deletes a user.
+	 *
+	 * Before using this method, you must call `can...Currently()` of this interface to ensure that the user
+	 * backend can perform this action at his time or with the current configuration, since this can change
+	 * during runtime. The implementing user back end will throw an ActionNotAvailableException if it doesn't.
+	 *
+	 * @param string $username the username of the user to be deleted
+	 * @throws ActionNotAvailableException if this action is not supported at this time
+	 * @throws UserDoesNotExistInBackEndException if specified username doesn't exist in the user back end
+	 */
+	public function deleteUser(string $username): void;
+}

lib/public/User/Backend/Action/IFindUsersByDisplayName.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2020, Alexey Abel <dev@abelonline.de>
+ *
+ * @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/>.
+ *
+ */
+
+namespace OCP\User\Backend\Action;
+
+use OCP\User\Backend\Exception\ActionNotAvailableException;
+
+
+/**
+ * @since 21.0.0
+ */
+interface IFindUsersByDisplayName {
+	/**
+	 * @return bool whether the implementing user back end has the ability to search users at this time
+	 * or with the current configuration
+	 */
+	public function canFindUsersByDisplayName() : bool;
+
+	/**
+	 * Finds users by display name and returns a list of matched users.
+	 *
+	 * Before using this method, you must call `can...Currently()` of this interface to ensure that the user
+	 * backend can perform this action at his time or with the current configuration, since this can change
+	 * during runtime. The implementing user back end will throw an ActionNotAvailableException if it doesn't.
+	 *
+	 * @param string $pattern the search pattern
+	 * @param int $limit limit the returned users to only this many
+	 * @param int $offset start the returned users at this position, 0-based
+	 * @return iterable list of users that matched the pattern or empty iterable if none matched
+	 * @throws ActionNotAvailableException if this action is not supported at this time
+	 */
+	public function findUsersByDisplayName(string $pattern, ?int $limit, ?int $offset): iterable;
+}