Skip to content

Latest commit

 

History

History
424 lines (310 loc) · 16.5 KB

README_EN.md

File metadata and controls

424 lines (310 loc) · 16.5 KB
Raw

TimeHelper

中文 | 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.

🧩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.

🚀Installation

Install via Composer.

composer require zjkal/time-helper

🌈Usage

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.
TimeHelper::secondEndToday();

//Return the number of seconds for N minutes (default is 1 minute).
TimeHelper::secondMinute(5);

//Return the number of seconds for N hours (default is 1 hour).
TimeHelper::secondHour(2);

//Return the number of seconds for N days (default is 1 day).
TimeHelper::secondDay(10);

//Return the number of seconds for N weeks (default is 1 week).
TimeHelper::secondWeek(4);

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');
//English
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.
TimeHelper::isYesterday(1586451741);

// Determine if a date is tomorrow.
TimeHelper::isTomorrow('2020-4-12');

// Determine if a date is this week.
TimeHelper::isThisWeek('2020-5-1');

// Determine if a date is this month.
TimeHelper::isThisMonth(1586451741);

// 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.
TimeHelper::getWeekDay('2022-11-27');

// Determine if a given time is a weekday (Monday through Friday).
TimeHelper::isWeekday('2023-03-08');

// Determine if a given time is a weekend day (Saturday or Sunday).
TimeHelper::isWeekend(1586451741);

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
TimeHelper::diffHours(1586451741,1586491741)

//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.
TimeHelper::afterMinute(5);

//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.
TimeHelper::afterHour(2);

//Return the timestamp of 0 o'clock 15 days ago.
TimeHelper::beforeDay(15,null,true);

//Return the timestamp of 15 days later.
TimeHelper::afterDay(15);

//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
TimeHelper::afterWeek(10,1646360133);

//Return the timestamp of 1 month before the specified time (Note that this usage is for PHP 8 or later)
TimeHelper::beforeMonth(datetime:1646360133);

//Return the timestamp 5 months from now
TimeHelper::afterMonth(5);

//Return the timestamp of 3 years ago from the specified time.
TimeHelper::beforeYear(3,'2022-7-11');

//Return the timestamp of 2 years later.
TimeHelper::afterYear(2);

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.
TimeHelper::getTimestamp();

//Get the millisecond-level timestamp.
TimeHelper::getMilliTimestamp();

//Get microsecond-level timestamp.
TimeHelper::getMicroTimestamp();

//Get the timestamp in nanoseconds.
TimeHelper::getNanoTimestamp();

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.
TimeHelper::isTimestamp(1646360133);

//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');

//Get the current time(default format is Y-m-d H:i:s)
TimeHelper::now();

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.
TimeHelper::daysInYear(1646360133);

//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
TimeHelper::timezoneFormat('America/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.
ChinaHoliday::isWorkday('2023-01-23');

//Determine if the specified date is a Chinese holiday.
ChinaHoliday::isHoliday(1646360133);

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.

📃Changelog

v1.1.11 December 17, 2024

  • Fixed a bug that could cause the wrong calculation of holiday data due to the difference in the time zone setting of the PHP runtime.

v1.1.10 Nov 16, 2024

  • Added data on Chinese holidays for 2025

v1.1.9 July 2, 2024

  • Added method to get the current time now()

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

😎Contributors

zjkal
zjkal 		miss-sugar
miss-sugar 		iuyes
李云龙 		ageChen
ageChen 		dkoin
dkoin

❤️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.

📖License

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