From 450136b7cffc874db7a4a1f69332cabad8f4dc8c Mon Sep 17 00:00:00 2001 From: Christoph Wurst Date: Fri, 16 Apr 2021 09:22:05 +0200 Subject: [PATCH] Add a helper function that makes it easier to log from anywhere Our DI is able to inject a logger implementation to any server and app class if they want one. However, sometimes DI isn't applicable or hard to add. In those cases we typically fell back to the *service locator* pattern where we acquired a logger from the server via a global variable. There were some issues with that * `\OC` is a private class, apps are not supposed to use it * `\OC::$server` is a global variable, a well known anti-pattern * `\OC::$server->get(...)` uses the service locator anti-pattern * `\OC::$server->get(...)` may throw * `\OC::$server->get(LoggerInterface::class)` is not scoped to an app With this patch I'm proposing a new helper function ``\OCP\Log\logger`` that can be used to acquire a logger more easily. This function is meant to be public API and therefore apps may use it and there is an optional parameter to specifiy the app ID. The function hides all the ugly details about the global variable and the potentially thrown exceptions from the user. Therefore it's guaranteed that you always get a logger instance. In the worst case you get a noop, though those occasions should be rare. Signed-off-by: Christoph Wurst --- composer.json | 3 + lib/composer/composer/autoload_files.php | 10 ++++ lib/composer/composer/autoload_real.php | 19 ++++++ lib/composer/composer/autoload_static.php | 4 ++ lib/public/Log/functions.php | 73 +++++++++++++++++++++++ 5 files changed, 109 insertions(+) create mode 100644 lib/composer/composer/autoload_files.php create mode 100644 lib/public/Log/functions.php diff --git a/composer.json b/composer.json index 69ac5821c92..6a8e9e99569 100644 --- a/composer.json +++ b/composer.json @@ -11,6 +11,9 @@ } }, "autoload": { + "files": [ + "lib/public/Log/functions.php" + ], "psr-4": { "": "lib/private/legacy", "OC\\": "lib/private", diff --git a/lib/composer/composer/autoload_files.php b/lib/composer/composer/autoload_files.php new file mode 100644 index 00000000000..16e661d85de --- /dev/null +++ b/lib/composer/composer/autoload_files.php @@ -0,0 +1,10 @@ + $baseDir . '/lib/public/Log/functions.php', +); diff --git a/lib/composer/composer/autoload_real.php b/lib/composer/composer/autoload_real.php index 27e0b34bf5b..6b98041770d 100644 --- a/lib/composer/composer/autoload_real.php +++ b/lib/composer/composer/autoload_real.php @@ -31,6 +31,25 @@ class ComposerAutoloaderInit749170dad3f5e7f9ca158f5a9f04f6a2 $loader->register(true); + $includeFiles = \Composer\Autoload\ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2::$files; + foreach ($includeFiles as $fileIdentifier => $file) { + composerRequire749170dad3f5e7f9ca158f5a9f04f6a2($fileIdentifier, $file); + } + return $loader; } } + +/** + * @param string $fileIdentifier + * @param string $file + * @return void + */ +function composerRequire749170dad3f5e7f9ca158f5a9f04f6a2($fileIdentifier, $file) +{ + if (empty($GLOBALS['__composer_autoload_files'][$fileIdentifier])) { + $GLOBALS['__composer_autoload_files'][$fileIdentifier] = true; + + require $file; + } +} diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php index 294969211ec..33493f064be 100644 --- a/lib/composer/composer/autoload_static.php +++ b/lib/composer/composer/autoload_static.php @@ -6,6 +6,10 @@ namespace Composer\Autoload; class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2 { + public static $files = array ( + '03ae51fe9694f2f597f918142c49ff7a' => __DIR__ . '/../../..' . '/lib/public/Log/functions.php', + ); + public static $prefixLengthsPsr4 = array ( 'O' => array ( diff --git a/lib/public/Log/functions.php b/lib/public/Log/functions.php new file mode 100644 index 00000000000..cc6961d8fba --- /dev/null +++ b/lib/public/Log/functions.php @@ -0,0 +1,73 @@ + + * + * @author 2022 Christoph Wurst + * + * @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 . + */ + +namespace OCP\Log; + +use OC; +use OCP\AppFramework\QueryException; +use Psr\Log\LoggerInterface; +use Psr\Log\NullLogger; +use function class_exists; + +/** + * Get a PSR logger + * + * Whenever possible, inject a logger into your classes instead of relying on + * this helper function. + * + * @warning the returned logger implementation is not guaranteed to be the same + * between two function calls. During early stages of the process you + * might in fact get a noop implementation when Nextcloud isn't ready + * to log. Therefore you MUST NOT cache the result of this function but + * fetch a new logger for every log line you want to write. + * + * @param string|null $appId optional parameter to acquire the app-specific logger + * + * @return LoggerInterface + * @since 24.0.0 + */ +function logger(string $appId = null): LoggerInterface { + if (!class_exists(OC::class) || OC::$server === null) { + // If someone calls this log before Nextcloud is initialized, there is + // no logging available. In that case we return a noop implementation + // TODO: evaluate whether logging to error_log could be an alternative + return new NullLogger(); + } + + if ($appId !== null) { + try { + $appContainer = OC::$server->getRegisteredAppContainer($appId); + return $appContainer->get(LoggerInterface::class); + } catch (QueryException $e) { + // Ignore and return the server logger below + } + } + + try { + return OC::$server->get(LoggerInterface::class); + } catch (QueryException $e) { + return new NullLogger(); + } +}