feature #36129 [HttpFoundation][HttpKernel][Security] Improve UnexpectedSessionUsageException backtrace (mtarld)

This PR was merged into the 5.1-dev branch.

Discussion
----------

[HttpFoundation][HttpKernel][Security] Improve UnexpectedSessionUsageException backtrace

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       |
| License       | MIT
| Doc PR        |

Improve `UnexceptedSessionUsageException` backtrace so that it leads to the place in the userland  where it was told to use session.

Commits
-------

1e1d332c7c Improve UnexcpectedSessionUsageException backtrace

Author: nicolas-grekas

CHANGELOG.md

@@ -14,6 +14,7 @@ CHANGELOG
    according to [RFC 8674](https://tools.ietf.org/html/rfc8674)
  * made the Mime component an optional dependency
  * added `MarshallingSessionHandler`, `IdentityMarshaller`
+ * made `Session` accept a callback to report when the session is being used
 
 5.0.0
 -----

Session/Session.php

@@ -35,10 +35,12 @@ class Session implements SessionInterface, \IteratorAggregate, \Countable
     private $attributeName;
     private $data = [];
     private $usageIndex = 0;
+    private $usageReporter;
 
-    public function __construct(SessionStorageInterface $storage = null, AttributeBagInterface $attributes = null, FlashBagInterface $flashes = null)
+    public function __construct(SessionStorageInterface $storage = null, AttributeBagInterface $attributes = null, FlashBagInterface $flashes = null, callable $usageReporter = null)
     {
         $this->storage = $storage ?: new NativeSessionStorage();
+        $this->usageReporter = $usageReporter;
 
         $attributes = $attributes ?: new AttributeBag();
         $this->attributeName = $attributes->getName();
@@ -153,6 +155,9 @@ public function isEmpty(): bool
     {
         if ($this->isStarted()) {
             ++$this->usageIndex;
+            if ($this->usageReporter && 0 <= $this->usageIndex) {
+                ($this->usageReporter)();
+            }
         }
         foreach ($this->data as &$data) {
             if (!empty($data)) {
@@ -229,6 +234,9 @@ public function setName(string $name)
     public function getMetadataBag()
     {
         ++$this->usageIndex;
+        if ($this->usageReporter && 0 <= $this->usageIndex) {
+            ($this->usageReporter)();
+        }
 
         return $this->storage->getMetadataBag();
     }
@@ -238,7 +246,7 @@ public function getMetadataBag()
      */
     public function registerBag(SessionBagInterface $bag)
     {
-        $this->storage->registerBag(new SessionBagProxy($bag, $this->data, $this->usageIndex));
+        $this->storage->registerBag(new SessionBagProxy($bag, $this->data, $this->usageIndex, $this->usageReporter));
     }
 
     /**

Session/SessionBagProxy.php

@@ -21,17 +21,22 @@ final class SessionBagProxy implements SessionBagInterface
     private $bag;
     private $data;
     private $usageIndex;
+    private $usageReporter;
 
-    public function __construct(SessionBagInterface $bag, array &$data, ?int &$usageIndex)
+    public function __construct(SessionBagInterface $bag, array &$data, ?int &$usageIndex, ?callable $usageReporter)
     {
         $this->bag = $bag;
         $this->data = &$data;
         $this->usageIndex = &$usageIndex;
+        $this->usageReporter = $usageReporter;
     }
 
     public function getBag(): SessionBagInterface
     {
         ++$this->usageIndex;
+        if ($this->usageReporter && 0 <= $this->usageIndex) {
+            ($this->usageReporter)();
+        }
 
         return $this->bag;
     }
@@ -42,6 +47,9 @@ public function isEmpty(): bool
             return true;
         }
         ++$this->usageIndex;
+        if ($this->usageReporter && 0 <= $this->usageIndex) {
+            ($this->usageReporter)();
+        }
 
         return empty($this->data[$this->bag->getStorageKey()]);
     }
@@ -60,6 +68,10 @@ public function getName(): string
     public function initialize(array &$array): void
     {
         ++$this->usageIndex;
+        if ($this->usageReporter && 0 <= $this->usageIndex) {
+            ($this->usageReporter)();
+        }
+
         $this->data[$this->bag->getStorageKey()] = &$array;
 
         $this->bag->initialize($array);

Tests/Session/SessionTest.php

@@ -281,7 +281,7 @@ public function testGetBagWithBagNotImplementingGetBag()
         $bag->setName('foo');
 
         $storage = new MockArraySessionStorage();
-        $storage->registerBag(new SessionBagProxy($bag, $data, $usageIndex));
+        $storage->registerBag(new SessionBagProxy($bag, $data, $usageIndex, null));
 
         $this->assertSame($bag, (new Session($storage))->getBag('foo'));
     }