diff options
Diffstat (limited to 'lib/public/App/IAppManager.php')
| -rw-r--r-- | lib/public/App/IAppManager.php | 226 |
1 files changed, 189 insertions, 37 deletions
diff --git a/lib/public/App/IAppManager.php b/lib/public/App/IAppManager.php index 7473b229427..20019ce1ffd 100644 --- a/lib/public/App/IAppManager.php +++ b/lib/public/App/IAppManager.php @@ -1,32 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Daniel Rudolf <github.com@daniel-rudolf.de> - * @author Greta Doci <gretadoci@gmail.com> - * @author Joas Schilling <coding@schilljs.com> - * @author Julius Haertl <jus@bitgrid.net> - * @author Julius Härtl <jus@bitgrid.net> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @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\App; @@ -36,20 +13,35 @@ use OCP\IUser; /** * Interface IAppManager * + * @warning This interface shouldn't be included with dependency injection in + * classes used for installing Nextcloud. + * * @since 8.0.0 */ interface IAppManager { + /** + * @since 30.0.0 + */ + public const BACKEND_CALDAV = 'caldav'; /** - * Returns the app information from "appinfo/info.xml". + * Returns the app information from "appinfo/info.xml" for an app * - * @param string $appId - * @return mixed + * @param string|null $lang + * @return array|null * @since 14.0.0 + * @since 31.0.0 Usage of $path is discontinued and throws an \InvalidArgumentException, use {@see self::getAppInfoByPath} instead. */ public function getAppInfo(string $appId, bool $path = false, $lang = null); /** + * Returns the app information from a given path ending with "/appinfo/info.xml" + * + * @since 31.0.0 + */ + public function getAppInfoByPath(string $path, ?string $lang = null): ?array; + + /** * Returns the app information from "appinfo/info.xml". * * @param string $appId @@ -60,10 +52,28 @@ interface IAppManager { public function getAppVersion(string $appId, bool $useCache = true): string; /** + * Returns the installed version of all apps + * + * @return array<string, string> + * @since 32.0.0 + */ + public function getAppInstalledVersions(bool $onlyEnabled = false): array; + + /** + * Returns the app icon or null if none is found + * + * @param string $appId + * @param bool $dark Enable to request a dark icon variant, default is a white icon + * @return string|null + * @since 29.0.0 + */ + public function getAppIcon(string $appId, bool $dark = false): ?string; + + /** * Check if an app is enabled for user * * @param string $appId - * @param \OCP\IUser $user (optional) if not defined, the currently loggedin user will be used + * @param \OCP\IUser|null $user (optional) if not defined, the currently loggedin user will be used * @return bool * @since 8.0.0 */ @@ -77,10 +87,43 @@ interface IAppManager { * @param string $appId * @return bool * @since 8.0.0 + * @deprecated 32.0.0 Use either {@see self::isEnabledForUser} or {@see self::isEnabledForAnyone} */ public function isInstalled($appId); /** + * Check if an app is enabled in the instance, either for everyone or for specific groups + * + * @since 32.0.0 + */ + public function isEnabledForAnyone(string $appId): bool; + + /** + * Check if an app should be enabled by default + * + * Notice: This actually checks if the app should be enabled by default + * and not if currently installed/enabled + * + * @param string $appId ID of the app + * @since 25.0.0 + */ + public function isDefaultEnabled(string $appId):bool; + + /** + * Load an app, if not already loaded + * @param string $app app id + * @since 27.0.0 + */ + public function loadApp(string $app): void; + + /** + * Check if an app is loaded + * @param string $app app id + * @since 27.0.0 + */ + public function isAppLoaded(string $app): bool; + + /** * Enable an app for every user * * @param string $appId @@ -117,17 +160,15 @@ interface IAppManager { * @param bool $automaticDisabled * @since 8.0.0 */ - public function disableApp($appId, $automaticDisabled = false); + public function disableApp($appId, $automaticDisabled = false): void; /** * Get the directory for the given app. * - * @param string $appId - * @return string * @since 11.0.0 * @throws AppPathNotFoundException */ - public function getAppPath($appId); + public function getAppPath(string $appId): string; /** * Get the web path for the given app. @@ -143,7 +184,7 @@ interface IAppManager { * List all apps enabled for a user * * @param \OCP\IUser $user - * @return string[] + * @return list<string> * @since 8.1.0 */ public function getEnabledAppsForUser(IUser $user); @@ -153,14 +194,23 @@ interface IAppManager { * * @return string[] * @since 8.1.0 + * @deprecated 32.0.0 Use either {@see self::getEnabledApps} or {@see self::getEnabledAppsForUser} */ public function getInstalledApps(); /** + * List all apps enabled, either for everyone or for specific groups only + * + * @return list<string> + * @since 32.0.0 + */ + public function getEnabledApps(): array; + + /** * Clear the cached list of apps when enabling/disabling an app * @since 8.1.0 */ - public function clearAppsCache(); + public function clearAppsCache(): void; /** * @param string $appId @@ -170,12 +220,39 @@ interface IAppManager { public function isShipped($appId); /** + * Loads all apps + * + * @param string[] $types + * @return bool + * + * This function walks through the Nextcloud directory and loads all apps + * it can find. A directory contains an app if the file `/appinfo/info.xml` + * exists. + * + * if $types is set to non-empty array, only apps of those types will be loaded + * @since 27.0.0 + */ + public function loadApps(array $types = []): bool; + + /** + * Check if an app is of a specific type + * @since 27.0.0 + */ + public function isType(string $app, array $types): bool; + + /** * @return string[] * @since 9.0.0 */ public function getAlwaysEnabledApps(); /** + * @return string[] app IDs + * @since 25.0.0 + */ + public function getDefaultEnabledApps(): array; + + /** * @param \OCP\IGroup $group * @return String[] * @since 17.0.0 @@ -188,4 +265,79 @@ interface IAppManager { * @since 17.0.0 */ public function getAppRestriction(string $appId): array; + + /** + * Returns the id of the user's default app + * + * If `user` is not passed, the currently logged in user will be used + * + * @param ?IUser $user User to query default app for + * @param bool $withFallbacks Include fallback values if no default app was configured manually + * Before falling back to predefined default apps, + * the user defined app order is considered and the first app would be used as the fallback. + * + * @since 25.0.6 + * @since 28.0.0 Added optional $withFallbacks parameter + * @deprecated 31.0.0 + * Use @see \OCP\INavigationManager::getDefaultEntryIdForUser() instead + */ + public function getDefaultAppForUser(?IUser $user = null, bool $withFallbacks = true): string; + + /** + * Get the global default apps with fallbacks + * + * @return string[] The default applications + * @since 28.0.0 + * @deprecated 31.0.0 + * Use @see \OCP\INavigationManager::getDefaultEntryIds() instead + */ + public function getDefaultApps(): array; + + /** + * Set the global default apps with fallbacks + * + * @param string[] $defaultApps + * @throws \InvalidArgumentException If any of the apps is not installed + * @since 28.0.0 + * @deprecated 31.0.0 + * Use @see \OCP\INavigationManager::setDefaultEntryIds() instead + */ + public function setDefaultApps(array $defaultApps): void; + + /** + * Check whether the given backend is required by at least one app. + * + * @param self::BACKEND_* $backend Name of the backend, one of `self::BACKEND_*` + * @return bool True if at least one app requires the backend + * + * @since 30.0.0 + */ + public function isBackendRequired(string $backend): bool; + + /** + * Clean the appId from forbidden characters + * + * @psalm-taint-escape callable + * @psalm-taint-escape cookie + * @psalm-taint-escape file + * @psalm-taint-escape has_quotes + * @psalm-taint-escape header + * @psalm-taint-escape html + * @psalm-taint-escape include + * @psalm-taint-escape ldap + * @psalm-taint-escape shell + * @psalm-taint-escape sql + * @psalm-taint-escape unserialize + * + * @since 31.0.0 + */ + public function cleanAppId(string $app): string; + + /** + * Get a list of all apps in the apps folder + * + * @return list<string> an array of app names (string IDs) + * @since 31.0.0 + */ + public function getAllAppsInAppsFolders(): array; } |