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 <[email protected]>

Author: ChristophWurst

composer.json

@@ -11,6 +11,9 @@
 		}
 	},
 	"autoload": {
+		"files": [
+			"lib/functions.php"
+		],
 		"psr-4": {
 			"": "lib/private/legacy",
 			"OC\\": "lib/private",

lib/composer/composer/autoload_files.php

@@ -0,0 +1,10 @@
+<?php
+
+// autoload_files.php @generated by Composer
+
+$vendorDir = dirname(dirname(__FILE__));
+$baseDir = dirname(dirname($vendorDir));
+
+return array(
+    'a13625b0b50fbf6c65490231df38b04b' => $baseDir . '/lib/functions.php',
+);

lib/composer/composer/autoload_real.php

@@ -50,6 +50,29 @@ public static function getLoader()
 
         $loader->register(true);
 
+        if ($useStaticLoader) {
+            $includeFiles = Composer\Autoload\ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c::$files;
+        } else {
+            $includeFiles = require __DIR__ . '/autoload_files.php';
+        }
+        foreach ($includeFiles as $fileIdentifier => $file) {
+            composerRequire53792487c5a8370acc0b06b1a864ff4c($fileIdentifier, $file);
+        }
+
         return $loader;
     }
 }
+
+/**
+ * @param string $fileIdentifier
+ * @param string $file
+ * @return void
+ */
+function composerRequire53792487c5a8370acc0b06b1a864ff4c($fileIdentifier, $file)
+{
+    if (empty($GLOBALS['__composer_autoload_files'][$fileIdentifier])) {
+        $GLOBALS['__composer_autoload_files'][$fileIdentifier] = true;
+
+        require $file;
+    }
+}

lib/composer/composer/autoload_static.php

@@ -6,6 +6,10 @@
 
 class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
 {
+    public static $files = array (
+        'a13625b0b50fbf6c65490231df38b04b' => __DIR__ . '/../../..' . '/lib/functions.php',
+    );
+
     public static $prefixLengthsPsr4 = array (
         'O' => 
         array (

lib/composer/composer/installed.php

@@ -5,7 +5,7 @@
         'type' => 'library',
         'install_path' => __DIR__ . '/../../../',
         'aliases' => array(),
-        'reference' => '1225189f74d06606aafc4150d07584b90cea50dd',
+        'reference' => 'acdfa9eb7e43337958e4211e33b16932aff8e238',
         'name' => '__root__',
         'dev' => false,
     ),
@@ -16,7 +16,7 @@
             'type' => 'library',
             'install_path' => __DIR__ . '/../../../',
             'aliases' => array(),
-            'reference' => '1225189f74d06606aafc4150d07584b90cea50dd',
+            'reference' => 'acdfa9eb7e43337958e4211e33b16932aff8e238',
             'dev_requirement' => false,
         ),
     ),

lib/public/Log/functions.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2021 Christoph Wurst <[email protected]>
+ *
+ * @author 2021 Christoph Wurst <[email protected]>
+ *
+ * @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\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 22.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();
+	}
+}