Merge pull request #124 from Planetbiru/3.15.0

3.15.0

Author: kamshory

CHANGELOG.md

@@ -1058,6 +1058,7 @@ This enhancement improves developer ergonomics when working with deeply nested d
 Added support for the `@TimeRange` validation annotation to validate time values within a specific range.
 
 **Usage Example:**
+
 ```php
 /**
  * @TimeRange(min="08:00", max="17:00")

src/Database/PicoDatabasePersistence.php

@@ -9,6 +9,7 @@
 use MagicObject\Exceptions\EntityException;
 use MagicObject\Exceptions\InvalidAnnotationException;
 use MagicObject\Exceptions\InvalidFilterException;
+use MagicObject\Exceptions\InvalidParameterException;
 use MagicObject\Exceptions\NoInsertableColumnException;
 use MagicObject\Exceptions\NoColumnMatchException;
 use MagicObject\Exceptions\NoDatabaseConnectionException;
@@ -2917,6 +2918,65 @@ public function deleteBy($propertyName, $propertyValue)
             throw new DataRetrievalException($e->getMessage());
         }
     }
+
+    /**
+     * Deletes a database record based on its primary key value(s).
+     *
+     * This method constructs and executes a DELETE SQL query to remove a record 
+     * that matches the given primary key value(s). It returns the number of affected rows.
+     * If an exception occurs during execution, the method returns 0.
+     *
+     * @param mixed $propertyValues The primary key value or an associative array of key-value pairs.
+     *                              - If the table has a single-column primary key, this can be a scalar.
+     *                              - If the table has a composite primary key, this must be an associative array.
+     * @return int The number of deleted records (0 or 1 typically).
+     */
+    public function deleteByPrimaryKey($propertyValues)
+    {
+        try
+        {
+            $sqlQuery = $this->deleteByPrimaryKeyQuery($propertyValues);
+            $stmt = $this->database->executeQuery($sqlQuery);
+            return $stmt->rowCount();
+        }
+        catch(Exception $e)
+        {
+            return 0;
+        }
+    }
+
+    /**
+     * Builds a DELETE SQL query to remove a record based on primary key value(s).
+     *
+     * This method uses the internal table metadata to determine the primary key columns
+     * and creates a `WHERE` clause that matches all key(s).
+     *
+     * @param mixed $propertyValues The primary key value or an associative array of key-value pairs.
+     *                              - For a single-column primary key: scalar value.
+     *                              - For composite key: associative array like ['id' => 5, 'lang' => 'en'].
+     * @return PicoDatabaseQueryBuilder The prepared query builder with the DELETE SQL query.
+     * @throws InvalidParameterException If the primary key values are invalid or missing.
+     */
+    public function deleteByPrimaryKeyQuery($propertyValues)
+    {
+        // Convert to array if necessary
+        $propertyValues = $this->toArray($propertyValues);
+        $info = $this->getTableInfo();
+        $primaryKeys = $info->getPrimaryKeys();
+
+        if ($this->isValidPrimaryKeyValues($primaryKeys, $propertyValues))
+        {
+            $queryBuilder = new PicoDatabaseQueryBuilder($this->database);
+            $where = $this->createWhereByPrimaryKeys($queryBuilder, $primaryKeys, $propertyValues);
+            return $queryBuilder
+                ->newQuery()
+                ->delete()
+                ->from($info->getTableName())
+                ->where($where);
+        }
+
+        throw new InvalidParameterException("Invalid or missing primary key values.");
+    }
 
     /**
      * Retrieves a single matched record from the database based on the specified property name and value.

src/MagicObject.php

@@ -2537,6 +2537,32 @@ public function size()
         return $length;
     }
 
+    /**
+     * Deletes a record from the database using its primary key value(s).
+     *
+     * This method delegates the delete operation to the persistence layer and ensures
+     * that the database connection is available before proceeding. It supports both
+     * single-column and composite primary keys.
+     *
+     * @param mixed $primaryKeyValue The value(s) of the primary key to identify the record.
+     *                                - For single-column primary key: a scalar value (e.g., 5).
+     *                                - For composite primary key: an **indexed array** of values
+     *                                  in the same order as defined in the table (e.g., [1, 2]).
+     *
+     * @return int The number of deleted records (1 if successful, 0 if no matching record found).
+     *
+     * @throws NoDatabaseConnectionException If no database connection is available.
+     */
+    public function deleteRecordByPrimaryKey($primaryKeyValue)
+    {
+        if ($this->_databaseConnected()) {
+            $persist = new PicoDatabasePersistence($this->_database, $this);
+            return $persist->deleteByPrimaryKey($primaryKeyValue);
+        } else {
+            throw new NoDatabaseConnectionException(self::MESSAGE_NO_DATABASE_CONNECTION);
+        }
+    }
+
     /**
      * Magic method called when a user calls any undefined method. 
      * The __call method checks the prefix of the called method and