Download the PHP package marsapp/timeperiodhelper without Composer

TimePeriodHelper

The time period processing library provides functions such as sorting, union, difference, intersection, and calculation time.

Continuation library marshung/helper, only keep and maintain TimePeriodHelper

Outline

• Installation
  • Composer Install
  • Include
• Usage
  • Note
  • Example
• API Reference
  • Operation Function
  • sort()
  • union()
  • diff()
  • intersect()
  • isOverlap()
  • contact()
  • greaterThan()
  • lessThan()
  • fill()
  • gap()
  • time()
  • cut()
  • extend()
  • shorten()
  • format()
  • validate()
  • filter()
  • Options Function
  • setUnit()
  • getUnit()
  • setFilterDatetime()
  • getFilterDatetime()
  • setSortOut()
  • getSortOut()
  • Tools Function
  • isDatetime()
  • timeFormatConv()
  • time2Second()
• Log

Installation

Composer Install

Include

Include composer autoloader before use.

Usage

Note

1. Format: $timePeriods = [[$startDatetime1, $endDatetime1], [$startDatetime2, $endDatetime2], ...];
   • $Datetime = Y-m-d H:i:s ; Y-m-d H:i:00 ; Y-m-d H:00:00 ;
2. If it is hour/minute/second, the end point is usually not included, for example, 8 o'clock to 9 o'clock is 1 hour.
   • ●=====○
3. If it is a day/month/year, it usually includes an end point, for example, January to March is 3 months.
   • ●=====●
4. When processing, assume that the $timePeriods format is correct. If necessary, you need to call the verification function to verify the data.
5. Ensure performance by keeping the $timePeriods format correct:
   • When getting the raw $timePeriods, sort out it by format(), filter(), union().
   • Handle $timePeriods using only the functions provided by TimePeriodHelper (Will not break the format, sort)
   • When you achieve the two operations described above, you can turn off Auto sort out (TimePeriodHelper::setSortOut(false)) to improve performance.

     • Good data mastering is a good programmer
     • Data should be organized during the validation and processing phases. Then use trusted data as a logical operation

Example

setSortOut(), setUnit() Scope: Global Data should be organized during the validation and processing phases. Then use trusted data as a logical operation.

API Reference

Operation Function

sort()

Sort time periods (Order by ASC)

1. When sorting, sort the start time first, if the start time is the same, then sort the end time
2. Sort Priority: Start Time => End Time

Parameters

• $timePeriods: Time period being processed. array

Return Values

• Returns the resulting array.

Example :

union()

Union one or more time periods

1. Sort and merge one or more time periods with contacts
2. TimePeriodHelper::union($timePeriods1, $timePeriods2, $timePeriods3, ......);

Parameters

• $timePeriods: Time period being processed. array

Return Values

• Returns the resulting array.

Example :

diff()

Computes the difference of time periods

1. Compares $timePeriods1 against $timePeriods2 and returns the values in $timePeriods1 that are not present in $timePeriods2.
2. e.g. TimePeriodHelper::diff($timePeriods1, $timePeriods2);
3. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.

Parameters

• $timePeriods1: The time periods to compare from, array
• $timePeriods2: An time periods to compare against, array
• $sortOut: Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

Example :

intersect()

Computes the intersection of time periods

1. e.g. TimePeriodHelper::intersect($timePeriods1, $timePeriods2);
2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.

Parameters

• $timePeriods1: The time periods to compare from, array
• $timePeriods2: An time periods to compare against, array
• $sortOut: Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

Example :

isOverlap()

Time period is overlap

Determine if there is overlap between the two time periods

Parameters

• $timePeriods1: The time periods to compare from, array
• $timePeriods2: An time periods to compare against, array

Return Values

• Returns the resulting bool.

Example :

contact()

The time period is in contact with the specified time (time period)

Parameters

• $timePeriods: The time periods to compare from, array
• $sDateTime: Specified time to compare against, string
• $eDateTime: Specified time to compare against, string
• $sortOut: Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

Example :

greaterThan()

Time period greater than the specified time

Parameters

• $timePeriods: The time periods to compare from, array
• $refDatetime: Specified time to compare against, string
• $fullTimePeriod: Get only the full time period, bool
• $sortOut: Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

Example :

lessThan()

Time period less than the specified time

Parameters

• $timePeriods: The time periods to compare from, array
• $refDatetime: Specified time to compare against, string
• $fullTimePeriod: Get only the intact time period, bool
• $sortOut: Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

Example :

fill()

Fill time periods

Leaving only the first start time and the last end time

Parameters

• $timePeriods: Time period being processed. array

Return Values

• Returns the resulting array.

Example :

gap()

Get gap time periods of multiple sets of time periods

1. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.

Parameters

• $timePeriods: Time period being processed. array
• $sortOut: Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

Example :

time()

Calculation period total time

1. You can specify the smallest unit (from setUnit())
2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
3. approximation: chop off

Parameters

• $timePeriods: Time period being processed. array
• $precision: Optional decimal places for the decimal point. int
• $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting number.

Example :

Unit:

• hour, hours, h
• minute, minutes, m
• second, seconds, s

cut()

Cut the time period of the specified length of time

1. You can specify the smallest unit (from setUnit())
2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.

Parameters

• $timePeriods: Time period being processed. array
• $time: Specified length of time
• $sortOut: $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

Example :

Unit:

• hour, hours, h
• minute, minutes, m
• second, seconds, s

extend()

Increase the time period of the specified length of time after the last time period

1. You can specify the smallest unit (from setUnit())
2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.

Parameters

• $timePeriods: Time period being processed. array
• $time: Specified length of time
• $interval: Interval with existing time period
• $sortOut: $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

If you can be sure that the input value is already collated(Executed union())

Example :

Unit:

• hour, hours, h
• minute, minutes, m
• second, seconds, s

shorten()

Shorten the specified length of time from behind

1. You can specify the smallest unit (from setUnit())
2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.

Parameters

• $timePeriods: Time period being processed. array
• $time: Specified length of time
• $crossperiod: Whether to shorten across time
• $sortOut: $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()

Return Values

• Returns the resulting array.

If you can be sure that the input value is already collated(Executed union())

Example :

Unit:

• hour, hours, h
• minute, minutes, m
• second, seconds, s

format()

Transform format

Parameters

• $timePeriods: Time period being processed. array
• $unit: Time unit, if default,use class options setting

Return Values

• Returns the resulting array.

$unit: Time unit, if default,use class options setting

Example :

validate()

Validate time period

Verify format, size, start/end time.
Format: Y-m-d H:i:s

Parameters

• $timePeriods: Time period being processed. array

Return Values

• Returns the resulting bool.

Exception

• If there is an error, an exception will be thrown

Example :

filter()

Remove invalid time period

Verify format, size, start/end time, and remove invalid.

Parameters

• $timePeriods: Time period being processed. array @see setFilterDatetime();

Return Values

• Returns the resulting array.

Example :

• If you do not want to filter the datetime format, set it to setFilterDatetime(false).
• Maybe the time format is not Y-m-d H:i:s (such as Y-m-d H:i), you need to close it.

Options Function

setUnit()

Specify the minimum unit of calculation

1. Scope: Global
2. hour,minute,second

Parameters

• $unit: time unit. e.g. hour, minute, second.
• $target: Specify function,or all functions

Return Values

• self

Exception

• If there is an error, an exception will be thrown

Example :

getUnit()

Get the unit used by the specified function

Parameters

• $target: Specify function's unit

Return Values

• Returns the resulting string.

Exception

• If there is an error, an exception will be thrown

Example :

setFilterDatetime()

If neet filter datetime : Set option

1. Scope: Global
2. If you do not want to filter the datetime format, set it to false.
3. Maybe the time format is not Y-m-d H:i:s (such as Y-m-d H:i), you need to close it.

Parameters

• $bool: If you do not want to filter the datetime format, set it to false.

Return Values

• self

Example :

getFilterDatetime()

If neet filter datetime : Get option

Return Values

• Returns the resulting bool.

Example :

setSortOut()

Auto sort out $timePeriods : Set option

1. Before the function is processed, union() will be used to organize $timePeriods format.
2. Scope: Global

Parameters

• $bool: Set auto sort out or not

Return Values

• self

Example :

getSortOut()

Auto sort out $timePeriods : Get option

Return Values

• Returns the resulting bool.

Example :

Tools Function

isDatetime()

Check datetime fast.

Only check format,no check for reasonableness

Parameters

• $datetime: datetime (format:Y-m-d H:i:s). string

Return Values

• Returns the resulting bool.

Example :

timeFormatConv()

Time format convert

• format:Y-m-d H:i:s
• When the length is insufficient, it will add the missing

Parameters

• $datetime: datetime (format:Y-m-d H:i:s). string
• $unit: Time unit, if default,use class options setting

Return Values

• Returns the resulting string.

Example :

time2Second()

Time Conversion frm unit to second

Parameters

• $time: time. number
• $unit: Time unit, if default,use class options setting

Return Values

• Returns the resulting number.

Example :

Log

• 2019-03-24
  • Create By Mars.Hung
  • Document, Test
• 2019-07-04
  • Unit Test, Code Coverage
• 2019-07-06
  • Code Quality Test by scrutinizer, codeclimate