[HttpFoundation] better fix for non-parseable Expires header date

It also fixes several phpdocs

src/Symfony/Component/HttpFoundation/HeaderBag.php

@@ -223,7 +223,7 @@ class HeaderBag implements \IteratorAggregate, \Countable
      * @param string    $key     The parameter key
      * @param \DateTime $default The default value
      *
-     * @return null|\DateTime The filtered value
+     * @return null|\DateTime The parsed DateTime or the default value if the header does not exist
      *
      * @throws \RuntimeException When the HTTP header is not parseable
      *
@@ -235,14 +235,6 @@ class HeaderBag implements \IteratorAggregate, \Countable
             return $default;
         }
 
-        if (-1 === $value) {
-            /**
-             * Since we need to return a valid date time a older date has been chosen
-             * https://github.com/symfony/symfony/pull/6471#discussion_r2527156
-             */
-            $value = 'Sat, 01 Jan 00 00:00:00 +0000';
-        }
-
         if (false === $date = \DateTime::createFromFormat(DATE_RFC2822, $value)) {
             throw new \RuntimeException(sprintf('The %s HTTP header is not parseable (%s).', $key, $value));
         }

src/Symfony/Component/HttpFoundation/Response.php

@@ -131,6 +131,8 @@ class Response
      * @param integer $status  The response status code
      * @param array   $headers An array of response headers
      *
+     * @throws \InvalidArgumentException When the HTTP status code is not valid
+     *
      * @api
      */
     public function __construct($content = '', $status = 200, $headers = array())
@@ -431,7 +433,7 @@ class Response
     /**
      * Retrieves the status code for the current web response.
      *
-     * @return string Status code
+     * @return integer Status code
      *
      * @api
      */
@@ -499,7 +501,7 @@ class Response
      *
      * Fresh responses may be served from cache without any interaction with the
      * origin. A response is considered fresh when it includes a Cache-Control/max-age
-     * indicator or Expiration header and the calculated age is less than the freshness lifetime.
+     * indicator or Expires header and the calculated age is less than the freshness lifetime.
      *
      * @return Boolean true if the response is fresh, false otherwise
      *
@@ -638,21 +640,26 @@ class Response
     /**
      * Returns the value of the Expires header as a DateTime instance.
      *
-     * @return \DateTime A DateTime instance
+     * @return \DateTime|null A DateTime instance or null if the header does not exist
      *
      * @api
      */
     public function getExpires()
     {
-        return $this->headers->getDate('Expires');
+        try {
+            return $this->headers->getDate('Expires');
+        } catch (\RuntimeException $e) {
+            // according to RFC 2616 invalid date formats (e.g. "0" and "-1") must be treated as in the past
+            return \DateTime::createFromFormat(DATE_RFC2822, 'Sat, 01 Jan 00 00:00:00 +0000');
+        }
     }
 
     /**
      * Sets the Expires HTTP header with a DateTime instance.
      *
-     * If passed a null value, it removes the header.
+     * Passing null as value will remove the header.
      *
-     * @param \DateTime $date A \DateTime instance
+     * @param \DateTime|null $date A \DateTime instance or null to remove the header
      *
      * @return Response
      *
@@ -672,7 +679,7 @@ class Response
     }
 
     /**
-     * Sets the number of seconds after the time specified in the response's Date
+     * Gets the number of seconds after the time specified in the response's Date
      * header when the the response should no longer be considered fresh.
      *
      * First, it checks for a s-maxage directive, then a max-age directive, and then it falls
@@ -693,10 +700,6 @@ class Response
         }
 
         if (null !== $this->getExpires()) {
-            if (!$this->getExpires() instanceof \DateTime) {
-                return 0;
-            }
-
             return $this->getExpires()->format('U') - $this->getDate()->format('U');
         }
 
@@ -800,7 +803,9 @@ class Response
     /**
      * Returns the Last-Modified HTTP header as a DateTime instance.
      *
-     * @return \DateTime A DateTime instance
+     * @return \DateTime|null A DateTime instance or null if the header does not exist
+     *
+     * @throws \RuntimeException When the HTTP header is not parseable
      *
      * @api
      */
@@ -812,9 +817,9 @@ class Response
     /**
      * Sets the Last-Modified HTTP header with a DateTime instance.
      *
-     * If passed a null value, it removes the header.
+     * Passing null as value will remove the header.
      *
-     * @param \DateTime $date A \DateTime instance
+     * @param \DateTime|null $date A \DateTime instance or null to remove the header
      *
      * @return Response
      *
@@ -836,7 +841,7 @@ class Response
     /**
      * Returns the literal value of the ETag HTTP header.
      *
-     * @return string The ETag HTTP header
+     * @return string|null The ETag HTTP header or null if it does not exist
      *
      * @api
      */
@@ -848,8 +853,8 @@ class Response
     /**
      * Sets the ETag value.
      *
-     * @param string  $etag The ETag unique identifier
+     * @param string|null $etag The ETag unique identifier or null to remove the header
-     * @param Boolean $weak Whether you want a weak ETag or not
+     * @param Boolean     $weak Whether you want a weak ETag or not
      *
      * @return Response
      *