vascowhite/time

A class to deal with operations on times independent of date.

v1.1.0 2016-10-05 11:48 UTC

Requires

• php: >=5.5.0

Requires (Dev)

• phpunit/phpunit: *

GPL-3.0

• Paul White

• time
• periods
• calculations

README

Moved to https://gitlab.com/vascowhite/Time

Time

Introduction

This is a class for dealing with times.

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.

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.

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.

Installation

Install using composer, add the following to composer.json:-

"require": {
    "vascowhite/time": "1.1.0"
}

Other methods of installation are possible, but not supported.

Requirements

Requires PHP >= 5.5.0

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.

There are various methods available for manipulating and comparing TimeValue objects.

TimeValue objects implement the __toString() magic method, so can be echoed etc..

TimeValue::__construct()

Signature:-

TimeValue __construct(String $time, String $format = 'H:i:s')

Arguments

$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'.

$format Optional format string, defaults to 'H:i:s'. Available formats are 'H:i:s', 'H', 'i', or 's'.

The following are examples of valid formats:-

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:-

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.

TimeValue::getSeconds()

Signature

Int getSeconds();

Arguments

None.

Return Returns an integer representing the number of seconds that the TimeValue spans.

Example

$time = new TimeValue('00:10:10');
echo $time->getSeconds; // Output 610

TimeValue::getTime()

Signature

String getTime()

Arguments

None.

Return

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.

Example

$time = new TimeValue('00:00:36000');
echo $time->getTime(); // Output "10:00:00"

TimeValue::add()

Signature

TimeValue add(TimeValue)

Arguments

The TimeValue to be added.

Return

Returns a TimeValue object set to the appropriate number of seconds.

Example

$time = new TimeValue('01:00:00');
echo $time->add(new TimeValue('30', 'i'); // Output "01:30:00"

TimeValue::sub()

Signature

TimeValue sub(TimeValue)

Arguments

The TimeValue to be subtracted.

Return

Returns a TimeValue object set to the appropriate number of seconds.

Example

$time = new TimeValue('01:00:00');
echo $time->sub(new TimeValue('00:30'); // Output "00:30:00"

TimeValue::average()

Signature

TimeValue average(TimeValues[])

Arguments

An array of TimeValue objects.

Return

Returns a TimeValue object set to the average number of seconds of the TimeValue objects in the supplied array.

Example

$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

TimeValue sum(TimeValues[])

Arguments

An array of TimeValue objects.

Return

Returns a TimeValue object set to the sum the TimeValue objects in the supplied array.

Example

$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

TimeValue createFromDateInterval(\DateInterval, bool)

Arguments

A \DateInterval object. A Boolean value. If true the returned \DateInterval object will represent a negative value. Defaults to false.

Return

Returns a TimeValue object set to the number of seconds represented by the \DateInterval object.

Example

$interval = new \DateInterval('P1Y1M6DT14H12M6S');
$timeValue = TimeValue::createFromDateInterval($interval); //34783926 seconds

TimeValue::toDateInterval()

Signature

TimeValue||Bool toDateInterval()

Arguments

None.

Return

Returns a \DateInterval object with all fields set as if created by \DateTime::diff(). Returns false if the conversion fails.

Example

$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
*/

TimeValue::format()

Signature

string format(string)

Arguments

A string representing the desired format. Uses same formatting as \DateInterval::format()