Pour la classe principale de Calendar (la sous-classe de
Calendar), tout partage une API commune
(un jeu commun et complet de méthodes et de classes). Bien qu'il y ait quelques légères
différences dans certains cas spécifiques, vous devriez trouver cette API intuitive et facile à
apprendre, une fois que vous serez familier avec ce qui est disponible.
Cette section résume les méthodes communes et met en évidence les variations. Pour plus
d'informations, consultez la documentation de l'API.
Constructeurs
Le constructeur de la classe Date accepte comme arguments des valeurs de date sous forme
entières, commençant par l'année (sur la gauche) pour aller jusqu'aux secondes (sur la
droite), dépendemment de la classe que vous utilisez ;
Par exemple :
<?php
// Classes Calendar Naturelle
$Year = new Calendar_Year(2003); // 2003
$Month = new Calendar_Month(2003, 10); // Octobre 2003
l$Day = new Calendar_Day(2003, 10, 25); // 25t Octobre 2003
$Hour = new Calendar_Hour(2003, 10, 25, 13); // 25t Octobre 2003 13:00:00
$Minute = new Calendar_Minute(2003, 10, 25, 13, 31); // 25t Octobre 2003 13:31:00
$Second = new Calendar_Second(2003, 10, 25, 13, 31, 45); // 25t Octobre 2003 13:31:45
// Classes Calendar Tabulaire
$Month = new Calendar_Month_Weekdays(2003, 10); // Octobre 2003
$Month = new Calendar_Month_Weeks(2003, 10); // Octobre 2003
$Week = new Calendar_Week(2003, 10, 25); // semaine contenant le 25 Octobre 2003
?>
Notez que les classes tabulaires, Calendar_Month_Weekdays
et Calendar_Month_Weeks, prennent toutes les deux un
troisième argument optionnel (un entier) qui représente le premier jour de la semaine et
ainsi, ajuste l'affichage tabulaire (normalement, par défaut, c'est Lundi (1) - le fait de passer
l'entier de valeur 0 à pour résultat de définir le premier jour de la semaine le Dimanche, par
exemple). Calendar_Week accepte l'argument représentant le
premier jour en tant que quatrième argument de son constructeur.
Position des méthodes
Toutes les classes Date et les classes Date tabulaires partagent les méthodes définies dans
la classe d'abstraction de base Calendar.
Parmis celà, il y a des méthodes pour un objet de chacune de ces classes pour les identifier
(quelle est cette date) ainsi que pour les dates suivantes et précédentes. Par exemple :
Notez que depuis le jour $Day, je peux trouver non seulement le
jour lui même mais aussi le mois (ou l'année/l'heure/la minute/la seconde).
Notez également que prevDay() retourne 30, faisant attention que le
jour précédent est en Septembre.
Les méthodes this***(), prev***() and
next***() sont disponibles pour les années, les mois, les jours, les
heures et les secondes.
Appelez une de ces méthodes et passez la valeur TRUE vous retournera un timestamp (le
type de timestamp dépend du moteur Calendar que vous utilisez - voir la FAQ),
par exemple :
Notez la façon dont le timestamp retourné augmente dépendemment de la méthode qui l'a
appelé pour l'obtenir. Le premier, obtenu avec thisYear(TRUE)(), est
un timestamp correspondant au début de l'année 2003 (en faite, le 1er Janvier 2003) tandis
que le troisième, obtenu avec thisDay(TRUE)(), est un timestamp c
correspondant au 25 Octobre 2003.
Avertissement
Les méthodes prev***() et next***()
retournent les valeurs calculées relatif à l'objet Calendar
courant. Dans l'exemple ci-dessus, si vous aviez voulu le jour
et le mois du jour suivant (qui doit être le 2 Octobre 2003),
appelez la méthode nextDay() puis
nextMonth(), ce qui vous donnera le 2
Novembre et non pas Octobre. A la place, vous devriez appeler
nextDay() en y passant l'argument TRUE pour récupérer le
timestamp du jour suivant. Faites attention à
Calendar_Decorator_Uri qui a été faite pour vous aider à
construire des URLs pour les liens suivants et précédants.
Il y a ausi les méthodes thisWeek(),
prevWeek() et nextWeek() qui ne deviennent
disponible que si vous utilisez une instance de la classe
Calendar_Week. Le format de la valeur retournée peut être
choisi parmis 'timestamp', 'n_in_month', 'n_in_year' or 'array'. Soyez prudent si vous
choisissez 'n_in_month', il retournera NULL s'il est sur le début ou la fin du mois.
Finallement, tous les objets Calendar fournissent les méthodes
getTimeStamp() et setTimeStamp(). Le premier
retourne un timestamp dans le format utilisé par le moteur Calendar que vous utilisé (i.e. Un
timestamp Unix si le moteur utilisé est le moteur UnixTs ou un format YYYY-MM-DD
HH:MM:SS). Le second attend un timestamp qui sera utilisé pour remplacer les valeurs
construites avec l'objet Calendar.
Construction et Récupération
Toute les classes Date et les classes tabulaires Date ont une méthode
build() qui est utilisée pour générer un fils de cet objet Date. Par
exemple, Calendar_Month construit l'objet
Calendar_Day ; le jour devient ainsi un
fils du mois.
Une fois que build() a été appelé, le fils peut être analysé depuis
l'objet Date en utilisant un simple itérateur fetch(), par exemple :
<?php
$Month = new Calendar_Month(2003, 10);
$Month->build();
while ($Day = $Month->fetch()) {
echo $Day->thisDay()."<br />\n";
}
?>
La méthode fetch() retourne un fils pour un instant, dans l'ordre
croissant des dates et retourne FALSE lorsqu'il n'y a plus de fils disponible. Il réinitialise
également automatiquement le collecteur interne de fils, ce qui signifie que vous pouvez
boucler sur celui-ci autant de fois que vous le voulez.
Si vous n'aimez pas l'itérateur et que vous voulez utiliser le votre, vous pouvez simplement
extraite le fils avec la méthode fetchAll() (qui retourne un tableau
indexé d'objets de fils de date) et vérifiez le numéro obtenu avec la fonction
size(). Soyez prudent avec l'index du tableau que vous obtenez de
fetchAll(). Pour les méthodes
Calendar_Year, Calendar_Month,
Calendar_Month_Weekdays,
Calendar_Month_Weeks et
Calendar_Week, le premier index du tableau vaut 1 tandis que
pour les méthodes Calendar_Day,
Calendar_Hour, Calendar_Minute
et Calendar_Second, l'index du tableau commence à 0.
Pourquoi ? Considérez 2003-1-1 00:00:00 ...
Note : Calendar_Second::build() ne fait rien du tout - il n'a aucun fils.
Sélectionnez un fils
Pour vous aider dans l'affichage du calendrier, la méthode build()
accepte un tableau indexé d'objets de date qui est comparé avec le fils construit. Si elle
trouve qu'un objet passé correspond à un fils, elle définie le statut de ce fils comme
sélectionné, ce qui signifie que la méthode isSelected() (disponible
sur tous les objets Date ainsi que les objets tabulaires de dare) retournera TRUE. Par
exemple :
<?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"; // Affiche 15 ou 23
}
}
?>
Dans l'exemple ci-dessus, seuls les 15 Octobre 2003 et 23 Octobre 2003 sont affichés.
L'objet que vous passez à build() qui correspond à un fils qui a été
construit, remplace le fils (i.e. s'il n'y avait pas de
correspondance, vous récupérerez votre objet). Celà vous permet d'injecter votre propre
objet dans la boucle, ce qui est mieux que d'étendre la classe
Calendar_Decorator.
Note : La méthode
Calendar_Year::build() prend un second
argument pour spécifier le premier jour de la semaine (voir ci-dessus la discussion sur les
constructeurs).
Jours tabulaires
La classe Calendar_Day a trois méthodes uniquement, qui
n'apparaissent nulle part ailleurs et sont utilisées pour construire les calendriers tabulaires.
isEmpty() est utilisé pour déterminer si oui ou non un jour est vide
(voir la FAQ pour la signification d'un jour vide). Les méthodes isFirst()
et isLast() sont utilisées pour marquer le début et la fin d'une
semaine.
L'utilisation de ces classes dépend de la classe utilisée pour construire l'objet Date. Si le
jour a été construit avec Calendar_Month_Weekdays, tous les
arbres de cette méthode sont applicables (vous devriez avoir des jours vides ainsi que
Calendar_Month_Weekdays construit un mois complet mais
délimite le début et la fin de chaque semaine, donc vous pouvez le trouver avec
isFirst() et isLast()). Si le jour a été construit
avec Calendar_Week, seul la méthode
isEmpty() est applicable (la première ou la dernière semaine du mois
contient surement des jours vides). Pour les objets Jours construient d'une toute autre
façon, isEmpty(), isFirst() et
isLast() sont sans signification.
Validation
Tous les objets Date et les objets Date tabulaire (excepté les semaines) sont capables de
s'auto-valider. Par défaut, ils acceptent les arguments données pour la construction mais
vous pouvez valider la date avec la méthode isValid(), par exemple :
<?php
$Day = new Calendar_Day(2003, 10, 32);
if (!$Day->isValid()) {
die ('Date invalide');
}
?>
Pour une validation plus fine, vous pouvez appeler tout d'abord la méthode
getValidator() qui va vour retourner une instance de
Calendar_Validator et donc, lister les erreurs de validation :
<?php
$Day = new Calendar_Day(2003, 10, 32);
if (!$Day->isValid()) {
$Validator = & $Day->getValidator();
while ($Error = $Validator->fetch()) {
echo $Error->getUnit().' est invalide<br />';
}
}
?>
ou...
<?php
$Day = new Calendar_Day(2003, 10, 32);
$Validator = & $Day->getValidator();
if (!$Validator->isValid()) {
while ($Error = $Validator->fetch()) {
echo $Error->toString().'<br />';
}
}
?>
Notez que plutôt de valider les dates, vous pouvez préférer les ajuster
automatiquement avec la méthode adjust(), par exemple :
<?php
$Day = new Calendar_Day(2003, 10, 32);
$Day->adjust();
echo $Day->thisYear(); // 2003
echo $Day->thisMonth(); // 11 (se déplace d'un mois)
echo $Day->thisDay(); // 1 (le premier du mois)
?>
Celà résume les méthodes disponibles avec PEAR::Calendar, mis à part celles
provenant des classes de décoration.
