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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.timesync.working">
    <title>Working with Zend_TimeSync</title>

    <para>
        <classname>Zend_TimeSync</classname> can return the actual time from any given
        <emphasis>NTP</emphasis> or <emphasis>SNTP</emphasis> time server.
        It can automatically handle multiple servers and provides a simple interface.
    </para>

    <note>
        <para>
            All examples in this chapter use a public, generic time server:
            <emphasis>0.europe.pool.ntp.org</emphasis>. You should use a public, generic time server
            which is close to your application server. See <ulink
                url="http://www.pool.ntp.org">http://www.pool.ntp.org</ulink> for information.
        </para>
    </note>

    <sect2 id="zend.timesync.working.generic">
        <title>Generic Time Server Request</title>

        <para>
            Requesting the time from a time server is simple. First, you provide the time server
            from which you want to request the time.
        </para>

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

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

        <para>
            So what is happening in the background of <classname>Zend_TimeSync</classname>? First
            the syntax of the time server is checked. In our example,
            '<emphasis>0.pool.ntp.org</emphasis>' is checked and recognised as a possible address
            for a time server. Then when calling <methodname>getDate()</methodname> the actual set
            time server is requested and it will return its own time.
            <classname>Zend_TimeSync</classname> then calculates the difference to the actual time
            of the server running the script and returns a <classname>Zend_Date</classname> object
            with the correct time.
        </para>

        <para>
            For details about <classname>Zend_Date</classname> and its methods see the <link
                linkend="zend.date.introduction"><classname>Zend_Date</classname>
                documentation</link>.
        </para>
    </sect2>

    <sect2 id="zend.timesync.working.multiple">
        <title>Multiple Time Servers</title>

        <para>
            Not all time servers are always available to return their time. Servers may be
            unavailable during maintenance, for example. When the time cannot be requested from the
            time server, you will get an exception.
        </para>

        <para>
            <classname>Zend_TimeSync</classname> is a simple solution that can handle multiple time
            servers and supports an automatic fallback mechanism. There are two supported ways; you
            can either specify an array of time servers when creating the instance, or you can add
            additional time servers to the instance using the <methodname>addServer()</methodname>
            method.
        </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>
            There is no limit to the number of time servers you can add. When a time server can not
            be reached, <classname>Zend_TimeSync</classname> will fallback and try to connect to the
            next time server.
        </para>

        <para>
            When you supply more than one time server- which is considered a best practice for
            <classname>Zend_TimeSync</classname>- you should name each server. You can name your
            servers with array keys, with the second parameter at instantiation, or with the second
            parameter when adding another time server.
        </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>
            Naming the time servers allows you to request a specific time server as we will see
            later in this chapter.
        </para>
    </sect2>

    <sect2 id="zend.timesync.working.protocol">
        <title>Protocols of Time Servers</title>

        <para>
            There are different types of time servers. Most public time servers use the
            <emphasis>NTP</emphasis> protocol. But there are other time synchronization
            protocols available.
        </para>

        <para>
            You set the proper protocol in the address of the time server. There are two
            protocols which are supported by <classname>Zend_TimeSync</classname>:
            <emphasis>NTP</emphasis> and <emphasis>SNTP</emphasis>. The default protocol is
            <emphasis>NTP</emphasis>. If you are using <emphasis>NTP</emphasis>, you can omit the
            protocol in the address as demonstrated in the previous examples.
        </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> can handle mixed time servers. So you are not
            restricted to only one protocol; you can add any server independently from its protocol.
        </para>
    </sect2>

    <sect2 id="zend.timesync.working.ports">
        <title>Using Ports for Time Servers</title>

        <para>
            As with every protocol within the world wide web, the <emphasis>NTP</emphasis> and
            <emphasis>SNTP</emphasis> protocols use standard ports. NTP uses port
            <emphasis>123</emphasis> and SNTP uses port <emphasis>37</emphasis>.
        </para>

        <para>
            But sometimes the port that the protocols use differs from the standard one. You can
            define the port which has to be used for each server within the address. Just add the
            number of the port after the address. If no port is defined, then
            <classname>Zend_TimeSync</classname> will use the standard port.
        </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>Time Servers Options</title>

        <para>
            There is only one option within <classname>Zend_TimeSync</classname> which will be used
            internally: <emphasis>timeout</emphasis>. You can set any self-defined option you are in
            need of and request it, however.
        </para>

        <para>
            The option <emphasis>timeout</emphasis> defines the number of seconds after which
            a connection is detected as broken when there was no response. The default value is
            <emphasis>1</emphasis>, which means that <classname>Zend_TimeSync</classname> will
            fallback to the next time server if the requested time server does not respond in one
            second.
        </para>

        <para>
            With the <methodname>setOptions()</methodname> method, you can set any option. This
            function accepts an array where the key is the option to set and the value is the value
            of that option. Any previously set option will be overwritten by the new value. If you
            want to know which options are set, use the <methodname>getOptions()</methodname>
            method. It accepts either a key which returns the given option if specified, or, if no
            key is set, it will return all set options.
        </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>
            As you can see, the options for <classname>Zend_TimeSync</classname> are static. Each
            instance of <classname>Zend_TimeSync</classname> will use the same options.
        </para>
    </sect2>

    <sect2 id="zend.timesync.working.different">
        <title>Using Different Time Servers</title>

        <para>
            <classname>Zend_TimeSync</classname>'s default behavior for requesting a time is to
            request it from the first given server. But sometimes it is useful to set a different
            time server from which to request the time. This can be done with the
            <methodname>setServer()</methodname> method. To define the used time server set the
            alias as a parameter within the method. To get the actual used time server call the
            <methodname>getServer()</methodname> method. It accepts an alias as a parameter which
            defines the time server to be returned. If no parameter is given, the current time
            server will be returned.
        </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>Information from Time Servers</title>

        <para>
            Time servers not only offer the time itself, but also additional information. You can
            get this information with the <methodname>getInfo()</methodname> method.
        </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>
            The returned information differs with the protocol used and can also differ with the
            server used.
        </para>
    </sect2>

    <sect2 id="zend.timesync.working.exceptions">
        <title>Handling Exceptions</title>

        <para>
            Exceptions are collected for all time servers and returned as an array. So you can
            iterate through all thrown exceptions as shown in the following example:
        </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>