GOV/Webservice/PHP/GovTools.php

<?php

require_once('GovTimespan.php');

class GovTools {

   /**
     * Converts date specification given in years into julian dates.
     */
   function normalizeNames( $govObject ) {
      // convert names into an array if necessary
      if( !is_array( $govObject->name ) ) {
        $n = $govObject->name;
        $govObject->name = array();
        $govObject->name[0] = $n;
      }
      
      foreach( $govObject->name as $n ) {
        if( isset( $n->{'begin-year'} ) ) {
            $year = $n->{'begin-year'};
            $jd = cal_to_jd(CAL_GREGORIAN,1,1,$year);
            unset($n->{'begin-year'});
            $n->begin->precision = 0;
            $n->begin->jd = $jd;
        }
      
        if( isset( $n->{'end-year'} ) ) {
            $year = $n->{'end-year'};
            $jd = cal_to_jd(CAL_GREGORIAN,1,1,$year);
            unset($n->{'end-year'});
            $n->end->precision = 0;
            $n->end->jd = $jd;
        }
      
        if( isset( $n->year ) ) {
            $year = $n->year;
            $jd = cal_to_jd(CAL_GREGORIAN,1,1,$year);
            unset($n->year);
        }
      }
   }

   function getName( $govObject, $julianDay, $preferredLanguage ) {
        $foundBegin = GovTimespan.NO_BEGIN;
        $foundName = null;
        $foundLanguage = null;
        $foundNameIsValidAtInterestingTime = false;
        
        GovTools::normalizeNames($govObject);
        
        $interestingTime = new GovTimespan( $julianDay*10+2, $julianDay*10+2, true );
        
        foreach($govObject->name as $name ) {
            $nameTimeBegin = GovTimespan.NO_BEGIN;
            $nameBegin = GovTimespan.NO_BEGIN;
            $nameTimeEnd = GovTimespan.NO_END;
            if( isset($name->begin) ) { 
                $nameTimeBegin = $name->begin->jd * 10 + $name->begin->precision; 
                $nameBegin = $name->begin->jd ;
            }
            if( isset($name->end) ) { $nameTimeEnd = $name->end->jd * 10 + $name->end->precision; }
         
            $nameTime = new GovTimespan( $nameTimeBegin, $nameTimeEnd, true );

            if ($nameBegin <= $julianDay) {
                if (($preferredLanguage != null) &&
                        $preferredLanguage == $foundLanguage &&
                        $preferredLanguage != $name->lang) {
                    // TODO what should happen here?
                } else {
                    $weDontHaveAnyNameYet = ($foundName == null);
                    $weHaveNotFoundCorrectLanguage =
                        (($preferredLanguage != null) &&
                        $preferredLanguage != $foundLanguage &&
                        $preferredLanguage == $name->lang);
                    $thisNameIsYoungerThanTheAlreadyFound =
                        (abs($nameBegin - $julianDay) < abs($foundBegin - $julianDay));
                    $thisNameIsValidAtInterestingTime = $interestingTime->overlaps($nameTime);

                    /*
                     * Which conditions have to be satisfied to pick this name instead a possible other?
                     * 1. We don't have any name yet -> use this one
                     * 2. We have not found the correct language -> use this one
                     * 3. The already found name is not valid at the interesting time
                     *    AND
                     *       This name is valid at the interesting time.
                     *       OR
                     *       This name is younger than the already found name.
                     */
                    if ($weDontHaveAnyNameYet || $weHaveNotFoundCorrectLanguage ||
                            (!$foundNameIsValidAtInterestingTime &&
                            ( $thisNameIsValidAtInterestingTime | $thisNameIsYoungerThanTheAlreadyFound) )) {
                        $foundName = $name;
                        $foundBegin = $nameBegin;
                        $foundLanguage = $name->lang;
                        $foundNameIsValidAtInterestingTime = $interestingTime->overlaps($nameTime);
                    }
                }
            }
        }

        if (($foundName == null) && ($preferredLanguage != null)) {
            /* no name could be found for the specified language -> return a name in
             * any language
             */
            $foundName = GovTools::getName($govObject, $julianDay, null);
        }

        return $foundName->value;
   }
}

?>