A typed class constant keeps the value it was given

Author: AJenbo

docs/CHANGELOG.md

@@ -122,6 +122,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **A typed class constant keeps the value it was given.** PHP 8.3 lets a class constant declare a type (`private const int DEFAULT_OPTIONS = JSON_HEX_TAG | JSON_THROW_ON_ERROR;`), and PHPantom took that declaration as the whole answer, so everything the initialiser said was thrown away the moment a type was written in front of it. Only the declared type reached the code that reads a constant's value, which is what decides a flag argument, a match subject, and a comparison against a constant. The everyday symptom was a `json_encode($value, self::DEFAULT_OPTIONS)` reported as `string|false` when the mask it is handed sets `JSON_THROW_ON_ERROR`, a failure that throws rather than returns. The initialiser is now read the same way an untyped constant's is, and the declared type is what stands when the value cannot be worked out. A declaration that says more than its initialiser does keeps its own answer, so a constant typed as an enum still resolves to that enum rather than to the case it happens to hold.
 - **An `&&` or `||` guard narrows the operand beside it wherever the check is written.** The right-hand side of `&&` runs only when the left-hand side held, and the right-hand side of `||` only when it did not, so a check on the left says something about the value the right reads. PHPantom only drew that conclusion when the whole check was an `if`, `while`, or `for` condition or a `return` value. Written anywhere else the guard proved nothing, and the operand beside it was read at the type the guard had just ruled out. That covers most of the places these are written: assigned to a variable (`$ok = is_string($v) && strlen($v) > 0;`), passed as an argument, put in an array, used as a ternary's condition, or nested inside a larger check. A guard now narrows the operands that follow it in every position, so the false type errors those forms produced are gone. It stays a statement about the operands: nothing after the check the guard sits in is affected, exactly as before.
 - **An autoloader's closure parameter is a string.** The class name PHP hands an autoloader is the only thing it is ever called with, but the stub for `spl_autoload_register()` promises no more than a `callable`, so `spl_autoload_register(function ($class) { … })` left `$class` with no type at all. Every string builtin applied to it then answered for an argument of any type: `str_replace('App\\', '', $class)` came back as `array|string`, and building the file path out of it was reported as a type error in the one place the value is guaranteed to be a string. The callback is now typed the way PHP calls it. Registering the default autoloader by passing nothing, a function name, or `null` is unaffected.
 - **`ReflectionClass::newInstanceArgs()` returns an instance rather than a maybe-instance.** It builds the same object `newInstance()` does, and throws when it cannot, but the stubs still carry the nullable return type PHP 5 gave it. A method returning `$reflection->newInstanceArgs([$arg])` was therefore reported for returning `Node|null` where it declares `Node`, and the same call written as `newInstance($arg)` was fine. Both now resolve to the instance type, so neither asks for a null check against a null that cannot arrive.

docs/todo.md

@@ -35,7 +35,6 @@ contributor even though it's short.
 | #    | Item                                                                                                                                                      | Impact      | Complexity  |
 | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
 | B51  | [`instanceof` does not eliminate a class from a union in the guarded branch](todo/bugs.md#b51-instanceof-does-not-eliminate-a-class-from-a-union-in-the-guarded-branch) | High        | High        |
-| B57  | [A typed class constant loses its literal value](todo/bugs.md#b57-a-typed-class-constant-loses-its-literal-value)                                           | Medium      | Medium      |
 | B75  | [A builtin's return type is not derived from the arguments actually passed](todo/bugs.md#b75-a-builtins-return-type-is-not-derived-from-the-arguments-actually-passed) (six sub-cases, one PR) | Medium      | Medium-High |
 | B58  | [The array union operator (`+`) does not preserve a previously narrowed key type](todo/bugs.md#b58-the-array-union-operator--does-not-preserve-a-previously-narrowed-key-type) | Medium      | High        |
 | B62  | [PHPUnit's `assertNotNull`/`assertNotFalse` are not recognized as narrowing assertions](todo/bugs.md#b62-phpunits-assertnotnullassertnotfalse-are-not-recognized-as-narrowing-assertions) | Medium      | Medium      |

docs/todo/bugs.md

@@ -27,35 +27,7 @@ No outstanding items.
 
 ## Type comparison
 
-### B57. A typed class constant loses its literal value
-
-**Impact: Medium · Complexity: Medium**
-
-```php
-final class Json
-{
-    private const int DEFAULT_OPTIONS = JSON_HEX_TAG | JSON_THROW_ON_ERROR;
-
-    public static function encode(mixed $value, int $options = 0): string
-    {
-        return json_encode($value, $options | self::DEFAULT_OPTIONS);   // reported: got string|false
-    }
-}
-```
-
-`json_encode()`'s return type narrows to plain `string` (dropping
-`false`) when the resolved `$flags` argument provably has
-`JSON_THROW_ON_ERROR` set — the flag makes a failure throw instead of
-returning `false`. That bitwise fold works when `DEFAULT_OPTIONS` is a
-plain untyped `const`, but PHP 8.3's typed class constants
-(`const int NAME = expr`) resolve to the declared type (`int`) instead
-of the constant-folded literal value of `expr`, so the downstream
-bitwise-OR reasoning never sees `JSON_THROW_ON_ERROR` and falls back to
-the unrefined `string|false`.
-
-**Fix:** when reading a typed class constant's value for constant
-folding, evaluate its initializer expression the same way an untyped
-constant's is evaluated, rather than substituting the declared type.
+No outstanding items.
 
 ## Standard-library return types
 

examples/php/completion.php

@@ -1407,6 +1407,9 @@ class ConditionalReturnDemo
     /** And so is one built out of several. */
     public const JSON_COMBO = JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR;
 
+    /** A declared type says what the constant may hold, not what it holds. */
+    public const int JSON_TYPED = JSON_HEX_TAG | JSON_THROW_ON_ERROR;
+
     public function demo(): void
     {
         $container = new Scaffolding\Container();
@@ -1529,6 +1532,8 @@ public function demo(): void
         $mask = JSON_UNESCAPED_SLASHES | self::JSON_FLAGS;
         $fromMask = json_encode(['ok' => true], $mask);
         strtoupper($fromMask);                    // mask in a variable → string
+        $typed = json_encode(['ok' => true], self::JSON_TYPED);
+        strtoupper($typed);                       // typed constant → string
 
         // More builtins whose shape an argument decides. Only the
         // all-elements form of `pathinfo()` returns the component array;

examples/php/scaffolding/assertions.php

@@ -753,6 +753,8 @@ function runDemoAssertions(): void
     assert(json_encode(['ok' => true], ConditionalReturnDemo::JSON_FLAGS) === '{"ok":true}', 'the flag counts when it is reached through a constant');
     $jsonMask = JSON_UNESCAPED_SLASHES | ConditionalReturnDemo::JSON_FLAGS;
     assert(json_encode(['url' => 'a/b'], $jsonMask) === '{"url":"a/b"}', 'a mask kept in a variable sets the same bits');
+    assert((ConditionalReturnDemo::JSON_TYPED & JSON_THROW_ON_ERROR) !== 0, 'a declared type does not replace the value the constant holds');
+    assert(json_encode(['ok' => true], ConditionalReturnDemo::JSON_TYPED) === '{"ok":true}', 'the flag counts when the constant is typed');
 
     // ── More argument-decided builtins ───────────────────────────────────
     assert(is_array(pathinfo('/tmp/report.csv')), 'the all-elements form returns the component array');

src/type_engine/call_resolution/return_types.rs

@@ -1999,20 +1999,30 @@ pub(super) fn resolve_static_access_type(text: &str, ctx: &ResolutionCtx<'_>) ->
         ctx.resolved_class_cache,
     );
     if let Some(constant) = merged.constants.iter().find(|c| c.name == _member) {
-        // Typed class constant — use its declared type.
-        if let Some(ref hint) = constant.type_hint {
-            return Some(hint.clone());
-        }
-        // Untyped constant — infer the value type from the initializer
-        // so template params bind to the constant's value (e.g. `int`)
-        // rather than the owning class.
+        // Infer the value type from the initializer so template params bind
+        // to the constant's value (e.g. `int`) rather than the owning class.
+        //
+        // A declared type (PHP 8.3's `const int NAME = …`) says what the
+        // constant may hold, not what it does hold, so the initialiser is
+        // still the sharper answer and is read first. It only stands in for
+        // the declaration when it refines it: an initialiser naming an enum
+        // case resolves to the case's class, which the structural check
+        // rejects, leaving the declared type as before.
         if let Some(ref val) = constant.value {
-            if let Some(ty) =
+            let inferred =
                 crate::type_engine::variable::rhs_resolution::infer_type_from_constant_value(val)
-            {
+                    .or_else(|| folded_class_constant_type(&merged, _member, val, ctx));
+            if let Some(ty) = inferred.filter(|ty| {
+                constant
+                    .type_hint
+                    .as_ref()
+                    .is_none_or(|hint| ty.is_subtype_of(hint))
+            }) {
                 return Some(ty);
             }
-            return folded_class_constant_type(&merged, _member, val, ctx);
+        }
+        if let Some(ref hint) = constant.type_hint {
+            return Some(hint.clone());
         }
     }
 

tests/integration/diagnostics_type_errors.rs

@@ -9931,6 +9931,31 @@ class Encoder {
     assert!(messages.is_empty(), "got {messages:?}");
 }
 
+/// A declared type on the constant (PHP 8.3 typed class constants) does not
+/// hide the value behind it: `const int FLAGS = …` still folds to the mask its
+/// initialiser computes.
+#[test]
+fn json_encode_reads_throw_on_error_through_a_typed_constant() {
+    let php = r#"<?php
+function useString(string $value): void {}
+
+class Encoder {
+    private const int DEFAULT_OPTIONS = JSON_HEX_TAG | JSON_THROW_ON_ERROR;
+    private const int ALIAS = self::DEFAULT_OPTIONS;
+
+    public function test(mixed $value, int $options): void {
+        useString(json_encode($value, self::DEFAULT_OPTIONS));
+        useString(json_encode($value, self::ALIAS));
+        useString(json_encode($value, $options | self::DEFAULT_OPTIONS));
+        $mask = JSON_UNESCAPED_SLASHES | self::DEFAULT_OPTIONS;
+        useString(json_encode($value, $mask));
+    }
+}
+"#;
+    let messages = type_error_messages(&collect_with_full_stubs(php));
+    assert!(messages.is_empty(), "got {messages:?}");
+}
+
 /// A constant defined in terms of itself has no value to fold, and folding it
 /// must terminate rather than chase the cycle.
 #[test]