PHPackages                             marsapp/timeperiodhelper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. marsapp/timeperiodhelper

ActiveLibrary

marsapp/timeperiodhelper
========================

TimePeriodHelper library provides functions such as sorting, union, difference, intersection, and calculation time.

0.7.0(3y ago)111.9k1[1 issues](https://github.com/marshung24/TimePeriodHelper/issues)1MITPHPPHP ^7 || ^8

Since Mar 26Pushed 3y agoCompare

[ Source](https://github.com/marshung24/TimePeriodHelper)[ Packagist](https://packagist.org/packages/marsapp/timeperiodhelper)[ Docs](https://github.com/marshung24/TimePeriodHelper)[ RSS](/packages/marsapp-timeperiodhelper/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)DependenciesVersions (12)Used By (1)

TimePeriodHelper
================

[](#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

[![Latest Stable Version](https://camo.githubusercontent.com/c9e495537c3bb57a5d7ae39efd153d40b127a73049e8049f5712b095db173c7c/68747470733a2f2f706f7365722e707567782e6f72672f6d6172736170702f74696d65706572696f6468656c7065722f762f737461626c65)](https://packagist.org/packages/marsapp/timeperiodhelper) [![Total Downloads](https://camo.githubusercontent.com/e0b0c78f85ff0e45663322e3c000c14db388f5fa8ce92ae780ea8e4f31b8e807/68747470733a2f2f706f7365722e707567782e6f72672f6d6172736170702f74696d65706572696f6468656c7065722f646f776e6c6f616473)](https://packagist.org/packages/marsapp/timeperiodhelper) [![Latest Unstable Version](https://camo.githubusercontent.com/3fb3e081a1dbf4167e23467c834489665f47d753d62a64a7e4cf185c117aee87/68747470733a2f2f706f7365722e707567782e6f72672f6d6172736170702f74696d65706572696f6468656c7065722f762f756e737461626c65)](https://packagist.org/packages/marsapp/timeperiodhelper) [![License](https://camo.githubusercontent.com/46f9ea3a78d3a738ba74d8e47d632cb92ad8b757965434d1fe4d798c57f8b8d7/68747470733a2f2f706f7365722e707567782e6f72672f6d6172736170702f74696d65706572696f6468656c7065722f6c6963656e7365)](https://packagist.org/packages/marsapp/timeperiodhelper) [![Build Status](https://camo.githubusercontent.com/f9ed8bc9b9a14cb4abe7083535bf0725ba5ca7e15f196cf1f40f5f10cc958937/68747470733a2f2f7472617669732d63692e636f6d2f6d61727368756e6732342f54696d65506572696f6448656c7065722e7376673f6272616e63683d6d6173746572)](https://travis-ci.com/marshung24/TimePeriodHelper) [![codecov](https://camo.githubusercontent.com/dc9cf5fa5254a7addc08041c2d74c2806b0be02018df9a27eb7e7a422263e2ee/68747470733a2f2f636f6465636f762e696f2f67682f6d61727368756e6732342f54696d65506572696f6448656c7065722f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/marshung24/TimePeriodHelper) [![Maintainability](https://camo.githubusercontent.com/079a9554489d3795035afeef5f548be76c4dde16e059b57219da114053c17b65/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f35646138336437333730663732336661363661662f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/marshung24/TimePeriodHelper/maintainability) [![Scrutinizer Code Quality](https://camo.githubusercontent.com/93d29fd8f7b60bccf43a83f3580462c347bd26658fb83279a4709ab94b2bc324/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6d61727368756e6732342f54696d65506572696f6448656c7065722f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/marshung24/TimePeriodHelper/?branch=master)

Outline
=======

[](#outline)

- [Installation](#installation)
    - [Composer Install](#composer-install)
    - [Include](#include)
- [Usage](#usage)
    - [Note](#note)
    - [Example](#example)
- [API Reference](#api-reference)
    - [Operation Function](#operation-function)
        - [sort()](#sort)
        - [union()](#union)
        - [diff()](#diff)
        - [intersect()](#intersect)
        - [isOverlap()](#isoverlap)
        - [contact()](#contact)
        - [greaterThan()](#greaterthan)
        - [lessThan()](#lessthan)
        - [fill()](#fill)
        - [gap()](#gap)
        - [time()](#time)
        - [cut()](#cut)
        - [extend()](#extend)
        - [shorten()](#shorten)
        - [format()](#format)
        - [validate()](#validate)
        - [filter()](#filter)
    - [Options Function](#options-function)
        - [setUnit()](#setunit)
        - [getUnit()](#getunit)
        - [setFilterDatetime()](#setfilterdatetime)
        - [getFilterDatetime()](#getfilterdatetime)
        - [setSortOut()](#setsortout)
        - [getSortOut()](#getsortout)
    - [Tools Function](#tools-function)
        - [isDatetime()](#isdatetime)
        - [timeFormatConv()](#timeformatconv)
        - [time2Second()](#time2second)
- [Log](#log)

[Installation](#outline)
========================

[](#installation)

[Composer Install](#outline)
----------------------------

[](#composer-install)

```
# composer require marsapp/timeperiodhelper

```

[Include](#outline)
-------------------

[](#include)

Include composer autoloader before use.

```
require __PATH__ . "vendor/autoload.php";
```

[Usage](#outline)
=================

[](#usage)

[Note](#outline)
----------------

[](#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](#outline)
-------------------

[](#example)

```
// Namespace use
use marsapp\helper\timeperiod\TimePeriodHelper;

// Get time periods. Maybe the data is confusing.
$workTimeperiods = [
    ['2019-01-04 13:00:30','2019-01-04 17:00:30'],
    ['2019-01-04 08:00:30','2019-01-04 10:00:30'],
    ['2019-01-04 10:00:30','2019-01-04 12:00:30'],
];

/*** Ensure performance by keeping the $timePeriods format correct ***/
// Filter $timeperiods to make sure the data is correct.
$workTimeperiods = TimePeriodHelper::filter($workTimeperiods);
// Sort out $timeperiods to make sure the content and sorting are correct.
$workTimeperiods = TimePeriodHelper::union($workTimeperiods);
// When you achieve the two operations described above, you can turn off Auto sort out (TimePeriodHelper::setSortOut(false)) to improve performance. (Global)
TimePeriodHelper::setSortOut(false);

// Set time unit (Global)
TimePeriodHelper::setUnit('minute');

// Maybe you want change time format
$workTimeperiods = TimePeriodHelper::format($workTimeperiods);

// Now value :
// $workTimeperiods = [ ['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 17:00:00'] ];

// Now you can execute the function you want to execute. Like gap()
$gapTimeperiods = TimePeriodHelper::gap($workTimeperiods);
// Result: [ ['2019-01-04 12:00:00','2019-01-04 13:00:00'] ]

// Calculation time
$workTime = TimePeriodHelper::time($workTimeperiods);
// Result: 480

$gapTime = TimePeriodHelper::time($gapTimeperiods);
// Result: 60
```

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

[API Reference](#outline)
=========================

[](#api-reference)

[Operation Function](#outline)
------------------------------

[](#operation-function)

### [sort()](#outline)

[](#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

```
sort(Array $timePeriods) : array
```

> Parameters
>
> - $timePeriods: Time period being processed. array
>
> Return Values
>
> - Returns the resulting array.

Example :

```
$templete = [
    ['2019-01-04 12:00:00','2019-01-04 18:00:00'],
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 12:00:00','2019-01-04 18:00:00'],
    ['2019-01-04 12:00:00','2019-01-04 17:00:00'],
    ['2019-01-04 12:00:00','2019-01-04 19:00:00'],
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 09:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 07:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 10:00:00','2019-01-04 16:00:00'],
    ['2019-01-04 11:00:00','2019-01-04 18:00:00'],
    ['2019-01-04 10:00:00','2019-01-04 18:00:00'],
    ['2019-01-04 11:00:00','2019-01-04 15:00:00']
];

$result = TimePeriodHelper::sort($templete);
//$result = [
//    ['2019-01-04 07:00:00','2019-01-04 12:00:00'],
//    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
//    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
//    ['2019-01-04 09:00:00','2019-01-04 12:00:00'],
//    ['2019-01-04 10:00:00','2019-01-04 16:00:00'],
//    ['2019-01-04 10:00:00','2019-01-04 18:00:00'],
//    ['2019-01-04 11:00:00','2019-01-04 15:00:00'],
//    ['2019-01-04 11:00:00','2019-01-04 18:00:00'],
//    ['2019-01-04 12:00:00','2019-01-04 17:00:00'],
//    ['2019-01-04 12:00:00','2019-01-04 18:00:00'],
//    ['2019-01-04 12:00:00','2019-01-04 18:00:00'],
//    ['2019-01-04 12:00:00','2019-01-04 19:00:00']
//];
```

### [union()](#outline)

[](#union)

Union one or more time periods

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

```
TimePeriodHelper::union(Array $timePeriods1, [Array $timePeriods2, [Array $timePeriods3, ......]]) : array
```

> Parameters
>
> - $timePeriods: Time period being processed. array
>
> Return Values
>
> - Returns the resulting array.

Example :

```
$templete1 = [
    ['2019-01-04 13:00:00','2019-01-04 15:00:00'],
    ['2019-01-04 10:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 19:00:00','2019-01-04 22:00:00'],
    ['2019-01-04 15:00:00','2019-01-04 18:00:00']
];

$templete2 = [
    ['2019-01-04 08:00:00','2019-01-04 09:00:00'],
    ['2019-01-04 14:00:00','2019-01-04 16:00:00'],
    ['2019-01-04 21:00:00','2019-01-04 23:00:00']
];
// Sort and merge one timeperiods
$result1 = TimePeriodHelper::union($templete1);
//$result1 = [
//    ['2019-01-04 10:00:00','2019-01-04 12:00:00'],
//    ['2019-01-04 13:00:00','2019-01-04 18:00:00'],
//    ['2019-01-04 19:00:00','2019-01-04 22:00:00']
//];

// Sort and merge two timeperiods
$result2 = TimePeriodHelper::union($templete1, $templete2);
//$result2 = [
//    ['2019-01-04 08:00:00','2019-01-04 09:00:00'],
//    ['2019-01-04 10:00:00','2019-01-04 12:00:00'],
//    ['2019-01-04 13:00:00','2019-01-04 18:00:00'],
//    ['2019-01-04 19:00:00','2019-01-04 23:00:00']
//];
```

### [diff()](#outline)

[](#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.

```
diff(Array $timePeriods1, Array $timePeriods2, $sortOut = 'default') : array
```

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

```
$templete1 = [
    ['2019-01-04 07:20:00','2019-01-04 08:00:00'],
    ['2019-01-04 07:00:00','2019-01-04 07:20:00'],
];
$templete2 = [
    ['2019-01-04 07:30:00','2019-01-04 07:40:00'],
];

/*** Note 5. Ensure performance by keeping the $timePeriods format correct. ***/
// 1. Set Auto sorting out (Scope: Global. Default, no need to set)
//TimePeriodHelper::setSortOut(true);

// 2. Set Manually sorting out (Scope: Global) (When a lot of logic operations, it is better)
TimePeriodHelper::setSortOut(false);
$templete1 = TimePeriodHelper::union($templete1);
$templete2 = TimePeriodHelper::union($templete2);

$result = TimePeriodHelper::diff($templete1, $templete2);
//$result = [
//    ['2019-01-04 07:00:00','2019-01-04 07:30:00'],
//    ['2019-01-04 07:40:00','2019-01-04 08:00:00'],
//];
```

### [intersect()](#outline)

[](#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.

```
intersect(Array $timePeriods1, Array $timePeriods2, $sortOut = 'default') : array
```

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

```
$templete1 = [
    ['2019-01-04 07:35:00','2019-01-04 08:00:00'],
    ['2019-01-04 07:00:00','2019-01-04 07:35:00'],
];
$templete2 = [
    ['2019-01-04 07:30:00','2019-01-04 07:40:00'],
];

/*** Note 5. Ensure performance by keeping the $timePeriods format correct. ***/
// 1. Set Auto sorting out (Scope: Global. Default, no need to set)
//TimePeriodHelper::setSortOut(true);

// 2. Set Auto sorting out (Scope: Global) (When a lot of logic operations, it is better)
TimePeriodHelper::setSortOut(false);
$templete1 = TimePeriodHelper::union($templete1);
$templete2 = TimePeriodHelper::union($templete2);

$result = TimePeriodHelper::intersect($templete1, $templete2);
//$result = [
//    ['2019-01-04 07:30:00','2019-01-04 07:40:00'],
//];
```

### [isOverlap()](#outline)

[](#isoverlap)

Time period is overlap

> Determine if there is overlap between the two time periods

```
isOverlap(Array $timePeriods1, Array $timePeriods2) : bool
```

> Parameters
>
> - $timePeriods1: The time periods to compare from, array
> - $timePeriods2: An time periods to compare against, array
>
> Return Values
>
> - Returns the resulting bool.

Example :

```
$templete1 = [
    ['2019-01-04 07:00:00','2019-01-04 08:00:00']
];
$templete2 = [
    ['2019-01-04 07:30:00','2019-01-04 07:40:00'],
];
$result = TimePeriodHelper::isOverlap($templete1, $templete2);
// $result = true;
```

### [contact()](#outline)

[](#contact)

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

```
contact(Array $timePeriods, String $sDateTime, String $eDateTime = null, $sortOut = 'default') : Array
```

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

```
$templete = [
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 13:00:00','2019-01-04 16:00:00'],
    ['2019-01-04 17:00:00','2019-01-04 19:00:00']
];

$result = TimePeriodHelper::contact($templete, '2019-01-04 12:00:00');
// $result = [];

$result = TimePeriodHelper::contact($templete, '2019-01-04 12:00:00', '2019-01-04 13:00:00');
// $result = [];

$result = TimePeriodHelper::contact($templete, '2019-01-04 12:00:00', '2019-01-04 14:00:00');
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00']];

$result = TimePeriodHelper::contact($templete, '2019-01-04 13:00:00');
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00']];

$result = TimePeriodHelper::contact($templete, '2019-01-04 13:00:00', '2019-01-04 14:00:00');
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00']];

$result = TimePeriodHelper::contact($templete, '2019-01-04 13:30:00');
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00']];

$result = TimePeriodHelper::contact($templete, '2019-01-04 13:30:00', '2019-01-04 18:00:00');
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00'], ['2019-01-04 17:00:00','2019-01-04 19:00:00']];

$result = TimePeriodHelper::contact($templete, '2019-01-04 13:30:00', '2019-01-04 22:00:00');
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00'], ['2019-01-04 17:00:00','2019-01-04 19:00:00']];
```

### [greaterThan()](#outline)

[](#greaterthan)

Time period greater than the specified time

```
greaterThan(Array $timePeriods, $refDatetime, $fullTimePeriod = true, $sortOut = 'default') : Array
```

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

```
$templete = [
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 13:00:00','2019-01-04 16:00:00'],
    ['2019-01-04 17:00:00','2019-01-04 19:00:00']
];

$result = TimePeriodHelper::greaterThan($templete, '2019-01-04 13:00:00', false);
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00'], ['2019-01-04 17:00:00','2019-01-04 19:00:00']];

$result = TimePeriodHelper::greaterThan($templete, '2019-01-04 14:00:00', false);
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00'], ['2019-01-04 17:00:00','2019-01-04 19:00:00']];

$result = TimePeriodHelper::greaterThan($templete, '2019-01-04 16:00:00', false);
// $result = [['2019-01-04 17:00:00','2019-01-04 19:00:00']];

$result = TimePeriodHelper::greaterThan($templete, '2019-01-04 13:00:00', true);
// $result = [['2019-01-04 13:00:00','2019-01-04 16:00:00'], ['2019-01-04 17:00:00','2019-01-04 19:00:00']];

$result = TimePeriodHelper::greaterThan($templete, '2019-01-04 14:00:00', true);
// $result = [['2019-01-04 17:00:00','2019-01-04 19:00:00']];

$result = TimePeriodHelper::greaterThan($templete, '2019-01-04 16:00:00', true);
// $result = [['2019-01-04 17:00:00','2019-01-04 19:00:00']];

$result = TimePeriodHelper::greaterThan($templete, '2019-01-04 14:00:00');
// $result = [['2019-01-04 17:00:00','2019-01-04 19:00:00']];
```

### [lessThan()](#outline)

[](#lessthan)

Time period less than the specified time

```
lessThan(Array $timePeriods, $refDatetime, $fullTimePeriod = true, $sortOut = 'default') : Array
```

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

```
$templete = [
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 13:00:00','2019-01-04 16:00:00'],
    ['2019-01-04 17:00:00','2019-01-04 19:00:00']
];

$result = TimePeriodHelper::lessThan($templete, '2019-01-04 13:00:00', false);
// $result = ['2019-01-04 08:00:00','2019-01-04 12:00:00']];

$result = TimePeriodHelper::lessThan($templete, '2019-01-04 14:00:00', false);
// $result = [['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 16:00:00']];

$result = TimePeriodHelper::lessThan($templete, '2019-01-04 16:00:00', false);
// $result = [['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 16:00:00']];

$result = TimePeriodHelper::lessThan($templete, '2019-01-04 13:00:00', true);
// $result = ['2019-01-04 08:00:00','2019-01-04 12:00:00']];

$result = TimePeriodHelper::lessThan($templete, '2019-01-04 14:00:00', true);
// $result = ['2019-01-04 08:00:00','2019-01-04 12:00:00']];

$result = TimePeriodHelper::lessThan($templete, '2019-01-04 16:00:00', true);
// $result = [['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 16:00:00']];

$result = TimePeriodHelper::lessThan($templete, '2019-01-04 14:00:00');
// $result = ['2019-01-04 08:00:00','2019-01-04 12:00:00']];
```

### [fill()](#outline)

[](#fill)

Fill time periods

> Leaving only the first start time and the last end time

```
fill(Array $timePeriods) : array
```

> Parameters
>
> - $timePeriods: Time period being processed. array
>
> Return Values
>
> - Returns the resulting array.

Example :

```
$templete = [
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 10:00:00','2019-01-04 19:00:00'],
    ['2019-01-04 12:00:00','2019-01-04 18:00:00']
];

$result = TimePeriodHelper::fill($templete);
//$result = [
//    ['2019-01-04 08:00:00','2019-01-04 19:00:00'],
//];
```

### [gap()](#outline)

[](#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.

```
gap(Array $timePeriods, $sortOut = 'default') : array
```

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

```
$templete = [
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 04:00:00','2019-01-04 05:00:00'],
    ['2019-01-04 07:00:00','2019-01-04 09:00:00'],
    ['2019-01-04 13:00:00','2019-01-04 18:00:00']
];

/*** Note 5. Ensure performance by keeping the $timePeriods format correct. ***/
// 1. Set Auto sorting out (Scope: Global. Default, no need to set)
//TimePeriodHelper::setSortOut(true);

// 2. Set Manually sorting out (Scope: Global) (When a lot of logic operations, it is better)
TimePeriodHelper::setSortOut(false);
$templete = TimePeriodHelper::union($templete);

$result = TimePeriodHelper::gap($templete);
//$result = [
//    ['2019-01-04 05:00:00','2019-01-04 07:00:00'],
//    ['2019-01-04 12:00:00','2019-01-04 13:00:00'],
//];
```

### [time()](#outline)

[](#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

```
time(Array $timePeriods, Int $precision = 0, $sortOut = 'default') : array
```

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

```
$templete = [
    ['2019-01-04 08:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 04:00:00','2019-01-04 05:00:00'],
    ['2019-01-04 07:00:00','2019-01-04 09:00:00'],
    ['2019-01-04 13:00:00','2019-01-04 18:30:30']
];

/*** Note 5. Ensure performance by keeping the $timePeriods format correct. ***/
// 1. Set Auto sorting out (Scope: Global. Default, no need to set)
//TimePeriodHelper::setSortOut(true);

// 2. Set Manually sorting out (Scope: Global) (When a lot of logic operations, it is better)
TimePeriodHelper::setSortOut(false);
$templete= TimePeriodHelper::union($templete);

TimePeriodHelper::setUnit('hour');
$resultH1 = TimePeriodHelper::time($templete);
// $resultH = 11;

$resultH2 = TimePeriodHelper::time($templete, 4);
// $resultH = 11.5083;

$resultM = TimePeriodHelper::setUnit('minutes')->time($templete, 2);
// $resultM = 690.5;

TimePeriodHelper::setUnit('s');
$resultS = TimePeriodHelper::time($templete);
// $resultS = 41430;
```

> Unit:
>
> - hour, hours, h
> - minute, minutes, m
> - second, seconds, s

### [cut()](#outline)

[](#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.

```
cut(Array $timePeriods, Int $time, $sortOut = 'default') : array
```

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

```
$templete = [
    ['2019-01-04 08:20:00','2019-01-04 12:00:00'],
    ['2019-01-04 08:00:00','2019-01-04 08:25:00']
];

/*** Note 5. Ensure performance by keeping the $timePeriods format correct. ***/
// 1. Set Auto sorting out (Scope: Global. Default, no need to set)
//TimePeriodHelper::setSortOut(true);

// 2. Set Manually sorting out (Scope: Global) (When a lot of logic operations, it is better)
TimePeriodHelper::setSortOut(false);
$templete = TimePeriodHelper::union($templete);

$resultM = TimePeriodHelper::setUnit('minutes')->cut($templete, '30');
// $resultM = [
//     ['2019-01-04 08:00:00','2019-01-04 08:30:00']
// ];

TimePeriodHelper::setUnit('hour');
$resultH1 = TimePeriodHelper::cut($templete, '30');
// $resultH1 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00']
// ];
```

> Unit:
>
> - hour, hours, h
> - minute, minutes, m
> - second, seconds, s

### [extend()](#outline)

[](#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.

```
extend(Array $timePeriods, Int $time, $interval = 0, $sortOut = 'default') : array
```

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

```
$templete = [
    ['2019-01-04 08:20:00','2019-01-04 12:00:00'],
    ['2019-01-04 08:00:00','2019-01-04 08:25:00'],
];

/*** Note 5. Ensure performance by keeping the $timePeriods format correct. ***/
// 1. Set Auto sorting out (Scope: Global. Default, no need to set)
//TimePeriodHelper::setSortOut(true);

// 2. Set Manually sorting out (Scope: Global) (When a lot of logic operations, it is better)
TimePeriodHelper::setSortOut(false);
$templete = TimePeriodHelper::union($templete);

$resultM1 = TimePeriodHelper::setUnit('minutes')->extend($templete, 30, 0);
// $resultM1 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:30:00']
// ];

$resultM2 = TimePeriodHelper::setUnit('minutes')->extend($templete, 30, 40);
// $resultM2 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 12:40:00','2019-01-04 13:10:00']
// ];

TimePeriodHelper::setUnit('hour');
$resultH1 = TimePeriodHelper::extend($templete, 2, 0);
// $resultH1 = [
//     ['2019-01-04 08:00:00','2019-01-04 14:00:00']
// ];

$resultH2 = TimePeriodHelper::setUnit('hour')->extend($templete, 2, 1);
// $resultH2 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 15:00:00']
// ];
```

> Unit:
>
> - hour, hours, h
> - minute, minutes, m
> - second, seconds, s

### [shorten()](#outline)

[](#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.

```
shorten(Array $timePeriods, Int $time, $crossperiod = true, $sortOut = 'default') : array
```

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

```
$templete = [
    ['2019-01-04 13:00:00','2019-01-04 15:00:00'],
    ['2019-01-04 08:20:00','2019-01-04 12:00:00'],
    ['2019-01-04 08:00:00','2019-01-04 08:25:00'],
];

/*** Note 5. Ensure performance by keeping the $timePeriods format correct. ***/
// 1. Set Auto sorting out (Scope: Global. Default, no need to set)
//TimePeriodHelper::setSortOut(true);

// 2. Set Manually sorting out (Scope: Global) (When a lot of logic operations, it is better)
TimePeriodHelper::setSortOut(false);
$templete = TimePeriodHelper::union($templete);

TimePeriodHelper::setUnit('minutes');
$resultM1 = TimePeriodHelper::shorten($templete, 30, true);
// $resultM1 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 14:30:00']
// ];

$resultH1 = TimePeriodHelper::setUnit('hour')->shorten($templete, 1, true);
// $resultH1 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 14:00:00']
// ];

$resultH2 = TimePeriodHelper::setUnit('hour')->shorten($templete, 2, true);
// $resultH2 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00']
// ];

$resultH3 = TimePeriodHelper::setUnit('hour')->shorten($templete, 5, true);
// $resultH3 = [
//     ['2019-01-04 08:00:00','2019-01-04 09:00:00']
// ];

$resultH4 = TimePeriodHelper::setUnit('hour')->shorten($templete, 10, true);
// $resultH4 = [];

$resultH5 = TimePeriodHelper::setUnit('hour')->shorten($templete, 1, false);
// $resultH5 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00'], ['2019-01-04 13:00:00','2019-01-04 14:00:00']
// ];

$resultH6 = TimePeriodHelper::setUnit('hour')->shorten($templete, 2, false);
// $resultH6 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00']
// ];

$resultH7 = TimePeriodHelper::setUnit('hour')->shorten($templete, 5, false);
// $resultH7 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00']
// ];

$resultH8 = TimePeriodHelper::setUnit('hour')->shorten($templete, 10, false);
// $resultH8 = [
//     ['2019-01-04 08:00:00','2019-01-04 12:00:00']
// ];
```

> Unit:
>
> - hour, hours, h
> - minute, minutes, m
> - second, seconds, s

### [format()](#outline)

[](#format)

Transform format

```
format(Array $timePeriods, $unit = 'default') : array
```

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

```
$templete = [
    ['2019-01-04 08:11:11','2019-01-04 12:22:22'],
    ['2019-01-04 04:33:33','2019-01-04 05:44:44'],
    ['2019-01-04 05:55','2019-01-04 06:55'],
    ['2019-01-04 07','2019-01-04 08'],
];

// Set time uint
TimePeriodHelper::setUnit('minute');

// Convert format
$result = TimePeriodHelper::format($templete);
//$result = [
//    ['2019-01-04 08:11:00','2019-01-04 12:22:00'],
//    ['2019-01-04 04:33:00','2019-01-04 05:44:00'],
//    ['2019-01-04 05:55:00','2019-01-04 06:55:00'],
//    ['2019-01-04 07:00:00','2019-01-04 08:00:00'],
//];
```

### [validate()](#outline)

[](#validate)

Validate time period

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

```
validate(Array $timePeriods) : Exception | true
```

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

```
$templete = [
    ['2019-01-04 02:00:00','2019-01-04 03:00:00'],
    ['2019-01-04 08:00:00','2019-01-04 12:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 04:00:00'],
    ['2019-01-04 04:00','2019-01-04 05:00:00'],
    'string',
    ['2019-01-04 08:00:00','2019-01-04 05:00:00'],
    ['2019-01-04 19:00:00','2019-01-04 19:00:00'],
];

try {
    $result = TimePeriodHelper::validate($templete);
} catch (\Exception $e) {
    $result = false;
}
//$result = false;
```

### [filter()](#outline)

[](#filter)

Remove invalid time period

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

```
filter(Array $timePeriods) : array
```

> Parameters
>
> - $timePeriods: Time period being processed. array @see setFilterDatetime();
>
> Return Values
>
> - Returns the resulting array.

Example :

```
$templete = [
    ['2019-01-04 02:00:00','2019-01-04 03:00:00'],
    ['2019-01-04 08:00:00','2019-01-04 12:00:00','2019-01-04 12:00:00'],
    ['2019-01-04 04:00:00'],
    ['2019-01-04 04:00','2019-01-04 05:00:00'],
    'string',
    ['2019-01-04 08:00:00','2019-01-04 05:00:00'],
    ['2019-01-04 19:00:00','2019-01-04 19:00:00'],
    ['2019-01-04 24:00:00','2019-01-05 24:00:00'],
];

// Set whether need to filter the datetime
//TimePeriodHelper::setFilterDatetime(false);

// Filter time period
$result = TimePeriodHelper::filter($templete);
//$result = [
//    ['2019-01-04 02:00:00','2019-01-04 03:00:00'],
//    ['2019-01-05 00:00:00','2019-01-06 00:00:00'],
//];
```

> - 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](#outline)
----------------------------

[](#options-function)

### [setUnit()](#outline)

[](#setunit)

Specify the minimum unit of calculation

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

```
setUnit(string $unit, string $target = 'all') : self
```

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

```
// Set unit hour for all
TimePeriodHelper::setUnit('hour');
// Set unit hour for format
TimePeriodHelper::setUnit('minute', 'format');

// Get unit
$result1 = TimePeriodHelper::getUnit('time');
//$result1 = 'hour';

$result2 = TimePeriodHelper::getUnit('format');
//$result2 = 'minute';
```

### [getUnit()](#outline)

[](#getunit)

Get the unit used by the specified function

```
getUnit(string $target) : string
```

> Parameters
>
> - $target: Specify function's unit
>
> Return Values
>
> - Returns the resulting string.
>
> Exception
>
> - If there is an error, an exception will be thrown

Example :

```
// Set unit hour for all
TimePeriodHelper::setUnit('hour');
// Set unit hour for format
TimePeriodHelper::setUnit('minute', 'format');

// Get unit
$result1 = TimePeriodHelper::getUnit('time');
//$result1 = 'hour';

$result2 = TimePeriodHelper::getUnit('format');
//$result2 = 'minute';
```

### setFilterDatetime()

[](#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.

```
setFilterDatetime(Bool $bool) : self
```

> Parameters
>
> - $bool: If you do not want to filter the datetime format, set it to false.
>
> Return Values
>
> - self

Example :

```
TimePeriodHelper::setFilterDatetime(false);
$result1 = TimePeriodHelper::getFilterDatetime();
//$result1 = false;

TimePeriodHelper::setFilterDatetime(true);
$result2 = TimePeriodHelper::getFilterDatetime();
//$result1 = true;
```

### [getFilterDatetime()](#outline)

[](#getfilterdatetime)

If neet filter datetime : Get option

```
getFilterDatetime() : bool
```

> Return Values
>
> - Returns the resulting bool.

Example :

```
TimePeriodHelper::setFilterDatetime(false);
$result1 = TimePeriodHelper::getFilterDatetime();
//$result1 = false;

TimePeriodHelper::setFilterDatetime(true);
$result2 = TimePeriodHelper::getFilterDatetime();
//$result1 = true;
```

### [setSortOut()](#outline)

[](#setsortout)

Auto sort out $timePeriods : Set option

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

```
setSortOut(bool $bool = true) : self
```

> Parameters
>
> - $bool: Set auto sort out or not
>
> Return Values
>
> - self

Example :

```
TimePeriodHelper::setSortOut(false);
$result1 = TimePeriodHelper::getSortOut();
//$result1 = false;

TimePeriodHelper::setSortOut(true);
$result2 = TimePeriodHelper::getSortOut();
//$result1 = true;
```

### [getSortOut()](#outline)

[](#getsortout)

Auto sort out $timePeriods : Get option

```
getSortOut() : bool
```

> Return Values
>
> - Returns the resulting bool.

Example :

```
TimePeriodHelper::setSortOut(false);
$result1 = TimePeriodHelper::getSortOut();
//$result1 = false;

TimePeriodHelper::setSortOut(true);
$result2 = TimePeriodHelper::getSortOut();
//$result1 = true;
```

[Tools Function](#outline)
--------------------------

[](#tools-function)

### [isDatetime()](#outline)

[](#isdatetime)

Check datetime fast.

> Only check format,no check for reasonableness

```
isDatetime(string $datetime) : bool
```

> Parameters
>
> - $datetime: datetime (format:Y-m-d H:i:s). string
>
> Return Values
>
> - Returns the resulting bool.

Example :

```
$result = TimePeriodHelper::isDatetime('2019-01-04 08:00:00');
// $result = true;

$result = TimePeriodHelper::isDatetime('2019-01-04 88:88:88');
// $result = true;

$result = TimePeriodHelper::isDatetime('2019-01-04 08:00');
// $result = false;
```

### [timeFormatConv()](#outline)

[](#timeformatconv)

Time format convert

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

```
 timeFormatConv(string $datetime, $unit = 'default') : string
```

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

```
$result = TimePeriodHelper::timeFormatConv('2019-01-04 08:33:33');
// $result = '2019-01-04 08:33:33';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08:33:33', 'default');
// $result = '2019-01-04 08:33:33';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08:33:33', 'second');
// $result = '2019-01-04 08:33:33';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08:33:33', 'minute');
// $result = '2019-01-04 08:33:00';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08:33:33', 'hour');
// $result = '2019-01-04 08:00:00';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08');
// $result = '2019-01-04 08:00:00';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08', 'default');
// $result = '2019-01-04 08:00:00';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08', 'default');
// $result = '2019-01-04 08:00:00';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08', 'default');
// $result = '2019-01-04 08:00:00';

$result = TimePeriodHelper::timeFormatConv('2019-01-04 08', 'default');
// $result = '2019-01-04 08:00:00';
```

### [time2Second()](#outline)

[](#time2second)

Time Conversion frm unit to second

```
time2Second($time, $unit = 'default') : number
```

> Parameters
>
> - $time: time. number
> - $unit: Time unit, if default,use class options setting
>
> Return Values
>
> - Returns the resulting number.

Example :

```
$result = TimePeriodHelper::time2Second(30);
// $result = 30;

$result = TimePeriodHelper::time2Second(30, 'default');
// $result = 30;

$result = TimePeriodHelper::time2Second(30, 'second');
// $result = 30;

$result = TimePeriodHelper::time2Second(30, 'minute');
// $result = 1800;

$result = TimePeriodHelper::time2Second(30, 'hour');
// $result = 108000;
```

[Log](#outline)
===============

[](#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

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity27

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~148 days

Recently: every ~362 days

Total

11

Last Release

1117d ago

PHP version history (2 changes)0.6.0PHP ^7.0

0.7.0PHP ^7 || ^8

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/34496839?v=4)[MarsHung](/maintainers/marshung24)[@marshung24](https://github.com/marshung24)

---

Top Contributors

[![marshung24](https://avatars.githubusercontent.com/u/34496839?v=4)](https://github.com/marshung24 "marshung24 (27 commits)")

### Embed Badge

![Health badge](/badges/marsapp-timeperiodhelper/health.svg)

```
[![Health](https://phpackages.com/badges/marsapp-timeperiodhelper/health.svg)](https://phpackages.com/packages/marsapp-timeperiodhelper)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)