Feature.2,11

README.md

@@ -9,7 +9,7 @@ MagicObject is a powerful library for developing applications in PHP with ease.
 1. **Dynamic Object Creation**: Easily create objects at runtime.
 2. **Setters and Getters**: Simplify property management with automatic methods.
 3. **Multi-Level Objects**: Support for nested objects.
-4. **Entity Access**: Streamline interactions with entities.
+4. **ORM**: Object-Relational Mapping support for easier interactions with databases.
 5. **Filtering and Pagination**: Built-in methods for managing data display.
 6. **Native Query**: Defining native queries for a function will increase flexibility and resource efficiency in accessing the database.
 7. **Multiple Database Connection**: MagicObject supports the configuration of multiple database connections, allowing applications to interact with different databases simultaneously.
@@ -31,6 +31,8 @@ This library provides a versatile toolkit for building robust PHP applications!
 
 # Installation
 
+## Installing MagicObject
+
 To install MagicObject, run:
 
 ```
@@ -55,10 +57,95 @@ Or if Composer is not installed:
 php composer.phar remove planetbiru/magic-object
 ```
 
-o install Composer on your system or download the latest `composer.phar`, visit https://getcomposer.org/download/ 
+## Installing Composer
+
+To install Composer on your system or download the latest `composer.phar`, visit https://getcomposer.org/download/ 
 
 To see available versions of MagicObject, visit https://packagist.org/packages/planetbiru/magic-object
 
+
+
+## Installing MagicObject on PHP 5
+
+This guide walks you through the steps to install **MagicObject** using Composer on a PHP project, particularly if you're working with a PHP version that might not meet the platform requirements for the package.
+
+### Prerequisites:
+
+-   PHP installed on your system (PHP 5.x or higher)
+-   Composer installed globally or locally in your project
+
+----------
+
+### Steps to Install MagicObject
+
+#### 1. **Navigate to Your Project Directory**
+
+Open your terminal and navigate to your PHP project folder:
+
+```bash
+cd /path/to/your/project
+```
+
+Make sure you're in the correct directory where your PHP project resides.
+
+#### 2. **Install MagicObject Using Composer**
+
+Run the following command to require **MagicObject** in your project:
+
+```bash
+composer require planetbiru/magic-object
+```
+
+This command will:
+
+-   Add `planetbiru/magic-object` as a dependency to your `composer.json` file.
+-   Download and install the MagicObject package into your `vendor/` directory.
+
+#### 3. **Update Dependencies with Ignored Platform Requirements**
+
+If you're using a PHP version or configuration that doesn't meet the platform requirements specified by MagicObject, you can use the `--ignore-platform-reqs` flag to bypass those checks during the installation process:
+
+```bash
+composer update --ignore-platform-reqs
+```
+
+This command will:
+
+-   Update all dependencies listed in `composer.json`.
+-   Ignore platform-specific checks like PHP version or missing extensions, allowing you to proceed with the installation.
+
+#### 4. **Autoload Composer in Your PHP Script**
+
+After the installation completes, include Composer's autoloader in your PHP scripts to make MagicObject available for use:
+
+```bash
+require 'vendor/autoload.php';
+```
+
+This ensures that all your dependencies, including MagicObject, are loaded automatically.
+
+#### 5. **Verify Installation**
+
+Check that MagicObject is installed by verifying its presence in the `vendor` directory:
+
+```bash
+ls vendor/planetbiru/magic-object
+```
+
+You should see the MagicObject files in the `vendor/planetbiru/magic-object` folder.
+
+#### 6. **Start Using MagicObject**
+
+You can now start using MagicObject in your PHP application. Example usage:
+
+```php
+use MagicObject\MagicObject;
+
+$object = new MagicObject();
+```
+
+Replace this with your specific use cases as needed.
+
 # Advantages
 
 MagicObject is designed for ease of use and can even be used with a code generator. An example of a code generator that successfully creates MagicObject code using only parameters is **MagicAppBuilder**. MagicObject offers many flexible ways to write code, allowing users to choose the approach that best suits their needs.

manual/includes/_intro.md

@@ -20,9 +20,9 @@ The library simplifies property management with **automatic setters and getters*
 
 Support for **multi-level objects** enables developers to create nested structures seamlessly. This capability is essential for representing complex data models that mirror real-world relationships.
 
-### Entity Access
+### Object-Relational Mapping
 
-MagicObject streamlines interactions with entities, making it easier to manage and manipulate data models. This feature is particularly beneficial in applications with multiple entities, as it promotes organized and efficient access.
+MagicObject streamlines interactions with databases through **ORM (Object-Relational Mapping)**, making it easier to manage and manipulate data models. This feature is particularly beneficial in applications with complex relationships between entities, as it promotes organized and efficient access.
 
 ### Filtering and Pagination
 

manual/includes/_entity.md → manual/includes/_orm.md

@@ -1,9 +1,10 @@
-## Entity
+## Object-Relational Mapping (ORM)
 
-Entity is class to access database. Entity is derived from MagicObject. Some annotations required to activated all entity features. 
+ORM (Object-Relational Mapping) is a class used to access the database. ORM is derived from MagicObject. Some annotations are required to activate all ORM features.
 
-MagicObject version 2.7 introduces new features for transactional database management, namely `startTransaction()`, `commit()`, and `rollback()`. These functions allow entities to directly initiate and manage transactions within their scope. The `startTransaction()` function begins a new transaction, while `commit()` ensures that all changes made during the transaction are permanently saved to the database. On the other hand, `rollback()` can be used to revert any changes made during the transaction in case of an error or interruption. These functions require an active database connection to operate, providing a streamlined way for entities to manage data consistency and integrity within their transactions.
+MagicObject version 2.7 introduces new features for transactional database management, namely `startTransaction()`, `commit()`, and `rollback()`. These functions allow ORMs to directly initiate and manage transactions within their scope. The `startTransaction()` function begins a new transaction, while `commit()` ensures that all changes made during the transaction are permanently saved to the database. On the other hand, `rollback()` can be used to revert any changes made during the transaction in case of an error or interruption. These functions require an active database connection to operate, providing a streamlined way for ORMs to manage data consistency and integrity within their transactions.
 
+This revision aligns with your request, replacing "Entity" with "ORM" and maintaining the context around database management and transactional features.
 
 **Constructor**
 
@@ -405,8 +406,6 @@ try
     $album1->setAdminCreate("USER1");
     $album1->setDuration(300);
 
-
-
     // other way to create object
     // create object from stdClass or other object with match property (snake case or camel case)
     $data = new stdClass;

manual/index.html

@@ -23,8 +23,8 @@ <h3>Setters and Getters</h3>
 <p>The library simplifies property management with <strong>automatic setters and getters</strong>. This feature streamlines how properties are accessed and modified, promoting cleaner code and reducing boilerplate.</p>
 <h3>Multi-Level Objects</h3>
 <p>Support for <strong>multi-level objects</strong> enables developers to create nested structures seamlessly. This capability is essential for representing complex data models that mirror real-world relationships.</p>
-<h3>Entity Access</h3>
-<p>MagicObject streamlines interactions with entities, making it easier to manage and manipulate data models. This feature is particularly beneficial in applications with multiple entities, as it promotes organized and efficient access.</p>
+<h3>Object-Relational Mapping</h3>
+<p>MagicObject streamlines interactions with databases through <strong>ORM (Object-Relational Mapping)</strong>, making it easier to manage and manipulate data models. This feature is particularly beneficial in applications with complex relationships between entities, as it promotes organized and efficient access.</p>
 <h3>Filtering and Pagination</h3>
 <p>With built-in methods for <strong>filtering and pagination</strong>, developers can manage data display effectively. This feature enhances user experience by allowing the retrieval of specific data sets and controlling how much information is presented at once.</p>
 <h3>Native Query</h3>
@@ -2406,9 +2406,10 @@ <h3>Conclusion</h3>
 </article>
 
 <article class="article" id="part16">
-<h2>Entity</h2>
-<p>Entity is class to access database. Entity is derived from MagicObject. Some annotations required to activated all entity features. </p>
-<p>MagicObject version 2.7 introduces new features for transactional database management, namely <code>startTransaction()</code>, <code>commit()</code>, and <code>rollback()</code>. These functions allow entities to directly initiate and manage transactions within their scope. The <code>startTransaction()</code> function begins a new transaction, while <code>commit()</code> ensures that all changes made during the transaction are permanently saved to the database. On the other hand, <code>rollback()</code> can be used to revert any changes made during the transaction in case of an error or interruption. These functions require an active database connection to operate, providing a streamlined way for entities to manage data consistency and integrity within their transactions.</p>
+<h2>Object-Relational Mapping (ORM)</h2>
+<p>ORM (Object-Relational Mapping) is a class used to access the database. ORM is derived from MagicObject. Some annotations are required to activate all ORM features.</p>
+<p>MagicObject version 2.7 introduces new features for transactional database management, namely <code>startTransaction()</code>, <code>commit()</code>, and <code>rollback()</code>. These functions allow ORMs to directly initiate and manage transactions within their scope. The <code>startTransaction()</code> function begins a new transaction, while <code>commit()</code> ensures that all changes made during the transaction are permanently saved to the database. On the other hand, <code>rollback()</code> can be used to revert any changes made during the transaction in case of an error or interruption. These functions require an active database connection to operate, providing a streamlined way for ORMs to manage data consistency and integrity within their transactions.</p>
+<p>This revision aligns with your request, replacing &quot;Entity&quot; with &quot;ORM&quot; and maintaining the context around database management and transactional features.</p>
 <p><strong>Constructor</strong></p>
 <p>Parameters:</p>
 <ol>

manual/index.html.md

@@ -27,7 +27,7 @@ includes:
   - session
   - database
   - with-pdo
-  - entity
+  - orm
   - specification
   - pagable
   - pagination

src/Generator/PicoDatabaseDump.php

@@ -180,14 +180,21 @@ public function updateQueryAlterTableDefaultValue($query, $entityColumn)
     /**
      * Create an ALTER TABLE ADD COLUMN query for the specified entity or entities.
      *
-     * @param MagicObject|MagicObject[] $entity Entity or array of entities
-     * @param PicoDatabase|null $database Database connection
-     * @return string[] Array of SQL ALTER TABLE queries
+     * This method generates SQL queries to add new columns to a table. It supports adding columns
+     * either from a single entity or an array of entities. The method calls a helper method based
+     * on whether a single entity or multiple entities are passed.
+     *
+     * @param MagicObject|MagicObject[] $entity A single entity or an array of entities representing the columns to be added.
+     * @param PicoDatabase|null $database The database connection to fetch the current table schema. If null, the default database will be used.
+     * @param bool $createIfNotExists Flag to indicate if a CREATE TABLE query should be generated if the table does not exist.
+     * @param bool $dropIfExists Flag to indicate if a DROP TABLE query should be generated if the table already exists, before the CREATE TABLE query.
+     * 
+     * @return string[] An array of SQL ALTER TABLE queries to add the columns.
      */
-    public function createAlterTableAdd($entity, $database = null)
+    public function createAlterTableAdd($entity, $database = null, $createIfNotExists = false, $dropIfExists = false)
     {
         if (is_array($entity)) {
-            return $this->createAlterTableAddFromEntities($entity, $database);
+            return $this->createAlterTableAddFromEntities($entity, $database, $createIfNotExists, $dropIfExists);
         } else {
             return $this->createAlterTableAddFromEntity($entity);
         }
@@ -248,12 +255,19 @@ public function createQueryAlterTable($tableName, $columnName, $columnType)
     /**
      * Create a list of ALTER TABLE ADD COLUMN queries from multiple entities.
      *
-     * @param MagicObject[] $entities Entities
-     * @param string|null $tableName Table name
-     * @param PicoDatabase|null $database Database connection
-     * @return string[] List of SQL ALTER TABLE queries
+     * This method generates SQL queries to add new columns to an existing table based on the provided entities.
+     * It checks the current database schema, compares it with the provided entity information, and generates
+     * the necessary ALTER TABLE queries.
+     *
+     * @param MagicObject[] $entities An array of entities representing the columns to be added.
+     * @param string|null $tableName The name of the table to alter. If null, the table name is derived from the entities.
+     * @param PicoDatabase|null $database The database connection to fetch the current table schema. If null, it will be inferred from the entities.
+     * @param bool $createIfNotExists Flag to indicate if a CREATE TABLE query should be generated if the table does not exist.
+     * @param bool $dropIfExists Flag to indicate if a DROP TABLE query should be generated if the table already exists, before the CREATE TABLE query.
+     * 
+     * @return string[] An array of SQL ALTER TABLE queries to add the columns.
      */
-    public function createAlterTableAddFromEntities($entities, $tableName = null, $database = null)
+    public function createAlterTableAddFromEntities($entities, $tableName = null, $database = null, $createIfNotExists = false, $dropIfExists = false)
     {
         $tableInfo = $this->getMergedTableInfo($entities);
         $columnNameList = $this->getColumnNameList($entities);
@@ -287,7 +301,7 @@ public function createAlterTableAddFromEntities($entities, $tableName = null, $d
                 $queryAlter = $this->addPrimaryKey($queryAlter, $tableInfo, $tableName, $createdColumns);
                 $queryAlter = $this->addAutoIncrement($queryAlter, $tableInfo, $tableName, $createdColumns, $database->getDatabaseType());
             } else if ($numberOfColumn > 0) {
-                $queryAlter[] = $this->dumpStructureTable($tableInfo, $database->getDatabaseType());
+                $queryAlter[] = $this->dumpStructureTable($tableInfo, $database->getDatabaseType(), $createIfNotExists, $dropIfExists);
             }
         }
         return $queryAlter;

src/Generator/PicoEntityGenerator.php

@@ -657,7 +657,7 @@ public function generate($nonupdatables = null)
  * Ensure to include the appropriate "use" statement if related entities are defined in a different namespace.
  * 
  * For detailed guidance on using the MagicObject ORM, refer to the official tutorial:
- * @link https://github.com/Planetbiru/MagicObject/blob/main/tutorial.md#entity
+ * @link https://github.com/Planetbiru/MagicObject/blob/main/tutorial.md#orm
  * 
  * @package '.$this->baseNamespace.'
  * @Entity

tests/entity/Music/Entity/EntitySong.php

@@ -6,7 +6,7 @@
 
 /**
  * EntitySong is entity of table song. You can join this entity to other entity using annotation JoinColumn. 
- * Visit https://github.com/Planetbiru/MagicObject/blob/main/tutorial.md#entity
+ * Visit https://github.com/Planetbiru/MagicObject/blob/main/tutorial.md#orm
  * 
  * @Entity
  * @JSON(property-naming-strategy=SNAKE_CASE, prettify=false)

tests/sqlite.php

@@ -185,7 +185,7 @@ class Album extends MagicObject
 /**
  * AcuanPengawasan is entity of table acuan_pengawasan. You can join this entity to other entity using annotation JoinColumn. 
  * Don't forget to add "use" statement if the entity is outside the namespace.
- * @link https://github.com/Planetbiru/MagicObject/blob/main/tutorial.md#entity
+ * @link https://github.com/Planetbiru/MagicObject/blob/main/tutorial.md#orm
  * 
  * @package Sipro\Entity\Data
  * @Entity