Time
, (*1)
Introduction
This is a class for dealing with times., (*2)
This time data type represents a period of time. It is expressed in the format 'H:i:s' (a left truncation of the representation of datetime). It is the elapsed time that would be measured on a stop watch that is unaware of date, time zones or DST., (*3)
PHP's native \DatePeriod is excellent for representing a time period of any length, however it does not lend itself to manipulating time periods or performing calculations with them. Hence, this class was born. Its scope has been limited to hours, minutes and seconds for now as this allows for accurate manipulation without worrying about DST, etc., the DateTime classes already have that well covered., (*4)
This class can add, subtract, average, sum and compare times. It will also convert a \DateInterval object to a TimeValue and a TimeValue object into a \DateInterval object., (*5)
Installation
Install using composer, add the following to composer.json:-, (*6)
"require": {
"vascowhite/time": "1.1.0"
}
Other methods of installation are possible, but not supported., (*7)
Requirements
Requires PHP >= 5.5.0, (*8)
TimeValue
This is an immutable class that represents a time data type. It knows nothing about dates, if you need times associated with dates, then PHP's
\DateTime Classes are what you are looking for., (*9)
There are various methods available for manipulating and comparing TimeValue objects., (*10)
TimeValue objects implement the __toString() magic method, so can be echoed etc.., (*11)
TimeValue::__construct()
Signature:-, (*12)
TimeValue __construct(String $time, String $format = 'H:i:s')
Arguments, (*13)
$time is a string representing a period of time. For example one hour, sixteen minutes and thirty seconds would be represented thus: '01:16:30'., (*14)
$format Optional format string, defaults to 'H:i:s'. Available formats are 'H:i:s', 'H', 'i', or 's'., (*15)
The following are examples of valid formats:-, (*16)
new TimeValue('12:15:20'); // 12 hours 15 minutes 20 seconds
new TimeValue('12', 'H'); // 12 hours 0 minutes 0 seconds
new TimeValue('12:15', 'H:i'); // 12 hours 15 minutes
new TimeValue('12:15', 'i:s'); // 12 minutes 15 seconds
new TimeValue('20', 's'); // 20 seconds.
Although the formats are specified none of the fields are limited to 2 digits. The following are also valid:-, (*17)
new TimeValue('120:150:200'); // 120 hours 150 minutes 200 seconds Will output '122:33:20'
new TimeValue('00:00:36000'); // 36000 seconds. Will output '10:00:00'
Return
Returns a TimeValue object., (*18)
TimeValue::getSeconds()
Signature, (*19)
Int getSeconds();
Arguments, (*20)
None., (*21)
Return
Returns an integer representing the number of seconds that the TimeValue spans., (*22)
Example, (*23)
$time = new TimeValue('00:10:10');
echo $time->getSeconds; // Output 610
TimeValue::getTime()
Signature, (*24)
String getTime()
Arguments, (*25)
None., (*26)
Return, (*27)
Returns a string representing the time in the format 'H:i:s'. The 'H' portion will expand to the required number of digits to represent the hour., (*28)
Example, (*29)
$time = new TimeValue('00:00:36000');
echo $time->getTime(); // Output "10:00:00"
TimeValue::add()
Signature, (*30)
TimeValue add(TimeValue)
Arguments, (*31)
The TimeValue to be added., (*32)
Return, (*33)
Returns a TimeValue object set to the appropriate number of seconds., (*34)
Example, (*35)
$time = new TimeValue('01:00:00');
echo $time->add(new TimeValue('30', 'i'); // Output "01:30:00"
TimeValue::sub()
Signature, (*36)
TimeValue sub(TimeValue)
Arguments, (*37)
The TimeValue to be subtracted., (*38)
Return, (*39)
Returns a TimeValue object set to the appropriate number of seconds., (*40)
Example, (*41)
$time = new TimeValue('01:00:00');
echo $time->sub(new TimeValue('00:30'); // Output "00:30:00"
TimeValue::average()
Signature, (*42)
TimeValue average(TimeValues[])
Arguments, (*43)
An array of TimeValue objects., (*44)
Return, (*45)
Returns a TimeValue object set to the average number of seconds of the TimeValue objects in the supplied array., (*46)
Example, (*47)
$timeValue1 = new TimeValue('00:20:00'); //1200 seconds
$timeValue2 = new TimeValue('00:10:00'); //600 seconds
$timeValue3 = new TimeValue('00:30:00'); //1800 seconds
$average = TimeValue::average([$timeValue1, $timeValue2, $timeValue3]);
echo $average->getSeconds(); //Output = 1200
TimeValue::sum()
Signature, (*48)
TimeValue sum(TimeValues[])
Arguments, (*49)
An array of TimeValue objects., (*50)
Return, (*51)
Returns a TimeValue object set to the sum the TimeValue objects in the supplied array., (*52)
Example, (*53)
$timeValue1 = new TimeValue('00:20:00'); //1200 seconds
$timeValue2 = new TimeValue('00:10:00'); //600 seconds
$timeValue3 = new TimeValue('00:30:00'); //1800 seconds
$sum = TimeValue::sum([$timeValue1, $timeValue2, $timeValue3]);
echo $sum->getSeconds(); //Output = 3600
TimeValue::createFromDateInterval()
Signature, (*54)
TimeValue createFromDateInterval(\DateInterval, bool)
Arguments, (*55)
A \DateInterval object.
A Boolean value. If true the returned \DateInterval object will represent a negative value. Defaults to false., (*56)
Return, (*57)
Returns a TimeValue object set to the number of seconds represented by the \DateInterval object., (*58)
Example, (*59)
$interval = new \DateInterval('P1Y1M6DT14H12M6S');
$timeValue = TimeValue::createFromDateInterval($interval); //34783926 seconds
TimeValue::toDateInterval()
Signature, (*60)
TimeValue||Bool toDateInterval()
Arguments, (*61)
None., (*62)
Return, (*63)
Returns a \DateInterval object with all fields set as if created by \DateTime::diff(). Returns false if the conversion fails., (*64)
Example, (*65)
$timeValue = new TimeValue('34783926', 's');
var_dump($timeValue);
/*
Output
object(DateInterval)[2]
public 'y' => int 1
public 'm' => int 1
public 'd' => int 6
public 'h' => int 14
public 'i' => int 12
public 's' => int 6
public 'weekday' => int 0
public 'weekday_behavior' => int 0
public 'first_last_day_of' => int 0
public 'invert' => int 0
public 'days' => int 402
public 'special_type' => int 0
public 'special_amount' => int 0
public 'have_weekday_relative' => int 0
public 'have_special_relative' => int 0
*/
Signature, (*66)
string format(string)
Arguments, (*67)
A string representing the desired format. Uses same formatting as [\DateInterval::format()][3], (*68)
Wallogit.com
