Adding expires() to CakeResponse to help adding expiration dates to the http response cache directives

lib/Cake/Network/CakeResponse.php

@@ -677,10 +677,54 @@ class CakeResponse {
 		$this->header(array(
 			'Date' => gmdate("D, j M Y G:i:s ", time()) . 'GMT',
 			'Last-Modified' => gmdate("D, j M Y G:i:s ", $since) . 'GMT',
-			'Expires' => gmdate("D, j M Y H:i:s", $time) . " GMT",
 			'Cache-Control' => 'public, max-age=' . ($time - time()),
 			'Pragma' => 'cache'
 		));
+		$this->expires($time);
+	}
+
+
+/**
+ * Sets the Expires header for the response by taking an expiration time
+ * If called with no parameters it will return the current Expires value
+ *
+ * ## Examples:
+ *
+ * `$response->expires('now')` Will Expire the response cache now
+ * `$response->expires(new DateTime('+1 day'))` Will set the expiration in next 24 hours
+ * `$response->expires)` Will return the current expiration header value
+ *
+ * @param string|DateTime $time
+ * @return string
+ */
+	public function expires($time = null) {
+		if ($time !== null) {
+			$date = $this->_getUTCDate($time);
+			$this->_headers['Expires'] = $date->format('D, j M Y H:i:s') . ' GMT';
+		}
+		if (isset($this->_headers['Expires'])) {
+			return $this->_headers['Expires'];
+		}
+		return null;
+	}
+
+/**
+ * Returns a DateTime object initialized at the $time param and using UTC
+ * as timezone
+ *
+ * @param string|int|DateTime $time 
+ * @return DateTime
+ */
+	protected function _getUTCDate($time = null) {
+		if ($time instanceof DateTime) {
+			$result = clone $time;
+		} else if (is_integer($time)) {
+			$result = new DateTime(date('Y-m-d H:i:s', $time));
+		} else {
+			$result = new DateTime($time);
+		}
+		$result->setTimeZone(new DateTimeZone('UTC'));
+		return $result;
 	}
 
 /**

lib/Cake/Test/Case/Network/CakeResponseTest.php

@@ -267,12 +267,13 @@ class CakeResponseTest extends CakeTestCase {
 	public function testCache() {
 		$response = new CakeResponse();
 		$since = time();
-		$time = '+1 day';
+		$time = new DateTime('+1 day', new DateTimeZone('UTC'));
+		$response->expires('+1 day');
 		$expected = array(
 			'Date' => gmdate("D, j M Y G:i:s ", $since) . 'GMT',
 			'Last-Modified' => gmdate("D, j M Y G:i:s ", $since) . 'GMT',
-			'Expires' => gmdate("D, j M Y H:i:s", strtotime($time)) . " GMT",
+			'Expires' => $time->format('D, j M Y H:i:s') . ' GMT',
-			'Cache-Control' => 'public, max-age=' . (strtotime($time) - time()),
+			'Cache-Control' => 'public, max-age=' . ($time->format('U') - time()),
 			'Pragma' => 'cache'
 		);
 		$response->cache($since);
@@ -570,4 +571,36 @@ class CakeResponseTest extends CakeTestCase {
 			->method('_sendContent')->with('This is a body');
 		$response->send();
 	}
+
+/**
+ * Tests setting the expiration date
+ *
+ * @return void
+ */
+	public function testExpires() {
+		$response = $this->getMock('CakeResponse', array('_sendHeader', '_sendContent'));
+		$now = new DateTime('now', new DateTimeZone('America/Los_Angeles'));
+		$response->expires($now);
+		$now->setTimeZone(new DateTimeZone('UTC'));
+		$this->assertEquals($now->format('D, j M Y H:i:s') . ' GMT', $response->expires());
+		$response->expects($this->at(1))
+			->method('_sendHeader')->with('Expires', $now->format('D, j M Y H:i:s') . ' GMT');
+		$response->send();
+
+		$response = $this->getMock('CakeResponse', array('_sendHeader', '_sendContent'));
+		$now = time();
+		$response->expires($now);
+		$this->assertEquals(gmdate('D, j M Y H:i:s', $now) . ' GMT', $response->expires());
+		$response->expects($this->at(1))
+			->method('_sendHeader')->with('Expires', gmdate('D, j M Y H:i:s', $now) . ' GMT');
+		$response->send();
+
+		$response = $this->getMock('CakeResponse', array('_sendHeader', '_sendContent'));
+		$time = new DateTime('+1 day', new DateTimeZone('UTC'));
+		$response->expires('+1 day');
+		$this->assertEquals($time->format('D, j M Y H:i:s') . ' GMT', $response->expires());
+		$response->expects($this->at(1))
+			->method('_sendHeader')->with('Expires', $time->format('D, j M Y H:i:s') . ' GMT');
+		$response->send();
+	}
 }