Added configuration for WordPress supportability

phpcs.xml.dist

@@ -28,4 +28,7 @@
 
     <exclude-pattern>*/polyfills/Stringable.php</exclude-pattern>
     <exclude-pattern>*/polyfills/WeakMap.php</exclude-pattern>
+
+    <exclude-pattern>*/tests/ElasticApmTests/ComponentTests/WordPress/mock_src/*.php</exclude-pattern>
+    <exclude-pattern>*/tests/ElasticApmTests/ComponentTests/WordPress/expected_process_AST_output/*.php</exclude-pattern>
 </ruleset>

phpstan.neon

@@ -10,6 +10,8 @@ parameters:
     excludePaths:
         - tests/polyfills/Stringable.php
         - tests/polyfills/WeakMap.php
+        - tests/ElasticApmTests/ComponentTests/WordPress/mock_src/*.php
+        - tests/ElasticApmTests/ComponentTests/WordPress/expected_process_AST_output/*.php
 
     ignoreErrors:
         #

src/ElasticApm/Impl/AutoInstrument/AutoInstrumentationBase.php

@@ -55,6 +55,14 @@ public function isEnabled(?string &$reason = null): bool
             return false;
         }
 
+        $isUserlandCodeInstrumentationEnabled = $this->tracer->getConfig()->astProcessEnabled();
+        if ($this->requiresUserlandCodeInstrumentation() && (!$isUserlandCodeInstrumentationEnabled)) {
+            $reason = 'Instrumentation ' . $this->name() . ' needs userland code instrumentation'
+                      . ' but AST-process is the only currently supported mechanism to instrument userland code and it is DISABLED'
+                      . ' (via ' . OptionNames::AST_PROCESS_ENABLED . ' configuration option)';
+            return false;
+        }
+
         $disabledInstrumentationsMatcher = $this->tracer->getConfig()->disableInstrumentations();
         if ($disabledInstrumentationsMatcher === null) {
             return true;
@@ -85,6 +93,14 @@ public function requiresAttachContextToExternalObjects(): bool
         return false;
     }
 
+    /**
+     * @return bool
+     */
+    public function requiresUserlandCodeInstrumentation(): bool
+    {
+        return false;
+    }
+
     /**
      * @return string[]
      */

src/ElasticApm/Impl/AutoInstrument/Autoloader.php

@@ -83,7 +83,25 @@ public static function autoloadCodeForClass(string $fqClassName): void
                 __LINE__,
                 __FUNCTION__
             );
+
+            /**
+             * elastic_apm_* functions are provided by the elastic_apm extension
+             *
+             * @noinspection PhpFullyQualifiedNameUsageInspection, PhpUndefinedFunctionInspection
+             * @phpstan-ignore-next-line
+             */
+            \elastic_apm_before_loading_agent_php_code();
+
             require $classSrcFileAbsolute;
+
+            /**
+             * elastic_apm_* functions are provided by the elastic_apm extension
+             *
+             * @noinspection PhpFullyQualifiedNameUsageInspection, PhpUndefinedFunctionInspection
+             * @phpstan-ignore-next-line
+             */
+            \elastic_apm_after_loading_agent_php_code();
+
             BootstrapStageLogger::logTrace(
                 "After require `$classSrcFileAbsolute' ...",
                 __LINE__,

src/ElasticApm/Impl/AutoInstrument/BuiltinPlugin.php

@@ -32,6 +32,9 @@
  */
 final class BuiltinPlugin extends PluginBase
 {
+    /** @var ?WordPressAutoInstrumentation */
+    private $wordPressAutoInstrumentationIfEnabled;
+
     public function __construct(Tracer $tracer)
     {
         parent::__construct(
@@ -42,10 +45,21 @@ public function __construct(Tracer $tracer)
                 new MySQLiAutoInstrumentation($tracer),
             ]
         );
+
+        $wordPressAutoInstrumentation = new WordPressAutoInstrumentation($tracer);
+        $this->wordPressAutoInstrumentationIfEnabled =
+            $this->checkIfInstrumentationEnabled($wordPressAutoInstrumentation)
+                ? $wordPressAutoInstrumentation
+                : null;
     }
 
     public function getDescription(): string
     {
         return 'BUILT-IN';
     }
+
+    public function getWordPressAutoInstrumentationIfEnabled(): ?WordPressAutoInstrumentation
+    {
+        return $this->wordPressAutoInstrumentationIfEnabled;
+    }
 }

src/ElasticApm/Impl/AutoInstrument/InstrumentationNames.php

@@ -37,4 +37,5 @@ final class InstrumentationNames
     public const CURL = 'curl';
     public const PDO = 'pdo';
     public const MYSQLI = 'mysqli';
+    public const WORDPRESS = 'wordpress';
 }

src/ElasticApm/Impl/AutoInstrument/InterceptionManager.php

@@ -27,6 +27,7 @@
 use Elastic\Apm\Impl\Log\Logger;
 use Elastic\Apm\Impl\Tracer;
 use Elastic\Apm\Impl\Util\ArrayUtil;
+use Elastic\Apm\Impl\Util\ClassNameUtil;
 use Elastic\Apm\Impl\Util\DbgUtil;
 use Throwable;
 
@@ -43,6 +44,9 @@ final class InterceptionManager
     /** @var Logger */
     private $logger;
 
+    /** @var BuiltinPlugin */
+    private $builtinPlugin;
+
     /** @var int|null */
     private $interceptedCallInProgressRegistrationId = null;
 
@@ -64,20 +68,12 @@ public function __construct(Tracer $tracer)
 
     private function loadPlugins(Tracer $tracer): void
     {
+        $this->builtinPlugin = new BuiltinPlugin($tracer);
         $registerCtx = new RegistrationContext();
-        $this->loadPluginsImpl($tracer, $registerCtx);
-
-        $this->interceptedCallRegistrations = $registerCtx->interceptedCallRegistrations;
-    }
-
-    private function loadPluginsImpl(Tracer $tracer, RegistrationContext $registerCtx): void
-    {
-        $builtinPlugin = new BuiltinPlugin($tracer);
         $registerCtx->dbgCurrentPluginIndex = 0;
-        $registerCtx->dbgCurrentPluginDesc = $builtinPlugin->getDescription();
-        $builtinPlugin->register($registerCtx);
-
-        // self::loadConfiguredPlugins();
+        $registerCtx->dbgCurrentPluginDesc = $this->builtinPlugin->getDescription();
+        $this->builtinPlugin->register($registerCtx);
+        $this->interceptedCallRegistrations = $registerCtx->interceptedCallRegistrations;
     }
 
     /**
@@ -101,8 +97,9 @@ public function internalFuncCallPreHook(
                 'interceptedCallArgs' => $this->logger->possiblySecuritySensitive($interceptedCallArgs),
             ]
         );
-        ($loggerProxy = $localLogger->ifTraceLevelEnabled(__LINE__, __FUNCTION__))
-        && $loggerProxy->log('Entered');
+        $loggerProxyTrace = $localLogger->ifTraceLevelEnabledNoLine(__FUNCTION__);
+
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Entered');
 
         $interceptRegistration
             = ArrayUtil::getValueIfKeyExistsElse($interceptRegistrationId, $this->interceptedCallRegistrations, null);
@@ -113,8 +110,7 @@ public function internalFuncCallPreHook(
         }
         $localLogger->addContext('interceptRegistration', $interceptRegistration);
 
-        ($loggerProxy = $localLogger->ifTraceLevelEnabled(__LINE__, __FUNCTION__))
-        && $loggerProxy->log('Calling preHook...');
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Calling preHook...');
         try {
             $preHookRetVal = ($interceptRegistration->preHook)($thisObj, $interceptedCallArgs);
         } catch (Throwable $throwable) {
@@ -133,8 +129,7 @@ public function internalFuncCallPreHook(
             $this->interceptedCallInProgressPreHookRetVal = $preHookRetVal;
         }
 
-        ($loggerProxy = $localLogger->ifTraceLevelEnabled(__LINE__, __FUNCTION__))
-        && $loggerProxy->log('preHook completed successfully', ['shouldCallPostHook' => $shouldCallPostHook]);
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'preHook completed successfully', ['shouldCallPostHook' => $shouldCallPostHook]);
         return $shouldCallPostHook;
     }
 
@@ -149,8 +144,14 @@ public function internalFuncCallPostHook(
         bool $hasExitedByException,
         $returnValueOrThrown
     ): void {
-        ($loggerProxy = $this->logger->ifTraceLevelEnabled(__LINE__, __FUNCTION__))
-        && $loggerProxy->log('Entered');
+        $localLogger = $this->logger->inherit()->addAllContext(
+            [
+                'interceptRegistrationId' => $this->interceptedCallInProgressRegistrationId,
+                'interceptRegistration'   => $this->interceptedCallInProgressRegistration,
+            ]
+        );
+        $loggerProxyTrace = $localLogger->ifTraceLevelEnabledNoLine(__FUNCTION__);
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Entered');
 
         if ($this->interceptedCallInProgressRegistrationId === null) {
             ($loggerProxy = $this->logger->ifErrorLevelEnabled(__LINE__, __FUNCTION__))
@@ -160,28 +161,92 @@ public function internalFuncCallPostHook(
         assert($this->interceptedCallInProgressRegistration !== null);
         assert($this->interceptedCallInProgressPreHookRetVal !== null);
 
-        $localLogger = $this->logger->inherit()->addAllContext(
-            [
-                'interceptRegistrationId' => $this->interceptedCallInProgressRegistrationId,
-                'interceptRegistration'   => $this->interceptedCallInProgressRegistration,
-            ]
-        );
-
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Calling postHook...');
         try {
             ($this->interceptedCallInProgressPreHookRetVal)(
                 $numberOfStackFramesToSkip + 1,
                 $hasExitedByException,
                 $returnValueOrThrown
             );
+            $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'postHook completed without throwing');
         } catch (Throwable $throwable) {
             ($loggerProxy = $localLogger->ifErrorLevelEnabled(__LINE__, __FUNCTION__))
-            && $loggerProxy->logThrowable(
-                $throwable,
-                'postHook has let a Throwable to escape'
-            );
+            && $loggerProxy->logThrowable($throwable, 'postHook has thrown');
         }
 
         $this->interceptedCallInProgressRegistrationId = null;
         $this->interceptedCallInProgressPreHookRetVal = null;
     }
+
+    public function astInstrumentationDirectCall(string $method): void
+    {
+        $localLogger = $this->logger->inherit()->addAllContext(['method' => $method]);
+
+        $loggerProxyTrace = $localLogger->ifTraceLevelEnabledNoLine(__FUNCTION__);
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Entered');
+
+        $wordPressAutoInstrumIfEnabled = $this->builtinPlugin->getWordPressAutoInstrumentationIfEnabled();
+        if ($wordPressAutoInstrumIfEnabled === null) {
+            static $loggedOnce = false;
+            if (!$loggedOnce) {
+                $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'WordPress instrumentation is DISABLED');
+                $loggedOnce = true;
+            }
+            return;
+        }
+
+        static $dbgImplFuncDesc = null;
+        if ($dbgImplFuncDesc === null) {
+            $dbgImplFuncDesc = ClassNameUtil::fqToShort(WordPressAutoInstrumentation::class) . '->directCall';
+        }
+        /** @var string $dbgImplFuncDesc */
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Calling ' . $dbgImplFuncDesc . '...');
+        try {
+            $wordPressAutoInstrumIfEnabled->directCall($method);
+            $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, $dbgImplFuncDesc . ' completed without throwing');
+        } catch (Throwable $throwable) {
+            ($loggerProxy = $localLogger->ifErrorLevelEnabled(__LINE__, __FUNCTION__)) && $loggerProxy->logThrowable($throwable, $dbgImplFuncDesc . ' has thrown');
+        }
+    }
+
+    /**
+     * @param ?string $instrumentedClassFullName
+     * @param string  $instrumentedFunction
+     * @param mixed[] $capturedArgs
+     *
+     * @return null|callable(?Throwable $thrown, mixed $returnValue): void
+     */
+    public function astInstrumentationPreHook(?string $instrumentedClassFullName, string $instrumentedFunction, array $capturedArgs): ?callable
+    {
+        $localLogger = $this->logger->inherit()->addAllContext(['instrumentedClassFullName' => $instrumentedClassFullName]);
+
+        $loggerProxyTrace = $localLogger->ifTraceLevelEnabledNoLine(__FUNCTION__);
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Entered');
+
+        $wordPressAutoInstrumIfEnabled = $this->builtinPlugin->getWordPressAutoInstrumentationIfEnabled();
+        if ($wordPressAutoInstrumIfEnabled === null) {
+            static $loggedOnce = false;
+            if (!$loggedOnce) {
+                $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'WordPress instrumentation is DISABLED');
+                $loggedOnce = true;
+            }
+            return null;
+        }
+
+        static $dbgImplFuncDesc = null;
+        if ($dbgImplFuncDesc === null) {
+            $dbgImplFuncDesc = ClassNameUtil::fqToShort(WordPressAutoInstrumentation::class) . '->preHook';
+        }
+        /** @var string $dbgImplFuncDesc */
+        $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, 'Calling ' . $dbgImplFuncDesc . '...');
+        try {
+            $retVal = $wordPressAutoInstrumIfEnabled->preHook($instrumentedClassFullName, $instrumentedFunction, $capturedArgs);
+            $loggerProxyTrace && $loggerProxyTrace->log(__LINE__, $dbgImplFuncDesc . ' completed without throwing', ['retVal == null' => ($retVal == null)]);
+            return $retVal;
+        } catch (Throwable $throwable) {
+            ($loggerProxy = $localLogger->ifErrorLevelEnabled(__LINE__, __FUNCTION__))
+            && $loggerProxy->logThrowable($throwable, $dbgImplFuncDesc . ' has thrown');
+            return null;
+        }
+    }
 }

src/ElasticApm/Impl/AutoInstrument/PhpPartFacade.php

@@ -515,4 +515,36 @@ private static function buildTracer(): ?Tracer
     public static function emptyMethod(): void
     {
     }
+
+    /**
+     * Calls to this method are inserted by AST instrumentation.
+     * See src/ext/WordPress_instrumentation.c
+     *
+     * @noinspection PhpUnused
+     *
+     * @param ?string $instrumentedClassFullName
+     * @param string  $instrumentedFunction
+     * @param mixed[] $capturedArgs
+     *
+     * @return null|callable(?Throwable $thrown, mixed $returnValue): void
+     */
+    public static function astInstrumentationPreHook(?string $instrumentedClassFullName, string $instrumentedFunction, array $capturedArgs): ?callable
+    {
+        return (($interceptionManager = self::singletonInstance()->interceptionManager) !== null)
+            ? $interceptionManager->astInstrumentationPreHook($instrumentedClassFullName, $instrumentedFunction, $capturedArgs)
+            : null;
+    }
+
+    /**
+     * Calls to this method are inserted by AST instrumentation.
+     * See src/ext/WordPress_instrumentation.c
+     *
+     * @noinspection PhpUnused
+     */
+    public static function astInstrumentationDirectCall(string $method): void
+    {
+        if (($interceptionManager = self::singletonInstance()->interceptionManager) !== null) {
+            $interceptionManager->astInstrumentationDirectCall($method);
+        }
+    }
 }