README

时间段处理库提供了排序、并集、差集、交集和计算时间等函数。

延续 marshung/helper 库，仅保留和维护 TimePeriodHelper

概要

• 安装
  • Composer 安装
  • 包含
• 用法
  • 注意
  • 示例
• API 参考
  • 操作函数
    • sort()
    • union()
    • diff()
    • intersect()
    • isOverlap()
    • contact()
    • greaterThan()
    • lessThan()
    • fill()
    • gap()
    • time()
    • cut()
    • extend()
    • shorten()
    • format()
    • validate()
    • filter()
  • 选项函数
    • setUnit()
    • getUnit()
    • setFilterDatetime()
    • getFilterDatetime()
    • setSortOut()
    • getSortOut()
  • 工具函数
    • isDatetime()
    • timeFormatConv()
    • time2Second()
• 日志

安装

Composer 安装

# composer require marsapp/timeperiodhelper

包含

在使用之前包含 composer 自动加载器。

require __PATH__ . "vendor/autoload.php";

用法

注意

1. 格式: $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. 如果是小时/分钟/秒，终点通常不包括在内，例如，从 8 点到 9 点是 1 小时。
   • ●=====○
3. 如果是日/月/年，通常包括终点，例如，从一月到三月是 3 个月。
   • ●=====●
4. 处理时，假设 $timePeriods 格式正确。如有必要，需要调用验证函数来验证数据。
5. 通过保持 $timePeriods 格式正确来确保性能
   • 获取原始 $timePeriods 时，使用 format()、filter()、union() 进行排序。
   • 仅使用 TimePeriodHelper 提供的函数处理 $timePeriods（不会破坏格式，排序）
   • 当实现上述两种操作后，可以关闭自动排序（TimePeriodHelper::setSortOut(false)）以提高性能。

   • 良好的数据掌握是一名优秀程序员
   • 在验证和处理阶段对数据进行组织。然后使用可信数据进行逻辑运算。

示例

// 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() 范围：全局数据应在验证和处理阶段进行组织。然后使用可信数据进行逻辑运算。

API 参考

操作函数

sort()

排序时间段（按升序排序）

1. 排序时，首先排序开始时间，如果开始时间相同，然后排序结束时间
2. 排序优先级：开始时间 => 结束时间

sort(Array $timePeriods) : array

参数

• $timePeriods: 正在处理的时段。数组

返回值

• 返回结果数组。

示例

$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()

合并一个或多个时间段

1. 排序并合并一个或多个具有联系的时间段
2. TimePeriodHelper::union($timePeriods1, $timePeriods2, $timePeriods3, ......);

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

参数

• $timePeriods: 正在处理的时段。数组

返回值

• 返回结果数组。

示例

$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()

计算时间段差集

1. 比较 $timePeriods1 和 $timePeriods2，并返回 $timePeriods1 中不存在于 $timePeriods2 中的值。
2. 例如：TimePeriodHelper::diff($timePeriods1, $timePeriods2);
3. $timePeriods 是否已排序将影响结果正确性。请参阅注意 5。通过保持 $timePeriods 格式正确来确保性能。

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

参数

• $timePeriods1: 比较的时段数组
• $timePeriods2: 要比较的时段数组
• $sortOut: 输入是否需要重新排列。值：true, false, 'default'。如果是 'default'，请参阅 getSortOut()

返回值

• 返回结果数组。

示例

$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()

计算时间段交集

1. 例如：TimePeriodHelper::intersect($timePeriods1, $timePeriods2);
2. $timePeriods 是否已排序将影响结果正确性。请参阅注意 5。通过保持 $timePeriods 格式正确来确保性能。

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

参数

• $timePeriods1: 比较的时段数组
• $timePeriods2: 要比较的时段数组
• $sortOut: 输入是否需要重新排列。值：true, false, 'default'。如果是 'default'，请参阅 getSortOut()

返回值

• 返回结果数组。

示例

$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()

时间段重叠

确定两个时间段是否存在重叠

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

参数

• $timePeriods1: 比较的时段数组
• $timePeriods2: 要比较的时段数组

返回值

• 返回结果布尔值。

示例

$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()

时间段与指定的时间（时间段）接触。

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

参数

• $timePeriods：要比较的时间段，数组。
• $sDateTime：要比较的指定时间，字符串。
• $eDateTime：要比较的指定时间，字符串。
• $sortOut: 输入是否需要重新排列。值：true, false, 'default'。如果是 'default'，请参阅 getSortOut()

返回值

• 返回结果数组。

示例

$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()

时间段大于指定时间。

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

参数

• $timePeriods：要比较的时间段，数组。
• $refDatetime：要比较的指定时间，字符串。
• $fullTimePeriod：仅获取完整的时间段，布尔值。
• $sortOut: 输入是否需要重新排列。值：true, false, 'default'。如果是 'default'，请参阅 getSortOut()

返回值

• 返回结果数组。

示例

$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()

时间段小于指定时间。

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

参数

• $timePeriods：要比较的时间段，数组。
• $refDatetime：要比较的指定时间，字符串。
• $fullTimePeriod：仅获取完整的时间段，布尔值。
• $sortOut: 输入是否需要重新排列。值：true, false, 'default'。如果是 'default'，请参阅 getSortOut()

返回值

• 返回结果数组。

示例

$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()

填充时间段。

仅保留第一个开始时间和最后一个结束时间。

fill(Array $timePeriods) : array

参数

• $timePeriods: 正在处理的时段。数组

返回值

• 返回结果数组。

示例

$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()

获取多组时间段的间隔时间段。

1. $timePeriods 是否已排序将影响结果正确性。请参阅注意 5。通过保持 $timePeriods 格式正确来确保性能。

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

参数

• $timePeriods: 正在处理的时段。数组
• $sortOut: 输入是否需要重新排列。值：true, false, 'default'。如果是 'default'，请参阅 getSortOut()

返回值

• 返回结果数组。

示例

$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()

计算时间段总时间。

1. 可以指定最小单位（从setUnit()获取）。
2. $timePeriods 是否已排序将影响结果正确性。请参阅注意 5。通过保持 $timePeriods 格式正确来确保性能。
3. 近似：截断。

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

参数

• $timePeriods: 正在处理的时段。数组
• $precision：小数点后的可选小数位数。整数。
• $sortOut：是否需要重新排列输入。值：true，false，'default'。如果是'default'，请参阅getSortOut()。

返回值

• 返回结果数字。

示例

$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;

单位

• 小时，小时，h
• 分钟，分钟，m
• 秒，秒，s

cut()

切割指定时间长度的时段。

1. 可以指定最小单位（从setUnit()获取）。
2. $timePeriods 是否已排序将影响结果正确性。请参阅注意 5。通过保持 $timePeriods 格式正确来确保性能。

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

参数

• $timePeriods: 正在处理的时段。数组
• $time：指定长度的时间。
• $sortOut：$sortOut 是否需要重新排列输入。值：true，false，'default'。如果是 'default'，请参阅 getSortOut()。

返回值

• 返回结果数组。

示例

$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']
// ];

单位

• 小时，小时，h
• 分钟，分钟，m
• 秒，秒，s

extend()

在最后一个时间段之后增加指定时间长度的时段。

1. 可以指定最小单位（从setUnit()获取）。
2. $timePeriods 是否已排序将影响结果正确性。请参阅注意 5。通过保持 $timePeriods 格式正确来确保性能。

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

参数

• $timePeriods: 正在处理的时段。数组
• $time：指定长度的时间。
• $interval：与现有时间段的时间间隔。
• $sortOut：$sortOut 是否需要重新排列输入。值：true，false，'default'。如果是 'default'，请参阅 getSortOut()。

返回值

• 返回结果数组。

如果可以确定输入值已经排序（执行了 union()）。

示例

$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']
// ];

单位

• 小时，小时，h
• 分钟，分钟，m
• 秒，秒，s

shorten()

从后面缩短指定长度的时间。

1. 可以指定最小单位（从setUnit()获取）。
2. $timePeriods 是否已排序将影响结果正确性。请参阅注意 5。通过保持 $timePeriods 格式正确来确保性能。

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

参数

• $timePeriods: 正在处理的时段。数组
• $time：指定长度的时间。
• $crossperiod：是否跨时间段缩短。
• $sortOut：$sortOut 是否需要重新排列输入。值：true，false，'default'。如果是 'default'，请参阅 getSortOut()。

返回值

• 返回结果数组。

如果可以确定输入值已经排序（执行了 union()）。

示例

$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']
// ];

单位

• 小时，小时，h
• 分钟，分钟，m
• 秒，秒，s

format()

转换格式

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

参数

• $timePeriods: 正在处理的时段。数组
• $unit：时间单位，如果是默认的，使用类选项设置。

返回值

• 返回结果数组。

$unit：时间单位，如果是默认的，使用类选项设置。

示例

$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()

验证时间段

验证格式，大小，开始/结束时间。
格式：Y-m-d H:i:s

validate(Array $timePeriods) : Exception | true

参数

• $timePeriods: 正在处理的时段。数组

返回值

• 返回结果布尔值。

异常

• 如果有错误，将抛出异常。

示例

$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()

移除无效的时间段。

验证格式，大小，开始/结束时间，并移除无效。

filter(Array $timePeriods) : array

参数

• $timePeriods：正在处理的时间段。数组 @see setFilterDatetime();

返回值

• 返回结果数组。

示例

$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'],
//];

• 如果您不想过滤datetime格式，请将其设置为 setFilterDatetime(false)。
• 可能的时间格式不是Y-m-d H:i:s（如Y-m-d H:i），您需要关闭它。

选项函数

setUnit()

指定计算的最小单位。

1. 范围：全局
2. 小时，分钟，秒

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

参数

• $unit：时间单位。例如：小时，分钟，秒。
• $target：指定函数，或所有函数

返回值

• self

异常

• 如果有错误，将抛出异常。

示例

// 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()

获取指定函数使用的单位。

getUnit(string $target) : string

参数

• $target：指定函数的单位

返回值

• 返回结果字符串。

异常

• 如果有错误，将抛出异常。

示例

// 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()

如果需要过滤datetime：设置选项

1. 范围：全局
2. 如果您不想过滤datetime格式，请将其设置为false。
3. 可能的时间格式不是Y-m-d H:i:s（如Y-m-d H:i），您需要关闭它。

setFilterDatetime(Bool $bool) : self

参数

• $bool：如果您不想过滤datetime格式，请将其设置为false。

返回值

• self

示例

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

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

getFilterDatetime()

如果需要过滤datetime：获取选项

getFilterDatetime() : bool

返回值

• 返回结果布尔值。

示例

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

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

setSortOut()

自动排序 $timePeriods：设置选项

1. 在函数处理之前，将使用 union() 组织 $timePeriods 格式。
2. 范围：全局

setSortOut(bool $bool = true) : self

参数

• $bool：设置是否自动排序

返回值

• self

示例

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

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

getSortOut()

自动排序 $timePeriods：获取选项

getSortOut() : bool

返回值

• 返回结果布尔值。

示例

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

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

工具函数

isDatetime()

快速检查日期时间。

仅检查格式，不检查合理性。

isDatetime(string $datetime) : bool

参数

• $datetime：日期时间（格式：Y-m-d H:i:s）。字符串

返回值

• 返回结果布尔值。

示例

$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()

时间格式转换

• 格式：Y-m-d H:i:s
• 当长度不足时，将添加缺失的部分。

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

参数

• $datetime：日期时间（格式：Y-m-d H:i:s）。字符串
• $unit：时间单位，如果是默认的，使用类选项设置。

返回值

• 返回结果字符串。

示例

$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()

时间从单位转换为秒

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

参数

• $time：时间。数字
• $unit：时间单位，如果是默认的，使用类选项设置。

返回值

• 返回结果数字。

示例

$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;

日志

• 2019-03-24
  • 创建者 Mars.Hung
  • 文档，测试
• 2019-07-04
  • 单元测试，代码覆盖率
• 2019-07-06
  • 通过 scrutinizer，codeclimate 进行代码质量测试