From fd2683fcc6d07548be168fffe206416a32bdc33b Mon Sep 17 00:00:00 2001
From: Thomas Landauer <thomas@landauer.at>
Date: Tue, 21 Jun 2022 20:23:23 +0200
Subject: [PATCH 1/4] Adding common problem cases and possible solutions

See https://github.com/vimeo/psalm/issues/8133#issuecomment-1162010190

Don't know if this is the best way to explain this, but it's a start :-)

Is there a better way to add the link to https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-mutation-free ?

I also removed the `<?php` tag from the code block.
---
 .../issues/PossiblyNullArgument.md            | 42 +++++++++++++++++--
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/docs/running_psalm/issues/PossiblyNullArgument.md b/docs/running_psalm/issues/PossiblyNullArgument.md
index 97e1c229fe0..6e4ec2cd2c2 100644
--- a/docs/running_psalm/issues/PossiblyNullArgument.md
+++ b/docs/running_psalm/issues/PossiblyNullArgument.md
@@ -3,8 +3,44 @@
 Emitted when calling a function with a value that’s possibly null when the function does not expect it
 
 ```php
-<?php
-
-function foo(string $s) : void {}
+function foo(string $s): void {}
 foo(rand(0, 1) ? "hello" : null);
 ```
+
+## Common Problem Cases
+
+### Using a Function Call inside `if`
+
+```php
+if (is_string($cat->getName()) {
+    foo($cat->getName());
+}
+```
+This fails since it's not guaranteed that subsequent calls to `$cat->getName()` always give the same result.
+
+#### Possible Solutions
+
+* Use a variable:
+    ```php
+    $catName = $cat->getName();
+    if (is_string($catName) {
+        foo($catName);
+    }
+    unset($catName);
+    ```
+* Add [`@psalm-mutation-free`](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-mutation-free) to the declaration of the function
+
+### Calling Another Function After `if`
+
+```php
+if (is_string($cat->getName()) {
+    changeCat();
+    foo($cat->getName());
+}
+```
+This fails since psalm cannot know if `changeCat()` does actually modify `$cat`.
+
+#### Possible Solutions
+
+* Add [`@psalm-mutation-free`](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-mutation-free) to the declaration of the other function (here: `changeCat()`) too
+* Use a variable: See above

From 7201f0941b669bd879e7106fd2d53b79ac8f75d2 Mon Sep 17 00:00:00 2001
From: Thomas Landauer <thomas@landauer.at>
Date: Tue, 21 Jun 2022 20:56:20 +0200
Subject: [PATCH 2/4] Improving link syntax

---
 docs/running_psalm/issues/PossiblyNullArgument.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/running_psalm/issues/PossiblyNullArgument.md b/docs/running_psalm/issues/PossiblyNullArgument.md
index 6e4ec2cd2c2..5ba4d737285 100644
--- a/docs/running_psalm/issues/PossiblyNullArgument.md
+++ b/docs/running_psalm/issues/PossiblyNullArgument.md
@@ -28,7 +28,7 @@ This fails since it's not guaranteed that subsequent calls to `$cat->getName()`
     }
     unset($catName);
     ```
-* Add [`@psalm-mutation-free`](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-mutation-free) to the declaration of the function
+* Add [`@psalm-mutation-free`](../../annotating_code/supported_annotations.md#psalm-mutation-free) to the declaration of the function
 
 ### Calling Another Function After `if`
 

From 80bcc8b5e312b1625fad6b838f4d244f1b605c06 Mon Sep 17 00:00:00 2001
From: Thomas Landauer <thomas@landauer.at>
Date: Tue, 21 Jun 2022 21:55:32 +0200
Subject: [PATCH 3/4] Improving second link too :-)

---
 docs/running_psalm/issues/PossiblyNullArgument.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/running_psalm/issues/PossiblyNullArgument.md b/docs/running_psalm/issues/PossiblyNullArgument.md
index 5ba4d737285..cabaeea33c6 100644
--- a/docs/running_psalm/issues/PossiblyNullArgument.md
+++ b/docs/running_psalm/issues/PossiblyNullArgument.md
@@ -42,5 +42,5 @@ This fails since psalm cannot know if `changeCat()` does actually modify `$cat`.
 
 #### Possible Solutions
 
-* Add [`@psalm-mutation-free`](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-mutation-free) to the declaration of the other function (here: `changeCat()`) too
+* Add [`@psalm-mutation-free`](../../annotating_code/supported_annotations.md#psalm-mutation-free) to the declaration of the other function (here: `changeCat()`) too
 * Use a variable: See above

From 3bca297fbaa3213534db3e434e4554e636d5effd Mon Sep 17 00:00:00 2001
From: Thomas Landauer <thomas@landauer.at>
Date: Tue, 21 Jun 2022 22:45:45 +0200
Subject: [PATCH 4/4] Bringing back `<?php`

---
 docs/running_psalm/issues/PossiblyNullArgument.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/running_psalm/issues/PossiblyNullArgument.md b/docs/running_psalm/issues/PossiblyNullArgument.md
index cabaeea33c6..82d3b21d3f5 100644
--- a/docs/running_psalm/issues/PossiblyNullArgument.md
+++ b/docs/running_psalm/issues/PossiblyNullArgument.md
@@ -3,6 +3,8 @@
 Emitted when calling a function with a value that’s possibly null when the function does not expect it
 
 ```php
+<?php
+
 function foo(string $s): void {}
 foo(rand(0, 1) ? "hello" : null);
 ```