Narrow preg_match/preg_match_all subject string type when match is truthy

[phpstan-bot]

Summary

When preg_match() or preg_match_all() is used as a condition (in if, ternary, &&, etc.) and returns truthy, the subject string parameter was not being narrowed based on the regex pattern. The PregMatchTypeSpecifyingExtension only narrowed the $matches array (arg 2) but never the subject string (arg 1). This fix adds subject narrowing using the regex pattern analysis that already exists in RegexArrayShapeMatcher.

Changes

• Added matchSubjectExpr() method to src/Type/Php/RegexArrayShapeMatcher.php that extracts the subject base type from a regex pattern (non-empty-string or non-falsy-string) using the existing RegexGroupParser infrastructure
• Modified src/Type/Php/PregMatchTypeSpecifyingExtension.php to:
  • Narrow the subject parameter (arg 1) in truthy context using the regex-derived subject type
  • Work even when there's no $matches argument (previously returned empty SpecifiedTypes immediately)
  • Guard against narrowing non-string subjects (e.g. int|string) by checking isString()->yes()
  • Skip subject narrowing when the subject expression shares a root variable with the matches argument to avoid conflicting type specifications (e.g. preg_match($pat, $matches[2], $matches))

Analogous cases probed

• preg_match_all: tested and working (uses the same extension)
• Negated !preg_match: works correctly (falsey branch keeps string, truthy branch narrows)
• Comparison preg_match() === 1: works correctly
• && conditions: works correctly (both subjects narrowed)
• Short ternary ?:: falsey branch correctly stays string
• Non-constant patterns: correctly returns string (no narrowing when pattern can't be analyzed)
• Non-string subjects (int|string): correctly skipped (no narrowing applied)
• Subject sharing variable with matches ($matches[2] as subject, $matches as output): correctly skipped to avoid conflicts

Root cause

PregMatchTypeSpecifyingExtension::specifyTypes() returned empty SpecifiedTypes when no $matches argument was present, and even when $matches was present, it only narrowed the matches array variable — never the subject string. The regex pattern analysis infrastructure (RegexGroupParser → RegexAstWalkResult::getSubjectBaseType()) already computed the subject type but it was only used for $matches[0]'s type, not for narrowing the subject variable itself.

Test

• Added tests/PHPStan/Analyser/nsrt/bug-14710.php with regression tests covering:
  • Ternary with preg_match (the reported issue)
  • if with preg_match (same underlying bug)
  • With and without $matches argument
  • preg_match_all
  • Negated condition
  • === 1 comparison
  • Non-narrowing patterns (e.g. /^$/ that can match empty strings)
  • Non-constant patterns (no narrowing possible)
  • Non-string subjects

Fixes phpstan/phpstan#14710

[staabm]

do we need a simliar fix for other type-specifying extensions?
can this fix be made in MutatingScope/TypeSpecifier/NodeScopeResolver instead, so it works for more expressions?

[phpstan-bot]

Done. Here's my response to the review, with the investigation behind it.

Addressing @staabm's review

do we need a similar fix for other type-specifying extensions?

No new extension is needed — the codebase already applies this exact per-function pattern:

• StrContainingTypeSpecifyingExtension narrows the haystack of str_contains/str_starts_with/strpos/etc. to non-empty-string/non-falsy-string when the call is truthy.
• CtypeDigitFunctionTypeSpecifyingExtension narrows its argument to numeric-string.

Each lives in its own extension because the narrowed type is derived from that function's specific semantics. preg_match/preg_match_all was simply the missing case, and this PR fills it analogously (its narrowed type comes from regex pattern analysis). I checked the other string predicates and there's no remaining gap.

can this fix be made in MutatingScope/TypeSpecifier/NodeScopeResolver instead, so it works for more expressions?

It can't, and shouldn't:

• The narrowing depends on regex pattern analysis (RegexGroupParser → RegexAstWalkResult::getSubjectBaseType()). Deciding "what does a function's truthy return imply about its arguments" is precisely the role of FunctionTypeSpecifyingExtension; the core scope machinery has no concept of it.
• It already works for arbitrary subject expressions (property fetches, array dims, not just variables), because it narrows via typeSpecifier->create($subjectArg->value, …) on the expression node.

What I did change

To genuinely honor the "works for more expressions" intent, I made the subject narrowing smarter for nullable subjects — something preg_match can do that str_contains can't, because it knows the pattern at compile time:

• A null subject is coerced to '' by preg_*, which cannot match a pattern whose derived subject type is non-empty. So ?string now narrows to non-falsy-string in the truthy branch (previously left as string|null). Non-string scalars like int are still left untouched, since an int can be coerced to a matching string — narrowing those away would be unsound.

I also added the regression coverage the PR claimed but was missing:

• subject sharing its root variable with the $matches arg (the conflict-avoidance guard)
• the int|string non-narrowing case

make tests (12539 tests) and make phpstan both pass. Pushed as 70f7cbbb6.