feature symfony#60895 [BrowserKit] Add isFirstPage() and isLastPage() methods to History (santysisi)

This PR was merged into the 7.4 branch.

Discussion
----------

[BrowserKit] Add `isFirstPage()` and `isLastPage()` methods to History

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | No
| License       | MIT

This PR introduces two new utility methods
- `isFirstPage()`: Returns `true` if the current position is at the start of the history stack.
- `isLastPage()`: Returns `true` if the current position is at the end of the history stack.

These methods are particularly useful in a testing context. For example, they enable clearer and more targeted assertions, such as:

```php
$this->assertTrue($client->getHistory()->isLastPage());
$this->assertTrue($client->getHistory()->isFirstPage());
$this->assertFalse($client->getHistory()->isFirstPage());
$this->assertFalse($client->getHistory()->isLastPage());
```

These new methods also allow developers to proactively check the navigation state before calling `back()` or `forward()`, which can be useful in certain scenarios to avoid unnecessary exceptions and reduce the need for additional error handling logic.

Commits
-------

8b2045e [BrowserKit] Add `isFirstPage()` and `isLastPage()` methods to History

Author: nicolas-grekas

src/Symfony/Component/BrowserKit/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+ * Add `isFirstPage()` and `isLastPage()` methods to the History class for checking navigation boundaries
+
 6.4
 ---
 

src/Symfony/Component/BrowserKit/History.php

@@ -50,14 +50,30 @@ public function isEmpty(): bool
         return 0 === \count($this->stack);
     }
 
+    /**
+     * Returns true if the stack is on the first page.
+     */
+    public function isFirstPage(): bool
+    {
+        return $this->position < 1;
+    }
+
+    /**
+     * Returns true if the stack is on the last page.
+     */
+    public function isLastPage(): bool
+    {
+        return $this->position > \count($this->stack) - 2;
+    }
+
     /**
      * Goes back in the history.
      *
      * @throws LogicException if the stack is already on the first page
      */
     public function back(): Request
     {
-        if ($this->position < 1) {
+        if ($this->isFirstPage()) {
             throw new LogicException('You are already on the first page.');
         }
 
@@ -71,7 +87,7 @@ public function back(): Request
      */
     public function forward(): Request
     {
-        if ($this->position > \count($this->stack) - 2) {
+        if ($this->isLastPage()) {
             throw new LogicException('You are already on the last page.');
         }
 

src/Symfony/Component/BrowserKit/Tests/AbstractBrowserTest.php

@@ -701,6 +701,8 @@ public function testBack()
         $this->assertArrayHasKey('myfile.foo', $client->getRequest()->getFiles(), '->back() keeps files');
         $this->assertArrayHasKey('X_TEST_FOO', $client->getRequest()->getServer(), '->back() keeps $_SERVER');
         $this->assertSame($content, $client->getRequest()->getContent(), '->back() keeps content');
+        $this->assertTrue($client->getHistory()->isFirstPage());
+        $this->assertFalse($client->getHistory()->isLastPage());
     }
 
     public function testForward()
@@ -741,6 +743,8 @@ public function testBackAndFrowardWithRedirects()
         $client->forward();
 
         $this->assertSame('http://www.example.com/redirected', $client->getRequest()->getUri(), '->forward() goes forward in the history skipping redirects');
+        $this->assertTrue($client->getHistory()->isLastPage());
+        $this->assertFalse($client->getHistory()->isFirstPage());
     }
 
     public function testReload()

src/Symfony/Component/BrowserKit/Tests/HistoryTest.php

@@ -99,4 +99,34 @@ public function testForward()
 
         $this->assertSame('http://www.example1.com/', $history->current()->getUri(), '->forward() returns the next request in the history');
     }
+
+    public function testIsFirstPage()
+    {
+        $history = new History();
+        $history->add(new Request('http://www.example.com/', 'get'));
+        $history->add(new Request('http://www.example1.com/', 'get'));
+        $history->back();
+
+        $this->assertFalse($history->isLastPage());
+        $this->assertTrue($history->isFirstPage());
+    }
+
+    public function testIsLastPage()
+    {
+        $history = new History();
+        $history->add(new Request('http://www.example.com/', 'get'));
+        $history->add(new Request('http://www.example1.com/', 'get'));
+
+        $this->assertTrue($history->isLastPage());
+        $this->assertFalse($history->isFirstPage());
+    }
+
+    public function testIsFirstAndLastPage()
+    {
+        $history = new History();
+        $history->add(new Request('http://www.example.com/', 'get'));
+
+        $this->assertTrue($history->isLastPage());
+        $this->assertTrue($history->isFirstPage());
+    }
 }