<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.date.additional">

    <title>Working Examples</title>

    <para>
        Within this chapter, we will describe several additional functions which are also available through
        <classname>Zend_Date</classname>. Of course all described functions have additional examples to show the
        expected working and the simple API for the proper using of them.
    </para>

    <sect2 id="zend.date.additional.checking">

        <title>Checking Dates</title>

        <para>
            Probably most dates you will get as input are strings. But the problem with strings is that
            you can not be sure if the string is a real date. Therefor <classname>Zend_Date</classname> has spent
            an own static function to check date strings. <classname>Zend_Locale</classname> has an own function
            <code>getDate($date, $locale);</code> which parses a date and returns the proper and normalized
            date parts. A monthname for example will be recognised and returned just a month number.
            But as <classname>Zend_Locale</classname> does not know anything about dates because it is a
            normalizing and localizing class we have integrated an own function <code>isDate($date);</code>
            which checks this.
        </para>

        <para>
            <code>isDate($date, $format, $locale);</code> can take up to 3 parameters and needs minimum one
            parameter. So what we need to verify a date is, of course, the date itself as string.
            The second parameter can be the format which the date is expected to have. If no format is given
            the standard date format from your locale is used. For details about how formats should look like
            see the chapter about <link linkend="zend.date.constants.selfdefinedformats">self defined formats</link>
            .
        </para>

        <para>
            The third parameter is also optional as the second parameter and can be used to give a locale.
            We need the locale to normalize monthnames and daynames. So with the third parameter we are able
            to recognise dates like '01.Jänner.2000' or '01.January.2000' depending on the given locale.
        </para>

        <para>
            <code>isDate();</code> of course checks if a date does exist. <classname>Zend_Date</classname> itself does not
            check a date. So it is possible to create a date like '31.February.2000' with <classname>Zend_Date</classname>
            because <classname>Zend_Date</classname> will automatically correct the date and return the proper date.
            In our case '03.March.2000'. <code>isDate()</code> on the other side does this check and will return
            false on '31.February.2000' because it knows that this date is impossible.
        </para>

        <example id="zend.date.additional.checking.example-1">
            <title>Checking Dates</title>
            <programlisting role="php"><![CDATA[
// Checking dates
$date = '01.03.2000';
if (Zend_Date::isDate($date)) {
    print "String $date is a date";
} else {
    print "String $date is NO date";
}

// Checking localized dates
$date = '01 February 2000';
if (Zend_Date::isDate($date,'dd MMMM yyyy', 'en')) {
    print "String $date is a date";
} else {
    print "String $date is NO date";
}

// Checking impossible dates
$date = '30 February 2000';
if (Zend_Date::isDate($date,'dd MMMM yyyy', 'en')) {
    print "String $date is a date";
} else {
    print "String $date is NO date";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.date.additional.sunrise-sunset">

        <title>Sunrise and Sunset</title>

        <para>
            <classname>Zend_Date</classname> has also functions integrated for getting informations from the sun. Often it is
            necessary to get the time for sunrise or sunset within a particularly day. This is quite easy with
            <classname>Zend_Date</classname> as just the expected day has to be given and additionally location for which
            the sunrise or sunset has to be calculated.
        </para>

        <para>
            As most people do not know the location of their city we have also spent a helper class which provides
            the location data for about 250 capital and other big cities around the whole world. Most people could
            use cities near themself as the difference for locations situated to each other can only be measured
            within some seconds.
        </para>

        <para>
            For creating a listbox and choosing a special city the function <classname>Zend_Date_Cities::getCityList</classname>
            can be used. It returns the names of all available predefined cities for the helper class.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-1">
            <title>Getting all Available Cities</title>
            <programlisting role="php"><![CDATA[
// Output the complete list of available cities
print_r (Zend_Date_Cities::getCityList());
]]></programlisting>
        </example>

        <para>
            The location itself can be received with the <classname>Zend_Date_Cities::City()</classname> function.
            It accepts the name of the city as returned by the <classname>Zend_Date_Cities::getCityList()</classname>
            function and optional as second parameter the horizon to set.
        </para>

        <para>
            There are 4 defined horizons which can be used with locations to receive the exact time of sunset and
            sunrise. The '<code>horizon</code>' parameter is always optional in all functions. If it is not set, the
            '<code>effective</code>' horizon is used.
        </para>

        <table id="zend.date.additional.sunrise-sunset.table">
            <title>Types of Supported Horizons for Sunset and Sunrise</title>
            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Horizon</entry>
                        <entry>Description</entry>
                        <entry>Usage</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>effective</entry>
                        <entry>Standard horizon</entry>
                        <entry>Expects the world to be a ball. This horizon is always used if non is defined.</entry>
                    </row>
                    <row>
                        <entry>civil</entry>
                        <entry>Common horizon</entry>
                        <entry>Often used in common medias like TV or radio</entry>
                    </row>
                    <row>
                        <entry>nautic</entry>
                        <entry>Nautic horizon</entry>
                        <entry>Often used in sea navigation</entry>
                    </row>
                    <row>
                        <entry>astronomic</entry>
                        <entry>Astronomic horizon</entry>
                        <entry>Often used for calculation with stars</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Of course also a self-defined location can be given and calculated with. Therefor a '<code>latitude</code>'
            and a '<code>longitude</code>' has to be given and optional the '<code>horizon</code>'.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-2">
            <title>Getting the Location for a City</title>
            <programlisting role="php"><![CDATA[
// Get the location for a defined city
// uses the effective horizon as no horizon is defined
print_r (Zend_Date_Cities::City('Vienna'));

// use the nautic horizon
print_r (Zend_Date_Cities::City('Vienna', 'nautic'));

// self definition of a location
$mylocation = array('latitude' => 41.5, 'longitude' => 13.2446);
]]></programlisting>
        </example>

        <para>
            As now all needed data can be set the next is to create a <classname>Zend_Date</classname> object with the day where
            sunset or sunrise should be calculated. For the calculation there are 3 functions available. It is possible
            to calculate sunset with '<code>getSunset()</code>', sunrise with '<code>getSunrise()</code>' and all
            available informations related to the sun with '<code>getSunInfo()</code>'. After the calculation the
            <classname>Zend_Date</classname> object will be returned with the calculated time.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-3">
            <title>Calculating Sun Information</title>
            <programlisting role="php"><![CDATA[
// Get the location for a defined city
$city = Zend_Date_Cities::City('Vienna');

// create a date object for the day for which the sun has to be calculated
$date = new Zend_Date('10.03.2007', Zend_Date::ISO_8601, 'de');

// calculate sunset
$sunset = $date->getSunset($city);
print $sunset->get(Zend_Date::ISO_8601);

// calculate all sun informations
$info = $date->getSunInfo($city);
foreach ($info as $sun) {
    print "\n" . $sun->get(Zend_Date::ISO_8601);
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.date.additional.timezones">

        <title>Time Zones</title>

        <para>
            Time zones are as important as dates themselves. There are several time zones depending on where
            in the world a user lives. So working with dates also means to set the proper timezone.
            This may sound complicated but it's easier as expected. As already mentioned in the first chapter
            of <classname>Zend_Date</classname> the default timezone has to be set. Either by <code>php.ini</code> or
            by definition within the bootstrap file.
        </para>

        <para>
            A <classname>Zend_Date</classname> object of course also stores the actual timezone. Even if the timezone
            is changed after the creation of the object it remembers the original timezone and works with it.
            It is also not necessary to change the timezone within the code with PHP functions.
            <classname>Zend_Date</classname> has two built-in functions which makes it possible to handle this.
        </para>

        <para>
            <code>getTimezone()</code> returns the actual set timezone of within the <classname>Zend_Date</classname>
            object. Remember that <classname>Zend_Date</classname> is not coupled with PHP internals. So the returned
            timezone is not the timezone of the PHP script but the timezone of the object.
            <code>setTimezone($zone)</code> is the second function and makes it possible to set new timezone for
            <classname>Zend_Date</classname>. A given timezone is always checked. If it does not exist an exception will
            be thrown. Additionally the actual scripts or systems timezone can be set to the date object by
            calling  <code>setTimezone()</code> without the zone parameter. This is also done automatically
            when the date object is created.
        </para>

        <example id="zend.date.additional.timezones.example-1">
            <title>Working with Time Zones</title>
            <programlisting role="php"><![CDATA[
// Set a default timezone... this has to be done within the bootstrap
// file or php.ini.
// We do this here just for having a complete example.
date_default_timezone_set('Europe/Vienna');

// create a date object
$date = new Zend_Date('10.03.2007', Zend_Date::DATES, 'de');

// view our date object
print $date->getIso();

// what timezone do we have ?
print $date->getTimezone();

// set another timezone
$date->setTimezone('America/Chicago');

// what timezone do we now have ?
print $date->getTimezone();

// see the changed date object
print $date->getIso();
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Date</classname> always takes the actual timezone for object creation as shown in the first
            lines of the example. Changing the timezone within the created object also has an effect to the
            date itself. Dates are always related to a timezone. Changing the timezone for a <classname>Zend_Date</classname>
            object does not change the time of <classname>Zend_Date</classname>. Remember that internally dates are always
            stored as timestamps and in GMT. So the timezone means how much hours should be substracted or added
            to get the actual global time for the own timezone and region.
        </para>

        <para>
            Having the timezone coupled within <classname>Zend_Date</classname> has another positive effect. It is possible
            to have several dates with different timezones.
        </para>

        <example id="zend.date.additional.timezones.example-2">
            <title>Multiple Time Zones</title>
            <programlisting role="php"><![CDATA[
// Set a default timezone... this has to be done within the bootstrap
// file or php.ini.
// We do this here just for having a complete example.
date_default_timezone_set('Europe/Vienna');

// create a date object
$date = new Zend_Date('10.03.2007 00:00:00', Zend_Date::ISO_8601, 'de');

// view our date object
print $date->getIso();

// the date stays unchanged even after changeing the timezone
date_default_timezone_set('America/Chicago');
print $date->getIso();

$otherdate = clone $date;
$otherdate->setTimezone('Brazil/Acre');

// view our date object
print $otherdate->getIso();

// set the object to the actual systems timezone
$lastdate = clone $date;
$lastdate->setTimezone();

// view our date object
print $lastdate->getIso();
]]></programlisting>
        </example>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->