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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.timesync.working">
   4     <title>Working with Zend_TimeSync</title>
   5
   6     <para>
   7         <classname>Zend_TimeSync</classname> can return the actual time from any given
   8         <emphasis>NTP</emphasis> or <emphasis>SNTP</emphasis> time server.
   9         It can automatically handle multiple servers and provides a simple interface.
  10     </para>
  11
  12     <note>
  13         <para>
  14             All examples in this chapter use a public, generic time server:
  15             <emphasis>0.europe.pool.ntp.org</emphasis>. You should use a public, generic time server
  16             which is close to your application server. See <ulink
  17                 url="http://www.pool.ntp.org">http://www.pool.ntp.org</ulink> for information.
  18         </para>
  19     </note>
  20
  21     <sect2 id="zend.timesync.working.generic">
  22         <title>Generic Time Server Request</title>
  23
  24         <para>
  25             Requesting the time from a time server is simple. First, you provide the time server
  26             from which you want to request the time.
  27         </para>
  28
  29         <programlisting language="php"><![CDATA[
  30 $server = new Zend_TimeSync('0.pool.ntp.org');
  31
  32 print $server->getDate()->getIso();
  33 ]]></programlisting>
  34
  35         <para>
  36             So what is happening in the background of <classname>Zend_TimeSync</classname>? First
  37             the syntax of the time server is checked. In our example,
  38             '<emphasis>0.pool.ntp.org</emphasis>' is checked and recognised as a possible address
  39             for a time server. Then when calling <methodname>getDate()</methodname> the actual set
  40             time server is requested and it will return its own time.
  41             <classname>Zend_TimeSync</classname> then calculates the difference to the actual time
  42             of the server running the script and returns a <classname>Zend_Date</classname> object
  43             with the correct time.
  44         </para>
  45
  46         <para>
  47             For details about <classname>Zend_Date</classname> and its methods see the <link
  48                 linkend="zend.date.introduction"><classname>Zend_Date</classname>
  49                 documentation</link>.
  50         </para>
  51     </sect2>
  52
  53     <sect2 id="zend.timesync.working.multiple">
  54         <title>Multiple Time Servers</title>
  55
  56         <para>
  57             Not all time servers are always available to return their time. Servers may be
  58             unavailable during maintenance, for example. When the time cannot be requested from the
  59             time server, you will get an exception.
  60         </para>
  61
  62         <para>
  63             <classname>Zend_TimeSync</classname> is a simple solution that can handle multiple time
  64             servers and supports an automatic fallback mechanism. There are two supported ways; you
  65             can either specify an array of time servers when creating the instance, or you can add
  66             additional time servers to the instance using the <methodname>addServer()</methodname>
  67             method.
  68         </para>
  69
  70         <programlisting language="php"><![CDATA[
  71 $server = new Zend_TimeSync(array('0.pool.ntp.org',
  72                                   '1.pool.ntp.org',
  73                                   '2.pool.ntp.org'));
  74 $server->addServer('3.pool.ntp.org');
  75
  76 print $server->getDate()->getIso();
  77 ]]></programlisting>
  78
  79         <para>
  80             There is no limit to the number of time servers you can add. When a time server can not
  81             be reached, <classname>Zend_TimeSync</classname> will fallback and try to connect to the
  82             next time server.
  83         </para>
  84
  85         <para>
  86             When you supply more than one time server- which is considered a best practice for
  87             <classname>Zend_TimeSync</classname>- you should name each server. You can name your
  88             servers with array keys, with the second parameter at instantiation, or with the second
  89             parameter when adding another time server.
  90         </para>
  91
  92         <programlisting language="php"><![CDATA[
  93 $server = new Zend_TimeSync(array('generic'  => '0.pool.ntp.org',
  94                                   'fallback' => '1.pool.ntp.org',
  95                                   'reserve'  => '2.pool.ntp.org'));
  96 $server->addServer('3.pool.ntp.org', 'additional');
  97
  98 print $server->getDate()->getIso();
  99 ]]></programlisting>
 100
 101         <para>
 102             Naming the time servers allows you to request a specific time server as we will see
 103             later in this chapter.
 104         </para>
 105     </sect2>
 106
 107     <sect2 id="zend.timesync.working.protocol">
 108         <title>Protocols of Time Servers</title>
 109
 110         <para>
 111             There are different types of time servers. Most public time servers use the
 112             <emphasis>NTP</emphasis> protocol. But there are other time synchronization
 113             protocols available.
 114         </para>
 115
 116         <para>
 117             You set the proper protocol in the address of the time server. There are two
 118             protocols which are supported by <classname>Zend_TimeSync</classname>:
 119             <emphasis>NTP</emphasis> and <emphasis>SNTP</emphasis>. The default protocol is
 120             <emphasis>NTP</emphasis>. If you are using <emphasis>NTP</emphasis>, you can omit the
 121             protocol in the address as demonstrated in the previous examples.
 122         </para>
 123
 124         <programlisting language="php"><![CDATA[
 125 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 126                                   'fallback' => 'ntp:\\1.pool.ntp.org',
 127                                   'reserve'  => 'ntp:\\2.pool.ntp.org'));
 128 $server->addServer('sntp:\\internal.myserver.com', 'additional');
 129
 130 print $server->getDate()->getIso();
 131 ]]></programlisting>
 132
 133         <para>
 134             <classname>Zend_TimeSync</classname> can handle mixed time servers. So you are not
 135             restricted to only one protocol; you can add any server independently from its protocol.
 136         </para>
 137     </sect2>
 138
 139     <sect2 id="zend.timesync.working.ports">
 140         <title>Using Ports for Time Servers</title>
 141
 142         <para>
 143             As with every protocol within the world wide web, the <emphasis>NTP</emphasis> and
 144             <emphasis>SNTP</emphasis> protocols use standard ports. NTP uses port
 145             <emphasis>123</emphasis> and SNTP uses port <emphasis>37</emphasis>.
 146         </para>
 147
 148         <para>
 149             But sometimes the port that the protocols use differs from the standard one. You can
 150             define the port which has to be used for each server within the address. Just add the
 151             number of the port after the address. If no port is defined, then
 152             <classname>Zend_TimeSync</classname> will use the standard port.
 153         </para>
 154
 155         <programlisting language="php"><![CDATA[
 156 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org:200',
 157                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 158 $server->addServer('sntp:\\internal.myserver.com:399', 'additional');
 159
 160 print $server->getDate()->getIso();
 161 ]]></programlisting>
 162     </sect2>
 163
 164     <sect2 id="zend.timesync.working.options">
 165         <title>Time Servers Options</title>
 166
 167         <para>
 168             There is only one option within <classname>Zend_TimeSync</classname> which will be used
 169             internally: <emphasis>timeout</emphasis>. You can set any self-defined option you are in
 170             need of and request it, however.
 171         </para>
 172
 173         <para>
 174             The option <emphasis>timeout</emphasis> defines the number of seconds after which
 175             a connection is detected as broken when there was no response. The default value is
 176             <emphasis>1</emphasis>, which means that <classname>Zend_TimeSync</classname> will
 177             fallback to the next time server if the requested time server does not respond in one
 178             second.
 179         </para>
 180
 181         <para>
 182             With the <methodname>setOptions()</methodname> method, you can set any option. This
 183             function accepts an array where the key is the option to set and the value is the value
 184             of that option. Any previously set option will be overwritten by the new value. If you
 185             want to know which options are set, use the <methodname>getOptions()</methodname>
 186             method. It accepts either a key which returns the given option if specified, or, if no
 187             key is set, it will return all set options.
 188         </para>
 189
 190         <programlisting language="php"><![CDATA[
 191 Zend_TimeSync::setOptions(array('timeout' => 3, 'myoption' => 'timesync'));
 192 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 193                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 194 $server->addServer('sntp:\\internal.myserver.com', 'additional');
 195
 196 print $server->getDate()->getIso();
 197 print_r(Zend_TimeSync::getOptions();
 198 print "Timeout = " . Zend_TimeSync::getOptions('timeout');
 199 ]]></programlisting>
 200
 201         <para>
 202             As you can see, the options for <classname>Zend_TimeSync</classname> are static. Each
 203             instance of <classname>Zend_TimeSync</classname> will use the same options.
 204         </para>
 205     </sect2>
 206
 207     <sect2 id="zend.timesync.working.different">
 208         <title>Using Different Time Servers</title>
 209
 210         <para>
 211             <classname>Zend_TimeSync</classname>'s default behavior for requesting a time is to
 212             request it from the first given server. But sometimes it is useful to set a different
 213             time server from which to request the time. This can be done with the
 214             <methodname>setServer()</methodname> method. To define the used time server set the
 215             alias as a parameter within the method. To get the actual used time server call the
 216             <methodname>getServer()</methodname> method. It accepts an alias as a parameter which
 217             defines the time server to be returned. If no parameter is given, the current time
 218             server will be returned.
 219         </para>
 220
 221         <programlisting language="php"><![CDATA[
 222 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 223                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 224 $server->addServer('sntp:\\internal.myserver.com', 'additional');
 225
 226 $actual = $server->getServer();
 227 $server = $server->setServer('additional');
 228 ]]></programlisting>
 229     </sect2>
 230
 231     <sect2 id="zend.timesync.working.informations">
 232         <title>Information from Time Servers</title>
 233
 234         <para>
 235             Time servers not only offer the time itself, but also additional information. You can
 236             get this information with the <methodname>getInfo()</methodname> method.
 237         </para>
 238
 239         <programlisting language="php"><![CDATA[
 240 $server = new Zend_TimeSync(array('generic'  => 'ntp:\\0.pool.ntp.org',
 241                                   'fallback' => 'ntp:\\1.pool.ntp.org'));
 242
 243 print_r ($server->getInfo());
 244 ]]></programlisting>
 245
 246         <para>
 247             The returned information differs with the protocol used and can also differ with the
 248             server used.
 249         </para>
 250     </sect2>
 251
 252     <sect2 id="zend.timesync.working.exceptions">
 253         <title>Handling Exceptions</title>
 254
 255         <para>
 256             Exceptions are collected for all time servers and returned as an array. So you can
 257             iterate through all thrown exceptions as shown in the following example:
 258         </para>
 259
 260         <programlisting language="php"><![CDATA[
 261 $serverlist = array(
 262         // invalid servers
 263         'invalid_a'  => 'ntp://a.foo.bar.org',
 264         'invalid_b'  => 'sntp://b.foo.bar.org',
 265 );
 266
 267 $server = new Zend_TimeSync($serverlist);
 268
 269 try {
 270     $result = $server->getDate();
 271     echo $result->getIso();
 272 } catch (Zend_TimeSync_Exception $e) {
 273
 274     $exceptions = $e->get();
 275
 276     foreach ($exceptions as $key => $myException) {
 277         echo $myException->getMessage();
 278         echo '<br />';
 279     }
 280 }
 281 ]]></programlisting>
 282     </sect2>
 283 </sect1>