Provide backwards-compatible Psr3 loggers when running under composer.

Author: ChrisLightfootWild

.phan/config.php

@@ -304,6 +304,7 @@
     // This is useful for excluding hopelessly unanalyzable
     // files that can't be removed for whatever reason.
     'exclude_file_list' => [
+        'src/API/Common/Compatibility/Psr3.php',
         'vendor/composer/composer/src/Composer/InstalledVersions.php',
     ],
 

.php-cs-fixer.php

@@ -5,7 +5,8 @@
 $finder = PhpCsFixer\Finder::create()
     ->in('examples/')
     ->in('tests/')
-    ->in('src/');
+    ->in('src/')
+    ->exclude('src/API/Common/Compatibility');
 
 $config = new PhpCsFixer\Config();
 

composer.json

@@ -63,6 +63,7 @@
         },
         "files": [
             "src/Context/fiber/initialize_fiber_handler.php",
+            "src/API/_bootstrap.php",
             "src/API/Trace/functions.php",
             "src/Contrib/Otlp/_register.php",
             "src/Contrib/Grpc/_register.php",

phpstan.neon.dist

@@ -10,6 +10,7 @@ parameters:
         - ./tests
         # - ./examples TODO: Uncomment this once examples are updated
     excludePaths:
+        - src/API/Common/Compatability
         - tests/TraceContext/W3CTestService
         - tests/Unit/Config/SDK/Configuration/ExampleSdk
     ignoreErrors:

psalm.xml.dist

@@ -14,6 +14,7 @@
         <directory name="./examples"/>
         <ignoreFiles>
             <directory name="./examples/traces/demo/"/>
+            <directory name="src/API/Common/Compatibility/"/>
             <directory name="tests/Unit/Config/SDK/Configuration/ExampleSdk"/>
             <directory name="tests/TraceContext/W3CTestService"/>
             <directory name="vendor"/>

src/API/Common/Compatibility/Psr3.php

@@ -0,0 +1,151 @@
+<?php
+
+/**
+ * @see https://github.com/php-fig/log/blob/1.0.0/Psr/Log/AbstractLogger.php
+ * @see https://github.com/php-fig/log/blob/1.0.0/Psr/Log/NullLogger.php
+ */
+
+declare(strict_types=1);
+
+namespace Psr\Log;
+
+/**
+ * This is a simple Logger implementation that other Loggers can inherit from.
+ *
+ * It simply delegates all log-level-specific methods to the `log` method to
+ * reduce boilerplate code that a simple Logger that does the same thing with
+ * messages regardless of the error level has to implement.
+ */
+abstract class AbstractLogger implements LoggerInterface
+{
+    /**
+     * System is unusable.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function emergency($message, array $context = [])
+    {
+        $this->log(LogLevel::EMERGENCY, $message, $context);
+    }
+
+    /**
+     * Action must be taken immediately.
+     *
+     * Example: Entire website down, database unavailable, etc. This should
+     * trigger the SMS alerts and wake you up.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function alert($message, array $context = [])
+    {
+        $this->log(LogLevel::ALERT, $message, $context);
+    }
+
+    /**
+     * Critical conditions.
+     *
+     * Example: Application component unavailable, unexpected exception.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function critical($message, array $context = [])
+    {
+        $this->log(LogLevel::CRITICAL, $message, $context);
+    }
+
+    /**
+     * Runtime errors that do not require immediate action but should typically
+     * be logged and monitored.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function error($message, array $context = [])
+    {
+        $this->log(LogLevel::ERROR, $message, $context);
+    }
+
+    /**
+     * Exceptional occurrences that are not errors.
+     *
+     * Example: Use of deprecated APIs, poor use of an API, undesirable things
+     * that are not necessarily wrong.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function warning($message, array $context = [])
+    {
+        $this->log(LogLevel::WARNING, $message, $context);
+    }
+
+    /**
+     * Normal but significant events.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function notice($message, array $context = [])
+    {
+        $this->log(LogLevel::NOTICE, $message, $context);
+    }
+
+    /**
+     * Interesting events.
+     *
+     * Example: User logs in, SQL logs.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function info($message, array $context = [])
+    {
+        $this->log(LogLevel::INFO, $message, $context);
+    }
+
+    /**
+     * Detailed debug information.
+     *
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function debug($message, array $context = [])
+    {
+        $this->log(LogLevel::DEBUG, $message, $context);
+    }
+}
+
+/**
+ * This Logger can be used to avoid conditional log calls
+ *
+ * Logging should always be optional, and if no logger is provided to your
+ * library creating a NullLogger instance to have something to throw logs at
+ * is a good way to avoid littering your code with `if ($this->logger) { }`
+ * blocks.
+ */
+class NullLogger extends AbstractLogger
+{
+    /**
+     * Logs with an arbitrary level.
+     *
+     * @param mixed $level
+     * @param string $message
+     * @param array $context
+     * @return null
+     */
+    public function log($level, $message, array $context = [])
+    {
+        // noop
+    }
+}

src/API/_bootstrap.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API;
+
+use function class_exists;
+use Composer\InstalledVersions;
+use Composer\Semver\VersionParser;
+
+if (
+    // Provide a backwards-compatible Psr3 implementation when running under composer.
+    class_exists(InstalledVersions::class, false)
+    && InstalledVersions::satisfies(new VersionParser(), 'composer/composer', '~2.0')
+) {
+    require_once __DIR__ . '/Common/Compatibility/Psr3.php';
+}

src/API/composer.json

@@ -30,6 +30,7 @@
             "OpenTelemetry\\API\\": "."
         },
         "files": [
+            "_bootstrap.php",
             "Trace/functions.php"
         ]
     },

src/SDK/Common/Util/ComposerHandler.php

@@ -2,17 +2,4 @@
 
 declare(strict_types=1);
 
-/**
- * If OTEL_PHP_AUTOLOAD_ENABLED=true, there may be compatability issues
- * if the version of PSR-3 installed in ./vendor conflicts with that of the
- * packaged composer PSR-3 library.
- *
- * If COMPOSER_DEV_MODE is present, then we can assume that a composer script
- * is running, and we can prevent the PSR-3 compatability issues by disabling
- * the SDK from activating.
- *
- * @see https://github.com/open-telemetry/opentelemetry-php/issues/1673
- */
-if (\OpenTelemetry\SDK\Common\Util\ComposerHandler::isRunning() === false) {
-    \OpenTelemetry\SDK\SdkAutoloader::autoload();
-}
+\OpenTelemetry\SDK\SdkAutoloader::autoload();