Geeklog Time... \'whitepaper\'

I've been working with Geeklog for more than six months now, and during that time the most often requested feature that I've seen has been for better (or any) handling of setting time zones different from the server and user preferenced time zones. To this end, I have suggestions on how to handle 'time' for possible use in Geeklog 2 and perhaps for future inclusion in the 1.3.x branch.

These are simple, straight forward recommendations meant more to spurn discussion then to be directly implemented into the codebase. However, these ideas are well thought out and have undergone some 'sanity' review.

There are currently almost 120 calls to the time() php function and about 55 calls to the sql now() function in the current geeklog (1.3.7) implementation. Since php and mysql do not allow these functions to be overridden, we must instead endeaver to replace them. Note: while reading this keep in mind that times entereted into the database must be kept consistent, we will need to have the ability to convert any user specified time zones to a universal 'site time' when populating the database and the reverse when retrieving from the database.

A simple solution, and probably the most obvious, would be replace all these function calls with a custom function call. This function would simply call the time() function and add the appropriate number of hours (times 3600) to take into account time zone differences. Perhaps this function, or another function, could also be used to return a user specified time zone by adding/subtracting a preferenced offset.

While workable, this solution has several drawbacks. First is that you still have 120 + 55 calls to time functions (though obviously only a small fraction of these are called each time a GL web page is accessed) which is redundent. While the time() and now() functions are really efficient, GL does not require accuracy Thinking along these lines brought me to the conclusion that a time class (stored in a global time variable) would be the best way to implement these time zone features. My reasoning is that once the class is initiated, we could access a time variable directly as precision within 5s is more than adequate for GL. Also within this structure we could store 'GL time' and 'user time' and increase the features available to GL users and adminsitrators for selecting time zones. This would give us the ability for every aspect of site time visible to the user to be consistent with their time zone.

In such a class, the 'GL time' can used both as the default user time and as the time GL uses to query and store date/time in the database, make (S)ID's, etc.. The 'user time' can be the display time, defaulted to match the GL time zone but user customizable to any time zone and date format (if the site administer so allows).

This theorized class could handle much more than the simple unix timestamp. When initialized we could have it populate string variables that contain short and long dates and use class member functions to covert other date/times into user local time zones and layouts.

To implement this would obviously require a new field in the database to hold each user's preferenced time zone (probably an offset from the 'site time') and perhaps additional date/time format options. Also, a config variable would likely need to be added to config.php setting a site time offset from the server. This offset could be in hours, but I think seconds may be better for extra flexibility. Perhaps a string of the form 2h, '120m', or '7200s' would be the most preferable to another choice.

A side effect and added benefit of implementing the class in the manner described here would be that moving a GL site to a server in another time zone would not cause a gap or overlap of the timestamps (used to generate the sid's) or require users to reselect a time zone offset. This, in effect, would make such a transfer appear seemless as a user with respect to site and article times.

I'm interested in knowing what other people think of this implementation or what other implementations you have come up with. I'd especially like to know what additional time releated features may or should be implemented.

An example psuedocode Time class:

class Time {
  var $GLtime;
  var $GLtimeString;
  var $GLtimeShortS;
  var $USRtime;
  var $USRtimeString;
  var $USRtimeShortS;

  function Time() {
    $this->GLtime = time() + $_CONF['GLTimeOffset'];
    $this->USRtime = $this->GLtime + $_USER['TimeOffsetFromGL'];
    $this->GLtimeString = getTimeString($this->GLtime);
    $this->GLtimeShortS = getTimeString($this->GLtime);
    $this->USRtimeString = getTimeString($this->USRtime);
    $this->USRtimeShortS = getTimeString($this->USRtime);
  }

  function getTime() {
    return $this->GLtime;
  }

  function getUSRTime() {
    return $this->USRtime;
  }

  function now() {
    // returns $this->GLtime formatted to be usefull with mysql calls
    // NOTE: the mysql now() function is syntax sensitive, using the numeric timestamp
    // or text formating based on context.  It should be enough adequate to return 
    // $this->GLtime directly, but some SQL in 1.3.x may need to be altered.
  }

  // since the time strings are probably only used for
  function getTimeString($time = '') {
    // returns time string to user preference for format and time zone, if $time not 
    // specified return $this->USRtime as default.  If no user time zone or format 
    // specified, use site defaults.
  }

  function getTimeShortS($time = '') {
    // same as above, but gets the short date/time format
  }

  // other functions...
  // GetTime functions for generic site time (ignore user preferenced time zone)
       // function getGLTimeString($time = '') 
       // function getGLTimeShortS($time = '')
  // Conversion funtions
       // function GL2USRtime()
       // function USR2GLtime()
  // more...?
}