Infer decimal-int-string/non-decimal-int-string for regex capturing groups matching (non-)digits

[phpstan-bot]

Summary

PHPStan's regex array-shape matcher inferred numeric-string for capturing groups that match digit sequences (\d+, [0-9]+, …). Following the recent ctype_digit() work (#5311), these are better described as decimal-int-string, and groups that can only match non-digits as non-decimal-int-string. This PR teaches the regex AST walker to produce both accessory types.

Changes

• src/Type/Regex/RegexGroupParser.php
  • createGroupType() now emits AccessoryDecimalIntegerStringType (instead of AccessoryNumericStringType) for digit-only groups, and AccessoryDecimalIntegerStringType(true) (non-decimal-int-string) for groups guaranteed to contain no digit.
  • The per-token walker tracks a single leading minus sign positionally, so -?[0-9]+ and -[0-9]+ remain decimal integers while a non-leading - (\d+-\d+) or a + ([+-]?\d+) disqualifies the inference.
  • Added negatedClassExcludesAllDigits() to detect negated classes ([^0-9], [^\d]) that exclude every digit; only those become non-decimal-int-string. A new inNegativeClass flag prevents the excluded digit tokens from disturbing the flags.
  • Decimal/non-decimal flags are AND-combined across alternation branches (with the sign flag reset per branch).
• src/Type/Regex/RegexGroupWalkResult.php
  • Replaced isNumeric with isDecimalInteger, added isNonDecimalInteger and a seenDecimalIntegerSign flag.
• Updated preg_match/preg_match_all/preg_replace_callback shape test expectations where digit captures now infer decimal-int-string (preg_match_shapes*.php, preg_match_all_shapes.php, bug-11293, bug-11311, bug-14177).

Root cause

The regex walker only modeled "matches digits" as numeric-string. numeric-string is broader than what a pure-digit regex matches (it also covers floats, exponents, + signs), so it under-described these groups. The walker already only set the numeric flag for pure-digit content, so the refinement to decimal-int-string is a strict improvement on the same code path. The inverse — a regex that can only match non-digit characters — was previously left as a plain (non-empty-)string; it is now non-decimal-int-string.

Test

• New tests/PHPStan/Analyser/nsrt/bug-14750.php covers the reported group cases (-?[0-9]+, [3-9]+, \d+, [3-9], [^0-9]) plus edge cases: \d* (''|decimal-int-string), required leading minus, non-leading minus (\d+-\d+), +-sign rejection, quantified negated digit class, a negated class that doesn't exclude all digits ([^1-4]), and a digit/non-digit alternation. Confirmed failing before the fix and passing after.
• Subject-type narrowing of the matched variable (lines 10/12 of the playground) is not implemented here; it requires full ^...$ anchor detection plus inverse narrowing in the falsey branch and is left as a follow-up.

Fixes phpstan/phpstan#14750

[staabm]

we are missing support for

if (preg_match('/^-?[0-9]+$/', $x)) {
		assertType('decimal-int-string', $x);
	}

[phpstan-bot]

I've addressed the review. Here's a summary of what I did.

What the review asked for

staabm pointed out that subject narrowing was missing:

if (preg_match('/^-?[0-9]+$/', $x)) {
    assertType('decimal-int-string', $x);  // was inferred as non-empty-string
}

This is narrowing of the subject ($x itself), which the original PR explicitly deferred as a follow-up.

Changes (src/Type/Regex/RegexGroupParser.php)

1. Anchored-subject narrowing — in parseGroups(), when the whole-pattern walk reports isDecimalInteger()->yes() and the pattern is anchored at both ends, the subject base type now becomes decimal-int-string (&non-falsy-string when a leading minus is required, or ''|decimal-int-string when zero-or-more digits allow an empty match).

2. New isAnchored() helper (+ isStartAnchor/isEndAnchor) — detects ^/\A at the start and $/\z/\Z at the end, recursing through #expression/#concatenation/#alternation. Crucially, it ignores ^/$ under the m (multiline) modifier, since those become line anchors and the subject could then be a multi-line string.

3. Empty literals made neutral — an empty literal value (anchors like ^/$, \b, \K) previously disqualified the decimal-integer inference; it's now treated as neutral, so the walk sees the digit body through the surrounding anchors. The non-empty guard is unchanged.

Anchoring is required because /[0-9]+/ (unanchored) matches a digit substring of e.g. "abc123", so only fully-anchored patterns may narrow the subject.

Tests

• bug-14750.php — added a pregMatchSubjectNarrowing() covering the reviewer's exact case plus \A...\z, \d* (empty subject), required leading minus, unanchored (no narrowing), start-only anchoring (no narrowing), and multiline mode (no narrowing). Verified these 5 new assertions fail before the source change and pass after.
• preg_match_shapes.php — two pre-existing assertions improved automatically (~^([157])$~ and /^[0-9]$/): the full-match element $matches[0] is the whole anchored subject and now correctly infers decimal-int-string. The latter's // could be numeric-string comment is now realized.

Verification

• make phpstan: no errors.
• Full NodeScopeResolverTest (1631 tests), Regex type/rule tests, and Php type extension tests: all green.

Committed and pushed as f6264fe9f.

I scoped this to the reviewer's request. One adjacent case — a top-level alternation of anchored decimal branches like /^\d+$|^-\d+$/ — is not narrowed, because the alternation AND-combine seeds from Maybe; fixing that would require touching the combine logic that capturing-group inference also relies on, so I left it out rather than risk regressions. The idiomatic /^-?\d+$/ form is fully covered.

[staabm]

we don't need support for \A and \Z. just ^ and $ is enough

[phpstan-bot]

Done. I addressed staabm's review ("we don't need support for \A and \Z. just ^ and $ is enough").

Changes

src/Type/Regex/RegexGroupParser.php

• isStartAnchor() now only recognizes ^ (dropped the \A branch).
• isEndAnchor() now only recognizes $ (dropped the \z/\Z branch).
• Updated the isAnchored() doc comment to say ^/$ instead of ^/\A and $/\z/\Z.
• The multiline-mode guard (^/$ are line anchors under the m modifier) is preserved.

tests/PHPStan/Analyser/nsrt/bug-14750.php

• Removed the \A\d+\z subject-narrowing test case, since those anchors are no longer treated as subject anchors.

Verification

• NodeScopeResolverTest: 1631/1631 pass.
• make phpstan: no errors.

Committed as 6f2549fde and pushed to create-pull-request/patch-0m2x77i.