ondrejmirtes · Sep 22, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026
diff --git a/.github/workflows/phar.yml b/.github/workflows/phar.yml
@@ -456,8 +456,34 @@
         if: matrix.target.family == 'zts'
         run: "php -r 'exit((bool) PHP_ZTS ? 0 : 1);'"
 
-      - name: "Compile phpstan_turbo with strict warnings"
+      # The training run of `make pgo` (bin/pgo-train.sh) runs bin/phpstan on
+      # the checkout, so the dependencies must be in place before the build.
+      - uses: "ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda" # v4.0.0
+        if: matrix.target.family == 'macos'
+        with:
+          ignore-cache: true
+
+      - name: "Install Composer dependencies (pinned composer)"
+        if: matrix.target.family != 'macos'
+        # checksum-pinned composer, run under the matrix PHP so platform
+        # requirements are validated against the interpreter the tests below
+        # run on. COMPOSER_HOME is isolated: on the runner (ZTS) legs,
+        # setup-php seeds ~/.composer/auth.json with the workflow's GitHub
+        # token, which this pinned composer rejects at startup ("github oauth
+        # token contains invalid characters") — everything here comes from
+        # packagist dists, no auth needed.
+        run: |
+          curl -fsSLo composer.phar "https://getcomposer.org/download/$COMPOSER_VERSION/composer.phar"
+          echo "$COMPOSER_PHAR_SHA256  composer.phar" | sha256sum -c -
+          COMPOSER_HOME="$(mktemp -d)" php composer.phar install --no-interaction --no-progress
+          rm composer.phar
+
+      - name: "Compile phpstan_turbo with strict warnings (profile-guided)"
         working-directory: "turbo-ext"
+        # `make pgo`: an instrumented build, a training run of PHPStan over
+        # its own sources with that build loaded, then the final build using
+        # the recorded profile — the same three stages `make pgo` runs
+        # locally, so a profile-guided binary can be reproduced outside CI.
         # Exemptions, each caused by third-party macro expansions, not our code:
         # -Wno-assume: zend's parameter-parsing macros expand __builtin_assume
         #   with (potential) side effects
@@ -467,7 +493,7 @@
         #   clang lexes the \N in "PhpParser\NodeVisitor" as a universal
         #   character name (GCC ignores the unknown -Wno- flag)
         run: |
-          make WARN_FLAGS="-Wall -Wextra -Werror -Wno-assume -Wno-unused-parameter -Wno-unicode" -j"$(getconf _NPROCESSORS_ONLN 2>/dev/null || nproc)"
+          make pgo WARN_FLAGS="-Wall -Wextra -Werror -Wno-assume -Wno-unused-parameter -Wno-unicode" -j"$(getconf _NPROCESSORS_ONLN 2>/dev/null || nproc)"
 
       # On arm64 AMFI refuses to map unsigned code, so the binary must carry
       # at least an ad-hoc signature. The linker applies one itself, but
@@ -489,26 +515,6 @@
           echo "built extension reports: $REPORTED, enabler expects: $EXPECTED"
           [ "$REPORTED" = "$EXPECTED" ]
 
-      - uses: "ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda" # v4.0.0
-        if: matrix.target.family == 'macos'
-        with:
-          ignore-cache: true
-
-      - name: "Install Composer dependencies (pinned composer)"
-        if: matrix.target.family != 'macos'
-        # checksum-pinned composer, run under the matrix PHP so platform
-        # requirements are validated against the interpreter the tests below
-        # run on. COMPOSER_HOME is isolated: on the runner (ZTS) legs,
-        # setup-php seeds ~/.composer/auth.json with the workflow's GitHub
-        # token, which this pinned composer rejects at startup ("github oauth
-        # token contains invalid characters") — everything here comes from
-        # packagist dists, no auth needed.
-        run: |
-          curl -fsSLo composer.phar "https://getcomposer.org/download/$COMPOSER_VERSION/composer.phar"
-          echo "$COMPOSER_PHAR_SHA256  composer.phar" | sha256sum -c -
-          COMPOSER_HOME="$(mktemp -d)" php composer.phar install --no-interaction --no-progress
-          rm composer.phar
-
       - name: "Smoke test (differential: native vs PHP implementations)"
         run: php -d extension="$PWD/turbo-ext/phpstan_turbo.so" turbo-ext/tests/smoke.php
 
@@ -609,10 +615,21 @@
       - name: "Trust the checkout despite the container/host uid mismatch"
         run: docker exec alpine-build git config --global --add safe.directory /work
 
-      - name: "Compile phpstan_turbo with strict warnings"
+      # The training run of `make pgo` runs bin/phpstan on the checkout, so
+      # the dependencies must be in place before the build.
+      - name: "Install Composer dependencies (pinned composer)"
+        run: |
+          docker exec -i alpine-build sh -e <<'EOF'
+          curl -fsSLo composer.phar "https://getcomposer.org/download/$COMPOSER_VERSION/composer.phar"
+          echo "$COMPOSER_PHAR_SHA256  composer.phar" | sha256sum -c -
+          COMPOSER_HOME="$(mktemp -d)" php composer.phar install --no-interaction --no-progress
+          rm composer.phar
+          EOF
+
+      - name: "Compile phpstan_turbo with strict warnings (profile-guided)"
         run: |
           docker exec -i -w /work/turbo-ext alpine-build sh -e <<'EOF'
-          make WARN_FLAGS="-Wall -Wextra -Werror -Wno-assume -Wno-unused-parameter -Wno-unicode" -j"$(getconf _NPROCESSORS_ONLN 2>/dev/null || nproc)"
+          make pgo WARN_FLAGS="-Wall -Wextra -Werror -Wno-assume -Wno-unused-parameter -Wno-unicode" -j"$(getconf _NPROCESSORS_ONLN 2>/dev/null || nproc)"
           EOF
 
       - name: "Verify the built extension reports the expected version"
@@ -624,15 +641,6 @@
           [ "$REPORTED" = "$EXPECTED" ]
           EOF
 
-      - name: "Install Composer dependencies (pinned composer)"
-        run: |
-          docker exec -i alpine-build sh -e <<'EOF'
-          curl -fsSLo composer.phar "https://getcomposer.org/download/$COMPOSER_VERSION/composer.phar"
-          echo "$COMPOSER_PHAR_SHA256  composer.phar" | sha256sum -c -
-          COMPOSER_HOME="$(mktemp -d)" php composer.phar install --no-interaction --no-progress
-          rm composer.phar
-          EOF
-
       - name: "Smoke test (differential: native vs PHP implementations)"
         run: docker exec alpine-build php -d extension=/work/turbo-ext/phpstan_turbo.so turbo-ext/tests/smoke.php
 

diff --git a/build/PHPStan/Build/TurboAttributeCollector.php b/build/PHPStan/Build/TurboAttributeCollector.php
@@ -33,6 +33,7 @@
 use PhpParser\Node\VariadicPlaceholder;
 use PhpParser\NodeTraverser;
 use PhpParser\NodeVisitorAbstract;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnum;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionIntersectionType;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionNamedType;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionUnionType;
@@ -162,6 +163,7 @@ final class TurboAttributeCollector
 		'offsetAccessTypeNode' => OffsetAccessTypeNode::class,
 		'conditionalTypeNode' => ConditionalTypeNode::class,
 		'conditionalTypeForParameterNode' => ConditionalTypeForParameterNode::class,
+		'reflectionEnum' => ReflectionEnum::class,
 	];
 
 	private string $realRoot;

diff --git a/src/Analyser/MutatingScope.php b/src/Analyser/MutatingScope.php
@@ -72,6 +72,7 @@
 use PHPStan\Rules\Properties\PropertyReflectionFinder;
 use PHPStan\ShouldNotHappenException;
 use PHPStan\TrinaryLogic;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\Accessory\AccessoryArrayListType;
 use PHPStan\Type\Accessory\HasOffsetValueType;
 use PHPStan\Type\Accessory\NonEmptyArrayType;
@@ -146,6 +147,7 @@
 use const PHP_INT_MAX;
 use const PHP_INT_MIN;
 
+#[ReferencedByTurboExtension(key: 'mutatingScope')]
 class MutatingScope implements Scope, NodeCallbackInvoker, CollectedDataEmitter
 {
 

diff --git a/src/Internal/LruCache.php b/src/Internal/LruCache.php
@@ -3,7 +3,7 @@
 namespace PHPStan\Internal;
 
 use PHPStan\ShouldNotHappenException;
-use PHPStan\Turbo\ReferencedByTurboExtension;
+use PHPStan\Turbo\ShadowedByTurboExtension;
 use function array_key_exists;
 use function array_key_first;
 use function count;
@@ -20,7 +20,7 @@
  *
  * @template TValue
  */
-#[ReferencedByTurboExtension(key: 'lruCache')]
+#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../turbo-ext/src/LruCache.cpp')]
 final class LruCache
 {
 

diff --git a/src/Reflection/ClassReflection.php b/src/Reflection/ClassReflection.php
@@ -38,6 +38,7 @@
 use PHPStan\Reflection\Php\UniversalObjectCratesClassReflectionExtension;
 use PHPStan\Reflection\SignatureMap\SignatureMapProvider;
 use PHPStan\ShouldNotHappenException;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\CircularTypeAliasDefinitionException;
 use PHPStan\Type\Constant\ConstantIntegerType;
 use PHPStan\Type\ErrorType;
@@ -82,6 +83,7 @@
  * @api
  */
 #[GenerateFactory(interface: ClassReflectionFactory::class)]
+#[ReferencedByTurboExtension(key: 'classReflection')]
 final class ClassReflection
 {
 

diff --git a/src/Reflection/Dummy/ChangedTypeMethodReflection.php b/src/Reflection/Dummy/ChangedTypeMethodReflection.php
@@ -10,10 +10,12 @@
 use PHPStan\Reflection\ExtendedParametersAcceptor;
 use PHPStan\ShouldNotHappenException;
 use PHPStan\TrinaryLogic;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\Type;
 use function count;
 use function is_bool;
 
+#[ReferencedByTurboExtension(key: 'changedTypeMethodReflection')]
 final class ChangedTypeMethodReflection implements ExtendedMethodReflection
 {
 

diff --git a/src/Reflection/Dummy/ChangedTypePropertyReflection.php b/src/Reflection/Dummy/ChangedTypePropertyReflection.php
@@ -7,8 +7,10 @@
 use PHPStan\Reflection\ExtendedPropertyReflection;
 use PHPStan\Reflection\WrapperPropertyReflection;
 use PHPStan\TrinaryLogic;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\Type;
 
+#[ReferencedByTurboExtension(key: 'changedTypePropertyReflection')]
 final class ChangedTypePropertyReflection implements WrapperPropertyReflection
 {
 

diff --git a/src/Reflection/ExtendedFunctionVariant.php b/src/Reflection/ExtendedFunctionVariant.php
@@ -2,13 +2,15 @@
 
 namespace PHPStan\Reflection;
 
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\Generic\TemplateTypeMap;
 use PHPStan\Type\Generic\TemplateTypeVarianceMap;
 use PHPStan\Type\Type;
 
 /**
  * @api
  */
+#[ReferencedByTurboExtension(key: 'extendedFunctionVariant')]
 class ExtendedFunctionVariant extends FunctionVariant implements ExtendedParametersAcceptor
 {
 

diff --git a/src/Reflection/Native/NativeParameterReflection.php b/src/Reflection/Native/NativeParameterReflection.php
@@ -4,11 +4,11 @@
 
 use PHPStan\Reflection\ParameterReflection;
 use PHPStan\Reflection\PassedByReference;
-use PHPStan\Turbo\ReferencedByTurboExtension;
+use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeCombinator;
 
-#[ReferencedByTurboExtension(key: 'nativeParameterReflection')]
+#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/NativeParameterReflection.cpp')]
 final class NativeParameterReflection implements ParameterReflection
 {
 

diff --git a/src/Reflection/Php/ExtendedDummyParameter.php b/src/Reflection/Php/ExtendedDummyParameter.php
@@ -8,9 +8,11 @@
 use PHPStan\Reflection\ParameterAllowedConstants;
 use PHPStan\Reflection\PassedByReference;
 use PHPStan\TrinaryLogic;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\MixedType;
 use PHPStan\Type\Type;
 
+#[ReferencedByTurboExtension(key: 'extendedDummyParameter')]
 final class ExtendedDummyParameter extends DummyParameter implements ExtendedParameterReflection
 {
 

diff --git a/src/Reflection/ReflectionProvider/MemoizingReflectionProvider.php b/src/Reflection/ReflectionProvider/MemoizingReflectionProvider.php
@@ -9,8 +9,10 @@
 use PHPStan\Reflection\FunctionReflection;
 use PHPStan\Reflection\NamespaceAnswerer;
 use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use function strtolower;
 
+#[ReferencedByTurboExtension(key: 'memoizingReflectionProvider')]
 final class MemoizingReflectionProvider implements ReflectionProvider
 {
 

diff --git a/src/Reflection/ResolvedMethodReflection.php b/src/Reflection/ResolvedMethodReflection.php
@@ -4,13 +4,15 @@
 
 use PHPStan\PhpDoc\ResolvedPhpDocBlock;
 use PHPStan\TrinaryLogic;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\Generic\TemplateTypeHelper;
 use PHPStan\Type\Generic\TemplateTypeMap;
 use PHPStan\Type\Generic\TemplateTypeVariance;
 use PHPStan\Type\Generic\TemplateTypeVarianceMap;
 use PHPStan\Type\Type;
 use function is_bool;
 
+#[ReferencedByTurboExtension(key: 'resolvedMethodReflection')]
 final class ResolvedMethodReflection implements ExtendedMethodReflection
 {
 

diff --git a/src/Reflection/ResolvedPropertyReflection.php b/src/Reflection/ResolvedPropertyReflection.php
@@ -3,12 +3,14 @@
 namespace PHPStan\Reflection;
 
 use PHPStan\TrinaryLogic;
+use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\Generic\TemplateTypeHelper;
 use PHPStan\Type\Generic\TemplateTypeMap;
 use PHPStan\Type\Generic\TemplateTypeVariance;
 use PHPStan\Type\Generic\TemplateTypeVarianceMap;
 use PHPStan\Type\Type;
 
+#[ReferencedByTurboExtension(key: 'resolvedPropertyReflection')]
 final class ResolvedPropertyReflection implements WrapperPropertyReflection
 {
 

diff --git a/src/Reflection/Type/CallbackUnresolvedMethodPrototypeReflection.php b/src/Reflection/Type/CallbackUnresolvedMethodPrototypeReflection.php
@@ -10,13 +10,13 @@
 use PHPStan\Reflection\ExtendedParametersAcceptor;
 use PHPStan\Reflection\Php\ExtendedDummyParameter;
 use PHPStan\Reflection\ResolvedMethodReflection;
-use PHPStan\Turbo\ReferencedByTurboExtension;
+use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\ThisType;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeCombinator;
 use function array_map;
 
-#[ReferencedByTurboExtension(key: 'callbackUnresolvedMethodPrototypeReflection')]
+#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/CallbackUnresolvedMethodPrototypeReflection.cpp')]
 final class CallbackUnresolvedMethodPrototypeReflection implements UnresolvedMethodPrototypeReflection
 {
 

diff --git a/src/Reflection/Type/CallbackUnresolvedPropertyPrototypeReflection.php b/src/Reflection/Type/CallbackUnresolvedPropertyPrototypeReflection.php
@@ -6,10 +6,10 @@
 use PHPStan\Reflection\Dummy\ChangedTypePropertyReflection;
 use PHPStan\Reflection\ExtendedPropertyReflection;
 use PHPStan\Reflection\ResolvedPropertyReflection;
-use PHPStan\Turbo\ReferencedByTurboExtension;
+use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\Type;
 
-#[ReferencedByTurboExtension(key: 'callbackUnresolvedPropertyPrototypeReflection')]
+#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/CallbackUnresolvedPropertyPrototypeReflection.cpp')]
 final class CallbackUnresolvedPropertyPrototypeReflection implements UnresolvedPropertyPrototypeReflection
 {
 

diff --git a/src/Reflection/Type/CalledOnTypeUnresolvedMethodPrototypeReflection.php b/src/Reflection/Type/CalledOnTypeUnresolvedMethodPrototypeReflection.php
@@ -10,7 +10,7 @@
 use PHPStan\Reflection\ExtendedParametersAcceptor;
 use PHPStan\Reflection\Php\ExtendedDummyParameter;
 use PHPStan\Reflection\ResolvedMethodReflection;
-use PHPStan\Turbo\ReferencedByTurboExtension;
+use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\Generic\GenericStaticType;
 use PHPStan\Type\StaticType;
 use PHPStan\Type\ThisType;
@@ -19,7 +19,7 @@
 use function array_map;
 use function count;
 
-#[ReferencedByTurboExtension(key: 'calledOnTypeUnresolvedMethodPrototypeReflection')]
+#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/CalledOnTypeUnresolvedMethodPrototypeReflection.cpp')]
 final class CalledOnTypeUnresolvedMethodPrototypeReflection implements UnresolvedMethodPrototypeReflection
 {
 

diff --git a/src/Reflection/Type/CalledOnTypeUnresolvedPropertyPrototypeReflection.php b/src/Reflection/Type/CalledOnTypeUnresolvedPropertyPrototypeReflection.php
@@ -6,12 +6,12 @@
 use PHPStan\Reflection\Dummy\ChangedTypePropertyReflection;
 use PHPStan\Reflection\ExtendedPropertyReflection;
 use PHPStan\Reflection\ResolvedPropertyReflection;
-use PHPStan\Turbo\ReferencedByTurboExtension;
+use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\StaticType;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeTraverser;
 
-#[ReferencedByTurboExtension(key: 'calledOnTypeUnresolvedPropertyPrototypeReflection')]
+#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/CalledOnTypeUnresolvedPropertyPrototypeReflection.cpp')]
 final class CalledOnTypeUnresolvedPropertyPrototypeReflection implements UnresolvedPropertyPrototypeReflection
 {
 

diff --git a/src/Rules/PhpDoc/UnresolvableTypeHelper.php b/src/Rules/PhpDoc/UnresolvableTypeHelper.php
@@ -3,6 +3,7 @@
 namespace PHPStan\Rules\PhpDoc;
 
 use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\ErrorType;
 use PHPStan\Type\NeverType;
 use PHPStan\Type\Type;
@@ -11,6 +12,7 @@
 use function array_values;
 
 #[AutowiredService]
+#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/UnresolvableTypeHelper.cpp')]
 final class UnresolvableTypeHelper
 {
 

diff --git a/src/Rules/PhpDoc/UnresolvableTypeResult.php b/src/Rules/PhpDoc/UnresolvableTypeResult.php
@@ -2,6 +2,9 @@
 
 namespace PHPStan\Rules\PhpDoc;
 
+use PHPStan\Turbo\ReferencedByTurboExtension;
+
+#[ReferencedByTurboExtension(key: 'unresolvableTypeResult')]
 final class UnresolvableTypeResult
 {
 

diff --git a/src/Turbo/TurboExtensionEnabler.php b/src/Turbo/TurboExtensionEnabler.php
@@ -33,7 +33,7 @@
 final class TurboExtensionEnabler
 {
 
-	public const EXPECTED_EXTENSION_VERSION = 'cb469d0';
+	public const EXPECTED_EXTENSION_VERSION = '500bbe7';
 
 	private static bool $active = false;
 

diff --git a/turbo-ext/.gitignore b/turbo-ext/.gitignore
@@ -39,3 +39,8 @@
 /src/parser/*.lo
 /src/.libs/
 /src/parser/.libs/
+
+# profile-guided build artifacts (make pgo)
+/pgo/
+/src/*.gcda
+/src/parser/*.gcda