[ZF-10089] Zend_Log

[zend.git] / documentation / manual / en / module_specs / Zend_Date-Additional.xml

<?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 <acronym>API</acronym> 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
            <methodname>getDate($date, $locale)</methodname> 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 <methodname>isDate($date)</methodname> which checks this.
        </para>

        <para>
            <methodname>isDate($date, $format, $locale)</methodname> 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 '<command>01.Jänner.2000</command>' or
            '<command>01.January.2000</command>' depending on the given locale.
        </para>

        <para>
            <methodname>isDate()</methodname> 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 '<command>31.February.2000</command>' with
            <classname>Zend_Date</classname> because <classname>Zend_Date</classname> will
            automatically correct the date and return the proper date. In our case
            '<command>03.March.2000</command>'. <methodname>isDate()</methodname> on the
            other side does this check and will return <constant>FALSE</constant> on
            '<command>31.February.2000</command>' because it knows that this date is impossible.
        </para>

        <example id="zend.date.additional.checking.example-1">
            <title>Checking Dates</title>

            <programlisting language="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
            <methodname>Zend_Date_Cities::getCityList()</methodname> 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 language="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
            <methodname>Zend_Date_Cities::city()</methodname> function. It accepts the name of the
            city as returned by the <methodname>Zend_Date_Cities::getCityList()</methodname>
            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 '<varname>$horizon</varname>' parameter is always optional in
            all functions. If it is not set, the '<property>effective</property>' 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
            '<property>latitude</property>' and a '<property>longitude</property>' has to be given
            and optional the '<property>horizon</property>'.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-2">
            <title>Getting the Location for a City</title>

            <programlisting language="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 '<methodname>getSunset()</methodname>', sunrise with
            '<methodname>getSunrise()</methodname>' and all available informations related to the
            sun with '<methodname>getSunInfo()</methodname>'. 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 language="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 <filename>php.ini</filename> 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 <acronym>PHP</acronym> functions. <classname>Zend_Date</classname>
            has two built-in functions which makes it possible to handle this.
        </para>

        <para>
            <methodname>getTimezone()</methodname> returns the actual set timezone of within the
            <classname>Zend_Date</classname> object. Remember that <classname>Zend_Date</classname>
            is not coupled with <acronym>PHP</acronym> internals. So the returned timezone is not
            the timezone of the <acronym>PHP</acronym> script but the timezone of the object.
            <methodname>setTimezone($zone)</methodname> 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
            <methodname>setTimezone()</methodname> 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 language="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 <acronym>GMT</acronym>. 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 language="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:
-->