Merge pull request #6327 from phpstan/turbo-trusted-types

Strip run-time type checks from PHPStan's own code with a turbo optimizer pass

Author: ondrejmirtes

.github/workflows/phar.yml

@@ -303,6 +303,9 @@ jobs:
       - name: "Forked-worker exit (exitImmediately() ends a child whose teardown would wedge)"
         run: php -d extension="$RUNNER_TEMP/turbo-ext/modules/phpstan_turbo.so" turbo-ext/tests/exit-immediately.php
 
+      - name: "Trusted types (the optimizer pass drops type checks under the prefix only)"
+        run: php -d extension="$RUNNER_TEMP/turbo-ext/modules/phpstan_turbo.so" -d opcache.enable_cli=1 turbo-ext/tests/trusted-types.php
+
       - name: "Signature parity (reflect native classes against the PHP twins)"
         run: php -d extension="$RUNNER_TEMP/turbo-ext/modules/phpstan_turbo.so" turbo-ext/tests/signature-parity.php
 
@@ -494,6 +497,9 @@ jobs:
       - name: "Forked-worker exit (exitImmediately() ends a child whose teardown would wedge)"
         run: php -d extension="$PWD/turbo-ext/phpstan_turbo.so" turbo-ext/tests/exit-immediately.php
 
+      - name: "Trusted types (the optimizer pass drops type checks under the prefix only)"
+        run: php -d extension="$PWD/turbo-ext/phpstan_turbo.so" -d opcache.enable_cli=1 turbo-ext/tests/trusted-types.php
+
       - name: "Signature parity (reflect native classes against the PHP twins)"
         run: php -d extension="$PWD/turbo-ext/phpstan_turbo.so" turbo-ext/tests/signature-parity.php
 
@@ -607,6 +613,9 @@ jobs:
       - name: "Forked-worker exit (exitImmediately() ends a child whose teardown would wedge)"
         run: docker exec alpine-build php -d extension=/work/turbo-ext/phpstan_turbo.so turbo-ext/tests/exit-immediately.php
 
+      - name: "Trusted types (the optimizer pass drops type checks under the prefix only)"
+        run: docker exec alpine-build php -d extension=/work/turbo-ext/phpstan_turbo.so -d opcache.enable_cli=1 turbo-ext/tests/trusted-types.php
+
       - name: "Signature parity (reflect native classes against the PHP twins)"
         run: docker exec alpine-build php -d extension=/work/turbo-ext/phpstan_turbo.so turbo-ext/tests/signature-parity.php
 
@@ -948,6 +957,10 @@ jobs:
         shell: bash
         run: php -d extension="$TURBO_DLL" turbo-ext/tests/exit-immediately.php
 
+      - name: "Trusted types (the optimizer pass drops type checks under the prefix only)"
+        shell: bash
+        run: php -d extension="$TURBO_DLL" -d opcache.enable_cli=1 turbo-ext/tests/trusted-types.php
+
       - name: "Signature parity (reflect native classes against the PHP twins)"
         shell: bash
         run: php -d extension="$TURBO_DLL" turbo-ext/tests/signature-parity.php

bin/phpstan

@@ -30,6 +30,7 @@ use Symfony\Component\Console\Helper\ProgressBar;
 	require_once __DIR__ . '/../src/Turbo/TurboProcessRestarter.php';
 	TurboProcessRestarter::restartIfSuitable($_SERVER['argv']);
 	TurboExtensionEnabler::enableIfLoaded();
+	TurboExtensionEnabler::trustOwnTypesIfSuitable($_SERVER['argv']);
 
 	$analysisStartTime = microtime(true);
 

build/phpstan.neon

@@ -154,6 +154,11 @@ parameters:
 			identifier: shipmonk.deadMethod
 			message: '#^Unused PHPStan\\Turbo\\TurboProcessRestarter::restartIfSuitable#'
 			reportUnmatched: false
+		-
+			# called from bin/phpstan before the autoloader, outside the analysed paths
+			identifier: shipmonk.deadMethod
+			message: '#^Unused PHPStan\\Turbo\\TurboExtensionEnabler::trustOwnTypesIfSuitable#'
+			reportUnmatched: false
 		-
 			# the turbo extension shadows this seam class; the nullable returns
 			# are the contract of the pair, the PHP twin honestly never hits

src/Turbo/TurboDiagnoseExtension.php

@@ -2,6 +2,7 @@
 
 namespace PHPStan\Turbo;
 
+use Phar;
 use PHPStan\Command\Output;
 use PHPStan\DependencyInjection\AutowiredService;
 use PHPStan\Diagnose\DiagnoseExtension;
@@ -64,9 +65,28 @@ public function print(Output $output): void
 			'<info>Turbo worker binary:</info> %s',
 			$workerBinaryLine,
 		));
+		$output->writeLineFormatted(sprintf(
+			'<info>Turbo trusted types:</info> %s',
+			$this->describeTrustedTypes(),
+		));
 		$output->writeLineFormatted('');
 	}
 
+	private function describeTrustedTypes(): string
+	{
+		if (TurboExtensionEnabler::isTrustingOwnTypes()) {
+			return 'on (PHPStan\'s own argument and return type checks are dropped; --debug keeps them)';
+		}
+		if (!TurboExtensionEnabler::isActive()) {
+			return 'off (extension inactive)';
+		}
+		if (Phar::running(false) === '') {
+			return 'off (not running from a phar)';
+		}
+
+		return 'off (--debug, or OPcache is not active)';
+	}
+
 	private function describeStatus(?string $workerBinary): string
 	{
 		if (!TurboExtensionEnabler::isLoaded()) {

src/Turbo/TurboExtensionEnabler.php

@@ -8,6 +8,7 @@
 use function dirname;
 use function extension_loaded;
 use function file_get_contents;
+use function in_array;
 use function is_file;
 use function json_decode;
 use function phpversion;
@@ -21,12 +22,14 @@ final class TurboExtensionEnabler
 	 * version is the short SHA of the last commit touching turbo-ext/src/,
 	 * enforced by the phar.yml turbo-version job.
 	 */
-	public const EXPECTED_EXTENSION_VERSION = 'dee1d70';
+	public const EXPECTED_EXTENSION_VERSION = 'e598750';
 
 	private static bool $typeCombinatorCacheEnabled = false;
 
 	private static bool $enabled = false;
 
+	private static bool $trustingOwnTypes = false;
+
 	public static function isLoaded(): bool
 	{
 		return extension_loaded('phpstan_turbo');
@@ -159,4 +162,57 @@ public static function enableIfLoaded(): void
 		self::$enabled = true;
 	}
 
+	/**
+	 * Whether the extension drops the engine's argument and return type
+	 * checks from PHPStan's own code in this process, see
+	 * trustOwnTypesIfSuitable().
+	 */
+	public static function isTrustingOwnTypes(): bool
+	{
+		return self::$trustingOwnTypes;
+	}
+
+	/**
+	 * PHPStan's code is verified by PHPStan itself at the strictest level, so
+	 * the engine's run-time checks of its parameter and return types re-check
+	 * what analysis already proved — at about 8% of the analysis CPU: a
+	 * class-typed parameter costs a class lookup and an instanceof on every
+	 * call, a typed return the same on the way out. With the extension active
+	 * and PHPStan running from a phar, its optimizer pass (TrustedTypes.cpp)
+	 * drops those checks from the code compiled out of the phar. Nothing else
+	 * is touched: extensions, bootstrap files and the analysed project keep
+	 * their checks, including on what they receive from PHPStan and return to
+	 * it — a check sits in the callee.
+	 *
+	 * What is lost is the TypeError at the boundary when such code passes a
+	 * wrong value into PHPStan: it surfaces later, deeper. That is why --debug
+	 * keeps the checks — the "run with --debug" advice on internal errors then
+	 * yields the original error. PHPUnit never gets here, so the test suites
+	 * of PHPStan and of extensions always run fully checked.
+	 *
+	 * Must run right after enableIfLoaded(), before the Composer autoloader
+	 * and preload.php are compiled: the pass rewrites scripts as they are
+	 * compiled, so whatever was compiled earlier keeps its checks.
+	 *
+	 * @param list<string> $argv
+	 */
+	public static function trustOwnTypesIfSuitable(array $argv): void
+	{
+		if (!self::$enabled) {
+			return;
+		}
+		if (in_array('--debug', $argv, true)) {
+			return;
+		}
+		if (!class_exists('Phar', false)) {
+			return;
+		}
+		$pharPath = Phar::running(false);
+		if ($pharPath === '') {
+			return;
+		}
+
+		self::$trustingOwnTypes = Runtime::trustTypesUnder('phar://' . $pharPath . '/');
+	}
+
 }

src/Turbo/TurboProcessRestarter.php

@@ -62,6 +62,9 @@ final class TurboProcessRestarter
 
 	private const OPCACHE_MAX_ACCELERATED_FILES_LIMIT = 20000;
 
+	/** PHP's default opcache.optimization_level, pinned so the optimizer (and the extension's pass in it) always runs */
+	private const OPCACHE_OPTIMIZATION_LEVEL = '0x7FFEBFFF';
+
 	/** The php.ini directives resolveOpcacheArgs() reacts to */
 	private const OPCACHE_INI_INPUTS = [
 		'opcache.file_cache_only',
@@ -296,6 +299,10 @@ private static function getOpcacheArgs(): array
 	 * - opcache.save_comments is pinned on: stripping doc comments (a common
 	 *   web tuning) breaks annotation readers in the project code the
 	 *   extensions bootstrap, which worked with OPcache dormant.
+	 * - opcache.optimization_level is pinned to PHP's default: the
+	 *   extension's pass dropping PHPStan's own type checks
+	 *   (TurboExtensionEnabler::trustOwnTypesIfSuitable()) runs inside the
+	 *   optimizer, which a php.ini can switch off entirely.
 	 *
 	 * Two configurations are left alone entirely — no OPcache entries at all,
 	 * so the restarted process runs with what the php.ini says, as before:
@@ -336,6 +343,7 @@ public static function resolveOpcacheArgs(array $ini): array
 			'opcache.max_file_size=0',
 			'opcache.file_cache=',
 			'opcache.save_comments=1',
+			'opcache.optimization_level=' . self::OPCACHE_OPTIMIZATION_LEVEL,
 			'opcache.memory_consumption=' . $memory,
 			'opcache.interned_strings_buffer=' . $internedStrings,
 			'opcache.max_accelerated_files=' . $files,

tests/PHPStan/Turbo/TurboProcessRestarterTest.php

@@ -20,6 +20,7 @@ final class TurboProcessRestarterTest extends PHPStanTestCase
 		'opcache.max_file_size=0',
 		'opcache.file_cache=',
 		'opcache.save_comments=1',
+		'opcache.optimization_level=0x7FFEBFFF',
 		'opcache.memory_consumption=256',
 		'opcache.interned_strings_buffer=64',
 		'opcache.max_accelerated_files=20000',
@@ -101,9 +102,9 @@ public function testResolveOpcacheArgs(array $ini, array $expected): void
 	private static function withSizes(int $memory, int $interned, int $files): array
 	{
 		$args = self::STOCK_ARGS;
-		$args[9] = 'opcache.memory_consumption=' . $memory;
-		$args[10] = 'opcache.interned_strings_buffer=' . $interned;
-		$args[11] = 'opcache.max_accelerated_files=' . $files;
+		$args[10] = 'opcache.memory_consumption=' . $memory;
+		$args[11] = 'opcache.interned_strings_buffer=' . $interned;
+		$args[12] = 'opcache.max_accelerated_files=' . $files;
 
 		return $args;
 	}
@@ -124,13 +125,21 @@ public static function dataResolveOpcacheRestartNeeded(): iterable
 			'opcache.max_file_size' => '0',
 			'opcache.file_cache' => '',
 			'opcache.save_comments' => '1',
+			'opcache.optimization_level' => '0x7FFEBFFF',
 			'opcache.memory_consumption' => '256',
 			'opcache.interned_strings_buffer' => '64',
 			'opcache.max_accelerated_files' => '20000',
 		];
 
 		yield 'already in effect' => [$inEffect, false];
 
+		// the optimizer switched off in php.ini would also switch off the
+		// extension's trusted-types pass, which runs inside it
+		yield 'optimizer disabled' => [
+			['opcache.optimization_level' => '0'] + $inEffect,
+			true,
+		];
+
 		// php.ini spellings the ini parser leaves as-is versus its "1"/"" for booleans
 		yield 'already in effect, php.ini spellings' => [
 			['opcache.enable' => 'On', 'opcache.validate_timestamps' => '', 'opcache.jit' => 'Disable'] + $inEffect,

turbo-ext/README.md

@@ -88,6 +88,20 @@ their threads, so PHP's full teardown can wedge in a fork-unsafe extension's
 module shutdown (ext-grpc without `grpc.enable_fork_support`); a forked child
 that does not exec() must `_exit()` instead.
 
+`Runtime::trustTypesUnder()` is the one entry point that changes how PHPStan's
+own code runs rather than replacing it: it arms an opcache optimizer pass
+(`TrustedTypes.cpp`) that drops the engine's argument and return type checks
+from scripts compiled under the given prefix — the running phar, passed by
+`TurboExtensionEnabler::trustOwnTypesIfSuitable()`. PHPStan's code is verified
+by PHPStan, so those checks re-check what analysis proved, at about 8% of the
+analysis CPU. Nothing outside the prefix is touched, and a check sits in the
+callee, so extensions and bootstrapped code keep checking what PHPStan hands
+them; what goes is the TypeError at the boundary when *they* pass PHPStan a
+wrong value — a `--debug` run keeps the checks for exactly that. Float-coercing
+signatures, typed variadics and typed property writes stay checked
+(`TrustedTypes.cpp` explains each); `tests/trusted-types.php` pins the
+behaviour.
+
 The extension is version-pinned (`TurboExtensionEnabler::EXPECTED_EXTENSION_VERSION`);
 a mismatched extension is ignored. There is no runtime kill switch — the only
 way to run without it is not to load it.

turbo-ext/analysis-stub.php

@@ -23,6 +23,10 @@ public static function enablePharForkGuard(string $pharPath): void
 	{
 	}
 
+	public static function trustTypesUnder(string $prefix): bool
+	{
+	}
+
 	public static function exitImmediately(): never
 	{
 	}

turbo-ext/config.w32

@@ -29,7 +29,7 @@ if (PHP_PHPSTAN_TURBO != "no") {
 	// directory by splitting on backslashes only — with forward slashes the
 	// objects compile flat while the link list expects the subpath
 	EXTENSION("phpstan_turbo",
-		"src\\main.cpp src\\support.cpp src\\ArenaCache.cpp src\\CombinationsHelper.cpp src\\ConditionalExpressionHolder.cpp src\\ExpressionResultStorage.cpp src\\ExpressionTypeHolder.cpp src\\NodeScanner.cpp src\\NodeTraverser.cpp src\\PharForkGuard.cpp src\\PhpFileCleaner.cpp src\\ScopeOps.cpp src\\SymbolFinderInFiles.cpp src\\TrinaryLogic.cpp src\\TypeCombinatorCache.cpp",
+		"src\\main.cpp src\\support.cpp src\\ArenaCache.cpp src\\CombinationsHelper.cpp src\\ConditionalExpressionHolder.cpp src\\ExpressionResultStorage.cpp src\\ExpressionTypeHolder.cpp src\\NodeScanner.cpp src\\NodeTraverser.cpp src\\PharForkGuard.cpp src\\PhpFileCleaner.cpp src\\ScopeOps.cpp src\\SymbolFinderInFiles.cpp src\\TrinaryLogic.cpp src\\TrustedTypes.cpp src\\TypeCombinatorCache.cpp",
 		true,
 		flags);
 	ADD_SOURCES(configure_module_dirname + "/src/parser",