Merge pull request #12485 from owncloud/jenkins-12383

New DateTimeFormatter class for dates in other timezones and languages

3 files changed, 130 insertions, 6 deletions

diff --git a/lib/public/idatetimeformatter.php b/lib/public/idatetimeformatter.php
new file mode 100644
index 00000000000..b72638ad6cd
--- /dev/null
+++ b/lib/public/idatetimeformatter.php
@@ -0,0 +1,121 @@
+<?php
+/**
+ * ownCloud
+ *
+ * @author Joas Schilling
+ * @copyright 2014 Joas Schilling nickvergessen@owncloud.com
+ *
+ * This file is licensed under the Affero General Public License version 3 or
+ * later.
+ * See the COPYING-README file.
+ */
+
+namespace OCP;
+
+interface IDateTimeFormatter {
+	/**
+	 * Formats the date of the given timestamp
+	 *
+	 * @param int|\DateTime		$timestamp
+	 * @param string	$format			Either 'full', 'long', 'medium' or 'short'
+	 * 				full:	e.g. 'EEEE, MMMM d, y'	=> 'Wednesday, August 20, 2014'
+	 * 				long:	e.g. 'MMMM d, y'		=> 'August 20, 2014'
+	 * 				medium:	e.g. 'MMM d, y'			=> 'Aug 20, 2014'
+	 * 				short:	e.g. 'M/d/yy'			=> '8/20/14'
+	 * 				The exact format is dependent on the language
+	 * @param \DateTimeZone	$timeZone	The timezone to use
+	 * @param \OCP\IL10N	$l			The locale to use
+	 * @return string Formatted date string
+	 */
+	public function formatDate($timestamp, $format = 'long', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null);
+
+	/**
+	 * Formats the date of the given timestamp
+	 *
+	 * @param int|\DateTime		$timestamp
+	 * @param string	$format			Either 'full', 'long', 'medium' or 'short'
+	 * 				full:	e.g. 'EEEE, MMMM d, y'	=> 'Wednesday, August 20, 2014'
+	 * 				long:	e.g. 'MMMM d, y'		=> 'August 20, 2014'
+	 * 				medium:	e.g. 'MMM d, y'			=> 'Aug 20, 2014'
+	 * 				short:	e.g. 'M/d/yy'			=> '8/20/14'
+	 * 				The exact format is dependent on the language
+	 * 					Uses 'Today', 'Yesterday' and 'Tomorrow' when applicable
+	 * @param \DateTimeZone	$timeZone	The timezone to use
+	 * @param \OCP\IL10N	$l			The locale to use
+	 * @return string Formatted relative date string
+	 */
+	public function formatDateRelativeDay($timestamp, $format = 'long', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null);
+
+	/**
+	 * Gives the relative date of the timestamp
+	 * Only works for past dates
+	 *
+	 * @param int|\DateTime	$timestamp
+	 * @param int|\DateTime	$baseTimestamp	Timestamp to compare $timestamp against, defaults to current time
+	 * @return string	Dates returned are:
+	 * 				<  1 month	=> Today, Yesterday, n days ago
+	 * 				< 13 month	=> last month, n months ago
+	 * 				>= 13 month	=> last year, n years ago
+	 * @param \OCP\IL10N		$l			The locale to use
+	 * @return string Formatted date span
+	 */
+	public function formatDateSpan($timestamp, $baseTimestamp = null, \OCP\IL10N $l = null);
+
+	/**
+	 * Formats the time of the given timestamp
+	 *
+	 * @param int|\DateTime $timestamp
+	 * @param string	$format			Either 'full', 'long', 'medium' or 'short'
+	 * 				full:	e.g. 'h:mm:ss a zzzz'	=> '11:42:13 AM GMT+0:00'
+	 * 				long:	e.g. 'h:mm:ss a z'		=> '11:42:13 AM GMT'
+	 * 				medium:	e.g. 'h:mm:ss a'		=> '11:42:13 AM'
+	 * 				short:	e.g. 'h:mm a'			=> '11:42 AM'
+	 * 				The exact format is dependent on the language
+	 * @param \DateTimeZone	$timeZone	The timezone to use
+	 * @param \OCP\IL10N		$l			The locale to use
+	 * @return string Formatted time string
+	 */
+	public function formatTime($timestamp, $format = 'medium', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null);
+
+	/**
+	 * Gives the relative past time of the timestamp
+	 *
+	 * @param int|\DateTime	$timestamp
+	 * @param int|\DateTime	$baseTimestamp	Timestamp to compare $timestamp against, defaults to current time
+	 * @return string	Dates returned are:
+	 * 				< 60 sec	=> seconds ago
+	 * 				<  1 hour	=> n minutes ago
+	 * 				<  1 day	=> n hours ago
+	 * 				<  1 month	=> Yesterday, n days ago
+	 * 				< 13 month	=> last month, n months ago
+	 * 				>= 13 month	=> last year, n years ago
+	 * @param \OCP\IL10N		$l			The locale to use
+	 * @return string Formatted time span
+	 */
+	public function formatTimeSpan($timestamp, $baseTimestamp = null, \OCP\IL10N $l = null);
+
+	/**
+	 * Formats the date and time of the given timestamp
+	 *
+	 * @param int|\DateTime $timestamp
+	 * @param string	$formatDate		See formatDate() for description
+	 * @param string	$formatTime		See formatTime() for description
+	 * @param \DateTimeZone	$timeZone	The timezone to use
+	 * @param \OCP\IL10N		$l			The locale to use
+	 * @return string Formatted date and time string
+	 */
+	public function formatDateTime($timestamp, $formatDate = 'long', $formatTime = 'medium', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null);
+
+	/**
+	 * Formats the date and time of the given timestamp
+	 *
+	 * @param int|\DateTime $timestamp
+	 * @param string	$formatDate		See formatDate() for description
+	 * 					Uses 'Today', 'Yesterday' and 'Tomorrow' when applicable
+	 * @param string	$formatTime		See formatTime() for description
+	 * @param \DateTimeZone	$timeZone	The timezone to use
+	 * @param \OCP\IL10N		$l			The locale to use
+	 * @return string Formatted relative date and time string
+	 */
+	public function formatDateTimeRelativeDay($timestamp, $formatDate = 'long', $formatTime = 'medium', \DateTimeZone $timeZone = null, \OCP\IL10N $l = null);
+}
diff --git a/lib/public/template.php b/lib/public/template.php
index 93af794ba62..89934a842ed 100644
--- a/lib/public/template.php
+++ b/lib/public/template.php
@@ -94,6 +94,7 @@ function human_file_size( $bytes ) {
  * @param int $timestamp unix timestamp
  * @param boolean $dateOnly
  * @return \OC_L10N_String human readable interpretation of the timestamp
+ *
  * @deprecated Use \OCP\Template::relative_modified_date() instead
  */
 function relative_modified_date( $timestamp, $dateOnly = false ) {
@@ -188,12 +189,12 @@ class Template extends \OC_Template {
 	}
 
 	/**
-	 * Return the relative date in relation to today. Returns something like "last hour" or "two month ago"
-	 *
-	 * @param int $timestamp unix timestamp
-	 * @param boolean $dateOnly
-	 * @return \OC_L10N_String human readable interpretation of the timestamp
-	 */
+	* Return the relative date in relation to today. Returns something like "last hour" or "two month ago"
+	*
+	* @param int $timestamp unix timestamp
+	* @param boolean $dateOnly
+	* @return string human readable interpretation of the timestamp
+	*/
 	public static function relative_modified_date($timestamp, $dateOnly = false) {
 		return \relative_modified_date($timestamp, null, $dateOnly);
 	}
diff --git a/lib/public/util.php b/lib/public/util.php
index 793a16c4d84..7f1974a421d 100644
--- a/lib/public/util.php
+++ b/lib/public/util.php
@@ -163,6 +163,8 @@ class Util {
 	 * @param bool $dateOnly option to omit time from the result
 	 * @param DateTimeZone|string $timeZone where the given timestamp shall be converted to
 	 * @return string timestamp
+	 *
+	 * @deprecated Use \OC::$server->query('DateTimeFormatter') instead
 	 */
 	public static function formatDate($timestamp, $dateOnly=false, $timeZone = null) {
 		return(\OC_Util::formatDate($timestamp, $dateOnly, $timeZone));