rememberPossiblyImpureFunctionValues docs

ondrejmirtes · ondrejmirtes · commit f7bea8dc1ae6 · 2022-06-29T08:52:04.000+02:00
diff --git a/website/src/_posts/remembering-and-forgetting-returned-values.md b/website/src/_posts/remembering-and-forgetting-returned-values.md
@@ -58,6 +58,8 @@ if (impureFunction()) {
 }
 ```
 
+If the `impureFunction()` didn't have the `/** @phpstan-impure */` annotation, the value would be remembered for further calls. If you want to change this behaviour and don't want to assume functions returning a value are pure by default, set `rememberPossiblyImpureFunctionValues: false` in your configuration file (available in PHPStan 1.8.0). See [Config Reference](/config-reference#rememberpossiblyimpurefunctionvalues) for more details.
+
 If you call an impure method on an object that already has a remembered method value, it will be forgotten:
 
 ```php
diff --git a/website/src/config-reference.md b/website/src/config-reference.md
@@ -410,6 +410,45 @@ public function setFoo(int $foo): void
 
 When set to `true`, it reports use of dynamic properties as undefined.
 
+### `rememberPossiblyImpureFunctionValues`
+
+<div class="text-xs inline-block border border-green-600 text-green-600 bg-green-100 rounded px-1 mb-4">Available in PHPStan 1.8.0</div>
+
+**default**: `true`
+
+By default, PHPStan considers all functions that return a value to be pure. That means that second call to the same function in the same scope will return the same narrowed type:
+
+```php
+public function getName(): string
+{
+    return $this->name;
+}
+
+if ($this->getName() === 'Foo') {
+    echo $this->getName(); // still 'Foo'
+}
+```
+
+This is a sane default in case of getters but sometimes we have a function that can return different values based on a global state like a random number generator, database, or time.
+
+```php
+public function getRandomNumber(): int
+{
+    return rand();
+}
+
+if ($this->getRandomNumber() === 4) {
+    echo $this->getRandomNumber(); // it's not going to be 4 but PHPStan will think it is
+}
+```
+
+You can mark `getRandomNumber()` with `/** @phpstan-impure */` but if you have many functions like this in your codebase and don't want to assume functions return the same value when called multiple times, you can set `rememberPossiblyImpureFunctionValues` to `false`:
+
+```yaml
+parameters:
+	rememberPossiblyImpureFunctionValues: false
+```
+
 Exceptions
 ------------
 

Original file line number	Diff line number	Diff line change
`@@ -58,6 +58,8 @@ if (impureFunction()) {`
`58`	`58`	`}`
`59`	`59`	```
`60`	`60`
	`61`	+If the `impureFunction()` didn't have the `/** @phpstan-impure */` annotation, the value would be remembered for further calls. If you want to change this behaviour and don't want to assume functions returning a value are pure by default, set `rememberPossiblyImpureFunctionValues: false` in your configuration file (available in PHPStan 1.8.0). See [Config Reference](/config-reference#rememberpossiblyimpurefunctionvalues) for more details.
	`62`	`+`
`61`	`63`	`If you call an impure method on an object that already has a remembered method value, it will be forgotten:`
`62`	`64`
`63`	`65`	```php