repo_zf1/documentation/manual/fr/module_specs/Zend_Date-Additional.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.date.additional">
    <title>Exemples concrets</title>

    <para>
        Dans ce chapitre, nous décrirons plusieurs fonctionnalités disponibles dans
        <classname>Zend_Date</classname>. Ceci sera fait au travers d'exemples concrets.
    </para>

    <sect2 id="zend.date.additional.checking">
        <title>Vérifier des dates</title>

        <para>
            La plupart du temps vous devrez traiter des dates issues d'entrées de vos
            scripts, sous forme de chaînes de caractères. Le problème avec les chaînes est que l'on
            ne sait pas si elles représentent réellement une date. Ainsi,
            <classname>Zend_Date</classname> possède une méthode statique pour vérifier cela.
            <classname>Zend_Locale</classname> a aussi une fonction <code>getDate($date,
            $locale);</code> qui analyse et retourne la date correctement normalisée. Le nom d'un
            mois, par exemple, sera reconnu et sera retourné comme entier. Étant donnée que le rôle
            de <classname>Zend_Locale</classname> est l'aide à la localisation et
            l'internationalisation, c'est <classname>Zend_Date</classname> qui propose une fonction
            de vérification&#160;:<methodname>isDate($date)</methodname>.
        </para>

        <para>
            <code>isDate($date, $format, $locale);</code> peut prendre jusqu'à 3 paramètres,
            1 seul est obligatoire. Le second paramètre exprime le format dans lequel la date doit
            se trouver. Si aucun format n'est spécifié, alors le format par défaut de la locale en
            cours sera utilisé. <link linkend="zend.date.constants.selfdefinedformats">Plus
            d'infos sur les formats</link>.
        </para>

        <para>
            Le 3ème paramètre est aussi optionnel et peut être utilisé pour spécifier une
            locale. Celle-ci est nécessaire afin de normaliser les noms des mois et des jours. Avec
            le 3ème paramètre fourni, des dates comme "01.Jänner.2000" ou "01.January.2000"
            pourront être reconnues en fonction de la locale passée.
        </para>

        <para>
            <code>isDate();</code> bien sûr, vérifie que la date existe.
            <classname>Zend_Date</classname> ne vérifie pas une date elle-même. Il est possible de
            créer une date avec "31.February.2000" dans <classname>Zend_Date</classname>,
            simplement la date sera convertie automatiquement par <classname>Zend_Date</classname>
            en "03.March.2000". <methodname>isDate()</methodname> effectue cette vérification et retournera
            <constant>FALSE</constant> sur "31.February.2000" car cette date n'existe pas.
        </para>

        <example id="zend.date.additional.checking.example-1">
            <title>Vérifier des dates</title>

            <programlisting language="php"><![CDATA[
// Vérification de dates
$date = '01.03.2000';
if (Zend_Date::isDate($date)) {
    print "la chaine $date est une date";
} else {
    print "la chaine $date n'est PAS une date";
}

// Vérification de dates localisées
$date = '01 February 2000';
if (Zend_Date::isDate($date,'dd MMMM yyyy', 'en')) {
    print "la chaine $date est une date";
} else {
    print "la chaine $date n'est PAS une date";
}

// Vérification de fausses dates
$date = '30 February 2000';
if (Zend_Date::isDate($date,'dd MMMM yyyy', 'en')) {
    print "String $date is a date";
} else {
    print "String $date is NO date";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.date.additional.sunrise-sunset">
        <title>Levé et couché du soleil</title>

        <para>
            <classname>Zend_Date</classname> possède aussi des fonctionnalités pour se
            renseigner sur le soleil. Il peut être utile dans une zone donnée, de savoir l'heure de
            levé et de couché du soleil. C'est très simple avec <classname>Zend_Date</classname>,
            il suffit de lui fournir une date, certes, mais aussi un endroit depuis lequel ces
            calculs seront faits.
        </para>

        <para>
            Comme presque personne ne connaît la localisation précise d'une ville sur la
            planète, nous avons aussi écrit une classe qui donne ces coordonnées, pour plus de 250
            grandes villes et capitales. Ainsi la plupart des gens pourra utiliser des villes
            proches de chez eux.
        </para>

        <para>
            A cet effet, <classname>Zend_Date_Cities::getCityList</classname> peut être
            utilisée, cette méthode retourne les noms de toutes les villes prédéfinies dans la
            classe d'aide.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-1">
            <title>Récupérer toutes les villes disponibles</title>

            <programlisting language="php"><![CDATA[
// Affiche la liste complète de toutes les villes disponibles
// dans la classe d'aide
print_r (Zend_Date_Cities::getCityList());
]]></programlisting>

        </example>

        <para>
            La localisation peut être récupérée avec
            <methodname>Zend_Date_Cities::City()</methodname>. Cette méthode prend en paramètre le
            nom d'une ville, tel que retourné par
            <methodname>Zend_Date_Cities::getCityList()</methodname>, et un second paramètre
            optionnel pour l'horizon.
        </para>

        <para>
            Il y a 4 horizons définis, qui peuvent être utilisés avec des lieux pour
            déterminer la date exacte de levé et couché du soleil. Le paramètre
            "<code>horizon</code>" est toujours optionnel, quelle que soit la fonction dans
            laquelle il est utilisé. S'il n'est pas précisé, la valeur "<code>effective</code>" lui
            sera attribuée par défaut.
        </para>

        <table id="zend.date.additional.sunrise-sunset.table">
            <title>Valeurs d'horizons supportées pour les levé et couché de soleil</title>

            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Horizon</entry>
                        <entry>Description</entry>
                        <entry>Usage</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>effective</entry>
                        <entry>Standard horizon</entry>
                        <entry>
                            Traite la Terre comme une balle. C'est la valeur par
                            défaut.
                        </entry>
                    </row>
                    <row>
                        <entry>civil</entry>
                        <entry>Common horizon</entry>
                        <entry>
                            Utilisé dans les médias courants, comme la TV ou la
                            radio
                        </entry>
                    </row>
                    <row>
                        <entry>nautic</entry>
                        <entry>Nautic horizon</entry>
                        <entry>Utilisé en navigation</entry>
                    </row>
                    <row>
                        <entry>astronomic</entry>
                        <entry>Astronomic horizon</entry>
                        <entry>Utilisé pour le calcul avec des étoiles</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Évidemment, un endroit personnalisé peut aussi être utilisé pour le calcul. Une
            "<code>latitude</code>" et une "<code>longitude</code>" seront alors nécessaires, en
            plus du paramètre optionnel "<code>horizon</code>".
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-2">
            <title>Trouver la localisation d'une ville</title>

            <programlisting language="php"><![CDATA[
// Trouve la localisation d'une ville avec l'horizon effectif
print_r (Zend_Date_Cities::city('Vienna'));

// utilise l'horizon nautique
print_r (Zend_Date_Cities::city('Vienna', 'nautic'));

// Voici une ville personnalisée qui n'est pas dans la liste prédéfinie
$mylocation = array('latitude' => 41.5, 'longitude' => 13.2446);
]]></programlisting>
        </example>

        <para>
            Dès lors, il faut créer un objet <classname>Zend_Date</classname> contenant la
            date dont on veut connaître les informations de levé et de couché du soleil. 3 méthodes
            nous seront proposées&#160;: <methodname>getSunset()</methodname>, <methodname>getSunrise()</methodname> et
            <methodname>getSunInfo()</methodname>. Ces 3 méthodes s'appliquent sur un objet
            <classname>Zend_Date</classname> et retournent un objet
            <classname>Zend_Date</classname>.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-3">
            <title>Calculer les informations relatives au soleil</title>

            <programlisting language="php"><![CDATA[
// Retrouve la localisation d'une ville
$city = Zend_Date_Cities::city('Vienna');

// Créer une date à partir de laquelle extraire
// les informations relatives au soleil
$date = new Zend_Date('10.03.2007', Zend_Date::ISO_8601, 'de');

// calcul du levé du soleil
$sunset = $date->getSunset($city);
print $sunset->get(Zend_Date::ISO_8601);

// calcul de toutes les informations solaires
$info = $date->getSunInfo($city);
foreach ($info as $sun) {
    print "\n" . $sun->get(Zend_Date::ISO_8601);
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.date.additional.timezones">
        <title>Fuseaux horaires (Timezones)</title>

        <para>
            Les zones de temps (Timezones) sont aussi importantes que les dates en
            elles-mêmes. Il existe plusieurs zones de temps (fuseaux horaires) sur la planète, et
            travailler avec des dates implique de définir un fuseau horaire pour cette date. Ceci
            semble complexe mais c'est plutôt simple. Comme déjà dit dans le premier chapitre sur
            <classname>Zend_Date</classname>, le fuseau horaire par défaut de <acronym>PHP</acronym> doit être
            configuré. En général, le fichier <code>php.ini</code> est utilisé à cet effet, mais ce
            n'est pas l'unique moyen.
        </para>

        <para>
            Un objet <classname>Zend_Date</classname> encapsule son propre fuseau horaire.
            Même en changeant le fuseau après la création de l'objet, celui-ci s'en souviendra. De
            même, changer le fuseau via <acronym>PHP</acronym> n'aura aucun impact sur l'objet
            <classname>Zend_Date</classname> avec lequel un travail est en cours, c'est celui-ci
            qui va vous permettre via des méthodes de gérer son fuseau.
        </para>

        <para>
            <methodname>getTimezone()</methodname> retourne le fuseau horaire actuel sur lequel travaille
            <classname>Zend_Date</classname>. Souvenez vous que <classname>Zend_Date</classname>
            n'est pas lié aux mécanismes interne de <acronym>PHP</acronym>, ainsi le fuseau retourné peut être
            différent de celui sur lequel <acronym>PHP</acronym> est réglé.<methodname>setTimezone($zone)</methodname> change le
            fuseau horaire actuel de l'objet <classname>Zend_Date</classname>. Le fuseau ainsi
            fournit est toujours vérifié, s'il n'existe pas, une exception sera levée. Si vous ne
            spécifiez pas de fuseau à cette méthode, alors c'est le fuseau interne de <acronym>PHP</acronym> qui sera
            utilisé par défaut, comme c'est le cas lors de la création d'un objet
            <classname>Zend_Date</classname> banal.
        </para>

        <example id="zend.date.additional.timezones.example-1">
            <title>Travailler avec les fuseaux horaires (timezones)</title>

            <programlisting language="php"><![CDATA[
// Règle le fuseau horaire PHP par défaut.
// En général, celui-ci est réglé dans php.ini.
// Ici nous le faisons pour l'exemple
date_default_timezone_set('Europe/Vienna');

// creation d'un objet date
$date = new Zend_Date('10.03.2007', Zend_Date::DATES, 'de');

// affichage de notre date
print $date->getIso();

// quel est son fuseau horaire ?
print $date->getTimezone();

// affectons un autre fuseau
$date->setTimezone('America/Chicago');

// quel est le fuseau ?
print $date->getTimezone();

// voyons les changements dans la date retournée
print $date->getIso();
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Date</classname> utilise toujours le fuseau par défaut (de <acronym>PHP</acronym>)
            lors de la création de l'instance. Remarquez que changer le fuseau de l'objet a un
            impact sur la date s'y trouvant. Une date est toujours exprimée relativement à un
            fuseau horaire, changer le fuseau dans l'objet ne change pas la date de l'objet, mais
            bien sa représentation. Rappelez vous qu'en interne, les dates sont représentées comme
            des timestamps <acronym>GMT</acronym>. Le fuseau donne une information de décalage par rapport à <acronym>GMT</acronym>, en
            positif ou négatif.
        </para>

        <para>
            Coupler le fuseau dans l'objet <classname>Zend_Date</classname> a un autre effet
            positif&#160;: il est possible de posséder plusieurs objets de date, avec chacun un
            fuseau horaire différent.
        </para>

        <example id="zend.date.additional.timezones.example-2">
            <title>Plusieurs fuseaux horaires</title>

            <programlisting language="php"><![CDATA[
// Règle le fuseau horaire PHP par défaut.
// En général, celui-ci est réglé dans php.ini
// Ici nous le faisons pour l'exemple
date_default_timezone_set('Europe/Vienna');

// creation d'un objet date
$date = new Zend_Date('10.03.2007 00:00:00', Zend_Date::ISO_8601, 'de');

// affichage de notre date
print $date->getIso();

// La date est inchangée, même si le fuseau PHP l'est
date_default_timezone_set('America/Chicago');
print $date->getIso();

$otherdate = clone $date;
$otherdate->setTimezone('Brazil/Acre');

// affichage de notre date
print $otherdate->getIso();

// affecte le fuseau horaire actuel de PHP, à notre objet date
$lastdate = clone $date;
$lastdate->setTimezone();

// affichage de notre date
print $lastdate->getIso();
]]></programlisting>
        </example>
    </sect2>
</sect1>