[HttpFoundation] deprecate using $first in get and added key in all

CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG
 
  * passing arguments to `Request::isMethodSafe()` is deprecated.
  * `ApacheRequest` is deprecated, use the `Request` class instead.
+ * passing a third argument to `HeaderBag::get()` is deprecated, use method `all()` instead
 
 4.3.0
 -----

HeaderBag.php

@@ -58,10 +58,18 @@ public function __toString()
     /**
      * Returns the headers.
      *
+     * @param string|null $key The name of the headers to return or null to get them all
+     *
      * @return array An array of headers
      */
-    public function all()
+    public function all(/*string $key = null*/)
     {
+        if (1 <= \func_num_args() && null !== $key = func_get_arg(0)) {
+            $key = str_replace('_', '-', strtolower($key));
+
+            return $this->headers[$key] ?? [];
+        }
+
         return $this->headers;
     }
 
@@ -103,28 +111,21 @@ public function add(array $headers)
      *
      * @param string      $key     The header name
      * @param string|null $default The default value
-     * @param bool        $first   Whether to return the first value or all header values
      *
-     * @return string|string[]|null The first header value or default value if $first is true, an array of values otherwise
+     * @return string|null The first header value or default value
      */
-    public function get($key, $default = null, $first = true)
+    public function get($key, $default = null)
     {
-        $key = str_replace('_', '-', strtolower($key));
-        $headers = $this->all();
+        $headers = $this->all((string) $key);
+        if (2 < \func_num_args()) {
+            @trigger_error(sprintf('Passing a third argument to "%s()" is deprecated since Symfony 4.4, use method "all()" instead', __METHOD__), E_USER_DEPRECATED);
 
-        if (!\array_key_exists($key, $headers)) {
-            if (null === $default) {
-                return $first ? null : [];
+            if (!func_get_arg(2)) {
+                return $headers;
             }
-
-            return $first ? $default : [$default];
-        }
-
-        if ($first) {
-            return \count($headers[$key]) ? $headers[$key][0] : $default;
         }
 
-        return $headers[$key];
+        return $headers[0] ?? $default;
     }
 
     /**
@@ -181,7 +182,7 @@ public function has($key)
      */
     public function contains($key, $value)
     {
-        return \in_array($value, $this->get($key, null, false));
+        return \in_array($value, $this->all((string) $key));
     }
 
     /**

Response.php

@@ -1024,7 +1024,7 @@ public function hasVary(): bool
      */
     public function getVary(): array
     {
-        if (!$vary = $this->headers->get('Vary', null, false)) {
+        if (!$vary = $this->headers->all('Vary')) {
             return [];
         }
 

ResponseHeaderBag.php

@@ -87,10 +87,19 @@ public function replace(array $headers = [])
 
     /**
      * {@inheritdoc}
+     *
+     * @param string|null $key The name of the headers to return or null to get them all
      */
-    public function all()
+    public function all(/*string $key = null*/)
     {
         $headers = parent::all();
+
+        if (1 <= \func_num_args() && null !== $key = func_get_arg(0)) {
+            $key = str_replace('_', '-', strtolower($key));
+
+            return 'set-cookie' !== $key ? $headers[$key] ?? [] : array_map('strval', $this->getCookies());
+        }
+
         foreach ($this->getCookies() as $cookie) {
             $headers['set-cookie'][] = (string) $cookie;
         }

Test/Constraint/ResponseHeaderSame.php

@@ -40,7 +40,7 @@ public function toString(): string
      */
     protected function matches($response): bool
     {
-        return $this->expectedValue === $response->headers->get($this->headerName, null, true);
+        return $this->expectedValue === $response->headers->get($this->headerName, null);
     }
 
     /**

Tests/HeaderBagTest.php

@@ -88,24 +88,34 @@ public function testGet()
         $bag = new HeaderBag(['foo' => 'bar', 'fuzz' => 'bizz']);
         $this->assertEquals('bar', $bag->get('foo'), '->get return current value');
         $this->assertEquals('bar', $bag->get('FoO'), '->get key in case insensitive');
-        $this->assertEquals(['bar'], $bag->get('foo', 'nope', false), '->get return the value as array');
+        $this->assertEquals(['bar'], $bag->all('foo'), '->get return the value as array');
 
         // defaults
         $this->assertNull($bag->get('none'), '->get unknown values returns null');
         $this->assertEquals('default', $bag->get('none', 'default'), '->get unknown values returns default');
-        $this->assertEquals(['default'], $bag->get('none', 'default', false), '->get unknown values returns default as array');
+        $this->assertEquals([], $bag->all('none'), '->get unknown values returns an empty array');
 
         $bag->set('foo', 'bor', false);
         $this->assertEquals('bar', $bag->get('foo'), '->get return first value');
-        $this->assertEquals(['bar', 'bor'], $bag->get('foo', 'nope', false), '->get return all values as array');
+        $this->assertEquals(['bar', 'bor'], $bag->all('foo'), '->get return all values as array');
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation Passing a third argument to "Symfony\Component\HttpFoundation\HeaderBag::get()" is deprecated since Symfony 4.4, use method "all()" instead
+     */
+    public function testGetIsEqualToNewMethod()
+    {
+        $bag = new HeaderBag(['foo' => 'bar', 'fuzz' => 'bizz']);
+        $this->assertSame($bag->all('none'), $bag->get('none', [], false), '->get unknown values returns default as array');
     }
 
     public function testSetAssociativeArray()
     {
         $bag = new HeaderBag();
         $bag->set('foo', ['bad-assoc-index' => 'value']);
         $this->assertSame('value', $bag->get('foo'));
-        $this->assertEquals(['value'], $bag->get('foo', 'nope', false), 'assoc indices of multi-valued headers are ignored');
+        $this->assertSame(['value'], $bag->all('foo'), 'assoc indices of multi-valued headers are ignored');
     }
 
     public function testContains()

Tests/ResponseHeaderBagTest.php

@@ -89,13 +89,13 @@ public function testCacheControlHeader()
 
         $bag = new ResponseHeaderBag();
         $bag->set('Cache-Control', ['public', 'must-revalidate']);
-        $this->assertCount(1, $bag->get('Cache-Control', null, false));
+        $this->assertCount(1, $bag->all('Cache-Control'));
         $this->assertEquals('must-revalidate, public', $bag->get('Cache-Control'));
 
         $bag = new ResponseHeaderBag();
         $bag->set('Cache-Control', 'public');
         $bag->set('Cache-Control', 'must-revalidate', false);
-        $this->assertCount(1, $bag->get('Cache-Control', null, false));
+        $this->assertCount(1, $bag->all('Cache-Control'));
         $this->assertEquals('must-revalidate, public', $bag->get('Cache-Control'));
     }
 
@@ -166,7 +166,7 @@ public function testCookiesWithSameNames()
             'foo=bar; path=/path/bar; domain=foo.bar; httponly; samesite=lax',
             'foo=bar; path=/path/bar; domain=bar.foo; httponly; samesite=lax',
             'foo=bar; path=/; httponly; samesite=lax',
-        ], $bag->get('set-cookie', null, false));
+        ], $bag->all('set-cookie'));
 
         $this->assertSetCookieHeader('foo=bar; path=/path/foo; domain=foo.bar; httponly; samesite=lax', $bag);
         $this->assertSetCookieHeader('foo=bar; path=/path/bar; domain=foo.bar; httponly; samesite=lax', $bag);