# Working Examples

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

## Checking Dates

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 Zend_Date has spent an own static function to check date strings. Zend_Locale has an own function getDate($date, $locale) 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 Zend_Locale does not know anything about dates because it is a normalizing and localizing class we have integrated an own function isDate($date) which checks this.

isDate($date, $format, $locale) 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 self defined formats.

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.

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

Checking Dates

    // 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";
    }

## Sunrise and Sunset

Zend_Date 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 Zend_Date as just the expected day has to be given and additionally location for which the sunrise or sunset has to be calculated.

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.

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

Getting all Available Cities

    // Output the complete list of available cities
    print_r (Zend_Date_Cities::getCityList());

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

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

Types of Supported Horizons for Sunset and Sunrise

Horizon | Description | Usage
--- | --- | ---
effective | Standard horizon | Expects the world to be a ball. This horizon is always used if non is defined.
civil | Common horizon | Often used in common medias like TV or radio
nautic | Nautic horizon | Often used in sea navigation
astronomic | Astronomic horizon | Often used for calculation with stars

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

Getting the Location for a City

    // 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);

As now all needed data can be set the next is to create a Zend_Date 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 'getSunset()', sunrise with 'getSunrise()' and all available informations related to the sun with 'getSunInfo()'. After the calculation the Zend_Date object will be returned with the calculated time.

Calculating Sun Information

    // 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);
    }

## Time Zones

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 Zend_Date the default timezone has to be set. Either by `php.ini` or by definition within the bootstrap file.

A Zend_Date 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. Zend_Date has two built-in functions which makes it possible to handle this.

getTimezone() returns the actual set timezone of within the Zend_Date object. Remember that Zend_Date is not coupled with PHP internals. So the returned timezone is not the timezone of the PHP script but the timezone of the object. setTimezone($zone) is the second function and makes it possible to set new timezone for Zend_Date. 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 setTimezone() without the zone parameter. This is also done automatically when the date object is created.

Working with Time Zones

    // 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();

Zend_Date 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 Zend_Date object does not change the time of Zend_Date. 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.

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

Multiple Time Zones

    // 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();