repo_zf1/documentation/manual/fr/module_specs/Zend_TimeSync-Working.xml

<!-- EN-Revision: 13828 -->
<sect1 id="zend.timesync.working">
    <title>Utiliser Zend_TimeSync</title>

    <para><classname>Zend_TimeSync</classname> peut retourner le temps de n'importe quel serveur via <emphasis
    role="strong">NTP</emphasis> ou <emphasis role="strong">SNTP</emphasis>. Il peut aussi gérer de multiples
    serveurs.</para>

    <note>
        <para>Dans tous les exemples qui suivront, nous utiliserons un pool de serveurs générique public : <emphasis
        role="strong">0.europe.pool.ntp.org</emphasis>. De votre côté, il est conseillé d'utiliser le pool le plus
        proche possible géographiquement de votre position. Lisez <ulink
        url="http://www.pool.ntp.org">http://www.pool.ntp.org</ulink> pour plus d'informations.</para>
    </note>

    <sect2 id="zend.timesync.working.generic">
        <title>Requêter un serveur de temps public</title>

        <para>Cette opération est très simple, il suffit de préciser le serveur de temps à utiliser.</para>

        <programlisting role="php"><![CDATA[
$server = new Zend_TimeSync('0.pool.ntp.org');

print $server->getDate()->getIso();
]]></programlisting>

        <para>Que se passe-t-il en arrière plan de <classname>Zend_TimeSync</classname> ? Tout d'abord la syntaxe est vérifiée.
        Ainsi, "<code>0.pool.ntp.org</code>" est vérifié et reconnu comme pouvant être un serveur de temps. Ensuite
        l'appel à <code>getDate()</code> génère une requête vers le serveur de temps qui retourne son temps.
        <classname>Zend_TimeSync</classname> va alors calculer la différence entre ce temps retourné, et le temps actuel du
        serveur sur lequel le script tourne, et retourner finalement un objet <classname>Zend_Date</classname> représentant le
        temps actuel, juste et corrigé.</para>

        <para>Pour plus de détails sur les objets <classname>Zend_Date</classname> et leurs méthodes, voyez la documentation de
        <link linkend="zend.date.introduction">Zend_Date</link>.</para>
    </sect2>

    <sect2 id="zend.timesync.working.multiple">
        <title>Serveurs de temps multiples</title>

        <para>Tous les serveurs de temps ne sont pas disponibles tout le temps, à 100%. Il peuvent subir des opérations
        de maintenance, ou tout simplement se retrouver saturés. Dans de tels cas, une exception sera levée.</para>

        <para><classname>Zend_TimeSync</classname> peut gérer plusieurs serveurs, et se connecter automatiquement au suivant, si
        le précédent ne répond pas. Passez un tableau de serverus de temps au constructeur de l'objet, ou utilisez la
        méthode <code>addServer()</code> :</para>

        <programlisting role="php"><![CDATA[
$server = new Zend_TimeSync(array('0.pool.ntp.org',
                                  '1.pool.ntp.org',
                                  '2.pool.ntp.org'));
$server->addServer('3.pool.ntp.org');

print $server->getDate()->getIso();
]]></programlisting>

        <para>Vous pouvez ajouter une infinité de serveurs, et <classname>Zend_TimeSync</classname> basculera automatiquement au
        suivant, si un ne répond pas.</para>

        <para>Vous devriez aussi nommer vos serveurs de temps. Ceci se fait au moyen de la clé du tableau de serveurs,
        ou en second paramètre de la méthode addServer() :</para>

        <programlisting role="php"><![CDATA[
$server = new Zend_TimeSync(array('generic'  => '0.pool.ntp.org',
                                  'fallback' => '1.pool.ntp.org',
                                  'reserve'  => '2.pool.ntp.org'));
$server->addServer('3.pool.ntp.org', 'additional');

print $server->getDate()->getIso();
]]></programlisting>

        <para>En nommant vos serveurs, vous pourrez en interroger un en particulier comme nous allons le voir.</para>
    </sect2>

    <sect2 id="zend.timesync.working.protocol">
        <title>Les protocoles des serveurs de temps</title>

        <para>La plupart des serveurs publics de temps utilisent le protocole <emphasis role="strong">NTP</emphasis>.
        Mais d'autres protocoles existent.</para>

        <para>Vous pouvez spécifier le protocole dans l'adresse du serveur de temps. <classname>Zend_TimeSync</classname> en
        supporte deux actuellement. Celui par défaut est <emphasis role="strong">NTP</emphasis>. Si vous omettez le
        protocole dans l'adresse, c'est NTP qui sera utilisé.</para>

        <programlisting role="php"><![CDATA[
$server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
                                  'fallback' => 'ntp:\\1.pool.ntp.org',
                                  'reserve'  => 'ntp:\\2.pool.ntp.org'));
$server->addServer('sntp:\\internal.myserver.com', 'additional');

print $server->getDate()->getIso();
]]></programlisting>

        <para><classname>Zend_TimeSync</classname> peut donc gérer plusieurs serveurs, et plusieurs protocoles, en même
        temps.</para>
    </sect2>

    <sect2 id="zend.timesync.working.ports">
        <title>Utiliser les ports pour les serveurs de temps</title>

        <para>Comme tous les protocoles, <emphasis role="strong">NTP</emphasis> et <emphasis
        role="strong">SNTP</emphasis> utilisent des ports par défaut.</para>

        <para>Quelque fois il peut être nécessaire de préciser le port à utiliser. Si c'est le cas, rajoutez le
        simplement à l'adresse du serveur à utiliser, sinon <classname>Zend_TimeSync</classname> utilisera celui par
        défaut.</para>

        <programlisting role="php"><![CDATA[
$server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org:200',
                                  'fallback' => 'ntp:\\1.pool.ntp.org'));
$server->addServer('sntp:\\internal.myserver.com:399', 'additional');

print $server->getDate()->getIso();
]]></programlisting>
    </sect2>

    <sect2 id="zend.timesync.working.options">
        <title>Options pour les serveurs de temps</title>

        <para>Actuellement seule une option est utilisée en interne par <classname>Zend_TimeSync</classname>. Mais vous pouvez en
        utiliser autant que vous voulez.</para>

        <para>L'option <emphasis role="strong">timeout</emphasis> définit le nombre de secondes au delà duquel la
        connexion sera considérée comme cassée. La valeur par défaut est <emphasis role="strong">1</emphasis>, donc
        <classname>Zend_TimeSync</classname> changera de serveur si la réponse du serveur actuellement interrogé met plus d'une
        seconde à arriver.</para>

        <para>Grâce à <code>setOptions()</code>, vous passez un tableau d'options que vous voulez. La clé du tableau
        représente le nom de l'option en question et la valeur, sa valeur. Pour voir les options déjà affectées,
        utilisez la méthode <code>getOptions()</code>. Elle accepte une clé nommant l'option à récupérer, ou alors si
        aucun paramètre ne lui est passé, la méthode retournera toutes les options connues.</para>

        <programlisting role="php"><![CDATA[
Zend_TimeSync::setOptions(array('timeout' => 3, 'myoption' => 'timesync'));
$server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
                                  'fallback' => 'ntp:\\1.pool.ntp.org'));
$server->addServer('sntp:\\internal.myserver.com', 'additional');

print $server->getDate()->getIso();
print_r(Zend_TimeSync::getOptions();
print "Timeout = " . Zend_TimeSync::getOptions('timeout');
]]></programlisting>

        <para>Comme vous pouvez le noter, les options de <classname>Zend_TimeSync</classname> sont statiques, ainsi chaque
        instance de <classname>Zend_TimeSync</classname> possèdera les mêmes options.</para>
    </sect2>

    <sect2 id="zend.timesync.working.different">
        <title>Utiliser des serveurs de temps différents</title>

        <para>Par défaut la requête utilisera le premier serveur défini, et ainsi de suite. Il peut être nécessaire
        parfois, de spécifier un serveur précis que l'on souhaite interroger. Utilisez <code>setServer()</code> et
        passez lui le nom du serveur que vous souhaitez interroger prochainement. Pour savoir le serveur qui va être
        utilisé, <code>getServer()</code> vous sera utile.</para>

        <programlisting role="php"><![CDATA[
$server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
                                  'fallback' => 'ntp:\\1.pool.ntp.org'));
$server->addServer('sntp:\\internal.myserver.com', 'additional');

$actual = $server->getServer();
$server = $server->setServer('additional');
]]></programlisting>
    </sect2>

    <sect2 id="zend.timesync.working.informations">
        <title>Informations sur les serveurs de temps</title>

        <para>Les serveurs de temps fournissent certes le temps, mais aussi d'autres informations. Pour prendre
        connaissance de ces informations, utilisez la méthode <code>getInfo()</code>.</para>

        <programlisting role="php"><![CDATA[
$server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
                                  'fallback' => 'ntp:\\1.pool.ntp.org'));

print_r ($server->getInfo());
]]></programlisting>

        <para>Des protocoles et des serveurs différents, retourneront des informations différentes.</para>
    </sect2>

    <sect2 id="zend.timesync.working.exceptions">
        <title>Gérer les exceptions</title>

        <para>Les exceptions sont collectées pour tous les serveurs et sont retournées en tant que tableau. Vous pourrez
        ainsi itérer sur vos exceptions, voyez plutôt :</para>

        <programlisting role="php"><![CDATA[
$serverlist = array(
        // invalid servers
        'invalid_a'  => 'ntp://a.foo.bar.org',
        'invalid_b'  => 'sntp://b.foo.bar.org',
);

$server = new Zend_TimeSync($serverlist);

try {
    $result = $server->getDate();
    echo $result->getIso();
} catch (Zend_TimeSync_Exception $e) {

    $exceptions = $e->get();

    foreach ($exceptions as $key => $myException) {
        echo $myException->getMessage();
        echo '<br />';
    }
}
]]></programlisting>
    </sect2>
</sect1>