UPDATE

Author: tamedevelopers

Capsule/TimeHelper.php

@@ -47,7 +47,7 @@ public function __construct($startDate = null, $endDate = null, $format = null)
     }
 
     /**
-     * format
+     * Format the range.
      *
      * @param  bool $start Whether to return the start date (true) or the end date (false).
      * @param  bool $year Whether to include the year in the result.
@@ -75,10 +75,10 @@ public function format($start = false, $year = false)
     }
 
     /**
-     * Set the timezone.
-     * @param string|null $timezone
-     * 
-     * @return string
+     * Configure and return a valid timezone string. Falls back to system default or UTC.
+     *
+     * @param string|null $timezone IANA timezone name or null. If invalid, fallback is used.
+     * @return string Valid IANA timezone identifier.
      */
     public static function configureAndSetTimezone($timezone = null)
     {
@@ -87,13 +87,14 @@ public static function configureAndSetTimezone($timezone = null)
         if(!empty($timezone) && in_array($timezone, Country::timeZone())){
             $timezone = $timezone;
         } else{
-            $timezone = date_default_timezone_get() ?? 'UTC';
+            $timezone = date_default_timezone_get() ?: 'UTC';
         }
 
         try {
             date_default_timezone_set($timezone);
         } catch (\Throwable $th) {
-            date_default_timezone_set('UTC');
+            $timezone = 'UTC';
+            date_default_timezone_set($timezone);
         }
 
         return $timezone;
@@ -143,4 +144,16 @@ public static function carbonInstance($date)
         return $date?->timestamp ?? $date;
     }
 
+    /**
+     * Build a microsecond string (6 digits) for pretty prints.
+     *
+     * @return string e.g. "123456"
+     */
+    public static function microseconds(): string
+    {
+        $micro = explode(' ', microtime());
+        $micros = (int) round(((float) ($micro[0] ?? 0)) * 1_000_000);
+        return str_pad((string) $micros, 6, '0', STR_PAD_LEFT);
+    }
+
 }

Traits/TimeTrait.php

@@ -65,19 +65,19 @@ public function greaterThanOrEqualTo($time): bool
     }
 
     /**
-     * build Time Modifier
+     * Modify builder for add/sub operations.
      *
-     * @param  string $mode
-     * @param  int $value
-     * @param  bool $sub
-     * @return $clone
+     * @param string $mode second|minute|hour|day|week|month|year
+     * @param int $value Amount to adjust
+     * @param bool $sub If true, subtract instead of add
+     * @return static
      */
     private function buildTimeModifier($mode = 'day', $value = 0, $sub = false)
     {
         $clone = $this->clone();
-        $date = $clone->format();
+        $date = $clone->format("Y-m-d H:i:s");
         $mode = Str::lower($mode);
-        $sign = !$sub ? '+' : '-';
+        $sign = $sub ? '-' : '+';
 
         $text = match ($mode) {
             'second',  => $value <= 1 ? 'second' : 'seconds',
@@ -163,7 +163,7 @@ private function setTimeZoneAndTimeStamp($timezone = null)
     }
 
     /**
-     * create timestamp
+     * timestampPrint(): rebuilds debug-like timestamp string.
      *
      * @return string
      */
@@ -179,7 +179,7 @@ private function timestampPrint()
     }
 
     /**
-     * buildTimePrint
+     * Pretty string including microseconds, tz and UTC offset (compat buildTimePrint())
      *
      * @return string
      */
@@ -190,6 +190,21 @@ private function buildTimePrint()
 
         return "{$date}.{$this->microseconds()} {$this->timezone} {$utc}";
     }
+
+    /**
+     * Return a pretty timestamp with microseconds, timezone, and UTC offset.
+     * Example: "2025-05-01 10:20:30.123456 America/New_York (-04:00)"
+     *
+     * @return string
+     */
+    public function debugTimestamp(): string
+    {
+        $date   = $this->format('Y-m-d H:i:s');
+        $micro  = $this->microseconds();
+        $tz     = $this->timezone->getName();
+        $offset = $this->format('(P)');
+        return sprintf('%s.%s %s %s', $date, $micro, $tz, $offset);
+    }
 
     /**
      * create microseconds
@@ -198,10 +213,9 @@ private function buildTimePrint()
      */
     private function microseconds()
     {
-        $microtime = explode(' ', microtime());
-        $milliseconds = (int) round($microtime[0] * 1000000); // Get microseconds
-
-        return str_pad(Str::trim($milliseconds), 6, '0', STR_PAD_LEFT);
+        $micro = explode(' ', microtime());
+        $micros = (int) round(((float) ($micro[0] ?? 0)) * 1_000_000);
+        return str_pad((string) $micros, 6, '0', STR_PAD_LEFT);
     }
 
     /**
@@ -287,7 +301,7 @@ private static function nonExistMethod($method = null, $args = null, $clone = nu
             $clone = new static();
         }
 
-        return $clone->$method(...$args);
+        return $clone->$method(...($args ?? []));
     }
 
 }