メソッドの概要
メソッドの概要
メインとなるカレンダーのクラス (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_Month_Weekdays と Calendar_Month_Weeks は、どちらもオプションで 3 番目の引数をとることに注意しましょう。この引数 (integer) は週の最初の曜日を決定し、表形式の表示を調整します (デフォルトは月曜日(1)です - 例えば、数値を 0 に変更すると日曜日が週の最初の曜日になります)。Calendar_Week は、コンストラクタの 4 番目の引数で週の最初の曜日を引数として受け取ることができます。
位置づけ用メソッド
すべての日付クラス・表形式日付クラスは、抽象基本クラスの 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月を表示
?>
$Day からは、日付だけではなく月 (あるいは年/時間/分/秒) も取得できることに注目しましょう。また、前日が 9 月であることをきちんと考慮したうえで、prevDay() が 30 を返していることにも注目しましょう。this***()、prev***() と next***() メソッドは、年・月・日・時・分・秒のそれぞれに対応するものが存在します。
これらのメソッドに 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 を表示
?>
取得するために呼び出されたメソッドによって、タイムスタンプの増加量が異なることに注目しましょう。最初の値は thisYear(TRUE)() によって得られたタイムスタンプで、2003 年のはじまり (つまり 2003 年 1 月 1 日) のものです。一方で、3 つめのものは thisDay(TRUE)() によって得られたタイムスタンプで、2003 年 10 月 25 日のものです。
prev***()とnext***()からはじまるメソッドは、現在使用中のカレンダーオブジェクトのとの相対的な値を計算して返します。上記の例では、次の日(2003年10月2日)の日と月の値を得たい際に nextDay()を呼びだして、nextMonth()を呼び出すこと、10 月ではなく 11 月 2 日の値を得ることになってしまいます。 そうではなく、nextDay() に引数 TRUE を指定してコールすることで、次の日のタイムスタンプを取得することができます。次へ/前へのリンクを作成することを助けるように設計された Calendar_Decorator_Uri も見てください。
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";
}
?>
fetch()メソッドは、日付の昇順で 1 回に 1 つの子供を返します。もうそれ以上子供が見つからない場合には FALSE を返します。そして自動的に内部の子供の集合がリセットされます。よって好きな回数だけこれらをループさせて使用することができます。
もしあなたがこのようなイテレータを好まず、独自のものを使用したいと望むなら、単純に子供を 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 を表示
}
}
?>
上の例では、2003 年 10 月 15 日と 2003 年 10 月 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 ('無効な日付です');
}
?>
より精密に検査するには、最初に getValidator() メソッドを呼び出し、Calendar_Validator のインスタンスを受け取ってから検証エラーを調べます。
<?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 クラスによって提供されるものを除くすべてをまとめました。
忘却曲線を使ってこの知識を確実に記憶に残す
