Timestamps

Most models in BZiON have at least one timestamp associated with them. As such, a lot of care has been put into properly handling and displaying dates and times. There is a number of helper functions and methods that can make sure timestamps are stored and shown correctly.

Database

All timestamps in the MySQL database are stored using the datetime format in the UTC timezone. That will prevent any issues caused when the database is transferred to another timezone, and even keep us unaffected from the Year 2038 problem! BZiON provides methods that will convert a timestamp to and from its MySQL representation.

Note that you should use the UTC_TIMESTAMP() MySQL method instead of NOW() when storing current timestamps directly to the database, since NOW() will incorrectly use the local timezone.

TimeDate class

BZiON uses the \TimeDate class to represent all timestamps. TimeDate is an extension of the Carbon library, which is itself an extension of PHP's original DateTime class. Carbon provides a great amount of helper methods that make working with timestamps much easier and more intuitive, about which you can read in Carbon's documentation page.

Our TimeDate class provides the fromMysql and toMysql methods, which will perform the necessary timezone and format conversions from and to a datetime readable by MySQL.

Note that modifier methods on TimeDate will both modify the object and return its modified version:

echo $dt->toDateTimeString();            // 2012-01-31 00:00:00

$later = $dt->addYears(5);
echo $dt->toDateTimeString();            // 2017-01-31 00:00:00
echo $later->toDateTimeString();         // 2017-01-31 00:00:00

In case this is not desirable, you can use the TimeDate::copy() method to clone the TimeDate object:

$dt = Carbon::now();

echo $dt->diffInYears($dt->copy()->addYears(5));  // 5
echo $dt->diffInYears($dt->addYears(5));          // 0

Displaying timestamps with Twig

Almost all timestamps in BZiON are displayed to the user using the humanTime twig filter. humanTime will format any TimeDate object according to the arguments provided to it or relatively to the current time (e.g. 2 days ago - unless the timestamp is too far in the past, in which case an absolute timestamp will be shown), and add an optional tooltip so that the user can find out the accurate timestamp of an event. It will also automatically convert the timestamp to the timezone specified by the user.

Timezones

Timezones in BZiON's database are stored as strings, such as Europe/Berlin, America/Chicago or UTC, corresponding to PHP's timezone list. We don't store timezones as the offset in hours and we don't use deprecated timezones such as Etc/GMT-1 because timezones are much more complex than a simple integer. (Also note that the + and - signs are reversed in PHP's Etc/GMT+... strings.)

In the user's profile page, only a handful of timezones is displayed (along with each one's offset), to prevent unnecessary clutter. However, BZiON will properly handle any timezone given to it.