Si vous souhaitez des formats WML, SOAP, PDF, GIF, ligne de commande, etc. etc.? PEAR::Calendar peut être utilisé pour générer n'importe quel format(voir les exemples pour SOAP et WML). Par contre, l'utilisation d'un format limitera ses possibilités (un problème rencontré sur toutes les librairies PHP consultées). Une classe PEAR::HTML_Calendar est susceptible d'être développée en utilisant PEAR::Calendar.
En lançant les exemples sur les serveurs de Sourceforge (qui sont toujours surchargés), le script example 3.php s'exécute en moins de 0.1 seconde (généralement deux fois plus rapide). Le code est très optimisé et tout a été mis en place pour que PHP n'analyse / exécute que le stricte nécessaire. En cas de doute, utilisezCache_Lite afin de mettre votre HTML en cache.
Tous les calculs sont gérés par une classe utilisant l'interface Calendar_Engine. L'implémentation par défaut est basée sur les fonctions date() et mktime() de PHP (les timestamps unix sont nécessaires pour ce moteur). Un second moteur utilisant PEAR::Date existe. Il est plus lent mais répond au problème de limite d'années. Pour passer d'un moteur à l'autre, utilisez la constante CALENDAR_ENGINE.
<?php
// moteur timestamp Unix (valeur par défaut)
// define('CALENDAR_ENGINE', 'UnixTs');
// avec PEAR::Date engine
define('CALENDAR_ENGINE', 'PearDate');
?>
Notez que le moteur de PearDate est basé sur PEAR::Date version 1.4 ou supérieure.
PEAR::Calendar n'utilise que des nombres en base 10 pour les calculs - les noms des jours et des mois dépendent de la configuration de votre PHP. Vous pouvez changer cela avec les fonctions PHP setlocale() et strftime().
<?php
$Day = & new Calendar_Day(2003, 10, 23);
setlocale (LC_TIME, 'de_DE'); // German
echo strftime('%A %d %B %Y', $Day->getTimeStamp());
?>
Notez que Calendar_Decorator_Textual vous aide à générer des noms de mois et de jours de façon indépendante du moteur Calendar que vous utilisez et qui peut être modifié avec setlocale().
PEAR::Calendar aide à générer des calendriers au format tableur tel que :
Octobre 2003 M T W T F S S 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
Notez les vides en haut à gauche et en bas à droite de cet exemple - ce sont des "EmptyDays". Les EmptyDays ne sont générés que par deux classes calendar : Calendar_Month_Weekdays et Calendar_Week. Par exemple en utilisant Calendar_Month_Weekdays :
<?php
require_once 'Calendar/Month/Weekdays.php';
$Month = & new Calendar_Month_Weekdays(2003, 10);
$Month->build();
while ($Day = & $Month->fetch()) {
if ($Day->isFirst()) // Recherche le premier début de semaine
echo "\n";
if ($Day->isEmpty()) // Verifie si day est vide
echo "\t";
else
echo $Day->thisDay()."\t";
if ($Day->isLast()) // Recherche la fin de la semaine
echo "\n";
}
?>
Un jour vide peut retourner une valeur correspondant à la fin du mois précédent ou au début du mois suivant. Vous pouvez obtenir des jours vides avec Calendar_Month_Weekdays et Calendar_Week. Calendar_Week vous permettra de construire 7 jours (utilisez Calendar_Month_Weeks pour construire des objets Calendar_Week), ainsi les fonctions isFirst() et isLast() ne sont plus applicables.
Tous les objets Calendar (excepté Calendar_Second, qui n'as pas de "fils") disposent de la méthode build() afin de construire des "fils" de cet objet. Par exemple, Calendar_Year::build() crée des objets Calendar_Month alors que Calendar_Hour::build() crée un objet Calendar_Minute. Vous avez également la possibilité de passer un objet Calendar sous forme de tableau indexé, celui-ci sera utilisé pour "selectionner" le fils correspondant. Par exemple :
<?php
$Month = & new Calendar_Month(2003, 10); // Oct 2003
$SelectedDay1 = & new Calendar_Day(2003, 10, 5); // Oct 5th 2003
$SelectedDay2 = & new Calendar_Day(2003, 10, 21); // Oct 21st 2003
// Placez un tableau...
$selection = array($SelectedDay1, $SelectedDay2);
$Month->build($selection);
while ($Day = & $Month->fetch()) {
if ($Day->isSelected())
echo $Day->thisYear().' '.$Day->thisMonth().' '.$Day->thisDay().' is selected'."\n";
}
?>
Note : En passant un objet de type date à la méthode build(), vous remplacerez les objets date correspondant, vous permettant par exemple d'attacher votre propre sous classe de Calendar_Decorator afin de personnaliser votre calendrier. Vous pouvez afficher le contenu d'un événement "events database table" avec cette approche.
Avant tout, pour les performances. Construire un fils coûte en performances alors que cela n'est pas toujours nécessaire. Avec un appel automatique, un appel à $Year->build() construirait les mois mais aussi les jours, les heures, les minutes etc. L'appel explicite de build() vous permet également de sélectionner les fils.
La validité est déterminée par le Calendar_Engine (par exemple $Month = & new Month(2003, 2, 29); est invalide, car 2003 n'est pas une année bissextile). Pour une validation rapide, vous pouvez appeler la méthode isValid() sur n'importe quel objet de date, cela vous renverra FALSE en cas de problème. Pour plus d'informations ou une validation plus détaillée, vous pouvez appeler la méthode getValidator() qui renvoie une instance de la classe Calendar_Validator. Par exemple :
<?php
$Month = & new Month(2003, 2, 29); // 29th Feb 2003 (?!?)
if (!$Month->isValid()) {
$Validator = & $Month->getValidator();
while ($Error = $Validator->fetch()) {
echo $Error->toString();
}
}
?>
Pous pouvez également vérifier une validité en appelant la méthode getValidator() puis isValidYear(), isValidMonth(), isValidDay(), isValidHour(), isValidMinute() ou isValidSecond() (ou encore isValid() qui appelle toutes les méthodes isValidxxx).
Si vous permettez par exemple à vos utilisateurs de se déplacer dans votre calendrier grâce aux URLs (ex: calendar.php?year=2003&month=13), il se peut qu'ils modifient cette URL vers une date invalide. Au lieu de leur afficher un message d'erreur, appelez la méthode Calendar::adjust() sur l'objet Calendar créé. Notre exemple vous donnera alors Janvier 2004. Ce comportement est possible grâce à la fonction mktime() pour les Timestamp Unix tout en étant construit dans le moteur PearDate pour vous.
La méthode fetchAll() peut être appelée pour n'importe quel objet afin d'obtenir un tableau indexé comportant tous les enfants construits, et vous permettant d'y accéder. Faites attention au premier index de ce tableau - dans certains cas, ce sera [1] et non [0] en fonction du type de l'objet construit. Par exemple :
<?php
$Month = & new Calendar_Month(2003, 10);
$Month->build();
$days = & $Month->fetchAll(); // on créé le tableau
echo $days[1]->thisDay(); // Le premier jour à l'index 1
$Hour = & new Calendar_Hour(2003, 10, 25, 15); // Oct 25th 2003, 3pm
$Hour->build();
$hours = & $Hour->fetchAll(); // on créé le tableau
echo $hours[0]->thisHour(); // La première heure à l'index 0
?>
Les classes suivantes sont toujours construites avec un premier index à 1 : Calendar_Month, Calendar_Month_Weekdays, Calendar_Month_Weeks, Calendar_Week et Calendar_Day Les classes suivantes sont toujours construites avec un premier index à 0 : Calendar_Hour, Calendar_Minute et Calendar_Second La méthode size() peut également être appelée après la méthode build() sur les objets date pour récupérer le nombre de fils.
Les semaines sont des "pseudo" jours. Ils sont pratiques pour mettre en page vos calendriers. Les semaines sont créées à partir d'un an, un mois et un jour du mois. Vous pouvez alors consulter le timestamp de la semaine qui sera le même que celui du début de cette semaine. Vous pourrez également connaître sa position numérique dans le mois, sa position numérique dans l'année (il s'agit d'un numéro ISO-8601 de semaine, les semaines commençant par un lundi) ou un tableau contenant les valeurs numériques de l'année, du mois et du premier jour de la semaine (sous la forme d'un nombre dans le mois). Par exemple :
<?php
$Week = & new Calendar_Week(2003, 10, 15);
$Week = new Calendar_Week(2003, 10, 15);
echo $Week->thisWeek(); // affiche 2 (semaine dans le mois)
echo $Week->thisWeek('n_in_month'); // affiche 2 - idem
echo $Week->thisWeek('n_in_year'); // affiche 41 (semaine dans l'année)
echo $Week->thisWeek('timestamp'); // affiche un timestamp Unix ou un datetime ISO-8601
// (YYYY-MM-DD HH:MM:SS), en fonction du moteur.
print_r $Week->thisWeek('array'); // [year] => 2003 [month] => 10 [day] => 12
?>
Lorsque vous utilisez un Calendar_Year, la constante CALENDAR_MONTH_STATE vous permet de contrôler le type d'objets month qui seront créés. Vous pouvez définir CALENDAR_MONTH_STATE aux valeurs CALENDAR_USE_MONTH_WEEKDAYS ou CALENDAR_USE_MONTH_WEEKS respectivement pour les Calendar_Month_Weekdays et les Calendar_Month_Week.
Oui. Pour les classes concernées par la notion de "semaine", il vous est possible de passer une valeur permettant de définir le premier jour de la semaine. Cette valeur doit être comprise entre 0 et 6, 0 étant le dimanche et 6 le samedi. Voici comment passer cette valeur :
<?php
$Year = new Calendar_Year(2003);
$selection = array();
$Year->build($selection, 0); // le second argument est le premier jour de la semaine (dimanche)
$MonthWeekdays = new Calendar_Month_Weekdays(2003, 10, 6); // troisième argument - samedi
$MonthWeeks = new Calendar_Month_Weekdays(2003, 10, 2); // troisième argument - mardi
$Week = new Calendar_Week(2003, 10, 15, 5) // quatrième argument - vendredi
?>