UPDATE

Author: tamedevelopers

Capsule/TimeHelper.php

@@ -8,23 +8,30 @@
 use Tamedevelopers\Support\Str;
 use Tamedevelopers\Support\Country;
 
+/**
+ * Class TimeHelper
+ *
+ * Utilities for timezone configuration, date parsing, and formatting helpers
+ * used by Time. This class also carries lightweight range formatting support
+ * via startDate/endDate/format passed from Time::dateRange.
+ */
 class TimeHelper {
 
     /**
-     * startDate
+     * Start of the range date (as Time instance)
      *
      * @var mixed
      */
     protected $startDate;    
     /**
-     * endDate
+     * End of the range date (as Time instance)
      *
      * @var mixed
      */
     protected $endDate;
 
     /**
-     * format
+     * Output format for range formatting.
      *
      * @var string|null
      */

Time.php

@@ -10,31 +10,57 @@
 use Tamedevelopers\Support\Traits\TimeTrait;
 use Tamedevelopers\Support\Capsule\TimeHelper;
 
+/**
+ * Class Time
+ *
+ * Time utility with dynamic static/instance method support.
+ * - Supports setters like date(), now(), today(), yesterday()
+ * - Add/subtract helpers: addSeconds/Minutes/Hours/Days/Weeks/Months/Years and sub*
+ * - Formatting: format(), toDateTimeString(), toJsTimer(), timestamp()
+ * - Range helper: dateRange()
+ * - Text features/config: config(), greeting (via __greeting), timeAgo (via __timeAgo)
+ *
+ * All methods are documented at their definitions for clarity.
+ */
 class Time {
 
     use TimeTrait;
 
     /**
-     * For storing the time value
-     * 
-     * @var mixed
-     * - int|string
+     * For storing the time value.
+     *
+     * @var int|string
      */
     protected $date;
 
     /**
-     * For storing the timestamp value
-     * 
+     * For storing a human-friendly timestamp snapshot
+     * (e.g., "2024-01-01 12:00:00.123456 UTC (+00:00)").
+     *
      * @var string
      */
     protected $timestamp;
 
     /**
-     * For storing the timezone value
-     * 
+     * For storing the timezone value.
+     *
      * @var string
      */
     protected $timezone;
+
+    /**
+     * Cached timezone name (alias of $timezone) for quick access.
+     *
+     * @var string|null
+     */
+    protected $timezoneName;
+
+    /**
+     * Cached UTC offset for the current $date (e.g., "+00:00").
+     *
+     * @var string|null
+     */
+    protected $utcOffset;
 
     /**
      * static
@@ -75,6 +101,13 @@ public function __construct($date = null, $timezone = null)
      * 
      * @return mixed
      */
+    /**
+     * Magic: instance dynamic calls map to supported methods.
+     *
+     * @param string $name Invoked method name
+     * @param array $args Arguments
+     * @return mixed
+     */
     public function __call($name, $args) 
     {
         return self::nonExistMethod($name, $args, $this);
@@ -87,6 +120,13 @@ public function __call($name, $args)
      * 
      * @return mixed
      */
+    /**
+     * Magic: static dynamic calls map to supported methods using stored static instance.
+     *
+     * @param string $name Invoked static method name
+     * @param array $args Arguments
+     * @return mixed
+     */
     public static function __callStatic($name, $args) 
     {
         return self::nonExistMethod($name, $args, self::$staticData);
@@ -97,6 +137,12 @@ public static function __callStatic($name, $args)
      * @param int $value
      * @return $this
      */
+    /**
+     * Add seconds to the current date.
+     *
+     * @param int $value Number of seconds to add
+     * @return $this New cloned instance with updated time
+     */
     public function addSeconds($value = 0)
     {
         return $this->buildTimeModifier('second', $value);
@@ -649,6 +695,12 @@ public function __timeAgo($mode = null)
      * 
      * @return mixed
      */
+    /**
+     * Retrieve text configuration entries.
+     *
+     * @param string|null $mode Specific key to fetch or null for all
+     * @return mixed
+     */
     private static function getText($mode  = null)
     {
         if(!defined('TAME_TIME_CONFIG')){
@@ -657,5 +709,32 @@ private static function getText($mode  = null)
 
         return TAME_TIME_CONFIG[$mode] ?? TAME_TIME_CONFIG;
     }
+
+    /**
+     * Magic: customize what is displayed during var-dump/dd().
+     * Provides a pretty, safe snapshot of the current time object.
+     *
+     * - timestamp: the unix timestamp (int)
+     * - formatted: default formatted string (Y-m-d H:i:s)
+     * - timezone: current timezone name
+     * - utc_offset: offset at the timestamp time
+     * - greeting: localized greeting based on hour
+     * - time_ago_short: a compact time-ago string
+     *
+     * @return array
+     */
+    public function __debugInfo(): array
+    {
+        $time = (int) $this->date;
+
+        return [
+            'timestamp'      => $time,
+            'formatted'      => date('Y-m-d H:i:s', $time),
+            'timezone'       => (string) $this->timezone,
+            'utc_offset'     => date('(P)', $time),
+            'greeting'       => $this->__greeting($time),
+            'time_ago_short' => $this->__timeAgo('short'),
+        ];
+    }
 }
 

Traits/TimeTrait.php

@@ -11,13 +11,18 @@
 use Tamedevelopers\Support\Country;
 use Tamedevelopers\Support\Capsule\TimeHelper;
 
+
 /**
+ * Trait TimeTrait
+ *
+ * Internal helpers used by the Time class for cloning, timezone handling,
+ * and common operations. Public API is provided by Time and dynamic dispatch.
  * @property mixed $staticData
 */
 trait TimeTrait{
 
     /**
-     * isTimeInstance
+     * Determine whether the static context already holds a Time instance.
      *
      * @return bool
      */
@@ -27,9 +32,9 @@ static protected function isTimeInstance()
     }
 
     /**
-     * Clone a new Instance of self
+     * Clone a new instance of the owning class.
      *
-     * @return $this
+     * @return $this A shallow clone of the current instance.
      */
     private function clone()
     {
@@ -39,7 +44,7 @@ private function clone()
     /**
      * Alias for clone() method.
      *
-     * @return $this
+     * @return $this A shallow clone of the current instance.
      */
     public function copy()
     {
@@ -80,13 +85,13 @@ private function buildTimeModifier($mode = 'day', $value = 0, $sub = false)
         $sign = $sub ? '-' : '+';
 
         $text = match ($mode) {
-            'second',  => $value <= 1 ? 'second' : 'seconds',
-            'minute',  => $value <= 1 ? 'minute' : 'minutes',
-            'hour',  => $value <= 1 ? 'hour' : 'hours',
-            'week',  => $value <= 1 ? 'week' : 'weeks',
-            'month',  => $value <= 1 ? 'month' : 'months',
-            'year',  => $value <= 1 ? 'year' : 'years',
-            default => $value <= 1 ? 'day' : 'days',
+            'second' => $value <= 1 ? 'second' : 'seconds',
+            'minute' => $value <= 1 ? 'minute' : 'minutes',
+            'hour'   => $value <= 1 ? 'hour' : 'hours',
+            'week'   => $value <= 1 ? 'week' : 'weeks',
+            'month'  => $value <= 1 ? 'month' : 'months',
+            'year'   => $value <= 1 ? 'year' : 'years',
+            default  => $value <= 1 ? 'day' : 'days',
         };
 
         // format text