Correct xdebug filename/trace function return types in functionMap to include false/null

[phpstan-bot]

Summary

PHPStan reported Strict comparison using !== between string and false will always evaluate to true for xdebug_get_profiler_filename() !== false. The xdebug function actually returns false when the profiler is not active, so the comparison is meaningful. The root cause was an inaccurate return type in resources/functionMap.php (string instead of string|false).

Changes

• resources/functionMap.php:
  • xdebug_get_profiler_filename: string → string|false (the reported bug).
  • xdebug_get_tracefile_name: string → string|false (documented as false|string).
  • xdebug_stop_trace: void → string|false (documented as false|string).
  • xdebug_start_trace: void → string|null, with parameter signature corrected to ?string $trace_file = null, int $options = 0.
  • Added xdebug_get_gcstats_filename => string|false, xdebug_start_gcstats => string|false, and xdebug_stop_gcstats => string|false (these were missing entirely, which is why xdebug_get_gcstats_filename() !== false was not flagged — it was treated as mixed).
• tests/PHPStan/Analyser/nsrt/bug-14736.php: new regression test asserting the corrected return types.

Root cause

The functionMap entries for the xdebug filename-returning and trace-control functions only described the success return value and omitted the false/null failure value. xdebug returns false (or null for xdebug_start_trace) when the corresponding subsystem (profiler, tracer, gc-stats collector) is not active. With a return type of plain string, any !== false / === false check was evaluated as always-true/always-false. The fix is the family-wide correction across all the filename getters (get_profiler_filename, get_tracefile_name, get_gcstats_filename) and the trace/gcstats start/stop functions, matching the xdebug documentation.

Test

tests/PHPStan/Analyser/nsrt/bug-14736.php asserts string|false for xdebug_get_profiler_filename, xdebug_get_gcstats_filename, xdebug_get_tracefile_name, xdebug_stop_trace, xdebug_start_gcstats, xdebug_stop_gcstats, and string|null for xdebug_start_trace. The test fails before the fix (e.g. string / mixed / null) and passes after.

Fixes phpstan/phpstan#14736