Merge pull request #59379 from nextcloud/fix/clean-ldap-ocp-typing

fix: Fix typing in LDAP provider public interfaces

apps/user_ldap/lib/LDAPProvider.php

@@ -8,6 +8,7 @@
 
 namespace OCA\User_LDAP;
 
+use LDAP\Connection;
 use OCA\User_LDAP\User\DeletedUsersIndex;
 use OCP\GroupInterface;
 use OCP\IGroupManager;
@@ -64,7 +65,7 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 	 * @return string with the LDAP DN
 	 * @throws \Exception if translation was unsuccessful
 	 */
-	public function getUserDN($uid) {
+	public function getUserDN(string $uid): string {
 		if (!$this->userBackend->userExists($uid)) {
 			throw new \Exception('User id not found in LDAP');
 		}
@@ -77,11 +78,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Translate a group id to LDAP DN.
-	 * @param string $gid group id
-	 * @return string
 	 * @throws \Exception
 	 */
-	public function getGroupDN($gid) {
+	public function getGroupDN(string $gid): string {
 		if (!$this->groupBackend->groupExists($gid)) {
 			throw new \Exception('Group id not found in LDAP');
 		}
@@ -95,11 +94,10 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 	/**
 	 * Translate a LDAP DN to an internal user name. If there is no mapping between
 	 * the DN and the user name, a new one will be created.
-	 * @param string $dn LDAP DN
-	 * @return string with the internal user name
+	 * @return string the internal user name
 	 * @throws \Exception if translation was unsuccessful
 	 */
-	public function getUserName($dn) {
+	public function getUserName(string $dn): string {
 		$result = $this->userBackend->dn2UserName($dn);
 		if (!$result) {
 			throw new \Exception('Translation to internal user name unsuccessful');
@@ -109,30 +107,24 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Convert a stored DN so it can be used as base parameter for LDAP queries.
-	 * @param string $dn the DN in question
-	 * @return string
 	 */
-	public function DNasBaseParameter($dn) {
+	public function DNasBaseParameter(string $dn): string {
 		return $this->helper->DNasBaseParameter($dn);
 	}
 
 	/**
 	 * Sanitize a DN received from the LDAP server.
-	 * @param array|string $dn the DN in question
-	 * @return array|string the sanitized DN
 	 */
-	public function sanitizeDN($dn) {
+	public function sanitizeDN(array|string $dn): array|string {
 		return $this->helper->sanitizeDN($dn);
 	}
 
 	/**
 	 * Return a new LDAP connection resource for the specified user.
 	 * The connection must be closed manually.
-	 * @param string $uid user id
-	 * @return \LDAP\Connection The LDAP connection
 	 * @throws \Exception if user id was not found in LDAP
 	 */
-	public function getLDAPConnection($uid) {
+	public function getLDAPConnection(string $uid): Connection {
 		if (!$this->userBackend->userExists($uid)) {
 			throw new \Exception('User id not found in LDAP');
 		}
@@ -142,11 +134,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 	/**
 	 * Return a new LDAP connection resource for the specified user.
 	 * The connection must be closed manually.
-	 * @param string $gid group id
-	 * @return \LDAP\Connection The LDAP connection
 	 * @throws \Exception if group id was not found in LDAP
 	 */
-	public function getGroupLDAPConnection($gid) {
+	public function getGroupLDAPConnection(string $gid): Connection {
 		if (!$this->groupBackend->groupExists($gid)) {
 			throw new \Exception('Group id not found in LDAP');
 		}
@@ -155,11 +145,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Get the LDAP base for users.
-	 * @param string $uid user id
-	 * @return string the base for users
 	 * @throws \Exception if user id was not found in LDAP
 	 */
-	public function getLDAPBaseUsers($uid) {
+	public function getLDAPBaseUsers(string $uid): string {
 		if (!$this->userBackend->userExists($uid)) {
 			throw new \Exception('User id not found in LDAP');
 		}
@@ -185,11 +173,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Get the LDAP base for groups.
-	 * @param string $uid user id
-	 * @return string the base for groups
 	 * @throws \Exception if user id was not found in LDAP
 	 */
-	public function getLDAPBaseGroups($uid) {
+	public function getLDAPBaseGroups(string $uid): string {
 		if (!$this->userBackend->userExists($uid)) {
 			throw new \Exception('User id not found in LDAP');
 		}
@@ -199,10 +185,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Clear the cache if a cache is used, otherwise do nothing.
-	 * @param string $uid user id
 	 * @throws \Exception if user id was not found in LDAP
 	 */
-	public function clearCache($uid) {
+	public function clearCache(string $uid): void {
 		if (!$this->userBackend->userExists($uid)) {
 			throw new \Exception('User id not found in LDAP');
 		}
@@ -212,10 +197,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 	/**
 	 * Clear the cache if a cache is used, otherwise do nothing.
 	 * Acts on the LDAP connection of a group
-	 * @param string $gid group id
 	 * @throws \Exception if user id was not found in LDAP
 	 */
-	public function clearGroupCache($gid) {
+	public function clearGroupCache(string $gid): void {
 		if (!$this->groupBackend->groupExists($gid)) {
 			throw new \Exception('Group id not found in LDAP');
 		}
@@ -224,37 +208,31 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Check whether a LDAP DN exists
-	 * @param string $dn LDAP DN
-	 * @return bool whether the DN exists
 	 */
-	public function dnExists($dn) {
+	public function dnExists(string $dn): bool {
 		$result = $this->userBackend->dn2UserName($dn);
 		return !$result ? false : true;
 	}
 
 	/**
 	 * Flag record for deletion.
-	 * @param string $uid user id
 	 */
-	public function flagRecord($uid) {
+	public function flagRecord(string $uid): void {
 		$this->deletedUsersIndex->markUser($uid);
 	}
 
 	/**
 	 * Unflag record for deletion.
-	 * @param string $uid user id
 	 */
-	public function unflagRecord($uid) {
+	public function unflagRecord(string $uid): void {
 		//do nothing
 	}
 
 	/**
 	 * Get the LDAP attribute name for the user's display name
-	 * @param string $uid user id
-	 * @return string the display name field
 	 * @throws \Exception if user id was not found in LDAP
 	 */
-	public function getLDAPDisplayNameField($uid) {
+	public function getLDAPDisplayNameField(string $uid): string {
 		if (!$this->userBackend->userExists($uid)) {
 			throw new \Exception('User id not found in LDAP');
 		}
@@ -263,11 +241,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Get the LDAP attribute name for the email
-	 * @param string $uid user id
-	 * @return string the email field
 	 * @throws \Exception if user id was not found in LDAP
 	 */
-	public function getLDAPEmailField($uid) {
+	public function getLDAPEmailField(string $uid): string {
 		if (!$this->userBackend->userExists($uid)) {
 			throw new \Exception('User id not found in LDAP');
 		}
@@ -276,11 +252,9 @@ class LDAPProvider implements ILDAPProvider, IDeletionFlagSupport {
 
 	/**
 	 * Get the LDAP type of association between users and groups
-	 * @param string $gid group id
-	 * @return string the configuration, one of: 'memberUid', 'uniqueMember', 'member', 'gidNumber', ''
 	 * @throws \Exception if group id was not found in LDAP
 	 */
-	public function getLDAPGroupMemberAssoc($gid) {
+	public function getLDAPGroupMemberAssoc(string $gid): string {
 		if (!$this->groupBackend->groupExists($gid)) {
 			throw new \Exception('Group id not found in LDAP');
 		}

lib/private/LDAP/NullLDAPProviderFactory.php

@@ -15,7 +15,7 @@ class NullLDAPProviderFactory implements ILDAPProviderFactory {
 	public function __construct(IServerContainer $serverContainer) {
 	}
 
-	public function getLDAPProvider() {
+	public function getLDAPProvider(): never {
 		throw new \Exception('No LDAP provider is available');
 	}
 

lib/public/LDAP/IDeletionFlagSupport.php

@@ -1,28 +1,34 @@
 <?php
 
+declare(strict_types=1);
+
 /**
  * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
+
 namespace OCP\LDAP;
 
+use OCP\AppFramework\Attribute\Consumable;
+
 /**
  * Interface IDeletionFlagSupport
  *
  * @since 11.0.0
  */
+#[Consumable(since: '11.0.0')]
 interface IDeletionFlagSupport {
 	/**
 	 * Flag record for deletion.
 	 * @param string $uid user id
 	 * @since 11.0.0
 	 */
-	public function flagRecord($uid);
+	public function flagRecord(string $uid): void;
 
 	/**
 	 * Unflag record for deletion.
 	 * @param string $uid user id
 	 * @since 11.0.0
 	 */
-	public function unflagRecord($uid);
+	public function unflagRecord(string $uid): void;
 }

lib/public/LDAP/ILDAPProvider.php

@@ -1,32 +1,37 @@
 <?php
 
+declare(strict_types=1);
+
 /**
  * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
+
 namespace OCP\LDAP;
 
+use LDAP\Connection;
+use OCP\AppFramework\Attribute\Consumable;
+
 /**
  * Interface ILDAPProvider
  *
  * @since 11.0.0
  */
+#[Consumable(since: '11.0.0')]
 interface ILDAPProvider {
 	/**
 	 * Translate a user id to LDAP DN.
 	 * @param string $uid user id
-	 * @return string
 	 * @since 11.0.0
 	 */
-	public function getUserDN($uid);
+	public function getUserDN(string $uid): string;
 
 	/**
 	 * Translate a group id to LDAP DN.
 	 * @param string $gid group id
-	 * @return string
 	 * @since 13.0.0
 	 */
-	public function getGroupDN($gid);
+	public function getGroupDN(string $gid): string;
 
 	/**
 	 * Translate a LDAP DN to an internal user name.
@@ -35,7 +40,7 @@ interface ILDAPProvider {
 	 * @throws \Exception if translation was unsuccessful
 	 * @since 11.0.0
 	 */
-	public function getUserName($dn);
+	public function getUserName(string $dn): string;
 
 	/**
 	 * Convert a stored DN so it can be used as base parameter for LDAP queries.
@@ -43,7 +48,7 @@ interface ILDAPProvider {
 	 * @return string
 	 * @since 11.0.0
 	 */
-	public function DNasBaseParameter($dn);
+	public function DNasBaseParameter(string $dn): string;
 
 	/**
 	 * Sanitize a DN received from the LDAP server.
@@ -51,23 +56,21 @@ interface ILDAPProvider {
 	 * @return array|string the sanitized DN
 	 * @since 11.0.0
 	 */
-	public function sanitizeDN($dn);
+	public function sanitizeDN(array|string $dn): array|string;
 
 	/**
 	 * Return a new LDAP connection resource for the specified user.
 	 * @param string $uid user id
-	 * @return \LDAP\Connection|resource
 	 * @since 11.0.0
 	 */
-	public function getLDAPConnection($uid);
+	public function getLDAPConnection(string $uid): Connection;
 
 	/**
 	 * Return a new LDAP connection resource for the specified group.
 	 * @param string $gid group id
-	 * @return \LDAP\Connection|resource
 	 * @since 13.0.0
 	 */
-	public function getGroupLDAPConnection($gid);
+	public function getGroupLDAPConnection(string $gid): Connection;
 
 	/**
 	 * Get the LDAP base for users.
@@ -76,7 +79,7 @@ interface ILDAPProvider {
 	 * @throws \Exception if user id was not found in LDAP
 	 * @since 11.0.0
 	 */
-	public function getLDAPBaseUsers($uid);
+	public function getLDAPBaseUsers(string $uid): string;
 
 	/**
 	 * Get the LDAP base for groups.
@@ -85,7 +88,7 @@ interface ILDAPProvider {
 	 * @throws \Exception if user id was not found in LDAP
 	 * @since 11.0.0
 	 */
-	public function getLDAPBaseGroups($uid);
+	public function getLDAPBaseGroups(string $uid): string;
 
 	/**
 	 * Check whether a LDAP DN exists
@@ -93,21 +96,21 @@ interface ILDAPProvider {
 	 * @return bool whether the DN exists
 	 * @since 11.0.0
 	 */
-	public function dnExists($dn);
+	public function dnExists(string $dn): bool;
 
 	/**
 	 * Clear the cache if a cache is used, otherwise do nothing.
 	 * @param string $uid user id
 	 * @since 11.0.0
 	 */
-	public function clearCache($uid);
+	public function clearCache(string $uid): void;
 
 	/**
 	 * Clear the cache if a cache is used, otherwise do nothing.
 	 * @param string $gid group id
 	 * @since 13.0.0
 	 */
-	public function clearGroupCache($gid);
+	public function clearGroupCache(string $gid): void;
 
 	/**
 	 * Get the LDAP attribute name for the user's display name
@@ -116,7 +119,7 @@ interface ILDAPProvider {
 	 * @throws \Exception if user id was not found in LDAP
 	 * @since 12.0.0
 	 */
-	public function getLDAPDisplayNameField($uid);
+	public function getLDAPDisplayNameField(string $uid): string;
 
 	/**
 	 * Get the LDAP attribute name for the email
@@ -125,7 +128,7 @@ interface ILDAPProvider {
 	 * @throws \Exception if user id was not found in LDAP
 	 * @since 12.0.0
 	 */
-	public function getLDAPEmailField($uid);
+	public function getLDAPEmailField(string $uid): string;
 
 	/**
 	 * Get the LDAP attribute name for the type of association between users and groups
@@ -134,7 +137,7 @@ interface ILDAPProvider {
 	 * @throws \Exception if group id was not found in LDAP
 	 * @since 13.0.0
 	 */
-	public function getLDAPGroupMemberAssoc($gid);
+	public function getLDAPGroupMemberAssoc(string $gid): string;
 
 	/**
 	 * Get an LDAP attribute for a nextcloud user

lib/public/LDAP/ILDAPProviderFactory.php

@@ -1,11 +1,15 @@
 <?php
 
+declare(strict_types=1);
+
 /**
  * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
+
 namespace OCP\LDAP;
 
+use OCP\AppFramework\Attribute\Consumable;
 use OCP\IServerContainer;
 
 /**
@@ -16,11 +20,11 @@ use OCP\IServerContainer;
  *
  * @since 11.0.0
  */
+#[Consumable(since: '11.0.0')]
 interface ILDAPProviderFactory {
 	/**
 	 * Constructor for the LDAP provider factory
 	 *
-	 * @param IServerContainer $serverContainer server container
 	 * @since 11.0.0
 	 */
 	public function __construct(IServerContainer $serverContainer);
@@ -28,15 +32,13 @@ interface ILDAPProviderFactory {
 	/**
 	 * creates and returns an instance of the ILDAPProvider
 	 *
-	 * @return ILDAPProvider
 	 * @since 11.0.0
 	 */
-	public function getLDAPProvider();
+	public function getLDAPProvider(): ILDAPProvider;
 
 	/**
 	 * Check if an ldap provider is available
 	 *
-	 * @return bool
 	 * @since 21.0.0
 	 */
 	public function isAvailable(): bool;