From cc6beabdbbd1733fecd2c030ddff90e598732e1a Mon Sep 17 00:00:00 2001 From: "Kamshory, MT" Date: Wed, 11 Dec 2024 14:37:08 +0700 Subject: [PATCH 1/4] Update PicoDatabaseDump.php --- src/Generator/PicoDatabaseDump.php | 36 +++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/src/Generator/PicoDatabaseDump.php b/src/Generator/PicoDatabaseDump.php index 613d0ec5..b913e56b 100644 --- a/src/Generator/PicoDatabaseDump.php +++ b/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; From 9cfa10e9bd70432cc5d4bbc30ee35da2d463dbb9 Mon Sep 17 00:00:00 2001 From: "Kamshory, MT" Date: Sun, 15 Dec 2024 12:13:33 +0700 Subject: [PATCH 2/4] Update --- README.md | 2 +- manual/includes/_intro.md | 4 ++-- manual/includes/{_entity.md => _orm.md} | 9 ++++----- manual/index.html | 11 ++++++----- manual/index.html.md | 2 +- src/Generator/PicoEntityGenerator.php | 2 +- tests/entity/Music/Entity/EntitySong.php | 2 +- tests/sqlite.php | 2 +- tutorial.md | 13 ++++++------- 9 files changed, 23 insertions(+), 24 deletions(-) rename manual/includes/{_entity.md => _orm.md} (99%) diff --git a/README.md b/README.md index 4b3c15d0..eafb288b 100644 --- a/README.md +++ b/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. diff --git a/manual/includes/_intro.md b/manual/includes/_intro.md index 4323ae9a..1a9bd5ac 100644 --- a/manual/includes/_intro.md +++ b/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 diff --git a/manual/includes/_entity.md b/manual/includes/_orm.md similarity index 99% rename from manual/includes/_entity.md rename to manual/includes/_orm.md index 8f132296..5869d421 100644 --- a/manual/includes/_entity.md +++ b/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; diff --git a/manual/index.html b/manual/index.html index 6b742efd..e8aed847 100644 --- a/manual/index.html +++ b/manual/index.html @@ -23,8 +23,8 @@

Setters and Getters

The library simplifies property management with automatic setters and getters. This feature streamlines how properties are accessed and modified, promoting cleaner code and reducing boilerplate.

Multi-Level Objects

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

-

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.

+

Object-Relational Mapping

+

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

With built-in methods for filtering and pagination, 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.

Native Query

@@ -2406,9 +2406,10 @@

Conclusion

-

Entity

-

Entity is class to access database. Entity is derived from MagicObject. Some annotations required to activated all entity 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.

+

Object-Relational Mapping (ORM)

+

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 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

Parameters:

    diff --git a/manual/index.html.md b/manual/index.html.md index ab8a49fe..760c588d 100644 --- a/manual/index.html.md +++ b/manual/index.html.md @@ -27,7 +27,7 @@ includes: - session - database - with-pdo - - entity + - orm - specification - pagable - pagination diff --git a/src/Generator/PicoEntityGenerator.php b/src/Generator/PicoEntityGenerator.php index 6d8038f7..c746a66a 100644 --- a/src/Generator/PicoEntityGenerator.php +++ b/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 diff --git a/tests/entity/Music/Entity/EntitySong.php b/tests/entity/Music/Entity/EntitySong.php index b5cd2d24..a5504d3f 100644 --- a/tests/entity/Music/Entity/EntitySong.php +++ b/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) diff --git a/tests/sqlite.php b/tests/sqlite.php index df5da3be..254a8265 100644 --- a/tests/sqlite.php +++ b/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 diff --git a/tutorial.md b/tutorial.md index 30e0ff0c..e723214e 100644 --- a/tutorial.md +++ b/tutorial.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 @@ -2820,12 +2820,13 @@ In **MagicObject 2.7**, when you pass a **PDO** connection object to the constru Version 2.7 of **MagicObject** introduces an important enhancement by allowing PDO connections to be used alongside **PicoDatabase**. This update provides greater flexibility for developers, allowing them to work with traditional PDO connections if they choose, while still benefiting from the advanced features of **MagicObject** for database interactions. This change aligns with the goal of making **MagicObject** more accessible to a wider range of developers, whether they are just starting with **MagicObject** or are looking to transition from an existing PDO-based application. -## 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** @@ -3227,8 +3228,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; From 3d701bda0e7715b765b6bc8bcc9721069b6afa79 Mon Sep 17 00:00:00 2001 From: "Kamshory, MT" Date: Sun, 15 Dec 2024 12:22:15 +0700 Subject: [PATCH 3/4] Update PicoDatabaseDump.php --- src/Generator/PicoDatabaseDump.php | 36 +++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/src/Generator/PicoDatabaseDump.php b/src/Generator/PicoDatabaseDump.php index 613d0ec5..b913e56b 100644 --- a/src/Generator/PicoDatabaseDump.php +++ b/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; From f028d061960585af25471160a54a4ae2f40bc03a Mon Sep 17 00:00:00 2001 From: "Kamshory, MT" Date: Sun, 15 Dec 2024 12:34:39 +0700 Subject: [PATCH 4/4] Update README.md --- README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index eafb288b..df6183e7 100644 --- a/README.md +++ b/README.md @@ -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.