Joomla! Documentation™

介紹

Joomla 的 Date class 是一個 helper class，它擴展了 PHP 的 DateTime class，也就是可以讓開發者更有效地處理日期格式。這個 class 讓開發者可以格式化日期為可讀格式、 MySQL 互動、UNIX 時間戳計計算，也提供 helper 方法來表示不同時區的數值。

關於 JDate" class name： 本頁面內容已經更新為使用命名空間的 class names。 整個 Joomla! 說明文件中您會看到 `JDate`、 `JApplication` 以及其他類似的命名 class，其實是class 別名，為了相容舊版本的原因而如此維護。我們推薦使用命名空間來取用Joomla class，這樣可以讓編輯器提示您程式碼以及檢查程式，有助於您的開發體驗，減少錯誤。

在這個Joomla codebase 檔案中 您可以查看完整的 class 別名清單

建立 Date Instance

所有的 date helper 方法都需要一個 Date class 的 instance。一開始，您需要建立一個。有兩種方式可以建立 Date object，其一是典型的作法，建立一個新的 instance：

use Joomla\CMS\Date\Date;

$date = new Date(); // Creates a new Date object equal to the current time.

您也可以使用定義於 Date 中的靜態方法來建立instance

use Joomla\CMS\Date\Date;

$date = Date::getInstance(); // Alias of 'new Date();'

這兩種方法沒有差別，因為 Date::getInstance 僅僅是建立新的Date instance，完全和第一種方法一樣。

另外，您也可以從 Application object 獲得當前日期時間 (為 Date 物件)。方法是使用：

use Joomla\CMS\Factory;

$date = Factory::getDate();

語法

Date 結構 (以及 getInstance 靜態方法) 接受兩個選填參數：準備要格式化的日期字串以及時區。沒有傳遞 date 字串的話，會用當前的日期時間建立一個 Date 物件，而如果沒有傳遞時區的話，會讓 Date 物件使用預設的時區設定。

如果使用的話，第一個語法，應該要是要能用PHP 原生 DateTime constructor 解析的字串，例如：

use Joomla\CMS\Date\Date;

$currentTime = new Date('now'); // Current date and time
$tomorrowTime = new Date('now +1 day'); // Current date and time, + 1 day.
$plus1MonthTime = new Date('now +1 month'); // Current date and time, + 1 month.
$plus1YearTime = new Date('now +1 year'); // Current date and time, + 1 year.
$plus1YearAnd1MonthTime = new Date('now +1 year +1 month'); // Current date and time, + 1 year and 1 month.
$plusTimeToTime = new Date('now +1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$plusTimeToTime = new Date('now -1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$combinedTimeToTime = new Date('now -1 hour -30 minutes 23 seconds'); // Current date and time, - 1 hour, +30 minutes and +23 seconds

$date = new Date('2012-12-1 15:20:00'); // 3:20 PM, December 1st, 2012

Unix 時間戳計 (以秒計算) 也可以傳遞，如同第一個語法一樣。數值會被轉換為日期時間。如果第二個參數有指定時區值到結構中，時間會根據時區值來轉換。

輸出日期

需要注意的是，當您在user context 輸出日期物件(Date object)時，不要只是print到畫面上。日期 物件的 toString() 方法僅僅呼叫它的父層 format() 方法，而沒有根據時區或自定義日期格式來結構。這不會有好的用戶體驗，而且可能會在您的擴充套件及 Joomla! 其他地方，導致不一致的結果。相反地，您需要使用以下的方法來輸出日期：

一般日期格式

有幾個日期格式是預先準備的 Joomla! 基礎語言包的一部分。這有助於更容易地國際化，會是有助益的。從en-GB 語言包找到的可以用的格式列在底下，高度建議您在輸出日期時，善用這些格式化字串，這樣您的日期會自動格式化為用戶自訂的樣式。在任何的語言字串中，它們可以用同樣的方式來取得 (範例請見底下)。

DATE_FORMAT_LC="l, d F Y"
DATE_FORMAT_LC1="l, d F Y"
DATE_FORMAT_LC2="l, d F Y H:i"
DATE_FORMAT_LC3="d F Y"
DATE_FORMAT_LC4="Y-m-d"
DATE_FORMAT_LC5="Y-m-d H:i"
DATE_FORMAT_LC6="Y-m-d H:i:s"
DATE_FORMAT_JS1="y-m-d"
DATE_FORMAT_CALENDAR_DATE="%Y-%m-%d"
DATE_FORMAT_CALENDAR_DATETIME="%Y-%m-%d %H:%M:%S"
DATE_FORMAT_FILTER_DATE="Y-m-d"
DATE_FORMAT_FILTER_DATETIME="Y-m-d H:i:s"

HtmlHelper 方法 (推薦使用)

一如許多的通用輸出項目，HtmlHelper class 也準備好要提供...help! HtmlHelper 的 date() 方法會接受任何日期結構允許的日期時間字段，以及格式化字段，並合適地輸出當前用戶所在的時區。也因為如此，我們推薦使用這個方法來為會員輸出日期。

use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;

$myDateString = '2012-12-1 15:20:00';
echo HtmlHelper::date($myDateString, Text::_('DATE_FORMAT_FILTER_DATETIME'));

日期物件 (Date Object) 的 format() 方法

另一個選項是手動格式化日期。假如使用這個方法，您會需要手動獲取以及設定用戶的時區。要在用戶介面之外格式化日期時間，例如在系統 log 記錄或是 API 呼叫中，這個方法會更有用。

use Joomla\CMS\Language\Text;
use Joomla\CMS\Date\Date;
use Joomla\CMS\Factory;

$myDateString = '2012-12-1 15:20:00';
$timezone = Factory::getUser()->getTimezone();

$date = new Date($myDateString);
$date->setTimezone($timezone);
echo $date->format(Text::_('DATE_FORMAT_FILTER_DATETIME'));

其他有用的程式碼範例

輸出當前時間

有兩種簡單的方法可以做到這個：

1. 使用 HtmlHelper 的 date( ) 方法，如果沒有提供日期值，預設會輸出當前的時間
2. Factory::getDate( ) 會取得當前時間來當成 Date 物件，接著我們就可以改成想要的格式

use Joomla\CMS\Factory;
use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;

// These two are functionally equivalent
echo HtmlHelper::date('now', Text::_('DATE_FORMAT_FILTER_DATETIME'));

$timezone = Factory::getUser()->getTimezone();
echo Factory::getDate()->setTimezone($timezone)->format(Text::_('DATE_FORMAT_FILTER_DATETIME'));

加入及取出日期

因為 Joomla Date 物件擴展了 PHP 的 DateTime 物件，它提供了新增及減去日期的方法。最見單的方式是使用modify() 方法，which accepts any relative modification string that the PHP strtotime() 方法也會可以接受。例如：

use Joomla\CMS\Date\Date;

$date = new Date('2012-12-1 15:20:00');
$date->modify('+1 year');
echo $date->toSQL(); // 2013-12-01 15:20:00

另外也有 add() 以及 sub() 方法可以使用，來對日期物件做出加或減。這些方法接受 PHP-標準 DateInterval 物件：

use Joomla\CMS\Date\Date;

$interval = new \DateInterval('P1Y1D'); // Interval represents 1 year and 1 day

$date1 = new Date('2012-12-1 15:20:00');
$date1->add($interval);
echo $date1->toSQL(); // 2013-12-02 15:20:00

$date2 = new Date('2012-12-1 15:20:00');
$date2->sub($interval);
echo $date2->toSQL(); // 2011-11-30 15:20:00

用 ISO 8601 格式輸出日期

$date = new Date('2012-12-1 15:20:00');
$date->toISO8601(); // 20121201T152000Z

用 RFC 822 格式輸出日期

$date = new Date('2012-12-1 15:20:00');
$date->toRFC822(); // Sat, 01 Dec 2012 15:20:00 +0000

用 SQL Date-Time 格式輸出日期

$date = new Date('20121201T152000Z');
$date->toSQL(); // 2012-12-01 15:20:00

用 Unix 格式輸出日期

Unix 時間戳記表示為 Unix Epoch (從1970年七月一日起)計算的秒數。

$date = new Date('20121201T152000Z');
$date->toUnix(); // 1354375200