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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<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>NTP</emphasis> ou <emphasis>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>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 language="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 à <methodname>getDate()</methodname>
            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
            <methodname>addServer()</methodname> :
        </para>

        <programlisting language="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 language="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>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>NTP</emphasis>. Si vous omettez le protocole dans l'adresse, c'est NTP qui
            sera utilisé.
        </para>

        <programlisting language="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>NTP</emphasis> et <emphasis>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 language="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>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>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 à <methodname>setOptions()</methodname>, 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
            <methodname>getOptions()</methodname>. 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 language="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 <methodname>setServer()</methodname> et passez lui le nom du serveur que vous
            souhaitez interroger prochainement. Pour savoir le serveur qui va être utilisé,
            <methodname>getServer()</methodname> vous sera utile.
        </para>

        <programlisting language="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
            <methodname>getInfo()</methodname>.
        </para>

        <programlisting language="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 language="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>