Aperçu de la méthode

Aperçu de la méthode – Résumé de l'API Calendar

Aperçu de la méthode

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(200310);                   // Octobre 2003
l$Day = new Calendar_Day(20031025);                   // 25t Octobre 2003
$Hour = new Calendar_Hour(2003102513);             // 25t Octobre 2003 13:00:00
$Minute = new Calendar_Minute(200310251331);     // 25t Octobre 2003 13:31:00
$Second = new Calendar_Second(20031025133145); // 25t Octobre 2003 13:31:45

// Classes Calendar Tabulaire
$Month = new Calendar_Month_Weekdays(200310);          // Octobre 2003
$Month = new Calendar_Month_Weeks(200310);             // Octobre 2003
$Week = new Calendar_Week(20031025);                 // 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 :

<?php
// Création d'un jour
$Day = new Calendar_Day(2003101); // 1er Octobre 2003

echo $Day->thisDay(); // Displays 1
echo $Day->prevDay(); // Displays 30 (le 30 Septembre)
echo $Day->nextDay(); // Displays 2

echo $Day->thisMonth(); // Displays 10
echo $Day->prevMonth(); // Displays 9
echo $Day->nextMonth(); // Displays 11
?>

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 :

<?php
// Création d'une seconde
$Second = new Calendar_Second(20031025133244);

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

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.

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(200310);

$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(200310);

$DayX = new Calendar_Day(20031015);
$DayY = new Calendar_Day(20031023);
$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(20031032);

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(20031032);

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

ou...

<?php
$Day 
= new Calendar_Day(20031032);

$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(20031032);

$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.

Tour d'horizon des classes de Calendar (Previous) A quoi sert Calendar_Decorator (Next)
Last updated: Sun, 29 Aug 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.