blueshoes php application framework and cms            core_date
[ class tree: core_date ] [ index: core_date ] [ all elements ]

Class: Bs_Date

Source Location: /core/date/Bs_Date.class.php

Class Overview

Bs_Object
   |
   --Bs_Date

This static class provides many useful date and time methods.


Author(s):

Version:

  • 4.5.$Revision: 1.2 $ $Date: 2003/10/29 17:48:37 $

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[line 60]
This static class provides many useful date and time methods.

This is new, untested code! please test the return values of the methods you're going to use... and make some comments in the methods you've used successfully. otherwise tell the author.

there are the following ways to write dates and times:

  1. the unix timestamp eg 982591823 for 2001-02-19 15:10:23 some notes about the unix timestamp: This timestamp is a long integer containing the number of seconds between the Unix Epoch (January 1 1970) and the time specified. On systems where time_t is a 32bit signed integer, as most common today, the valid range for year is somewhere between 1902 and 2037. Year may be a two or four digit value, with values between 0-69 mapping to 2000-2069 and 70-99 to 1970-1999.
  2. us datetime eg 2001/02/19 15:10:23 (there is also mm.dd.yyyy and mm.dd.yy which makes it terrible.)
  3. eu datetime eg 19.02.2001 15:10:23
  4. sql datetime eg 2001-02-19 15:10:23
  5. sql timestamp eg 20010219151023
  6. mysql datetime eg 2001-02-19 15:10:23 (actually mysql takes any special character instead of the '-'.)
  7. 'array' array('year'=>'2002', 'month'=>'12', 'day'=>'31', 'hour'=>'24', 'min'=>'59', 'sec'=>'59'); the values are stored as strings, not numbers. this way we can have '03' instead of '3' for a month for example.
the problem starts when ppl type in 19.2.01 and things like that, or don't use the expected punctuation like "." for eu dates and "/" for us dates.

while unix treats 0-69 as year 2000 and 70-99 as year 1900, we do it different here! 0-29 is considered 2000 and 30-99 is considered 1999. (because of the birthdays). i think it happens way more often that someone has to type in a birthday and just types 10.3.45 instead someone typing in 10.3.45 when he means an event on 10.3.2045. anyway... please be strict and don't accept 2-digit year values from user input. reject it! this is only the fallback... todo: add functionality to let the user define the year-range himself (what is 1900 and what is 2000).

to make things easier, when converting from one date type to another, like from us to eu, we convert it to a unix timestamp internally. this might be a problem for dates outside the timestamp range (January 1 1970 - 2037) ... phew ... should we change this behavior? i think yes.

dependencies: Bs_String




Tags:

copyright:  blueshoes.org
version:  4.5.$Revision: 1.2 $ $Date: 2003/10/29 17:48:37 $
author:  andrej arn <at blueshoes dot org>


[ Top ]


Class Variables

$_Bs_String =

[line 65]

reference to the global pseudostatic Bs_String object.


Type:   mixed


[ Top ]



Class Methods


constructor Bs_Date [line 71]

Bs_Date Bs_Date( )

constructor.



[ Top ]

method cleanDateArray [line 613]

array cleanDateArray( array $arr)

takes a date array and cleans its elements.

if these keys don't exist, they'll be added: 'year', 'month', 'day', 'hour', 'min', 'sec'




Tags:

return:  (hash)


Parameters:

array   $arr   (hash)

[ Top ]

method euDatetimeToSqlDatetime [line 820]

string euDatetimeToSqlDatetime( [string $euDatetime = ''])

converts a eu datetime into a sql datetime



Tags:

return:  sql datetime


Parameters:

string   $euDatetime  

[ Top ]

method euDatetimeToUnixTimestamp [line 444]

string euDatetimeToUnixTimestamp( mixed $euDatetime, string $usDatetime)

converts a eu datetime into a unix timestamp. eg 19.2.2001 15:10:23 -> 982591823

we are NOT using php's built in strToTime() because it returns wrong dates for eu dates :( at least until now, 2001/02/20. hope it will improve. so we use some own php code.

for the date part, we use our own euDateToUnixTimestamp() method. then we create a us date with formatUnixTimestamp(). finally we convert the us date together with the time part to a timestamp using usDatetimeToUnixTimestamp().

i have tested it and a) performance is definitely NOT an issue, and b) it works quite well, even with a date like "15.3.1999 10:26:10" (note the extra spaces in the middle).




Tags:

return:  unix timestamp


Parameters:

string   $usDatetime  

[ Top ]

method euDatetimeToUsDatetime [line 790]

string euDatetimeToUsDatetime( [string $euDatetime = ''])

converts a eu datetime into a us datetime



Tags:

return:  us datetime


Parameters:

string   $euDatetime  

[ Top ]

method euDateToArray [line 504]

array euDateToArray( string $euDate)

converts a eu date into an array.

this method does not use the unix-timestamp, so there is no limitation in the time range.




Tags:

return:  (hash with the keys 'year', 'month', 'day', 'hour', 'min' and 'sec' as strings.)
see:  Bs_Date::sqlDateToArray()
throws:  bool FALSE (not a valid date. eg wrong syntax, or 31.03.2002)


Parameters:

string   $euDate   (31.12.2002)

[ Top ]

method euDateToSqlDate [line 835]

string euDateToSqlDate( [string $euDate = ''])

converts a eu date into a sql date



Tags:

return:  sql date


Parameters:

string   $euDate  

[ Top ]

method euDateToUnixTimestamp [line 653]

string euDateToUnixTimestamp( mixed $euDate, string $usDatetime)

converts a eu date into a unix timestamp. eg 19.2.2001 -> 982591823

we are NOT using php's built in strToTime() because it returns wrong dates for eu dates :( at least until now, 2001/02/20. hope it will improve. so we use some own php code.




Tags:

return:  unix timestamp


Parameters:

string   $usDatetime  

[ Top ]

method euDateToUsDate [line 805]

string euDateToUsDate( [string $euDate = ''])

converts a eu date into a us date



Tags:

return:  us date


Parameters:

string   $euDate  

[ Top ]

method euTimeToUnixTimestamp [line 709]

string euTimeToUnixTimestamp( string $euTime)

converts a eu time into a unix timestamp. 15:10:23 ->

because the time looks the same in all versions (us, eu, sql) all these methods are using timeToUnixTimestamp().




Tags:

return:  unix timestamp
see:  Bs_Date::timeToUnixTimestamp()


Parameters:

string   $euTime  

[ Top ]

method formatArray [line 121]

string formatArray( [string $style = 'eu-2'], [array $array = NULL])

returns a date-array formatted as a date, time or datetime.

this method uses getFormatForStyle().




Tags:

see:  $this->getFormatForStyle()
access:  public


Parameters:

string   $style   how the datetime should be returned. getFormatForStyle(). default is 'eu-2'.
array   $array   (none means 'use the current date/time'.)

[ Top ]

method formatEuDatetime [line 253]

string formatEuDatetime( [string $style = 'eu-2'], [string $euDatetime = NULL])

returns a eu datetime formatted as any datetime, eg 27.8.1999 13:39:36 -> 1999/08/27 13:39:36 this method makes use of formatUnixTimestamp(), so watch out for the $style options.



Tags:



Parameters:

string   $style   how the datetime should be returned. see below. default is 'eu-2'.
string   $euDatetime   a eu datetime or none. none means 'use the current date/time'.

[ Top ]

method formatSqlDatetime [line 271]

string formatSqlDatetime( [string $style = 'eu-2'], [string $sqlDatetime = NULL])

returns a sql datetime formatted as any datetime, eg 1999-08-27 13:39:36 -> 27.8.1999 13:39:36 this method makes use of formatUnixTimestamp(), so watch out for the $style options.



Tags:



Parameters:

string   $style   how the datetime should be returned. see below. default is 'eu-2'.
string   $sqlDatetime   a sql datetime or none. none means 'use the current date/time'.

[ Top ]

method formatSqlTimestamp [line 289]

string formatSqlTimestamp( [string $style = 'eu-2'], [string $sqlTimestamp = NULL])

returns a mysql timestamp formatted as a datetime, eg 19990827133936 -> 27.08.1999 13:39:36 this method makes use of formatUnixTimestamp(), so watch out for the $style options.



Tags:



Parameters:

string   $style   how the datetime should be returned. see below. default is 'eu-2'.
string   $sqlTimestamp   a sql timestamp or none. none means 'use the current date/time'.

[ Top ]

method formatUnixTimestamp [line 100]

string formatUnixTimestamp( [string $style = 'eu-2'], [string $unixTimestamp = NULL])

returns a unix timestamp formatted as a datetime, eg 982591823 -> 19.02.2001 15:10:23.

this method uses getFormatForStyle().




Parameters:

string   $style   how the datetime should be returned. getFormatForStyle(). default is 'eu-2'.
string   $unixTimestamp   (a unix timestamp or none. none means 'use the current date/time'.)

[ Top ]

method formatUsDatetime [line 235]

string formatUsDatetime( [string $style = 'eu-2'], [string $usDatetime = NULL])

returns a us datetime formatted as any datetime, eg 1999/08/27 13:39:36 -> 27.08.1999 13:39:36 this method makes use of formatUnixTimestamp(), so watch out for the $style options.



Tags:



Parameters:

string   $style   how the datetime should be returned. see below. default is 'eu-2'.
string   $usDatetime   a us datetime or none. none means 'use the current date/time'.

[ Top ]

method getFormatForStyle [line 163]

string getFormatForStyle( [string $style = 'eu-2'])

takes a style definition and returns the format for it. see below.

possible values for the $style param:

'eu-1' -> dd.mm.yyyy hh:mm:ss 'eu-2' -> dd.mm.yyyy hh:mm 'eu-3' -> dd.mm.yyyy 'eu-4' -> hh:mm:ss 'eu-5' -> hh:mm

'us-1' -> yyyy/mm/dd hh:mm:ss 'us-2' -> yyyy/mm/dd hh:mm 'us-3' -> yyyy/mm/dd 'us-4' -> hh:mm:ss 'us-5' -> hh:mm

'sql-1' -> yyyy-mm-dd hh:mm:ss 'sql-2' -> yyyy-mm-dd hh:mm 'sql-3' -> yyyy-mm-dd 'sql-4' -> hh:mm:ss 'sql-5' -> hh:mm

'ts-1' -> yyyymmddhhmmss

note that 'sql' is the same format as 'iso', but there is no such alias. we're not gangsters we don't need aliases, right? :-)




Tags:

access:  public


Parameters:

string   $style   (see above)

[ Top ]

method getSeparator [line 588]

string getSeparator( string $date)

tries to find the separator used in a date.

example: 2002/12/31 => / 31.12.2002 => .




Tags:

return:  (char)
throws:  bool FALSE (nothing found)


Parameters:

string   $date  

[ Top ]

method monthNumberToString [line 1030]

string monthNumberToString( int $month, [string $lang = 'en'], [string $type = 'long'])

converts a numerical month value to a string.

the following languages are supported: en

example: $month = monthNumberToString(12); //returns 'December' $month = monthNumberToString(12, 'en', $type='short'); //returns 'Dec'




Tags:

todo:  maybe we better use the bs_kb.LangMonth table?
throws:  bool FALSE


Parameters:

int   $month  
string   $lang   the iso-code, default is 'en'. see above.
string   $type   one of 'long' (default) or 'short'.

[ Top ]

method monthStringToNumber [line 924]

mixed monthStringToNumber( string $month, [bool $zeroFill = FALSE])

converts a month like 'Feb' or 'February' into a numerical month value (2).

takes the param $month in the languages:

  • english en - danish da
  • french fr - italian it
  • german de - spanish es
  • dutch nl - portuguese pt
you don't need to "normalize" strings, eg 'février' to 'fevrier'.

for details see db-table bs_kb.LangMonth.




Tags:

return:  (int 1 to 12 or string '01' to '12' depending on $zeroFill)
throws:  int 0 (if not known, no match. does *not* return '00' if $zeroFill is TRUE.)


Parameters:

string   $month  
bool   $zeroFill   if set to TRUE, the return value is a 2 char string. default is FALSE.

[ Top ]

method monthToInt [line 1009]

void monthToInt( mixed $month, [mixed $zeroFill = FALSE])

use monthStringToNumber instead.



Tags:

deprecated:  


[ Top ]

method now [line 85]

string now( )

returns the current datetime in us style.

this function is an alias for this->formatUnixTimestamp('us-1')




Tags:

return:  current datetime in us style.
see:  $this->formatUnixTimestamp()


[ Top ]

method sqlDatetimeToEuDatetime [line 882]

string sqlDatetimeToEuDatetime( string $sqlDatetime)

converts a sql datetime into a european datetime



Tags:

return:  eu datetime


Parameters:

string   $sqlDatetime  

[ Top ]

method sqlDatetimeToUnixTimestamp [line 392]

string sqlDatetimeToUnixTimestamp( string $sqlDatetime)

converts a sql datetime into a unix timestamp. eg 2001-02-19 15:10:23 -> 982591823

we are using php's built in strToTime(). hope it will get better...




Tags:

return:  unix timestamp
throws:  -1


Parameters:

string   $sqlDatetime  

[ Top ]

method sqlDatetimeToUsDatetime [line 850]

string sqlDatetimeToUsDatetime( [string $sqlDatetime = ''])

converts a sql datetime into a us datetime eg '2001-02-28 20:54:23' -> '2001/02/28 20:54:23'



Tags:

return:  us datetime


Parameters:

string   $sqlDatetime  

[ Top ]

method sqlDateToArray [line 546]

array sqlDateToArray( string $sqlDate)

converts a sql date into an array.

this method does not use the unix-timestamp, so there is no limitation in the time range.




Tags:

see:  Bs_Date::euDateToArray()
throws:  bool FALSE (not a valid date. eg wrong syntax, or 2002-03-31)


Parameters:

string   $sqlDate   (2002-12-31)

[ Top ]

method sqlDateToEuDate [line 897]

string sqlDateToEuDate( [string $sqlDate = ''])

converts a sql date into a eu date



Tags:

return:  eu date


Parameters:

string   $sqlDate  

[ Top ]

method sqlDateToUnixTimestamp [line 407]

string sqlDateToUnixTimestamp( string $sqlDate)

converts a sql date into a unix timestamp. eg 2001-02-19 ->

we are using php's built in strToTime(). hope it will get better...




Tags:

return:  unix timestamp
throws:  bool false


Parameters:

string   $sqlDate  

[ Top ]

method sqlDateToUsDate [line 867]

string sqlDateToUsDate( [string $sqlDate = ''])

converts a sql date into a us date



Tags:

return:  us date


Parameters:

string   $sqlDate  

[ Top ]

method sqlTimestampToUnixTimestamp [line 306]

string sqlTimestampToUnixTimestamp( string $sqlTimestamp)

converts an sql timestamp into a unix timestamp. eg 20010219151023 -> 982591823



Tags:

return:  unix timestamp this method required Bs_String.


Parameters:

string   $sqlTimestamp  

[ Top ]

method sqlTimeToUnixTimestamp [line 422]

string sqlTimeToUnixTimestamp( string $sqlTime)

converts a sql time into a unix timestamp. 15:10:23 ->

because the time looks the same in all versions (us, eu, sql) all these methods are using timeToUnixTimestamp().




Tags:

return:  unix timestamp
see:  Bs_Date::timeToUnixTimestamp()


Parameters:

string   $sqlTime  

[ Top ]

method timeToUnixTimestamp [line 328]

string timeToUnixTimestamp( string $time)

converts a time into a unix timestamp. 15:10:23 -> 984665423

this function gets used by usDateToUnixTimestamp(), euDateToUnixTimestamp(), sqlDateToUnixTimestamp() because the time looks the same in all of these versions (us, eu, sql). the day, month and year of the returned timestamp will be from the current date.

we are using php's built in strToTime(). hope it will get better... but should be ok for the time stuff.




Tags:

return:  unix timestamp


Parameters:

string   $time  

[ Top ]

method usDatetimeToEuDatetime [line 721]

string usDatetimeToEuDatetime( [string $usDatetime = ''])

converts a us datetime into a european datetime



Tags:

return:  eu datetime


Parameters:

string   $usDatetime  

[ Top ]

method usDatetimeToSqlDatetime [line 760]

string usDatetimeToSqlDatetime( [string $usDatetime = ''])

converts a us datetime into a sql datetime



Tags:

return:  sql datetime


Parameters:

string   $usDatetime  

[ Top ]

method usDatetimeToUnixTimestamp [line 342]

string usDatetimeToUnixTimestamp( string $usDatetime)

converts a us datetime into a unix timestamp. eg 2001/02/19 15:10:23 -> 982591823

we are using php's built in strToTime(). hope it will get better...




Tags:

return:  unix timestamp


Parameters:

string   $usDatetime  

[ Top ]

method usDateToEuDate [line 741]

string usDateToEuDate( [string $usDate = ''])

converts a us date into a european date



Tags:

return:  eu date
throws:  bs_exception or -1, both is possible.


Parameters:

string   $usDate  

[ Top ]

method usDateToSqlDate [line 775]

string usDateToSqlDate( [string $usDate = ''])

converts a us date into a sql date



Tags:

return:  sql date


Parameters:

string   $usDate  

[ Top ]

method usDateToUnixTimestamp [line 362]

string usDateToUnixTimestamp( string $usDate)

converts a us date into a unix timestamp. eg 2001/02/19 ->

we are using php's built in strToTime(). hope it will get better...




Tags:

return:  unix timestamp


Parameters:

string   $usDate  

[ Top ]

method usTimeToUnixTimestamp [line 377]

string usTimeToUnixTimestamp( string $usTime)

converts a us time into a unix timestamp. 15:10:23 ->

because the time looks the same in all versions (us, eu, sql) all these methods are using timeToUnixTimestamp().




Tags:

return:  unix timestamp
see:  Bs_Date::timeToUnixTimestamp()


Parameters:

string   $usTime  

[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:08:39 +0100 by phpDocumentor 1.2.3