symfony · maldoinc · Jul 5, 2016 · Jul 6, 2016 · Jul 17, 2016 · Jul 29, 2016
diff --git a/src/Symfony/Component/HttpFoundation/ParameterBag.php b/src/Symfony/Component/HttpFoundation/ParameterBag.php
@@ -187,6 +187,39 @@ public function getBoolean($key, $default = false)
         return $this->filter($key, $default, FILTER_VALIDATE_BOOLEAN);
     }
 
+    /**
+     * Returns the parameter value converted to a DateTime object.
+     *
+     * @param string                          $key      The parameter key
+     * @param string                          $format   The expected date format
+     * @param \DateTimeInterface|string|null  $default  The default value to be converted to a DateTime object if the parameter key does not exist
+     * @param \DateTimeZone|null              $timeZone A DateTimeZone object representing the desired time zone
+     *
+     * @return \DateTimeInterface|null
+     */
+    public function getDate($key, $format, $default = null, \DateTimeZone $timeZone = null)
+    {
+        $time = $this->get($key, $default);
+
+        if ((null === $time) || $time instanceof \DateTimeInterface) {
+            return $time;
+        }
+
+        // if the user has specified a timezone then pass that
+        // otherwise do not even attempt to put a value but rather let the runtime decide
+        // the default value by itself
+        // this is in order to ensure compatibility with all php versions since
+        // some accept null as a TimeZone parameter and others do not
+        if (null !== $timeZone) {
+            $result = \DateTime::createFromFormat($format, $time, $timeZone);
+        } else {
+            $result = \DateTime::createFromFormat($format, $time);
+        }
+
+        // Failure to parse the date according to the specified format will return null
+        return false === $result ? null : $result;
+    }
+
     /**
      * Filter key.
      *

diff --git a/src/Symfony/Component/HttpFoundation/Tests/ParameterBagTest.php b/src/Symfony/Component/HttpFoundation/Tests/ParameterBagTest.php
@@ -124,6 +124,34 @@ public function testGetInt()
         $this->assertEquals(0, $bag->getInt('unknown'), '->getInt() returns zero if a parameter is not defined');
     }
 
+    public function testGetDate()
+    {
+        $isoDate = '2016-07-05T15:30:00UTC';
+        $bag = new ParameterBag(array(
+            'd1' => '2016-01-01',
+            'iso' => $isoDate,
+        ));
+
+        $date = \DateTime::createFromFormat('Y-m-d', '2016-01-01');
+        $diff = $date->diff($bag->getDate('d1', 'Y-m-d'));
+
+        $this->assertEquals(0, $diff->days, '->getDate() returns a date via the format specified');
+        $this->assertNull($bag->getDate('d1', 'd/m/Y'), '->getDate() returns null if the format is not valid');
+        $this->assertNull($bag->getDate('d2', 'd/m/Y'), '->getDate() returns null if the parameter is not found');
+        $this->assertEquals($date->format('Ymd'), $bag->getDate('d1', 'Y-m-d', new \DateTime('2016-12-01'))->format('Ymd'), '->getDate() parses the value if the key is present');
+
+        $date = $bag->getDate('iso', \DateTime::ISO8601);
+        $this->assertEquals(new \DateTime($isoDate), $date);
+        $this->assertEquals('UTC', $date->getTimezone()->getName());
+
+        $this->assertEquals($date, $bag->getDate('nokey', \DateTime::ISO8601, $isoDate));
+        $this->assertInstanceOf(\DateTimeInterface::class, $bag->getDate('nokey', \DateTime::ISO8601, $date));
+        $this->assertNull($bag->getDate('nokey', 'd/m/Y', $isoDate), '->getDate() returns null when the default value is not in the specified format');
+
+        $tz = $bag->getDate('d1', 'Y-m-d', null, new \DateTimeZone('Europe/Tirane'))->getTimezone()->getName();
+        $this->assertEquals('Europe/Tirane', $tz, '->getDate() accepts a DateTimeZone object which specifies the preferred timezone');
+    }
+
     public function testFilter()
     {
         $bag = new ParameterBag(array(
@@ -133,7 +161,7 @@ public function testFilter()
             'dec' => '256',
             'hex' => '0x100',
                'array' => array('bang'),
-            ));
+        ));
 
         $this->assertEmpty($bag->filter('nokey'), '->filter() should return empty by default if no key is found');