Add Optional Timestamps Support to Models

CHANGELOG.md

@@ -28,6 +28,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Calling create() resets model state to ensure clean inserts
   - Database-generated primary keys are now synced into the model after save()
   - Models are hydrated only on fetch operations, not implicitly via getters
+- `DbModel::save()` now automatically applies timestamps when the model uses the `HasTimestamps` trait
+- `SoftDeletes` now uses model timestamp format when available (datetime/unix) for `deleted_at`
 
 ### Fixed
 - PHP 8.1 compatibility: Fixed null parameter deprecations in `explode()`, `parse_url()`, and `str_replace()`
@@ -48,6 +50,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Support for force mode and specific task execution
   - Automatic cleanup of stale locks (older than 24 hours)
   - Full documentation in `docs/cron-scheduler.md`
+- **Opt-in Model Timestamps**: Introduced `HasTimestamps` trait for `DbModel`:
+  - Automatically sets `created_at` on insert 
+  - Automatically sets `updated_at` on insert and update
+  - Supports custom timestamp column names via model constants (`CREATED_AT`, `UPDATED_AT`)
+  - Supports datetime and unix timestamp formats via `TIMESTAMP_TYPE`
 
 ### Removed
 - Support for PHP 7.3 and earlier versions

src/Model/DbModel.php

@@ -182,6 +182,10 @@ public function create(): self
      */
     public function save(): bool
     {
+        if (method_exists($this, 'touchTimestamps')) {
+            $this->touchTimestamps();
+        }
+
         $this->syncAttributesToOrm();
 
         $result = $this->getOrmInstance()->save();

src/Model/Helpers/model.php

@@ -20,10 +20,10 @@
 
 /**
  * Gets the model instance
- * @template T of Model
  * @param class-string<T> $modelClass
  * @return T
  * @throws ModelException
+ * @template T of Model
  */
 function model(string $modelClass): Model
 {

src/Model/Traits/HasTimestamps.php

@@ -0,0 +1,126 @@
+<?php
+
+/**
+ * Quantum PHP Framework
+ *
+ * An open source software development framework for PHP
+ *
+ * @package Quantum
+ * @author Arman Ag. <arman.ag@softberg.org>
+ * @copyright Copyright (c) 2018 Softberg LLC (https://softberg.org)
+ * @link http://quantum.softberg.org/
+ * @since 3.0.0
+ */
+
+namespace Quantum\Model\Traits;
+
+/**
+ * Trait HasTimestamps
+ *
+ * @property array $attributes
+ * @property string $idColumn
+ */
+trait HasTimestamps
+{
+    /**
+     * Column name for created timestamp
+     * @var string
+     */
+    public string $createdAt = 'created_at';
+
+    /**
+     * Column name for updated timestamp
+     * @var string
+     */
+    public string $updatedAt = 'updated_at';
+
+    /**
+     * Timestamp storage type: datetime|unix
+     * @var string
+     */
+    public string $timestampType = 'datetime';
+
+    /**
+     * Determine whether the current model is new (insert) or existing (update).
+     * @return bool
+     */
+    protected function isNewRecord(): bool
+    {
+        $id = $this->attributes[$this->idColumn] ?? null;
+
+        return $id === null || $id === '';
+    }
+
+    /**
+     * Returns the current timestamp value based on model config.
+     * Supports: datetime|unix
+     * @return int|string
+     */
+    protected function nowTimestampValue()
+    {
+        if ($this->getTimestampType() === 'unix') {
+            return time();
+        }
+
+        return date('Y-m-d H:i:s');
+    }
+
+    /**
+     * Get timestamp type.
+     * @return string
+     */
+    protected function getTimestampType(): string
+    {
+        if (defined(static::class . '::TIMESTAMP_TYPE')) {
+            return static::TIMESTAMP_TYPE;
+        }
+
+        return $this->timestampType;
+    }
+
+    /**
+     * Get "created at" column name.
+     * @return string
+     */
+    protected function getCreatedAtColumn(): string
+    {
+        if (defined(static::class . '::CREATED_AT')) {
+            return static::CREATED_AT;
+        }
+
+        return $this->createdAt;
+    }
+
+    /**
+     * Get "updated at" column name.
+     * @return string
+     */
+    protected function getUpdatedAtColumn(): string
+    {
+        if (defined(static::class . '::UPDATED_AT')) {
+            return static::UPDATED_AT;
+        }
+
+        return $this->updatedAt;
+    }
+
+    /**
+     * Touch timestamps on save
+     * @return void
+     */
+    protected function touchTimestamps(): void
+    {
+        $now = $this->nowTimestampValue();
+
+        $createdAt = $this->getCreatedAtColumn();
+        $updatedAt = $this->getUpdatedAtColumn();
+
+        if ($this->isNewRecord()) {
+            if (!array_key_exists($createdAt, $this->attributes)) {
+                $this->attributes[$createdAt] = $now;
+            }
+        }
+
+        $this->attributes[$updatedAt] = $now;
+    }
+}

src/Model/Traits/SoftDeletes.php

@@ -39,9 +39,8 @@ trait SoftDeletes
      */
     public function delete(): bool
     {
-        $this->prop($this->getDeleteAtColumn(), date('Y-m-d H:i:s'));
+        $this->prop($this->getDeletedAtColumn(), $this->getSoftDeleteTimestampValue());
         return $this->save();
-
     }
 
     /**
@@ -51,7 +50,7 @@ public function delete(): bool
      */
     public function restore(): bool
     {
-        $this->prop($this->getDeleteAtColumn(), null);
+        $this->prop($this->getDeletedAtColumn(), null);
         return $this->save();
     }
 
@@ -85,7 +84,7 @@ public function onlyTrashed(): self
     {
         $this->includeTrashed = true;
 
-        $this->getOrmInstance()->isNotNull($this->getDeleteAtColumn());
+        $this->getOrmInstance()->isNotNull($this->getDeletedAtColumn());
 
         return $this;
     }
@@ -175,15 +174,28 @@ public function first(): ?DbModel
     protected function applySoftDeleteScope(): void
     {
         if (!$this->includeTrashed) {
-            $this->getOrmInstance()->isNull($this->getDeleteAtColumn());
+            $this->getOrmInstance()->isNull($this->getDeletedAtColumn());
+        }
+    }
+
+    /**
+     * Returns timestamp value for soft delete based on model timestamp config (if available).
+     * @return int|string
+     */
+    protected function getSoftDeleteTimestampValue()
+    {
+        if (method_exists($this, 'nowTimestampValue')) {
+            return $this->nowTimestampValue();
         }
+
+        return date('Y-m-d H:i:s');
     }
 
     /**
      * Get the column name used for soft deletes.
      * @return string
      */
-    protected function getDeleteAtColumn(): string
+    protected function getDeletedAtColumn(): string
     {
         if (defined(static::class . '::DELETED_AT')) {
             return static::DELETED_AT;

src/Module/Templates/DemoApi/src/Controllers/AccountController.php.tpl

@@ -9,7 +9,7 @@
  * @author Arman Ag. <arman.ag@softberg.org>
  * @copyright Copyright (c) 2018 Softberg LLC (https://softberg.org)
  * @link http://quantum.softberg.org/
- * @since 2.9.9
+ * @since 3.0.0
  */
 
 namespace {{MODULE_NAMESPACE}}\Controllers;
@@ -30,11 +30,19 @@ class AccountController extends BaseController
      * Auth service
      * @var AuthService
      */
-    public $authService;
+    public AuthService $authService;
 
     /**
      * Works before an action
      */
+
+    /**
+     * @return void
+     * @throws ReflectionException
+     * @throws \Quantum\App\Exceptions\BaseException
+     * @throws \Quantum\Di\Exceptions\DiException
+     * @throws \Quantum\Service\Exceptions\ServiceException
+     */
     public function __before()
     {
         $this->authService = service(AuthService::class);

src/Module/Templates/DemoApi/src/Controllers/CommentController.php.tpl

@@ -9,7 +9,7 @@
  * @author Arman Ag. <arman.ag@softberg.org>
  * @copyright Copyright (c) 2018 Softberg LLC (https://softberg.org)
  * @link http://quantum.softberg.org/
- * @since 2.9.9
+ * @since 3.0.0
  */
 
 namespace {{MODULE_NAMESPACE}}\Controllers;
@@ -31,13 +31,10 @@ class CommentController extends BaseController
     /**
      * @var CommentService
      */
-    public $commentService;
+    public CommentService $commentService;
 
     /**
-     * @throws ReflectionException
-     * @throws BaseException
-     * @throws DiException
-     * @throws ServiceException
+     * Works before an action
      */
     public function __before()
     {

src/Module/Templates/DemoApi/src/Controllers/PostController.php.tpl

@@ -9,7 +9,7 @@
  * @author Arman Ag. <arman.ag@softberg.org>
  * @copyright Copyright (c) 2018 Softberg LLC (https://softberg.org)
  * @link http://quantum.softberg.org/
- * @since 2.9.9
+ * @since 3.0.0
  */
 
 namespace {{MODULE_NAMESPACE}}\Controllers;
@@ -32,24 +32,21 @@ class PostController extends BaseController
     /**
      * Posts per page
      */
-    const POSTS_PER_PAGE = 8;
+    protected const POSTS_PER_PAGE = 8;
 
     /**
      * Current page
      */
-    const CURRENT_PAGE = 1;
+    protected const CURRENT_PAGE = 1;
 
     /**
      * Post service
      * @var PostService
      */
-    public $postService;
+    public PostService $postService;
 
     /**
-     * @throws ReflectionException
-     * @throws BaseException
-     * @throws DiException
-     * @throws ServiceException
+     * Works before an action
      */
     public function __before()
     {

src/Module/Templates/DemoApi/src/Controllers/PostManagementController.php.tpl

@@ -9,7 +9,7 @@
  * @author Arman Ag. <arman.ag@softberg.org>
  * @copyright Copyright (c) 2018 Softberg LLC (https://softberg.org)
  * @link http://quantum.softberg.org/
- * @since 2.9.9
+ * @since 3.0.0
  */
 
 namespace {{MODULE_NAMESPACE}}\Controllers;
@@ -32,18 +32,11 @@ class PostManagementController extends BaseController
      * Post service
      * @var PostService
      */
-    public $postService;
+    public PostService $postService;
 
     /**
      * Works before an action
      */
-
-    /**
-     * @throws ReflectionException
-     * @throws BaseException
-     * @throws DiException
-     * @throws ServiceException
-     */
     public function __before()
     {
         $this->postService = service(PostService::class);
@@ -75,7 +68,6 @@ class PostManagementController extends BaseController
             'title' => $request->get('title', null, true),
             'content' => $request->get('content', null, true),
             'image' => '',
-            'updated_at' => date('Y-m-d H:i:s'),
         ];
 
         if ($request->hasFile('image')) {
@@ -109,7 +101,6 @@ class PostManagementController extends BaseController
         $postData = [
             'title' => $request->get('title', null, true),
             'content' => $request->get('content', null, true),
-            'updated_at' => date('Y-m-d H:i:s'),
         ];
 
         $post = $this->postService->getPost($postUuid);
@@ -177,7 +168,6 @@ class PostManagementController extends BaseController
             'title' => $post->title,
             'content' => $post->content,
             'image' => '',
-            'updated_at' => date('Y-m-d H:i:s'),
         ]);
 
         $response->json([