Skip to content

Improve range() return type for invalid steps and long ranges - #6492

Merged
staabm merged 8 commits into
phpstan:2.3.xfrom
zonuexe:10022/range-php83
Nov 13, 2026
Merged

staabm merged 8 commits into
phpstan:2.3.xfrom
zonuexe:10022/range-php83

Conversation

@zonuexe

@zonuexe zonuexe commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Ref phpstan/phpstan#10022

Two inaccuracies in the return type of range():

  1. An invalid $step makes range() throw a ValueError, but the extension still returned an array type. It now returns never when every combination of the constant arguments throws. PHP 7 returned false with a warning instead, so on PHP 7 it returns false. When the extension cannot decide a combination, the general type joins the types of the other combinations in the union.
  2. For a range longer than RANGE_LENGTH_THRESHOLD the extension generalized the argument types, which predates the PHP 8.3 changes. It now generalizes the values the range consists of:
 // range('A', 'z')
-non-empty-list<int|(literal-string&lowercase-string&non-falsy-string)|(literal-string&non-falsy-string&uppercase-string)>
+non-empty-list<literal-string&non-empty-string>

 // range(1, 200, 1.0)
-non-empty-list<float>
+non-empty-list<int<1, 200>>

Since d52db07 the extension skips calling range() for a range longer than ARRAY_COUNT_LIMIT. On that path it applies the same rules to the argument types, and it rejects a negative $step on an increasing range on PHP 8.3+.

The extension folds the constant arguments by calling the native range(), so a caught ValueError only says that the runtime rejects the step. I gated both changes on PhpVersion $scope->getPhpVersion() wherever PHP 8.3 changed the behaviour, so conditions like PHP_VERSION_ID < 80300 narrow them. A $step of 0, or one wider than the range, has been a ValueError since PHP 8.0, unless both boundaries are equal and not both ints, while a negative $step on an increasing range and a non-finite $step only became one in 8.3. Before 8.3 an infinite $step failed as one wider than the range. An integral float $step produces ints since 8.3 and floats before that. Analysing for PHP 8.2 still gives non-empty-list<int> for range(2, 5, -1) and non-empty-list<float> for range(1, 200, 1.0). RangePhp82Test covers that axis: it sets phpVersion to 8.2 and runs on 8.3+. The tests in nsrt/ cover that axis with PHP_VERSION_ID conditions. The checks live in RangeFunctionArgumentsHelper, which this PR shares with #6539.

This does not close phpstan/phpstan#10022. PHPStan already infers the PHP 8.3 result for the reproducer in that issue, range('1', 'a'), because the extension folds the constant arguments through the native range(). For the same reason the folded values follow the PHP version PHPStan runs on rather than the configured phpVersion: with phpVersion: 80200 on a PHPStan running on 8.5, range('1', 'a') still comes out as the 49 element character range instead of array{1, 0}. Making the values follow phpVersion means reimplementing range() down to the rounding of start + i * step, and I did not want to put that in this PR. This PR fixes what you can decide without knowing the values: which steps PHP rejects, and how to generalize a range past the threshold.

@zonuexe
zonuexe marked this pull request as draft September 21, 2026 10:55
@zonuexe
zonuexe marked this pull request as ready for review September 21, 2026 11:26
@phpstan-bot

Copy link
Copy Markdown
Collaborator

This pull request has been marked as ready for review.

@zonuexe
zonuexe marked this pull request as draft September 21, 2026 14:22
@zonuexe
zonuexe marked this pull request as ready for review September 21, 2026 15:36
@zonuexe

zonuexe commented Sep 21, 2026

Copy link
Copy Markdown
Contributor Author

The Mutation Testing jobs fail on tests/PHPStan/Rules/Comparison/ImpossibleCheckTypeFunctionCallRuleTest.php:588, where #[RequiresPhp('>= 8.0')] lacks the patch version (phpunit.attributeRequiresPhpVersion). That line comes from 2.2.x, and #6491 and #6488 fail the same way, so I left it out of this PR.

@phpstan-bot

Copy link
Copy Markdown
Collaborator

This pull request has been marked as ready for review.

@zonuexe
zonuexe marked this pull request as draft September 22, 2026 17:12
@zonuexe

zonuexe commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

After I opened this PR, d52db07 landed on 2.2.x: the extension no longer calls range() for a range longer than ARRAY_COUNT_LIMIT. I rebased onto it and added 3695000, which applies this PR's rules on that path. In the table, the rows with 1000 items take it.

Current 2.2.x against this PR, with PHPStan running on PHP 8.5 (non-empty-list shortened to list):

Expression Analysed PHP 2.2.x This PR
range(2, 5, 0) 7.4 list<int> false
8.2, 8.5 list<int> *NEVER*
range(1, 10, INF) 7.4 list<float|int> false
8.2, 8.5 list<float|int> *NEVER*
range(2, 5, -1) 8.5 list<int> *NEVER*
range(1, 1000, -1) 8.5 list<int<1, 1000>> *NEVER*
range(1, 200, 1.0) 8.5 list<float> list<int<1, 200>>
range(1, 1000, 1.0) 8.5 list<float> list<int<1, 1000>>
range(1.0, 1000.0) all list<float|int> list<float>
range('A', 'z') all list<int|(literal-string&lowercase-string&non-falsy-string)|(literal-string&non-falsy-string&uppercase-string)> list<literal-string&non-empty-string>
range(0, 2000000000) all list<int<0, 2000000000>> list<int<0, 2000000000>>

Analysing for 8.2, range(2, 5, -1), range(1, 1000, -1), range(1, 200, 1.0) and range(1, 1000, 1.0) keep the 2.2.x types, since PHP before 8.3 ignored the sign of the step and produced floats for a float step. range(0, 20000000) takes 98 MB on both, so the memory fix of d52db07 stays in place.

@zonuexe
zonuexe force-pushed the 10022/range-php83 branch 3 times, most recently from 4a20caf to 9abe059 Compare September 22, 2026 21:00
@zonuexe
zonuexe marked this pull request as ready for review September 22, 2026 21:20
@phpstan-bot

Copy link
Copy Markdown
Collaborator

This pull request has been marked as ready for review.

@VincentLanglet

Copy link
Copy Markdown
Contributor

Dunno what you think @staabm ; but it's maybe simpler/better to target 2.3.x for all those new PR ?

@zonuexe

zonuexe commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

I rebased this PR and #6539 onto 2.3.x locally. The only conflict was in PhpVersions, where 2.3.x appends methods at the same place as hasStricterRangeFunction(). Tests and self-analysis pass on both 2.2.x and 2.3.x, so I'll target whichever branch fits your release plan.

@zonuexe
zonuexe marked this pull request as draft October 6, 2026 16:32
@zonuexe
zonuexe changed the base branch from 2.2.x to 2.3.x October 6, 2026 16:38
@zonuexe
zonuexe marked this pull request as ready for review October 6, 2026 16:38
@zonuexe
zonuexe force-pushed the 10022/range-php83 branch from fc6b43c to 2fb052c Compare October 6, 2026 16:38
@phpstan-bot

Copy link
Copy Markdown
Collaborator

This pull request has been marked as ready for review.

@zonuexe
zonuexe marked this pull request as draft November 2, 2026 15:41
@zonuexe
zonuexe marked this pull request as ready for review November 2, 2026 19:03
@phpstan-bot

Copy link
Copy Markdown
Collaborator

This pull request has been marked as ready for review.

@staabm
staabm force-pushed the 10022/range-php83 branch from 4fbfd67 to 4566b0b Compare November 8, 2026 06:42
@zonuexe

zonuexe commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

I tried float ranges here, as promised in #6539. 256fcb2 bounds a long list of floats by its boundaries: range(1.0, 1000.0) returns non-empty-list<float<1.0, 1000.0>> instead of non-empty-list<float>.

PHP stops the float loop at element <= end (>= when decreasing), so no item passes the end. If PHPStan calls range() itself, the first and the last item set the bounds: range(0, 31, 0.3) gives float<0.0, 30.9>. Above the array count limit, PHPStan takes the bounds from the arguments, and they can be looser than the items: range(1.5, -1000) gives float<-1000.0, 1.5>, but the last item is -998.5. A string boundary keeps float unbounded.

@staabm

staabm commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

//cc @SanderMuller

@SanderMuller SanderMuller left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I compared this with the real range() on PHP 7.4, 8.0, 8.2, 8.3 and 8.5. The grid has 9,216 calls: 24 start values times 24 end values times 16 steps. The boundaries are ints, floats, and numeric and non-numeric strings. The steps include 0, negative steps, INF, -INF, NAN and 1e20. For each phpVersion I compared the dumped type with the result on that PHP version.

  • No call gets *NEVER* or false where that PHP version returns an array. This is also true for the phpVersion ranges 8.0–8.2, 8.2–8.5 and 7.4–8.5.
  • On 8.3 and 8.5, all 5,220 calls that throw now give *NEVER*. On 8.0 and 8.2, 922 of the 3,798 calls that throw do.
  • I could not make a float range pass its end. I tried increasing and decreasing ranges of up to 3,000 items with steps such as 0.1, 0.3 and 0.01 on 7.4, 8.2, 8.3 and 8.5. So the float<…> bounds from the arguments hold.
  • Some array shapes do not match PHP 7.4, 8.0 and 8.2, for example range(5, '1.5', 1). They are the same on 2.3.x, and they come from the runtime-values limit in your description.

One gap on PHP 7: when the helper cannot decide a combination, the type does not get false. For example, range(0, 0, 0) returns false on 7.4 and throws on 8.0, but with phpVersion: 70400 this PR gives non-empty-list<int>. On 7.4, 2,797 of the calls have this gap (3,719 on 2.3.x). I tried this in the branch for an undecided combination:

$hasUnknownCombination = true;
if (!$throwsValueError->yes()) {
	$constantReturnTypes[] = new ConstantBooleanType(false);
}

That closes 2,762 of them. The other 35 are character ranges such as range('a', '1', 2) that PHP 8.3 and newer accept, which is the runtime-values limit again. The results for 8.2 and 8.5 do not change, and the range-related nsrt tests still pass.

The 4 nsrt files fail on 2.3.x and pass here. bug-10022-php82.php has lint < 8.3, so I could not run it on 8.5. On 55593f2 the full test suite, make phpstan and phpcs pass. The four red integration jobs are also red on #7038 at the same base commit.

Performance: on the file with the 9,216 calls, 8 runs each, both sides take 5.74 s (σ 0.02 s).

@zonuexe

zonuexe commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor Author

@SanderMuller Thanks for the comparison. I applied your change to the undecided combinations in 976a138: on PHP 7, range(0, 0, 0) now gives non-empty-list<int>|false. A test on 8.0–8.2 checks that false stays out when the analysed version throws.

@SanderMuller SanderMuller left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I ran the grid again on dc4d89b. On PHP 7.4 the gap is down from 2,797 calls to the 35 character ranges, and the types are the same as with my prototype. The results for 8.0 to 8.5 and for the phpVersion ranges did not change.

The new assertions in bug-10022.php and range-invalid-step.php fail without the change in 976a138 and pass with it. On this head the test suite, make phpstan and phpcs pass. The red CI jobs are also red on #7038 or on the 2.3.x tip.

zonuexe and others added 8 commits November 13, 2026 06:30
PHP 8.0-8.2 ignore the sign of the step and, for numeric boundaries,
reject one that is 0 or wider than the range; PHP 7 does the same with a
warning and false instead of a ValueError. PHP 8.3 checks a step of 0, a
NAN step and a step of PHP_INT_MIN before the boundaries, rejects a
negative step on an increasing range, and builds a character range from
two single bytes, in which a float step turns every character but a digit
into 0.

RangeFunctionArgumentsHelper::rejects() answers for the PHP versions of
the scope, with PhpVersions::hasStricterRangeFunction() telling them
apart. It uses the verdict of calling range() only when PHPStan itself
runs on PHP 8.3 or newer, and leaves undecided what it cannot tell
without running an older PHP: string boundaries before PHP 8.3, and
numbers beyond 2 ** 53, which PHP compares exactly as integers.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
An invalid step makes range() throw a ValueError on PHP 8 and return
false with a warning on PHP 7, so a call where every combination of the
constant arguments is rejected is now `*NEVER*` on PHP 8 and `false` on
PHP 7. The extension folds the constant arguments by calling range() on
the PHP version PHPStan runs on, so RangeFunctionArgumentsHelper decides
whether the PHP versions of the scope reject the step as well. A
combination it cannot decide adds the general type to the union, next to
the types of the other combinations.

Long ranges are generalized from the values the range consists of, so
range('A', 'z') is a list of single byte strings and, since PHP 8.3,
where an integral float step stopped producing floats, range(1, 200, 1.0)
is a list of ints. Before PHP 8.3 a float argument still produces floats.
A range longer than ARRAY_COUNT_LIMIT, for which the extension skips
calling range(), gets the same rules from its argument types, including
the PHP 8.3 rejection of a negative step on an increasing range.

Ref phpstan/phpstan#10022

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
When the analysed PHP versions only maybe include 8.3, rejects() combines
the PHP 8.3 rules with the older ones. range(1, 10, -1) tells them apart:
PHP 8.3 rejects the negative step on an increasing range, while earlier
versions ignore its sign.
On PHP versions on both sides of 8.0 an invalid step returns false on
PHP 7 and throws on PHP 8, so the type is false rather than never. An
argument that is only partly a constant might still make a valid range,
so it keeps the general type.
getConstantScalarTypes() returns nothing for a type that is only partly
a constant, so such an argument leaves no combination, and a non-zero
number of combinations already means that every argument is a constant.
The isConstantScalarValue() checks before returning never were therefore
always true.
range() stops before it passes the end, so a list of floats too long to be folded into a constant array becomes list<float<min, max>> instead of list<float>. A string boundary keeps the floats unbounded.
When the runtime rejects a combination of constant arguments that the analysed version might accept, the general type covers it. PHP 7 returns false for the arguments that PHP 8 rejects with a ValueError, so false stays in the type unless the analysed version throws.
@staabm
staabm merged commit ec03c84 into phpstan:2.3.x Nov 13, 2026
884 of 892 checks passed
@staabm

staabm commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

thank you!

@zonuexe
zonuexe deleted the 10022/range-php83 branch November 13, 2026 05:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support PHP 8.3 range() changes

5 participants