load an xdebug stub when required, re: vimeo/psalm#2118 (#2133)

* load an xdebug stub when required, re: vimeo/psalm#2118

* correcting case sensitivity of XDebug to Xdebug

* only load the Xdebug stub when needed

config.xsd

@@ -54,6 +54,7 @@
         <xs:attribute name="maxStringLength" type="xs:string" />
         <xs:attribute name="resolveFromConfigFile" type="xs:string" />
         <xs:attribute name="includePhpVersionsInErrorBaseline" type="xs:string" />
+        <xs:attribute name="loadXdebugStub" type="xs:string" />
     </xs:complexType>
 
     <xs:complexType name="ProjectFilesType">

docs/running_psalm/configuration.md

@@ -203,6 +203,16 @@ When `true`, Psalm will attempt to find all unused variables, the equivalent of
 ```
 When `true`, Psalm will attempt to find all unused code (including unused variables), the equivalent of running with `--find-unused-code`. Defaults to `false`.
 
+#### loadXdebugStub
+```xml
+<psalm
+  loadXdebugStub="[bool]"
+>
+```
+If not present, Psalm will only load the Xdebug stub if psalm has unloaded the extension.
+When `true`, Psalm will load the Xdebug extension stub (as the extension is unloaded when Psalm runs).
+Setting to `false` prevents the stub from loading.
+
 ### Running Psalm
 
 #### autoloader

src/Psalm/Config.php

@@ -134,6 +134,13 @@ class Config
      */
     public $throw_exception = false;
 
+    /**
+     * Whether or not to load Xdebug stub
+     *
+     * @var bool|null
+     */
+    public $load_xdebug_stub = null;
+
     /**
      * The directory to store PHP Parser (and other) caches
      *
@@ -683,6 +690,7 @@ class Config
             'ignoreInternalFunctionFalseReturn' => 'ignore_internal_falsable_issues',
             'ignoreInternalFunctionNullReturn' => 'ignore_internal_nullable_issues',
             'includePhpVersionsInErrorBaseline' => 'include_php_versions_in_error_baseline',
+            'loadXdebugStub' => 'load_xdebug_stub',
         ];
 
         foreach ($booleanAttributes as $xmlName => $internalName) {
@@ -1505,6 +1513,16 @@ class Config
             $stub_files[] = $phpstorm_meta_path;
         }
 
+        if ($this->load_xdebug_stub) {
+            $xdebug_stub_path = __DIR__ . '/Internal/Stubs/Xdebug.php';
+
+            if (!file_exists($xdebug_stub_path)) {
+                throw new \UnexpectedValueException('Cannot locate XDebug stub');
+            }
+
+            $stub_files[] = $xdebug_stub_path;
+        }
+
         foreach ($stub_files as $file_path) {
             $file_path = \str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $file_path);
             $codebase->scanner->addFileToShallowScan($file_path);

src/Psalm/Internal/Stubs/Xdebug.php

@@ -0,0 +1,43 @@
+<?php
+
+const XDEBUG_TRACE_APPEND = 1;
+const XDEBUG_TRACE_COMPUTERIZED = 2;
+const XDEBUG_TRACE_HTML = 4;
+const XDEBUG_TRACE_NAKED_FILENAME = 8;
+const XDEBUG_CC_UNUSED = 1;
+const XDEBUG_CC_DEAD_CODE = 2;
+const XDEBUG_CC_BRANCH_CHECK = 4;
+const XDEBUG_STACK_NO_DESC = 1;
+const XDEBUG_FILTER_TRACING = 256;
+const XDEBUG_FILTER_CODE_COVERAGE = 512;
+const XDEBUG_FILTER_NONE = 0;
+const XDEBUG_PATH_WHITELIST = 1;
+const XDEBUG_PATH_BLACKLIST = 2;
+const XDEBUG_NAMESPACE_WHITELIST = 17;
+const XDEBUG_NAMESPACE_BLACKLIST = 18;
+
+function xdebug_code_coverage_started() : bool
+{
+}
+
+/**
+* @return array<string, array<int, int>>
+*/
+function xdebug_get_code_coverage() : array
+{
+}
+
+/**
+* @param array<int, string> $configuration
+*/
+function xdebug_set_filter(int $group, int $list_type, array $configuration) : array
+{
+}
+
+function xdebug_start_code_coverage(int $options) : void
+{
+}
+
+function xdebug_stop_code_coverage(int $cleanup = 1) : void
+{
+}

src/psalm-language-server.php

@@ -194,7 +194,7 @@ $ini_handler = new \Psalm\Internal\Fork\PsalmRestarter('PSALM');
 
 $ini_handler->disableExtension('grpc');
 
-// If XDebug is enabled, restart without it
+// If Xdebug is enabled, restart without it
 $ini_handler->check();
 
 setlocale(LC_CTYPE, 'C');

src/psalm-refactor.php

@@ -138,7 +138,7 @@ $vendor_dir = getVendorDir($current_dir);
 
 $first_autoloader = requireAutoloaders($current_dir, isset($options['r']), $vendor_dir);
 
-// If XDebug is enabled, restart without it
+// If Xdebug is enabled, restart without it
 (new \Composer\XdebugHandler\XdebugHandler('PSALTER'))->check();
 
 $path_to_config = get_path_to_config($options);

src/psalm.php

@@ -313,9 +313,13 @@ if (isset($options['generate-json-map']) && is_string($options['generate-json-ma
     $type_map_location = $options['generate-json-map'];
 }
 
-// If XDebug is enabled, restart without it
+// If Xdebug is enabled, restart without it
 $ini_handler->check();
 
+if (is_null($config->load_xdebug_stub) && '' !== $ini_handler->getSkippedVersion()) {
+    $config->load_xdebug_stub = true;
+}
+
 setlocale(LC_CTYPE, 'C');
 
 if (isset($options['set-baseline'])) {

src/psalter.php

@@ -173,7 +173,7 @@ $vendor_dir = getVendorDir($current_dir);
 
 $first_autoloader = requireAutoloaders($current_dir, isset($options['r']), $vendor_dir);
 
-// If XDebug is enabled, restart without it
+// If Xdebug is enabled, restart without it
 (new \Composer\XdebugHandler\XdebugHandler('PSALTER'))->check();
 
 $paths_to_check = getPathsToCheck(isset($options['f']) ? $options['f'] : null);