Skip to content

Commit 38acc29

Browse files
tamedeveloperstamedevelopers
committed
update
1 parent 821eea6 commit 38acc29

File tree

2 files changed

+153
-27
lines changed

2 files changed

+153
-27
lines changed

‎src/Traits/TimeExtraTrait.php‎

Lines changed: 142 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ trait TimeExtraTrait
1818
{
1919
/**
2020
* Create a DateTime for the given timestamp in the instance timezone.
21+
*
22+
* @param int $timestamp Unix timestamp
23+
* @return DateTime DateTime adjusted to the instance timezone
2124
*/
2225
private function dtInTz(int $timestamp): DateTime
2326
{
@@ -28,12 +31,15 @@ private function dtInTz(int $timestamp): DateTime
2831

2932
/**
3033
* Normalize various date inputs to a timestamp (int).
31-
* Accepts string/int/DateTime/Time.
34+
* Accepts string|int|DateTime|Time|Carbon-like.
35+
*
36+
* @param mixed $other A date-like value to normalize
37+
* @return int Unix timestamp
3238
*/
3339
private function normalizeToTimestamp($other): int
3440
{
3541
if ($other instanceof Time) {
36-
// Access protected via class context
42+
// Use format('U') to get integer timestamp from Time
3743
return (int) $other->format('U');
3844
}
3945

@@ -47,8 +53,11 @@ private function normalizeToTimestamp($other): int
4753

4854
/**
4955
* Helper to return a cloned instance with a new timestamp set.
56+
*
57+
* @param int $timestamp Unix timestamp to set on the clone
58+
* @return static Cloned instance with timestamp applied
5059
*/
51-
private function cloneWithTimestamp(int $timestamp)
60+
private function cloneWithTimestamp(int $timestamp): static
5261
{
5362
$clone = $this->clone();
5463
$clone->date = $timestamp;
@@ -60,24 +69,36 @@ private function cloneWithTimestamp(int $timestamp)
6069
// Date boundary methods
6170
// ---------------------------
6271

63-
/** Set time to 00:00:00 of the current day. */
64-
public function startOfDay()
72+
/**
73+
* Set time to 00:00:00 of the current day.
74+
*
75+
* @return static
76+
*/
77+
public function startOfDay(): static
6578
{
6679
$dt = $this->dtInTz((int) $this->date);
6780
$dt->setTime(0, 0, 0);
6881
return $this->cloneWithTimestamp((int) $dt->getTimestamp());
6982
}
7083

71-
/** Set time to 23:59:59 of the current day. */
72-
public function endOfDay()
84+
/**
85+
* Set time to 23:59:59 of the current day.
86+
*
87+
* @return static
88+
*/
89+
public function endOfDay(): static
7390
{
7491
$dt = $this->dtInTz((int) $this->date);
7592
$dt->setTime(23, 59, 59);
7693
return $this->cloneWithTimestamp((int) $dt->getTimestamp());
7794
}
7895

79-
/** Beginning of the week (Monday 00:00:00). */
80-
public function startOfWeek()
96+
/**
97+
* Beginning of the week (Monday 00:00:00).
98+
*
99+
* @return static
100+
*/
101+
public function startOfWeek(): static
81102
{
82103
$dt = $this->dtInTz((int) $this->date);
83104
$dayOfWeek = (int) $dt->format('N'); // 1 (Mon) .. 7 (Sun)
@@ -89,8 +110,12 @@ public function startOfWeek()
89110
return $this->cloneWithTimestamp((int) $dt->getTimestamp());
90111
}
91112

92-
/** End of the week (Sunday 23:59:59). */
93-
public function endOfWeek()
113+
/**
114+
* End of the week (Sunday 23:59:59).
115+
*
116+
* @return static
117+
*/
118+
public function endOfWeek(): static
94119
{
95120
$start = $this->startOfWeek();
96121
$dt = $this->dtInTz((int) $start->date);
@@ -99,17 +124,25 @@ public function endOfWeek()
99124
return $this->cloneWithTimestamp((int) $dt->getTimestamp());
100125
}
101126

102-
/** First day of current month at 00:00:00. */
103-
public function startOfMonth()
127+
/**
128+
* First day of current month at 00:00:00.
129+
*
130+
* @return static
131+
*/
132+
public function startOfMonth(): static
104133
{
105134
$dt = $this->dtInTz((int) $this->date);
106135
$dt->setDate((int) $dt->format('Y'), (int) $dt->format('m'), 1);
107136
$dt->setTime(0, 0, 0);
108137
return $this->cloneWithTimestamp((int) $dt->getTimestamp());
109138
}
110139

111-
/** Last day of current month at 23:59:59. */
112-
public function endOfMonth()
140+
/**
141+
* Last day of current month at 23:59:59.
142+
*
143+
* @return static
144+
*/
145+
public function endOfMonth(): static
113146
{
114147
$dt = $this->dtInTz((int) $this->date);
115148
$lastDay = (int) $dt->format('t');
@@ -118,17 +151,25 @@ public function endOfMonth()
118151
return $this->cloneWithTimestamp((int) $dt->getTimestamp());
119152
}
120153

121-
/** January 1st, 00:00:00. */
122-
public function startOfYear()
154+
/**
155+
* January 1st, 00:00:00.
156+
*
157+
* @return static
158+
*/
159+
public function startOfYear(): static
123160
{
124161
$dt = $this->dtInTz((int) $this->date);
125162
$dt->setDate((int) $dt->format('Y'), 1, 1);
126163
$dt->setTime(0, 0, 0);
127164
return $this->cloneWithTimestamp((int) $dt->getTimestamp());
128165
}
129166

130-
/** December 31st, 23:59:59. */
131-
public function endOfYear()
167+
/**
168+
* December 31st, 23:59:59.
169+
*
170+
* @return static
171+
*/
172+
public function endOfYear(): static
132173
{
133174
$dt = $this->dtInTz((int) $this->date);
134175
$dt->setDate((int) $dt->format('Y'), 12, 31);
@@ -140,7 +181,12 @@ public function endOfYear()
140181
// Comparison helpers
141182
// ---------------------------
142183

143-
/** Check if two dates are the same calendar day (in instance timezone). */
184+
/**
185+
* Check if two dates are the same calendar day (in instance timezone).
186+
*
187+
* @param mixed $otherDate A date-like value to compare
188+
* @return bool
189+
*/
144190
public function isSameDay($otherDate): bool
145191
{
146192
$ts = $this->normalizeToTimestamp($otherDate);
@@ -149,7 +195,12 @@ public function isSameDay($otherDate): bool
149195
return $a === $b;
150196
}
151197

152-
/** Check if two dates are in the same month and year (in instance timezone). */
198+
/**
199+
* Check if two dates are in the same month and year (in instance timezone).
200+
*
201+
* @param mixed $otherDate A date-like value to compare
202+
* @return bool
203+
*/
153204
public function isSameMonth($otherDate): bool
154205
{
155206
$ts = $this->normalizeToTimestamp($otherDate);
@@ -158,7 +209,12 @@ public function isSameMonth($otherDate): bool
158209
return $a === $b;
159210
}
160211

161-
/** Check if two dates are in the same year (in instance timezone). */
212+
/**
213+
* Check if two dates are in the same year (in instance timezone).
214+
*
215+
* @param mixed $otherDate A date-like value to compare
216+
* @return bool
217+
*/
162218
public function isSameYear($otherDate): bool
163219
{
164220
$ts = $this->normalizeToTimestamp($otherDate);
@@ -167,28 +223,49 @@ public function isSameYear($otherDate): bool
167223
return $a === $b;
168224
}
169225

170-
/** Strict equality (same timestamp). */
226+
/**
227+
* Strict equality (same timestamp).
228+
*
229+
* @param mixed $otherDate A date-like value to compare
230+
* @return bool
231+
*/
171232
public function equalTo($otherDate): bool
172233
{
173234
$ts = $this->normalizeToTimestamp($otherDate);
174235
return (int) $this->date === $ts;
175236
}
176237

177-
/** Greater than (after). */
238+
/**
239+
* Greater than (after).
240+
*
241+
* @param mixed $otherDate A date-like value to compare
242+
* @return bool
243+
*/
178244
public function gt($otherDate): bool
179245
{
180246
$ts = $this->normalizeToTimestamp($otherDate);
181247
return (int) $this->date > $ts;
182248
}
183249

184-
/** Less than (before). */
250+
/**
251+
* Less than (before).
252+
*
253+
* @param mixed $otherDate A date-like value to compare
254+
* @return bool
255+
*/
185256
public function lt($otherDate): bool
186257
{
187258
$ts = $this->normalizeToTimestamp($otherDate);
188259
return (int) $this->date < $ts;
189260
}
190261

191-
/** Check if current date is in the inclusive range [date1, date2]. */
262+
/**
263+
* Check if current date is in the inclusive range [date1, date2].
264+
*
265+
* @param mixed $date1 First boundary of range
266+
* @param mixed $date2 Second boundary of range
267+
* @return bool
268+
*/
192269
public function between($date1, $date2): bool
193270
{
194271
$ts1 = $this->normalizeToTimestamp($date1);
@@ -203,7 +280,12 @@ public function between($date1, $date2): bool
203280
// Difference calculations
204281
// ---------------------------
205282

206-
/** Absolute number of full days difference (calendar aware). */
283+
/**
284+
* Absolute number of full days difference (calendar aware).
285+
*
286+
* @param mixed $otherDate A date-like value to compare against
287+
* @return int Number of days difference (absolute)
288+
*/
207289
public function diffInDays($otherDate): int
208290
{
209291
$ts = $this->normalizeToTimestamp($otherDate);
@@ -212,20 +294,38 @@ public function diffInDays($otherDate): int
212294
return (int) $a->diff($b)->days;
213295
}
214296

297+
/**
298+
* Absolute number of hours difference.
299+
*
300+
* @param mixed $otherDate A date-like value to compare against
301+
* @return int Number of hours difference (absolute)
302+
*/
215303
public function diffInHours($otherDate): int
216304
{
217305
$ts = $this->normalizeToTimestamp($otherDate);
218306
$seconds = abs(((int) $this->date) - $ts);
219307
return (int) floor($seconds / 3600);
220308
}
221309

310+
/**
311+
* Absolute number of minutes difference.
312+
*
313+
* @param mixed $otherDate A date-like value to compare against
314+
* @return int Number of minutes difference (absolute)
315+
*/
222316
public function diffInMinutes($otherDate): int
223317
{
224318
$ts = $this->normalizeToTimestamp($otherDate);
225319
$seconds = abs(((int) $this->date) - $ts);
226320
return (int) floor($seconds / 60);
227321
}
228322

323+
/**
324+
* Absolute number of seconds difference.
325+
*
326+
* @param mixed $otherDate A date-like value to compare against
327+
* @return int Number of seconds difference (absolute)
328+
*/
229329
public function diffInSeconds($otherDate): int
230330
{
231331
$ts = $this->normalizeToTimestamp($otherDate);
@@ -236,6 +336,11 @@ public function diffInSeconds($otherDate): int
236336
// Convenience checks
237337
// ---------------------------
238338

339+
/**
340+
* Whether current instance date is today (in instance timezone).
341+
*
342+
* @return bool
343+
*/
239344
public function isToday(): bool
240345
{
241346
$now = new DateTime('now', new DateTimeZone((string) $this->__getTimezone()));
@@ -244,6 +349,11 @@ public function isToday(): bool
244349
return $today === $cur;
245350
}
246351

352+
/**
353+
* Whether current instance date is tomorrow (in instance timezone).
354+
*
355+
* @return bool
356+
*/
247357
public function isTomorrow(): bool
248358
{
249359
$tz = new DateTimeZone((string) $this->__getTimezone());
@@ -252,6 +362,11 @@ public function isTomorrow(): bool
252362
return $tomorrow->format('Y-m-d') === $cur;
253363
}
254364

365+
/**
366+
* Whether current instance date is yesterday (in instance timezone).
367+
*
368+
* @return bool
369+
*/
255370
public function isYesterday(): bool
256371
{
257372
$tz = new DateTimeZone((string) $this->__getTimezone());

‎tests/time.php‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,17 @@
4343
'Time-4: '. $time4->getTimeZone(),
4444
],
4545

46+
[
47+
$time->startOfYear()->format(),
48+
$time->startOfDay()->format(),
49+
$time->startOfWeek()->format(),
50+
$time->startOfMonth()->format(),
51+
$time->isSameDay(TameTime('now')->format()),
52+
$time->isSameMonth('today'),
53+
$time->gt('today'),
54+
$time->lt('today'),
55+
],
56+
4657
// [
4758
// $time3->date('first day of December 2008')->format(),
4859
// $time3->yesterday()->format(),

0 commit comments

Comments
 (0)