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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20807 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.timesync.working">
   5     <title>Utiliser Zend_TimeSync</title>
   6
   7     <para>
   8         <classname>Zend_TimeSync</classname> peut retourner le temps de n'importe quel serveur
   9         via <emphasis>NTP</emphasis> ou <emphasis>SNTP</emphasis>. Il peut aussi gérer de multiples
  10         serveurs.
  11     </para>
  12
  13     <note>
  14         <para>
  15             Dans tous les exemples qui suivront, nous utiliserons un pool de serveurs
  16             générique public : <emphasis>0.europe.pool.ntp.org</emphasis>. De votre côté, il est
  17             conseillé d'utiliser le pool le plus proche possible géographiquement de votre position.
  18             Lisez <ulink url="http://www.pool.ntp.org">http://www.pool.ntp.org</ulink> pour plus
  19             d'informations.
  20         </para>
  21     </note>
  22
  23     <sect2 id="zend.timesync.working.generic">
  24         <title>Requêter un serveur de temps public</title>
  25
  26         <para>
  27             Cette opération est très simple, il suffit de préciser le serveur de temps à
  28             utiliser.
  29         </para>
  30
  31         <programlisting language="php"><![CDATA[
  32 $server = new Zend_TimeSync('0.pool.ntp.org');
  33
  34 print $server->getDate()->getIso();
  35 ]]></programlisting>
  36
  37         <para>
  38             Que se passe-t-il en arrière plan de <classname>Zend_TimeSync</classname> ? Tout
  39             d'abord la syntaxe est vérifiée. Ainsi, "<code>0.pool.ntp.org</code>" est vérifié et
  40             reconnu comme pouvant être un serveur de temps. Ensuite l'appel à <methodname>getDate()</methodname>
  41             génère une requête vers le serveur de temps qui retourne son temps.
  42             <classname>Zend_TimeSync</classname> va alors calculer la différence entre ce temps
  43             retourné, et le temps actuel du serveur sur lequel le script tourne, et retourner
  44             finalement un objet <classname>Zend_Date</classname> représentant le temps actuel, juste
  45             et corrigé.
  46         </para>
  47
  48         <para>
  49             Pour plus de détails sur les objets <classname>Zend_Date</classname> et leurs
  50             méthodes, voyez la documentation de <link
  51             linkend="zend.date.introduction">Zend_Date</link>.
  52         </para>
  53     </sect2>
  54
  55     <sect2 id="zend.timesync.working.multiple">
  56         <title>Serveurs de temps multiples</title>
  57
  58         <para>
  59             Tous les serveurs de temps ne sont pas disponibles tout le temps, à 100%. Il
  60             peuvent subir des opérations de maintenance, ou tout simplement se retrouver saturés.
  61             Dans de tels cas, une exception sera levée.
  62         </para>
  63
  64         <para>
  65             <classname>Zend_TimeSync</classname> peut gérer plusieurs serveurs, et se
  66             connecter automatiquement au suivant, si le précédent ne répond pas. Passez un tableau
  67             de serverus de temps au constructeur de l'objet, ou utilisez la méthode
  68             <methodname>addServer()</methodname> :
  69         </para>
  70
  71         <programlisting language="php"><![CDATA[
  72 $server = new Zend_TimeSync(array('0.pool.ntp.org',
  73                                   '1.pool.ntp.org',
  74                                   '2.pool.ntp.org'));
  75 $server->addServer('3.pool.ntp.org');
  76
  77 print $server->getDate()->getIso();
  78 ]]></programlisting>
  79
  80         <para>
  81             Vous pouvez ajouter une infinité de serveurs, et
  82             <classname>Zend_TimeSync</classname> basculera automatiquement au suivant, si un ne
  83             répond pas.
  84         </para>
  85
  86         <para>
  87             Vous devriez aussi nommer vos serveurs de temps. Ceci se fait au moyen de la clé
  88             du tableau de serveurs, ou en second paramètre de la méthode addServer() :
  89         </para>
  90
  91         <programlisting language="php"><![CDATA[
  92 $server = new Zend_TimeSync(array('generic'  => '0.pool.ntp.org',
  93                                   'fallback' => '1.pool.ntp.org',
  94                                   'reserve'  => '2.pool.ntp.org'));
  95 $server->addServer('3.pool.ntp.org', 'additional');
  96
  97 print $server->getDate()->getIso();
  98 ]]></programlisting>
  99
 100         <para>
 101             En nommant vos serveurs, vous pourrez en interroger un en particulier comme nous
 102             allons le voir.
 103         </para>
 104     </sect2>
 105
 106     <sect2 id="zend.timesync.working.protocol">
 107         <title>Les protocoles des serveurs de temps</title>
 108
 109         <para>
 110             La plupart des serveurs publics de temps utilisent le protocole
 111             <emphasis>NTP</emphasis>. Mais d'autres protocoles existent.
 112         </para>
 113
 114         <para>
 115             Vous pouvez spécifier le protocole dans l'adresse du serveur de temps.
 116             <classname>Zend_TimeSync</classname> en supporte deux actuellement. Celui par défaut est
 117             <emphasis>NTP</emphasis>. Si vous omettez le protocole dans l'adresse, c'est NTP qui
 118             sera utilisé.
 119         </para>
 120
 121         <programlisting language="php"><![CDATA[
 122 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 123                                   'fallback' => 'ntp:\\1.pool.ntp.org',
 124                                   'reserve'  => 'ntp:\\2.pool.ntp.org'));
 125 $server->addServer('sntp:\\internal.myserver.com', 'additional');
 126
 127 print $server->getDate()->getIso();
 128 ]]></programlisting>
 129
 130         <para>
 131             <classname>Zend_TimeSync</classname> peut donc gérer plusieurs serveurs, et
 132             plusieurs protocoles, en même temps.
 133         </para>
 134     </sect2>
 135
 136     <sect2 id="zend.timesync.working.ports">
 137         <title>Utiliser les ports pour les serveurs de temps</title>
 138
 139         <para>
 140             Comme tous les protocoles, <emphasis>NTP</emphasis> et <emphasis>SNTP</emphasis>
 141             utilisent des ports par défaut.
 142         </para>
 143
 144         <para>
 145             Quelque fois il peut être nécessaire de préciser le port à utiliser. Si c'est le
 146             cas, rajoutez le simplement à l'adresse du serveur à utiliser, sinon
 147             <classname>Zend_TimeSync</classname> utilisera celui par défaut.
 148         </para>
 149
 150         <programlisting language="php"><![CDATA[
 151 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org:200',
 152                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 153 $server->addServer('sntp:\\internal.myserver.com:399', 'additional');
 154
 155 print $server->getDate()->getIso();
 156 ]]></programlisting>
 157     </sect2>
 158
 159     <sect2 id="zend.timesync.working.options">
 160         <title>Options pour les serveurs de temps</title>
 161
 162         <para>
 163             Actuellement seule une option est utilisée en interne par
 164             <classname>Zend_TimeSync</classname>. Mais vous pouvez en utiliser autant que vous
 165             voulez.
 166         </para>
 167
 168         <para>
 169             L'option <emphasis>timeout</emphasis> définit le nombre de secondes au delà duquel
 170             la connexion sera considérée comme cassée. La valeur par défaut est
 171             <emphasis>1</emphasis>, donc <classname>Zend_TimeSync</classname> changera de serveur si
 172             la réponse du serveur actuellement interrogé met plus d'une seconde à arriver.
 173         </para>
 174
 175         <para>
 176             Grâce à <methodname>setOptions()</methodname>, vous passez un tableau d'options que vous
 177             voulez. La clé du tableau représente le nom de l'option en question et la valeur, sa
 178             valeur. Pour voir les options déjà affectées, utilisez la méthode
 179             <methodname>getOptions()</methodname>. Elle accepte une clé nommant l'option à récupérer, ou alors
 180             si aucun paramètre ne lui est passé, la méthode retournera toutes les options
 181             connues.
 182         </para>
 183
 184         <programlisting language="php"><![CDATA[
 185 Zend_TimeSync::setOptions(array('timeout' => 3, 'myoption' => 'timesync'));
 186 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 187                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 188 $server->addServer('sntp:\\internal.myserver.com', 'additional');
 189
 190 print $server->getDate()->getIso();
 191 print_r(Zend_TimeSync::getOptions();
 192 print "Timeout = " . Zend_TimeSync::getOptions('timeout');
 193 ]]></programlisting>
 194
 195         <para>
 196             Comme vous pouvez le noter, les options de <classname>Zend_TimeSync</classname>
 197             sont statiques, ainsi chaque instance de <classname>Zend_TimeSync</classname> possèdera
 198             les mêmes options.
 199         </para>
 200     </sect2>
 201
 202     <sect2 id="zend.timesync.working.different">
 203         <title>Utiliser des serveurs de temps différents</title>
 204
 205         <para>
 206             Par défaut la requête utilisera le premier serveur défini, et ainsi de suite. Il
 207             peut être nécessaire parfois, de spécifier un serveur précis que l'on souhaite
 208             interroger. Utilisez <methodname>setServer()</methodname> et passez lui le nom du serveur que vous
 209             souhaitez interroger prochainement. Pour savoir le serveur qui va être utilisé,
 210             <methodname>getServer()</methodname> vous sera utile.
 211         </para>
 212
 213         <programlisting language="php"><![CDATA[
 214 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 215                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 216 $server->addServer('sntp:\\internal.myserver.com', 'additional');
 217
 218 $actual = $server->getServer();
 219 $server = $server->setServer('additional');
 220 ]]></programlisting>
 221     </sect2>
 222
 223     <sect2 id="zend.timesync.working.informations">
 224         <title>Informations sur les serveurs de temps</title>
 225
 226         <para>
 227             Les serveurs de temps fournissent certes le temps, mais aussi d'autres
 228             informations. Pour prendre connaissance de ces informations, utilisez la méthode
 229             <methodname>getInfo()</methodname>.
 230         </para>
 231
 232         <programlisting language="php"><![CDATA[
 233 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 234                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 235
 236 print_r ($server->getInfo());
 237 ]]></programlisting>
 238
 239         <para>
 240             Des protocoles et des serveurs différents, retourneront des informations
 241             différentes.
 242         </para>
 243     </sect2>
 244
 245     <sect2 id="zend.timesync.working.exceptions">
 246         <title>Gérer les exceptions</title>
 247
 248         <para>
 249             Les exceptions sont collectées pour tous les serveurs et sont retournées en tant
 250             que tableau. Vous pourrez ainsi itérer sur vos exceptions, voyez plutôt :
 251         </para>
 252
 253         <programlisting language="php"><![CDATA[
 254 $serverlist = array(
 255         // invalid servers
 256         'invalid_a'  => 'ntp://a.foo.bar.org',
 257         'invalid_b'  => 'sntp://b.foo.bar.org',
 258 );
 259
 260 $server = new Zend_TimeSync($serverlist);
 261
 262 try {
 263     $result = $server->getDate();
 264     echo $result->getIso();
 265 } catch (Zend_TimeSync_Exception $e) {
 266
 267     $exceptions = $e->get();
 268
 269     foreach ($exceptions as $key => $myException) {
 270         echo $myException->getMessage();
 271         echo '<br />';
 272     }
 273 }
 274 ]]></programlisting>
 275     </sect2>
 276 </sect1>