ivyforms / backend / src / Common / Helpers / DateTimeHelper / DateTimeHelper.php

DateTimeHelper.php in The Innovative Form Builder – IvyForms 0.8, at backend/src/Common/Helpers/DateTimeHelper/DateTimeHelper.php

248 lines 7.5 KB

Raw Download Zip

1	<?php
2
3	namespace IvyForms\Common\Helpers\DateTimeHelper;
4
5	// phpcs:disable PSR1.Files.SideEffects
6	if (!defined('ABSPATH')) {
7	exit; // Exit if accessed directly
8	}
9	use DateTimeImmutable;
10	use DateTimeZone;
11	use Exception;
12	use RuntimeException;
13	use IvyForms\Services\Translations\BackendStrings;
14
15	/**
16	* Helper utilities for date and time operations.
17	*/
18	class DateTimeHelper
19	{
20	/**
21	* Convert time string (HH:MM or HH:MM:SS) to Unix timestamp using current date in WP timezone.
22	*
23	* @param mixed $value Time value (HH:MM, HH:MM:SS, or numeric timestamp)
24	* @return int\|null Unix timestamp or null if invalid
25	*/
26	public static function timeToTimestamp($value): ?int
27	{
28	if ($value === null \|\| $value === '') {
29	return null;
30	}
31
32	// If already numeric (timestamp), validate and return
33	if (is_numeric($value)) {
34	return (int)$value;
35	}
36
37	$timeString = trim((string)$value);
38	return self::parseTimeStringToTimestamp($timeString);
39	}
40
41	/**
42	* Parse time string (HH:MM or HH:MM:SS) to Unix timestamp.
43	*
44	* @param string $timeString Time string to parse
45	* @return int\|null Unix timestamp or null if invalid
46	*/
47	private static function parseTimeStringToTimestamp(string $timeString): ?int
48	{
49	if (!preg_match('/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/', $timeString, $matches)) {
50	return null;
51	}
52
53	$hours = (int)$matches[1];
54	$minutes = (int)$matches[2];
55	$seconds = isset($matches[3]) ? (int)$matches[3] : 0;
56
57	if (!self::isValidTimeComponents($hours, $minutes, $seconds)) {
58	return null;
59	}
60
61	return self::createTimestampFromTime($hours, $minutes, $seconds);
62	}
63
64	/**
65	* Validate time components.
66	*
67	* @param int $hours Hours (0-23)
68	* @param int $minutes Minutes (0-59)
69	* @param int $seconds Seconds (0-59)
70	* @return bool True if valid
71	*/
72	private static function isValidTimeComponents(int $hours, int $minutes, int $seconds): bool
73	{
74	return $hours <= 23 && $minutes <= 59 && $seconds <= 59;
75	}
76
77	/**
78	* Create Unix timestamp from time components using today's date.
79	*
80	* @param int $hours Hours
81	* @param int $minutes Minutes
82	* @param int $seconds Seconds
83	* @return int Unix timestamp
84	* @throws RuntimeException If unable to create timestamp
85	*/
86	private static function createTimestampFromTime(int $hours, int $minutes, int $seconds): int
87	{
88	try {
89	$timezone = self::getWpTimezone();
90	$today = new DateTimeImmutable('today', $timezone);
91	$dateString = $today->format('Y-m-d');
92	$timeString = sprintf('%02d:%02d:%02d', $hours, $minutes, $seconds);
93	$dateTime = new DateTimeImmutable("$dateString $timeString", $timezone);
94	return $dateTime->getTimestamp();
95	} catch (\Throwable $exception) {
96	throw new RuntimeException(
97	BackendStrings::getExceptionStrings()['time_conversion_failed'] . ': ' . $exception->getMessage()
98	);
99	}
100	}
101
102	/**
103	* Format Unix timestamp back to time string (HH:MM).
104	*
105	* @param int $timestamp Unix timestamp
106	* @return string Formatted time string without seconds
107	*/
108	public static function timestampToTime(int $timestamp): string
109	{
110	$timezone = self::getWpTimezone();
111	$dateTime = new DateTimeImmutable('@' . $timestamp);
112	$dateTime = $dateTime->setTimezone($timezone);
113	return $dateTime->format('H:i');
114	}
115
116	/**
117	* Format Unix timestamp back to time string with seconds (HH:MM:SS).
118	*
119	* @param int $timestamp Unix timestamp
120	* @return string Formatted time string with seconds
121	*/
122	public static function timestampToTimeWithSeconds(int $timestamp): string
123	{
124	$timezone = self::getWpTimezone();
125	$dateTime = new DateTimeImmutable('@' . $timestamp);
126	$dateTime = $dateTime->setTimezone($timezone);
127	return $dateTime->format('H:i:s');
128	}
129
130	/**
131	* Get WordPress timezone.
132	*
133	* @return DateTimeZone
134	* @throws RuntimeException If unable to get valid timezone
135	*/
136	public static function getWpTimezone(): DateTimeZone
137	{
138	if (!function_exists('wp_timezone')) {
139	throw new RuntimeException(BackendStrings::getExceptionStrings()['wp_timezone_not_exist']);
140	}
141
142	return wp_timezone();
143	}
144
145	/**
146	* Normalize time values to Unix timestamp format.
147	*
148	* @param int\|string\|null $value Field value
149	* @return string Normalized value as string
150	*/
151	public static function normalizeTimeValue($value): string
152	{
153	if ($value === null \|\| $value === '') {
154	return '';
155	}
156
157	return (string)(self::timeToTimestamp($value) ?? $value);
158	}
159
160	/**
161	* Convert date string (YYYY-MM-DD or various formats) to Unix timestamp.
162	*
163	* @param mixed $value Date value (YYYY-MM-DD, or numeric timestamp)
164	* @return int\|null Unix timestamp or null if invalid
165	*/
166	public static function dateToTimestamp($value): ?int
167	{
168	if ($value === null \|\| $value === '') {
169	return null;
170	}
171
172	// If already numeric (timestamp), validate and return
173	if (is_numeric($value)) {
174	return (int)$value;
175	}
176
177	$dateString = trim((string)$value);
178	return self::parseDateStringToTimestamp($dateString);
179	}
180
181	/**
182	* Parse date string to Unix timestamp.
183	*
184	* @param string $dateString Date string to parse
185	* @return int\|null Unix timestamp or null if invalid
186	*/
187	public static function parseDateStringToTimestamp(string $dateString): ?int
188	{
189	try {
190	$timezone = self::getWpTimezone();
191	$dateTime = new DateTimeImmutable($dateString, $timezone);
192
193	// Set time to midnight (00:00:00) for date-only values
194	$dateTime = $dateTime->setTime(0, 0, 0);
195
196	return $dateTime->getTimestamp();
197	} catch (\Throwable $exception) {
198	return null;
199	}
200	}
201
202	/**
203	* Format Unix timestamp back to date string (YYYY-MM-DD).
204	*
205	* @param int $timestamp Unix timestamp
206	* @return string Formatted date string
207	* @throws Exception
208	*/
209	public static function timestampToDate(int $timestamp): string
210	{
211	$timezone = self::getWpTimezone();
212	$dateTime = new DateTimeImmutable('@' . $timestamp);
213	$dateTime = $dateTime->setTimezone($timezone);
214	return $dateTime->format('Y-m-d');
215	}
216
217	/**
218	* Format Unix timestamp to a custom date format.
219	*
220	* @param int $timestamp Unix timestamp
221	* @param string $format PHP date format string
222	* @return string Formatted date string
223	* @throws Exception
224	*/
225	public static function timestampToDateFormat(int $timestamp, string $format): string
226	{
227	$timezone = self::getWpTimezone();
228	$dateTime = new DateTimeImmutable('@' . $timestamp);
229	$dateTime = $dateTime->setTimezone($timezone);
230	return $dateTime->format($format);
231	}
232
233	/**
234	* Normalize date values to Unix timestamp format.
235	*
236	* @param int\|string\|null $value Field value
237	* @return string Normalized value as string
238	*/
239	public static function normalizeDateValue($value): string
240	{
241	if ($value === null \|\| $value === '') {
242	return '';
243	}
244
245	return (string)(self::dateToTimestamp($value) ?? $value);
246	}
247	}
248