メソッドの概要

メソッドの概要

メインとなるカレンダーのクラス (Calendar のサブクラス) はすべて共通 API (共通のクラスメソッド) を共有しています。あるクラスでは細かなバリエーションがありますが、なにが利用できるかを一度知ってしまえば、直感的に理解し、容易に思い出すことができるでしょう。このセクションでは共通のメソッドを要約し、このバリエーションを強調します。詳しい情報は API のドキュメントをみてください。

コンストラクタ

データクラスのコンストラクタは日付の数値を引数にとります。年のはじまり (左側) から秒 (右側) までです。これはあなたの利用するクラスに依存します。たとえば、

<?php
// 普通のカレンダークラス
$Year = new Calendar_Year(2003);                         // 2003
$Month = new Calendar_Month(2003, 10);                   // 2003年10月
$Day = new Calendar_Day(2003, 10, 25);                   // 2003年10月25日
$Hour = new Calendar_Hour(2003, 10, 25, 13);             // 2003年10月25日 13:00:00
$Minute = new Calendar_Minute(2003, 10, 25, 13, 31);     // 2003年10月25日 13:31:00
$Second = new Calendar_Second(2003, 10, 25, 13, 31, 45); // 2003年10月25日 13:31:45

// 表形式のカレンダークラス
$Month = new Calendar_Month_Weekdays(2003, 10);          // 2003年10月
$Month = new Calendar_Month_Weeks(2003, 10);             // 2003年10月
$Week = new Calendar_Week(2003, 10, 25);                 // 2003年10月25日を含む週
?>

位置づけ用メソッド

すべての日付クラス・表形式日付クラスは、抽象基本クラスの Calendar で定義されたメソッドを共有しています。これらの中にはオブジェクト自体の日付を識別するメソッドや以前の日付、次の日付を識別するメソッドがあります。例えば、

<?php
// 日の作成
$Day = new Calendar_Day(2003, 10, 1); // 2003年10月1日

echo $Day->thisDay(); // 1日を表示
echo $Day->prevDay(); // 30日を表示 (9月30日)
echo $Day->nextDay(); // 2日を表示

echo $Day->thisMonth(); // 10月を表示
echo $Day->prevMonth(); // 9月を表示
echo $Day->nextMonth(); // 11月を表示
?>

これらのメソッドに TRUE を渡すと、タイムスタンプ形式で結果をかえします (タイムスタンプの形式は使用しているカレンダーエンジンによります。FAQ を参照ください)。例えば、

<?php
// 秒の作成
$Second = new Calendar_Second(2003, 10, 25, 13, 32, 44);

echo $Second->thisYear(TRUE);     // 1041375600 を表示
echo $Second->thisMonth(TRUE);    // 1064959200 を表示
echo $Second->thisDay(TRUE);      // 1067032800 を表示
echo $Second->thisHour(TRUE);     // 1067079600 を表示
echo $Second->thisMinute(TRUE);   // 1067081520 を表示
echo $Second->thisSecond(TRUE);   // 1067081564 を表示
?>

thisWeek(), prevWeek() および nextWeek() といったメソッドもあります。これらのメソッドはCalendar_Week のインスタンスを使用している場合のみ利用することができます。返される値のフォーマットは'timestamp', 'n_in_month', 'n_in_year' あるいは 'array' の中から選択することができます。'n_in_month' を選択した場合に、月のはじまりか終わりになってしまった場合には NULL 値が返されることに注意してください。

最後になりますが、すべてのカレンダーオブジェクトは getTimeStamp() と setTimeStamp() メソッドを提供します。前者はあなたが利用しているカレンダーエンジンのフォーマットでのタイムスタンプを返します (例えば、もしデフォルトの Unix タイムエンジンを使用しているなら、Unix 形式のYYYY-MM-DD HH:MM:SS というフォーマットのタイムスタンプです)。後者はカレンダーオブジェクトが構築した値を変換するのに用いたタイムスタンプを除外します。

構築および取得

すべての日付クラス、表形式の日付クラスは、データオブジェクトの子供を作るためのbuild() メソッドを持っています。たとえば、Calendar_Month は月の"子供"の存在である Calendar_Day オブジェクトをビルドします。

一度 build() が呼び出されると、子供は単純な fetch() イテレータを使用して日付オブジェクトから取り出すことができます。例えば、

<?php
$Month = new Calendar_Month(2003, 10);

$Month->build();

while ($Day = $Month->fetch()) {
    echo $Day->thisDay()."<br />\n";
}
?>

もしあなたがこのようなイテレータを好まず、独自のものを使用したいと望むなら、単純に子供を fetchAll() メソッド (子供の日付オブジェクトをインデックス化された配列で返します) で取り出し、size()　でその数をチェックすることができます。fetchAll() で返されるインデックスに注意してください。Calendar_Year, Calendar_Month, Calendar_Month_Weekdays, Calendar_Month_Weeks そして Calendar_Weekではインデックスの最初の値は 1 です。一方で、Calendar_Day, Calendar_Hour, Calendar_Minute そして Calendar_Second ではインデックスの最初の値は 0 です。なぜでしょうか? 次のような表記を考えてみてください。 2003-1-1 00:00:00 ...

注意: Calendar_Second::build() は実際には何もしません。これは子要素をもたないからです。

子要素の選択

カレンダーのレンダリングを簡単にするために、build() メソッドは子供のオブジェクトと比較する日付オブジェクトの配列を受け取ることができます (どの日付のオブジェクトやtabular日付のオブジェクトでも利用することができます)。配列のオブジェクトが子要素とマッチする場合は、その要素が選択状態となり、isSelected()メソッド (これはあらゆる日付オブジェクト・表形式日付オブジェクトで使用可能です) は TRUE を返します。例えば、

<?php
$Month = new Calendar_Month(2003, 10);

$DayX = new Calendar_Day(2003, 10, 15);
$DayY = new Calendar_Day(2003, 10, 23);
$selection = array($DayX, $DayY);

$Month->build($selection);

while ($Day = $Month->fetch()) {
    if ($Day->isSelected()) {
        echo $Day->thisDay()."<br />\n"; // 15 あるいは 23 を表示
    }
}
?>

build() に渡したオブジェクトのうち、子要素とマッチするオブジェクトは子要素を置き換えます (つまり、マッチした要素については、その要素がそのまま戻されます)。これをうまく利用すると、オブジェクトをループの中に "組み込む" ことができるようになります。一般的には、これは Calendar_Decorator を拡張することによって行います。

注意: Calendar_Year::build() メソッドは 2 番目の引数に週のはじまりの曜日をとります (コンストラクタに関する上の記述を参照ください)。

表形式の日付

Calendar_Day クラスは 3 つの独自のメソッドを持っています。これらのメソッドは他のクラスには存在せず、純粋に表形式カレンダーを作成するために用いられます。isEmpty() は日にちが空白かどうかを判断するために用いられます (FAQ の空白の日にちの説明を参照してください)。isFirst() と isLast() は週のはじまりと終わりを区別するために使用されます。

あなたがこれらのメソッドを使用する必要があるかどうかは、日付オブジェクトを構築するするのにどのクラスを使用したかによります。もし、日付オブジェクトが Calendar_Month_Weekdays によって構築されたのなら、これら 3 つのメソッドのどれもを利用することができます (空の日付があってもかまいません。Calendar_Month_Weekdays で完全な月を作成し、それぞれの週のはじまりとおわりが区切られるので、isFirst() と isLast() によって判断することができます)。Calendar_Week によって日付が作られれたなら、isEmpty() メソッドだけが利用できます (月の最初と最後の週には空白の日付が含まれる可能性があります)。他の方法で日付オブジェクトが作成された場合、isEmpty(), isFirst() と isLast() は無意味です。

バリデーション

すべての日付オブジェクトと表オブジェクト (週を除く) は、自分自身の妥当性を検証する機能をもっています。デフォルトではどのような引数もコンストラクタに渡すことができますが、isValid() メソッドを用いて日付を検証することができます。例えば、

<?php
$Day = new Calendar_Day(2003, 10, 32);

if (!$Day->isValid()) {
    die ('無効な日付です');
}
?>

<?php
$Day = new Calendar_Day(2003, 10, 32);

if (!$Day->isValid()) {
    $Validator = & $Day->getValidator();
    while ($Error = $Validator->fetch()) {
        echo $Error->getUnit().' は無効です<br>';
    }
}
?>

<?php
$Day = new Calendar_Day(2003, 10, 32);

$Validator = & $Day->getValidator();
if (!$Validator->isValid()) {
    while ($Error = $Validator->fetch()) {
        echo $Error->toString().'<br>';
    }
}
?>

日付を検査するよりは、むしろ adjust() メソッドを使って日付を自動的に調整するほうがよいことに注意してください。

<?php
$Day = new Calendar_Day(2003, 10, 32);

$Day->adjust();

echo $Day->thisYear();      // 2003
echo $Day->thisMonth();     // 11 (翌月に移動)
echo $Day->thisDay();       // 1  (月初)
?>

ここでは、PEAR::Calendar で利用できるメソッドのうち、Decorator クラスによって提供されるものを除くすべてをまとめました。