From f86b74a659dbbef3f8a8a48754c4a9846462043a Mon Sep 17 00:00:00 2001
From: Nicolas Giraud <nicolas.giraud.dev@gmail.com>
Date: Fri, 7 Feb 2025 19:40:03 +0100
Subject: [PATCH] Add documentation about `thenReturnSelf()`

This fixes https://github.com/phake/phake/issues/220
---
 src/doc/answers.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/src/doc/answers.md b/src/doc/answers.md
index f11b236..5a9e76e 100644
--- a/src/doc/answers.md
+++ b/src/doc/answers.md
@@ -4,6 +4,55 @@ Answers
 In all of the examples so far, the `thenReturn()` answer is being used. There are other answers that are remarkably
 useful writing your tests.
 
+Returning the object itself
+---------------------------
+
+When stubbing a method that can return the instance of the object itself (`$this`), it can be required to force the answer
+to be the instance of the mock. Rather than calling `thenReturn()` with the same mock variable as argument, Phake provides
+a cleaner way by calling the method `thenReturnSelf()`.
+Consider the following interface and class.
+
+```php-inline
+interface MyInterface
+{
+	public function foo(): ?static;
+
+	public function bar(): int;
+}
+```
+
+```php-inline
+class MyClass
+{
+	public function useFooBar(MyInterface $object): ?int
+	{
+		return $object->foo()?->bar();
+	}
+}
+```
+
+As `MyInterface::foo()` is not always returning the instance of the object calling, a unit test trying to cover `MyClass` that
+uses any instance of such interface would require to stub `static` as answer.
+
+```php-inline
+class MyClassTest extends PHPUnit\Framework\TestCase
+{
+	public function testUseFooBar(): void
+	{
+		$mock = Phake::mock(MyInterface::class);
+		Phake::when($mock)->foo()->thenReturnSelf();
+		Phake::when($mock)->bar()->thenReturn(42);
+
+		self::assertSame(42, (new MyClass())->useFooBar($mock));
+
+		$mock = Phake::mock(MyInterface::class);
+		Phake::when($mock)->foo()->thenReturn(null);
+
+		self::assertNull((new MyClass())->useFooBar($mock));
+	}
+}
+```
+
 Throwing Exceptions
 -------------------