Zend_Date
の API はシンプルで統一性がありますが、
非常に柔軟で強力な設計になっており、
さまざまな操作や演算ができます。
Zend_Date
オブジェクトの作成によって入力が正規化されると、
このオブジェクトはタイムゾーンに関連付けられます。しかし、内部的な形式としては通常の
UNIX タイムスタンプを使用します。
各地域固有の方式で日付を表示するには、まずタイムゾーンを知る必要があります。
デフォルトのタイムゾーンは常に GMT/UTC です。オブジェクトのタイムゾーンを調べるには
getTimeZone())
を使用します。オブジェクトのタイムゾーンを変更するには
setTimeZone())
を使用します。
これらのオブジェクトに対するすべての操作は、このタイムゾーンを想定して行われます。
異なるタイムゾーンの日付オブジェクトを混在させないよう注意しましょう。
タイムスタンプにのみかかわる操作しかしないのならよいのですが、
それ以外の場合には期待通りの結果が得られなくなるでしょう。
異なるタイムゾーンの Zend_Date
に対する操作は、
たいていの場合はうまく動作します。というのも Zend_Date
のインスタンスを作成する際に、値が UNIX タイムスタンプに正規化されるからです。
ほとんどのメソッドで、引数 $part
に定数を指定できます。
これにより、日付のどの部分を選択するかを指定します。この定数は、
たとえば Zend_Date::HOUR
のようになります。
これらの定数は、以下のすべての関数で使用できます。使用可能なすべての定数の一覧は
項8.5.2. 「全定数の一覧」 にあります。
$part
を省略した場合は、Zend_Date::TIMESTAMP
が指定されたものとみなします。また、ユーザ定義の書式を
$part
で使用することもできます。ここには、
Zend_Locale_Format::getDate()
と同様のコードを使用します。
日付オブジェクトが明らかに無効な値を用いて作成された場合 (たとえば月が 12 より大きいなど) は、
Zend_Date
は例外をスローします。ただし、特定の日付フォーマットが指定されている場合、
つまり $part
が null
あるいは Zend_Date::DATES
("あいまいな" フォーマット)
のいずれかである場合は別です。
例 8.8. ユーザ定義の入力日付書式
<?php $date1 = new Zend_Date('Feb 31, 2007', null, 'en_US'); echo $date1, "\n"; // 出力は "Mar 3, 2007 12:00:00 AM" となります $date2 = new Zend_Date('Feb 31, 2007', Zend_Date::DATES, 'en_US'); echo $date2, "\n"; // 出力は "Mar 3, 2007 12:00:00 AM" となります $date3 = new Zend_Date('Feb 31, 2007', 'MM.dd.YYYY'); // 指定したフォーマットで解釈するように強制します echo $date3, "\n"; // 出力は "Mar 3, 2007 12:00:00 AM" となります ?>
オプションのパラメータ $locale
を指定すると、
その $locale
をもとに $date
オペランドを解決します。
つまり、日付文字列に含まれる月名や曜日名などを、そのロケールにあわせて適切に解釈します
(
Zend_Locale_Format::getDate()
を参照ください)。
各地域固有の形式の文字列で $date
オペランドが指定された際に
自動で正規化が行われるのは、$part
が
定数 Zend_Date::DATE*
あるいは Zend_Date::TIME*
のいずれかであるときです。
$date
が日付を含む文字列の場合は、
月名や曜日名をパースする際に使用する言語はロケールをもとに決定します。
入力パラメータ $date
が指定されなかった場合は、
$locale
パラメータの内容をもとにして地域化した結果
(日付書式を文字列で表したもの) を出力します。
入力パラメータ $date
に具体的な型が指定されている場合もあります
(たとえば addHour()
では $hour
です)。
このような場合でも、引数として Zend_Date
オブジェクトを使用できることに注意しましょう。
$locale
を指定しなかった場合は、
現在のオブジェクトのロケールを使用して
$date
を解釈します。あるいは出力用書式を選択します。
メソッド add(), sub(), compare(), get(), and set()
は、日付全般に対して使用できます。それぞれのメソッドは、
そのインスタンスが保持する日付の値を操作します。
これらのメソッドのうち、get()
以外ではすべて $date
オペランドが必要となります。
ここには Zend_Date
のインスタンスか
数値文字列、あるいは整数値を指定します。
これらのメソッドで $date
にオブジェクト以外を指定した場合、
それはタイムスタンプであるとみなされます。
しかし、$part
オペランドを使用すると、
ふたつの日付データが日付のどの部分を表すものなのかを指定できます。
たとえば "年"、"分" などが指定できます。それだけではなく、
"December 31, 2007 23:59:59" のような長い形式の文字列も
$date
に指定できます。
compare()
および get()
以外のメソッドは、処理の結果としてオブジェクト内の日付が変更されます。
例 8.9. 日付要素の操作
<?php require_once 'Zend/Date.php'; $date = new Zend_Date(); // $date のタイムスタンプは time() の返す値と等しくなります // $date に 12 時間足します $date->add('12', Zend_Date::HOUR); print $date; ?>
基本的な操作について、一般的な日付要素と組み合わせて使用する際に
便利なメソッドが用意されています。
これらのメソッドを使用すると、上で説明したメソッドのように
日付要素の定数
をいちいちタイプする必要がなくなります。
好都合なことに、これらのメソッドの名前は
プレフィックス (基本操作の名前) とサフィックス (日付要素の名前)
を組み合わせた形式、たとえば addYear()
のようになっています。以下の一覧における、すべての
"日付要素" と "基本操作" の組み合わせが存在します。
たとえば "add" は、各要素について
addDay()
や addYear()
などといったメソッドが存在します。
これらの便利なメソッドの機能は、基本操作メソッドと同等です。
しかし、$date
オペランドに文字列や整数値を使用する場合は、
メソッド名のサフィックスが指す日付要素以外を指定することはできません。
つまり、$date
が文字列あるいは整数値の場合は、
$date
オペランドの単位が
メソッド名によって ("Year" や "Minute" などに) 決まるということです。
表 8.1. 日付要素
日付要素 | 説明 |
---|---|
Timestamp (タイムスタンプ) | UNIX タイムスタンプ。January 1st, 1970 00:00:00 GMT/UTC からの経過秒数です。 |
Year (年) | グレゴリオ暦の年 (例: 2006)。 |
Month (月) | グレゴリオ暦の月 (1-12、各地域固有の名前もサポートしています)。 |
24 hour clock (24 時間の時間) | その日の時間 (0-23)。これは、その日がはじまってからの経過時間数を表します。 |
minute (分) | 時間内の分 (0-59)。これは、その時間がはじまってからの経過分数を表します。 |
Second (秒) | 分内の秒 (0-59)。これは、その分が始まってからの経過秒数を表します。 |
millisecond (ミリ秒) |
ミリ秒 (0-999)。これは、千分の一秒を表します。
Zend_Date では、秒未満の単位を扱うために
二つのメソッドを用意しています。デフォルトでは、
Zend_Date のインスタンスはミリ秒単位の精度を使用します。
これは getFractionalPrecision() を使用して取得します。
精度を変更するには setFractionalPrecision($precision)
を使用します。しかし、精度は事実上ミリ秒までに制限されます。
というのも、Zend_Date は
microtime()
を使用しているからです。
|
Day (日) |
Zend_Date::DAY_SHORT は $date
から抽出します。これは、$date オペランドが
Zend_Date のインスタンスであるか、
あるいは数値文字列である場合に行われます。
それ以外の場合は、以下の定数によって指定した規約に基づいて抽出します。
Zend_Date::WEEKDAY_NARROW 、Zend_Date::WEEKDAY_NAME 、
Zend_Date::WEEKDAY_SHORT 、
Zend_Date::WEEKDAY (グレゴリオ暦とみなして処理します)。
|
Week (週) |
Zend_Date::WEEK は $date
から抽出します。これは、$date オペランドが
Zend_Date のインスタンスであるか、
あるいは数値文字列である場合に行われます。
それ以外の場合は例外が発生します (グレゴリオ暦とみなして処理します)。
|
Date (日) |
Zend_Date::DAY_MEDIUM は $date
から抽出します。これは、$date オペランドが
Zend_Date のインスタンスである場合に行われます。
それ以外の場合は、文字列 $date
を正規化して Zend_Date::DATE_MEDIUM 形式の日付にしようとします。
Zend_Date::DAY_MEDIUM の書式は、
そのオブジェクトのロケールに依存します。
|
Weekday (曜日) |
曜日は、0 (日曜日) から 6 (土曜日) までの数字で表されます。
Zend_Date::WEEKDAY_DIGIT は $date
から抽出します。これは、$date オペランドが
Zend_Date のインスタンスであるか、
あるいは数値文字列である場合に行われます。
それ以外の場合は、以下の定数によって指定した規約に基づいて抽出します。
Zend_Date::WEEKDAY_NARROW 、Zend_Date::WEEKDAY_NAME 、
Zend_Date::WEEKDAY_SHORT 、
Zend_Date::WEEKDAY (グレゴリオ暦とみなして処理します)。
|
DayOfYear (年内の日数) |
Zend_Date では、これは年初からの経過日数
(0-365) を表します。これまでの他の単位と同様、
端数は切り捨てられます (グレゴリオ暦とみなして処理します)。
|
Arpa |
Arpa 日付 (つまり RFC 822 形式の日付) をサポートしています。
出力形式は、"GMT" あるいは "地方時 + 時差" 形式になります
(RFC 822 の section 5 を参照ください)。
PHP 5.2.2 より前のバージョンでは、定数 DATE_RFC822 を
PHP の日付関数で使用したときに
おかしな結果
となる場合がありました。Zend_Date は、正しい結果を返します。
例: Mon, 31 Dec 06 23:59:59 GMT
|
Iso |
出力形式として、完全な ISO 8601 日付のみをサポートしています。
例: 2009-02-14T00:31:30+01:00
|
便利なメソッド群ではなく以下の基本操作を使用する場合には、
適切な定数
を $part
パラメータで指定します。
表 8.2. 基本操作
基本操作 | 説明 |
---|---|
get() |
get($part = null, $locale = null)
|
set() |
set($date, $part = null, $locale = null)
ロケール |
add() |
add($date, $part = null, $locale = null)
ロケール |
sub() |
sub($date, $part = null, $locale = null)
ロケール |
copyPart() |
copyPart($part, $locale = null)
オブジェクトの複製を返します。もとのオブジェクトの日付のうち
|
compare() |
compare($date, $part = null, $locale = null)
|
以下の基本操作については、 項8.4. 「Zend_Date API の概要」 の一覧にある各日付要素に特化した便利なメソッドは存在しません。
表 8.3. 日付の比較用メソッド
メソッド | 説明 |
---|---|
equals() |
equals($date, $part = null, $locale = null)
ロケール |
isEarlier() |
isEarlier($date, $part = null, $locale = null)
このオブジェクトの日付要素 |
isLater() |
isLater($date, $part = null, $locale = null)
このオブジェクトの日付要素 |
isToday() |
isToday() 今日の年月日が、このオブジェクトの日付と一致するかどうかを調べます (このオブジェクトのタイムゾーンを用いて判断します)。 |
isTomorrow() |
isTomorrow() 明日の年月日が、このオブジェクトの日付と一致するかどうかを調べます (このオブジェクトのタイムゾーンを用いて判断します)。 |
isYesterday() |
isYesterday() 昨日の年月日が、このオブジェクトの日付と一致するかどうかを調べます (このオブジェクトのタイムゾーンを用いて判断します)。 |
isLeapYear() |
isLeapYear()
|
Zend_Date
インスタンスに関する情報の取得をサポートするメソッド群について説明します。
表 8.4. 日付出力用のメソッド
メソッド | 説明 |
---|---|
toString() |
toString($format = null, $locale = null)
直接実行することもできますし、マジックメソッド |
toValue() |
toValue($part = null)
指定した日付要素 |
get() |
get($part = null, $locale = null)
このメソッドは、オブジェクトの日付要素 |
now() |
now($locale = null)
この関数は、 |
Zend_Date
インスタンスに関する情報の取得をサポートするメソッド群について説明します。