4 Star 10 Fork 4

zjkal / time-helper

Create your Gitee Account
Explore and code with more than 12 million developers,Free private repositories !:)
Sign up
Clone or Download
Sync branch
Notice: Creating folder will generate an empty file .keep, because not support in Git


中文 | English

License PHP Version Require Latest Stable Version Total Downloads GitHub Workflow Status

TimeHelper is a simple and user-friendly PHP Date and Time Helper Library that enables quick implementation of common date and time operations. It includes functionalities such as getting the number of seconds from a specified time, obtaining a user-friendly time format, checking time ranges, calculating the difference between two times, and providing timestamps for N hours/days/weeks/months/years ago or in the future, among other features.


  • Easy to use: It does not rely on any extensions and is ready to use out of the box.
  • Simplicity through complexity reduction: All methods can accept either arbitrary date and time formats or timestamps.
  • Quick and efficient: All operations can be accomplished with just one static method for each.
  • Long-term maintenance: The author is a freelancer committed to ensuring the project's long-term stability and continuous updates.


Install via Composer.

composer require zjkal/time-helper


Check the Documentation or read the brief instructions below

1. Get the required number of seconds.

This is usually used for setting cache expiration time, setting end time, and so on.

//Return the number of seconds before midnight tonight.

//Return the number of seconds for N minutes (default is 1 minute).

//Return the number of seconds for N hours (default is 1 hour).

//Return the number of seconds for N days (default is 1 day).

//Return the number of seconds for N weeks (default is 1 week).

2. Return a friendly date format, such as N seconds ago, N minutes ago, N hours ago, and so on.

This is usually used for social media platforms, comments, forums, and so on.

//There are two parameters:
//The first parameter can be either a string representing a date/time or a timestamp.
//The second parameter is the language (default is Chinese; pass in "en" for English).
TimeHelper::toFriendly('2022-3-2 10:15:33');
TimeHelper::toFriendly(1646186290, 'en');

3. Determine if a date/time falls within a certain range.

//Determine if a date is today.
TimeHelper::isToday('2020-4-10 23:01:11');

// Determine if a date is yesterday.

// Determine if a date is tomorrow.

// Determine if a date is this week.

// Determine if a date is this month.

// Determine if a date is this year.
TimeHelper::isThisYear('Apr 11, 2020');

// Determine the day of the week for a given time. If no time is passed in, the current time is used. Returns a value from 1 to 7, where 1 is Monday and 7 is Sunday.

// Determine if a given time is a weekday (Monday through Friday).

// Determine if a given time is a weekend day (Saturday or Sunday).

4. Calculate the difference between two dates/times.

If only one parameter is passed in, it will be compared to the current time.

//Calculate the number of seconds between two dates
TimeHelper::diffSeconds('2022-4-10 23:01:11',1586451741)

//Calculate the number of minutes between two dates
TimeHelper::diffMinutes('Apr 11, 2020 11:51:21','Apr 11, 2020 11:31:21')

//Calculate the number of hours between two dates

//Calculate the difference in days between two dates.
TimeHelper::diffDays('2022-4-10 23:01:11','Apr 11, 2020');

//Calculate the difference in weeks between two dates.
TimeHelper::diffWeeks('2022-4-10 23:01:11');

//Calculate the difference in months between two dates.
TimeHelper::diffMonths(1586451741,'Apr 11, 2020');

//Calculate the difference in years between two dates.
TimeHelper::diffYears('2022-4-10 23:01:11','Apr 11, 2020');

//Compare two times. If the second parameter is empty, compare it with the current time.
//If the first time is greater than the second time, 1 is returned, if it is less than -1, and if they are equal, 0 is returned.
TimeHelper::compare('2022-4-10 23:01:11','Apr 11, 2020');

5. Return the timestamp of N hours/days/weeks/months/years ago or in the future.

If only one argument is passed, the calculation will be based on the current time. If a second argument is passed, the calculation will be based on that time. If the third argument is set to true, the calculated time will be rounded to the nearest integer.

//Return the timestamp of 0 seconds 3 minutes ago from the specified time.
TimeHelper::beforeMinute(3,'2022-3-2 10:15:33',true);

//Return the timestamp of 5 minutes after the current time.

//Return the timestamp of 1 hour before the specified time (Note: This usage is only available in PHP 8 or later).
TimeHelper::beforeHour(datetime:'Apr 11, 2020');

//Return the timestamp of 2 hours later.

//Return the timestamp of 0 o'clock 15 days ago.

//Return the timestamp of 15 days later.

//Return the timestamp of 2 weeks ago from the specified time.
TimeHelper::beforeWeek(2,'2022-4-10 23:01:11');

//Return the timestamp for 10 weeks after the specified time

//Return the timestamp of 1 month before the specified time (Note that this usage is for PHP 8 or later)

//Return the timestamp 5 months from now

//Return the timestamp of 3 years ago from the specified time.

//Return the timestamp of 2 years later.

6.Get the current timestamp in seconds/milliseconds/microseconds/nanoseconds.

Generating an order number or interfacing with other programming languages may require this.

//Get the timestamp in seconds. You can use time() instead.

//Get the millisecond-level timestamp.

//Get microsecond-level timestamp.

//Get the timestamp in nanoseconds.

7.Date Conversion

This function is used for converting date format when crawling web pages or integrating with third-party programs with inconsistent date formats.

//Convert any format of time to a specified format.
//The first parameter is the format of the time, consistent with the format of the system function date().
//The second parameter is the format of the time, which should be consistent with the format of the date() function. The second parameter is any format of the date and time. If not passed, it defaults to the current time, which can be replaced by the date() function.
TimeHelper::format('Y-m-d H:i:s','May 3, 2022');

//Check if a string is a timestamp, return true if it is, false if it is not.

//Convert any time string to a timestamp.
TimeHelper::toTimestamp('Apr 11, 2020');

//Based on the date string, modify the specified time and return the modified timestamp
TimeHelper::modifyTimestamp('+1 day', '2023-9-1 12:00:00');

8.Leap year calculation

More convenient to use than native methods.

//Determine whether it is a leap year, return true if it is, false if it is not.
TimeHelper::isLeapYear('2020-3-2 10:15:33');

//Determine how many days the year of the given date has.

//Determine how many days the current month of the given date has.
TimeHelper::daysInMonth('Apr 11, 2020');

9.Time zone related 🆕

It mainly provides methods for obtaining time in different time zones and converting time in different time zones

//Converts a time or timestamp in any format to a time in the specified time zone
//The first parameter is the target time zone to convert
//The second parameter is the original time zone, if not passed, it defaults to the current time zone
//The third parameter is a time or timestamp in any format, if not passed, it defaults to the current time
//The fourth parameter is the time format, which is consistent with the format of the system function date(). If not passed, the default is Y-m-d H:i:s
TimeHelper::timezoneFormat('Europe/London', 'Asia/Shanghai', '2023-8-15 19:16:43', 'H:i:s');
//Get the current time in Los Angeles
//Convert Los Angeles Time to London Time
TimeHelper::timezoneFormat('Europe/London', 'America/Los_Angeles', 'Aug 15, 2023 10:15:33', 'H:i:s');
//Convert timestamp to London time
TimeHelper::timezoneFormat('Europe/London', null, 1692097543);

For the list of supported time zones, please refer to List of Supported Timezones

10.Chinese holiday/workday related 🔥

This is a function specifically designed for judging Chinese holidays. It currently includes holiday data from 2020 to 2024 and will be continuously updated in the future. For the convenience of maintenance, a separate class ChinaHoliday is created, which can also accept any type of time format or timestamp as input.

use zjkal\ChinaHoliday;

//Determine if the specified date is a working day in China.

//Determine if the specified date is a Chinese holiday.

Special Notes: All time-related methods can accept time in any format or timestamp. However, please note that for dates in the format of m/d/y or d-m-y, if the separator is a slash (/), the American m/d/y format is used. If the separator is a hyphen (-) or a dot (.), the European d-m-y format is used. To avoid potential errors, it is recommended to use the YYYY-MM-DD format or other formats as much as possible.


v1.1.8 June 6, 2024

  • Fixed a bug to get friendly time

v1.1.7 June 1, 2024

  • Added method diffSeconds() to calculate the difference in seconds between two dates.
  • Added method diffMinutes() to calculate the difference in minutes between two dates.
  • Added method diffHours() to calculate the difference in hours between two dates.
  • Added modifyTimestamp() method to modify the specified time based on the date string.
  • Streamline the code

v1.1.6 Apr 25, 2024

  • Added method isYesterday() to determine if it is yesterday
  • Added method isTomorrow() to determine if it is tomorrow
Click to read more

v1.1.5 Feb 5, 2024

  • Streamline and optimize your code

v1.1.4 Oct 25, 2023

  • Added data for Chinese holidays in 2024

v1.1.3 Oct 19, 2023

  • Improved the compatibility of the toTimestamp() method and can convert time in some special formats

v1.1.2 Sep 16, 2023

  • Added method compare() to compare two times sooner or later

v1.1.1 Aug 15, 2023

  • Added time zone-related methods, which can convert time or timestamp in any format to the time in the specified time zone

v1.1.0 Mar 19, 2023

  • The ChinaHoliday class has been added, which is specially used to maintain methods related to Chinese holidays
  • Added the method isWorkday() to judge whether it is a Chinese working day
  • Added the method isHoliday() to judge whether it is a Chinese holiday

v1.0.10 Mar 13, 2023

  • Add the method isWeekday() to judge whether the specified date is a normal day
  • Add the method isWeekend() to judge whether the specified date is a weekend

v1.0.9 Mar 8, 2023

  • Modify the toTimestamp() method to return the current timestamp instead of throwing an exception when no parameter is passed or an empty parameter is passed in
  • Added the method isLeapYear() to judge whether it is a leap year
  • Added the method daysInYear() to get the number of days in the current year
  • Added the method daysInMonth() to get the number of days in the month of the date

v1.0.8 Feb 21, 2023

  • Added the method getWeekDay() to judge the day of the week for the specified time

v1.0.7 Feb 8, 2023

  • Added the method format() to convert time in any format to a specified format
  • Delete the obsolete method friendly_date(), please use toFriendly() instead

v1.0.6 Jan 27, 2023

  • fix bugs

v1.0.5 Jan 16, 2023

  • Optimized friendly time display algorithm

v1.0.4 Jan 8, 2023

  • Fixed the BUG of variable type

v1.0.3 Jan 7, 2023

  • Added a method to judge whether a string is a timestamp
  • Added a method to convert a string of any time type into a timestamp
  • Added a method to obtain timestamps at the second/millisecond/microsecond/nanosecond level

v1.0.2 Jan 5, 2023

  • Added method to return seconds for N minutes/hours

v1.0.1 Jan 4, 2023

  • For all methods that return timestamps of N minutes/hours/days/months/years ago or later, the parameter of rounding up is added.

v1.0.0 Aug 25, 2022

  • Separate from tp-helper's time class

❤️Sponsored by JetBrains

I would like to thank Jetbrains for providing me with the IDE open source license to complete the development work on this and other open source projects.



The MIT License (MIT). Please see License File for more information.

MIT License Copyright (c) 2024 zjkal Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


一个简单快捷高效的PHP日期时间助手类库。 a smart PHP datetime helper library. expand collapse

Releases (20)





Load More
can not load any more
马建仓 AI 助手


344bd9b3 5694891 D2dac590 5694891