feat: add Date factory support for model date handling

src/core/src/Database/Eloquent/Concerns/HasAttributes.php

@@ -4,9 +4,13 @@
 
 namespace Hypervel\Database\Eloquent\Concerns;
 
+use Carbon\Carbon;
+use Carbon\CarbonInterface;
+use DateTimeInterface;
 use Hyperf\Contract\Castable;
 use Hyperf\Contract\CastsAttributes;
 use Hyperf\Contract\CastsInboundAttributes;
+use Hypervel\Support\Facades\Date;
 
 trait HasAttributes
 {
@@ -76,4 +80,64 @@ protected function casts(): array
     {
         return [];
     }
+
+    /**
+     * Return a timestamp as DateTime object with time set to 00:00:00.
+     *
+     * Uses the Date facade to respect any custom date class configured
+     * via Date::use() (e.g., CarbonImmutable).
+     */
+    protected function asDate(mixed $value): CarbonInterface
+    {
+        return $this->asDateTime($value)->startOfDay();
+    }
+
+    /**
+     * Return a timestamp as DateTime object.
+     *
+     * Uses the Date facade to respect any custom date class configured
+     * via Date::use() (e.g., CarbonImmutable).
+     */
+    protected function asDateTime(mixed $value): CarbonInterface
+    {
+        // If this value is already a Carbon instance, we shall just return it as is.
+        // This prevents us having to re-instantiate a Carbon instance when we know
+        // it already is one, which wouldn't be fulfilled by the DateTime check.
+        if ($value instanceof CarbonInterface) {
+            return Date::instance($value);
+        }
+
+        // If the value is already a DateTime instance, we will just skip the rest of
+        // these checks since they will be a waste of time, and hinder performance
+        // when checking the field. We will just return the DateTime right away.
+        if ($value instanceof DateTimeInterface) {
+            return Date::parse(
+                $value->format('Y-m-d H:i:s.u'),
+                $value->getTimezone()
+            );
+        }
+
+        // If this value is an integer, we will assume it is a UNIX timestamp's value
+        // and format a Carbon object from this timestamp. This allows flexibility
+        // when defining your date fields as they might be UNIX timestamps here.
+        if (is_numeric($value)) {
+            return Date::createFromTimestamp($value, date_default_timezone_get());
+        }
+
+        // If the value is in simply year, month, day format, we will instantiate the
+        // Carbon instances from that format. Again, this provides for simple date
+        // fields on the database, while still supporting Carbonized conversion.
+        if ($this->isStandardDateFormat($value)) {
+            return Date::instance(Carbon::createFromFormat('Y-m-d', $value)->startOfDay());
+        }
+
+        $format = $this->getDateFormat();
+
+        // Finally, we will just assume this date is in the format used by default on
+        // the database connection and use that format to create the Carbon object
+        // that is returned back out to the developers after we convert it here.
+        $date = Date::createFromFormat($format, $value);
+
+        return $date ?: Date::parse($value);
+    }
 }

src/core/src/Database/Eloquent/Concerns/HasTimestamps.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Database\Eloquent\Concerns;
+
+use Carbon\CarbonInterface;
+use Hypervel\Support\Facades\Date;
+
+/**
+ * Overrides Hyperf's HasTimestamps to use the Date facade.
+ *
+ * This allows applications to configure a custom date class (e.g., CarbonImmutable)
+ * via Date::use() and have it respected throughout the framework.
+ */
+trait HasTimestamps
+{
+    /**
+     * Get a fresh timestamp for the model.
+     *
+     * Uses the Date facade to respect any custom date class configured
+     * via Date::use() (e.g., CarbonImmutable).
+     */
+    public function freshTimestamp(): CarbonInterface
+    {
+        return Date::now();
+    }
+}

src/core/src/Database/Eloquent/Model.php

@@ -17,6 +17,7 @@
 use Hypervel\Database\Eloquent\Concerns\HasObservers;
 use Hypervel\Database\Eloquent\Concerns\HasRelations;
 use Hypervel\Database\Eloquent\Concerns\HasRelationships;
+use Hypervel\Database\Eloquent\Concerns\HasTimestamps;
 use Hypervel\Database\Eloquent\Concerns\TransformsToResource;
 use Hypervel\Database\Eloquent\Relations\Pivot;
 use Hypervel\Router\Contracts\UrlRoutable;
@@ -80,6 +81,7 @@ abstract class Model extends BaseModel implements UrlRoutable, HasBroadcastChann
     use HasObservers;
     use HasRelations;
     use HasRelationships;
+    use HasTimestamps;
     use TransformsToResource;
 
     /**

src/core/src/Database/Eloquent/Relations/MorphPivot.php

@@ -9,6 +9,7 @@
 use Hypervel\Database\Eloquent\Concerns\HasCallbacks;
 use Hypervel\Database\Eloquent\Concerns\HasGlobalScopes;
 use Hypervel\Database\Eloquent\Concerns\HasObservers;
+use Hypervel\Database\Eloquent\Concerns\HasTimestamps;
 use Psr\EventDispatcher\StoppableEventInterface;
 
 class MorphPivot extends BaseMorphPivot
@@ -17,6 +18,7 @@ class MorphPivot extends BaseMorphPivot
     use HasCallbacks;
     use HasGlobalScopes;
     use HasObservers;
+    use HasTimestamps;
 
     /**
      * Delete the pivot model record from the database.

src/core/src/Database/Eloquent/Relations/Pivot.php

@@ -9,6 +9,7 @@
 use Hypervel\Database\Eloquent\Concerns\HasCallbacks;
 use Hypervel\Database\Eloquent\Concerns\HasGlobalScopes;
 use Hypervel\Database\Eloquent\Concerns\HasObservers;
+use Hypervel\Database\Eloquent\Concerns\HasTimestamps;
 use Psr\EventDispatcher\StoppableEventInterface;
 
 class Pivot extends BasePivot
@@ -17,6 +18,7 @@ class Pivot extends BasePivot
     use HasCallbacks;
     use HasGlobalScopes;
     use HasObservers;
+    use HasTimestamps;
 
     /**
      * Delete the pivot model record from the database.