diff --git a/manual/includes/_intro.md b/manual/includes/_intro.md new file mode 100644 index 00000000..4323ae9a --- /dev/null +++ b/manual/includes/_intro.md @@ -0,0 +1,89 @@ +# Introduction + +## What Is MagicObject + +MagicObject is a powerful library designed to simplify object management and data handling in PHP applications. It provides a set of features that enhance flexibility, efficiency, and maintainability, making it easier for developers to create and manage complex applications. + +In modern application development, managing objects efficiently is paramount. The **MagicObject** library provides an extensive suite of features that simplify object creation, data handling, and database interactions. Below, we’ll explore some of the core functionalities that make MagicObject a powerful tool for developers. + +## Key Features + +### Dynamic Object Creation + +MagicObject allows for **dynamic object creation**, enabling developers to instantiate objects at runtime easily. This flexibility is crucial for applications that require variable object structures based on user input or external data sources. + +### 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. + +### 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 + +Defining **native queries** within the library increases flexibility and resource efficiency in database access. This feature allows developers to leverage the full power of SQL while benefiting from MagicObject's abstraction layer. + +### Multiple Database Connections + +MagicObject supports the configuration of **multiple database connections**, enabling applications to interact with different databases simultaneously. This capability is vital for applications that aggregate data from various sources or require connections to multiple environments. + +### Database Dumping + +Efficiently exporting database contents is made possible through **database dumping** features. This functionality aids in backup processes, data migrations, and reporting. + +### Serialization/Deserialization + +Handling JSON and YAML formats is straightforward with built-in **serialization and deserialization** methods. This feature is essential for applications that communicate with APIs or require data interchange formats. + +### Data Importing + +MagicObject provides robust support for **data importing**, allowing users to bring data into the application even if the source and destination schemas differ. This flexibility is crucial in data migration and integration scenarios. + +### File Reading + +The library supports reading configuration files in various formats, including **INI, YAML, and JSON**. This feature simplifies application configuration management, making it easier to maintain different environments. + +### Environment Variable Access + +MagicObject enables easy fetching of **environment variable values**, promoting better configuration management and enhancing security by separating sensitive information from code. + +### Configuration Encryption + +To secure application settings, MagicObject offers **configuration encryption** features. This ensures that sensitive data, such as API keys and database credentials, are protected from unauthorized access. + +### HTTP Data Handling + +Creating objects from global request variables (e.g., POST, GET) is simplified with built-in **HTTP data handling** capabilities. This feature enhances the ease of integrating with web forms and APIs. + +### Session Management + +Integrating with **PHP sessions** allows MagicObject to maintain state effectively across user interactions. This functionality is crucial for applications that rely on user sessions for personalized experiences. + +### Object Labeling + +Enhancing object identification through **object labeling** improves the clarity of code and debugging processes. Labels allow developers to categorize and reference objects more easily. + +### Multi-Language Support + +Facilitating **localization** is a key feature of MagicObject, allowing developers to create applications that can serve multiple languages and regions. This capability is essential for reaching a global audience. + +### File Uploads + +Handling file uploads efficiently is another strength of MagicObject. The library provides tools to manage file uploads securely and effectively, making it easier to incorporate user-generated content. + +### Annotations + +Adding **metadata to objects** through annotations allows for better structure and organization within the code. This feature can be leveraged for documentation, validation, and configuration purposes. + +### Debugging + +Finally, MagicObject includes comprehensive **debugging tools** to inspect and analyze objects during development. This feature is invaluable for troubleshooting and ensuring that applications run smoothly. diff --git a/manual/index.html b/manual/index.html index a1a767a6..f965bcf2 100644 --- a/manual/index.html +++ b/manual/index.html @@ -12,6 +12,54 @@
+

Introduction

+

What Is MagicObject

+

MagicObject is a powerful library designed to simplify object management and data handling in PHP applications. It provides a set of features that enhance flexibility, efficiency, and maintainability, making it easier for developers to create and manage complex applications.

+

In modern application development, managing objects efficiently is paramount. The MagicObject library provides an extensive suite of features that simplify object creation, data handling, and database interactions. Below, we’ll explore some of the core functionalities that make MagicObject a powerful tool for developers.

+

Key Features

+

Dynamic Object Creation

+

MagicObject allows for dynamic object creation, enabling developers to instantiate objects at runtime easily. This flexibility is crucial for applications that require variable object structures based on user input or external data sources.

+

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.

+

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

+

Defining native queries within the library increases flexibility and resource efficiency in database access. This feature allows developers to leverage the full power of SQL while benefiting from MagicObject's abstraction layer.

+

Multiple Database Connections

+

MagicObject supports the configuration of multiple database connections, enabling applications to interact with different databases simultaneously. This capability is vital for applications that aggregate data from various sources or require connections to multiple environments.

+

Database Dumping

+

Efficiently exporting database contents is made possible through database dumping features. This functionality aids in backup processes, data migrations, and reporting.

+

Serialization/Deserialization

+

Handling JSON and YAML formats is straightforward with built-in serialization and deserialization methods. This feature is essential for applications that communicate with APIs or require data interchange formats.

+

Data Importing

+

MagicObject provides robust support for data importing, allowing users to bring data into the application even if the source and destination schemas differ. This flexibility is crucial in data migration and integration scenarios.

+

File Reading

+

The library supports reading configuration files in various formats, including INI, YAML, and JSON. This feature simplifies application configuration management, making it easier to maintain different environments.

+

Environment Variable Access

+

MagicObject enables easy fetching of environment variable values, promoting better configuration management and enhancing security by separating sensitive information from code.

+

Configuration Encryption

+

To secure application settings, MagicObject offers configuration encryption features. This ensures that sensitive data, such as API keys and database credentials, are protected from unauthorized access.

+

HTTP Data Handling

+

Creating objects from global request variables (e.g., POST, GET) is simplified with built-in HTTP data handling capabilities. This feature enhances the ease of integrating with web forms and APIs.

+

Session Management

+

Integrating with PHP sessions allows MagicObject to maintain state effectively across user interactions. This functionality is crucial for applications that rely on user sessions for personalized experiences.

+

Object Labeling

+

Enhancing object identification through object labeling improves the clarity of code and debugging processes. Labels allow developers to categorize and reference objects more easily.

+

Multi-Language Support

+

Facilitating localization is a key feature of MagicObject, allowing developers to create applications that can serve multiple languages and regions. This capability is essential for reaching a global audience.

+

File Uploads

+

Handling file uploads efficiently is another strength of MagicObject. The library provides tools to manage file uploads securely and effectively, making it easier to incorporate user-generated content.

+

Annotations

+

Adding metadata to objects through annotations allows for better structure and organization within the code. This feature can be leveraged for documentation, validation, and configuration purposes.

+

Debugging

+

Finally, MagicObject includes comprehensive debugging tools to inspect and analyze objects during development. This feature is invaluable for troubleshooting and ensuring that applications run smoothly.

+
+ +

MagicObject Installation

To install MagicObbject

composer require planetbiru/magic-object
@@ -24,11 +72,11 @@

MagicObject Installation

To install composer on your PC or download latest composer.phar, click https://getcomposer.org/download/

-
+

MagicObject Implementation

-
+

Simple Object

Set and Get Properties Value

<?php
@@ -284,7 +332,7 @@ 
Pop

 ``
-
+

Extends MagicObject

User can extend MagicObject to many classes.

<?php
@@ -338,7 +386,7 @@ 
Class Parameters

 
Default value: CAMEL_CASE
-
+

Multilevel Object

In the first code snippet, you are creating a multilevel object structure to represent a car with its components, specifically the tire and body.

<?php
@@ -441,7 +489,7 @@ 
Conclusion

 
Both examples demonstrate how MagicObject allows you to create complex object structures and manage nested data efficiently. The use of YAML for configuration or data storage makes it easier to define complex structures in a human-readable format. The ability to set and get properties through method chaining enhances the flexibility and readability of your code.
-
+

Object from Yaml

From Yaml String

<?php
@@ -507,7 +555,7 @@ 
From Yaml File
-
+

Object from INI

INI not support multilevel object. If multilevel object needed, use Yaml instead.

From INI String

@@ -536,7 +584,7 @@

From INI File
-
+

Environment Variable

Many application use environment variable to store the config. We can replace the config template with the environment variable. We must set the environment variable to the server before run the application.

# config.yml
@@ -631,7 +679,7 @@ 
Create Environment Variable

 service httpd restart
-
+

Secret Object

Definition

Secret Objects are very important in applications that use very sensitive and secret configurations. This configuration must be encrypted so that it cannot be seen either when someone tries to open the configuration file, environment variables, or even when the developer accidentally debugs an object related to the database so that the properties of the database object are exposed including the host name, database name, username and even password.

@@ -1222,7 +1270,7 @@

Secure Config from DynamicObject
-
+

Input POST/GET/COOKIE/REQUEST/SERVER

In PHP, handling user input can be done through various superglobals, such as $_POST, $_GET, $_COOKIE, $_REQUEST, and $_SERVER. Each of these superglobals serves a specific purpose for gathering data from different types of requests.

Input POST

@@ -1349,7 +1397,7 @@

Conclusion

In summary, handling input in PHP through superglobals is straightforward but requires careful filtering to ensure security. Using classes like InputPost, InputGet, InputCookie, InputRequest, and InputServer can abstract the underlying superglobal accesses, making the code cleaner and potentially more secure by enforcing consistent input handling and sanitization practices.

-
+

Session

Session variables keep information about one single user, and are available to all pages in one application.

Session with File

@@ -1450,7 +1498,7 @@

Conclusion

This implementation provides a robust framework for session management in a PHP application, allowing flexibility in storage options (files or Redis) while emphasizing security through encryption. The use of YAML for configuration keeps the setup clean and easily adjustable. By encapsulating session configuration in dedicated classes, you enhance maintainability and security.

-
+

Entity

Entity is class to access database. Entity is derived from MagicObject. Some annotations required to activated all entity features.

Constructor

@@ -5938,7 +5986,7 @@

Method

}
-
+

Specification

Specifications are implemented in the PicoSpecification and PicoPredicate classes. PicoSpecification is a framework that can contain one or more PicoPredicate.

For example, we have the following query:

@@ -6431,7 +6479,7 @@

Specification

}
-
+

Pageable and Sortable

In MagicObject, pageable is used to divide data rows into several pages. This is required by the application to display a lot of data per page. While sortable is used to sort data before the data is divided per page.

Pageable can stand alone without sortable. However, this method is not recommended because the data sequence is not as expected. If new data is entered, users will have difficulty finding where it is located in the list and on which page the data will appear. The solution is to add a sortable that will sort the data based on certain columns. For example, the time of data creation is descending, then the new data will be on the first page. Conversely, if sorted based on the time of data creation is ascending, then the new data will be on the last page.

@@ -6723,7 +6771,7 @@

Pageable and Sortable

ORDER BY user_name ASC, email DESC, phone ASC LIMIT 200 OFFSET 400

-
+

Filtering, Ordering and Pagination

MagicObject will filter data according to the given criteria. On the other hand, MagicObject will only retrieve data on the specified page by specifying limit and offset data in the select query.

Example parameters:

@@ -7606,7 +7654,7 @@

Filtering, Ordering and Pagination

?>
-
+

Native Query

In MagicObject version 2, native queries have been introduced as an efficient way to interact with the database.

Native queries offer significant performance improvements when handling large volumes of data, allowing users to craft highly efficient queries that meet diverse requirements.

@@ -8236,7 +8284,7 @@

Best Practices

By leveraging the native query feature in MagicObject, you can create efficient and maintainable database interactions, enhancing your application's performance and security.

-
+

Multiple Database Connections

MagicObject version 2 introduces support for multiple database connections, enabling users to manage entities stored across different databases seamlessly. When performing operations such as JOINs with entities from multiple databases, it is essential to define a database connection for each entity involved.

Example Scenario

@@ -8401,7 +8449,7 @@

Conclusion

With MagicObject version 2, managing entities across multiple database connections is straightforward. By defining the correct associations and utilizing the provided methods, users can effectively work with complex data structures that span multiple databases. Make sure to handle exceptions properly to ensure robustness in your application.

-
+

Dump Database

We can dump database to another database type. We do not need any database converter. Just define the target database type when we dump the database.

Database Dump Overview

@@ -8882,7 +8930,7 @@

Summary

This approach allows developers to quickly switch between database types and manage their database schemas and data efficiently. The use of dedicated instances of PicoDatabaseDump for multiple tables ensures clarity and organization in your database operations.

-
+

Object Label

<?php
 
@@ -9007,7 +9055,7 @@ 
Object Label

 // it will print "Admin Create"
-
+

Database Query Builder

Database Query Builder is a feature for creating object-based database queries. The output of the Database Query Builder is a query that can be directly executed by the database used.

Database Query Builder is actually designed for all relational databases but is currently only available in two languages, namely MySQL and PostgreSQL. MagicObject internally uses the Database Query Builder to create queries based on given methods and parameters.

@@ -9274,7 +9322,7 @@

Methods

This way, $active will be escaped before being executed by the database. You don't need to escape it first.

-
+

Upload File

Uploading lots of files with arrays is difficult for some developers, especially novice developers. There is a significant difference between uploading a single file and multiple files.

When the developer decides to change the form from single file to multiple files or vice versa, the backend developer must change the code to handle the uploaded files.

@@ -9334,7 +9382,7 @@

Summary

This implementation offers a straightforward way to manage file uploads in PHP, abstracting complexities for developers. By using methods like getAll() and isMultiple(), developers can seamlessly handle both types of uploads without needing to write separate logic for each scenario. This approach not only improves code maintainability but also enhances the developer experience.

-
+

Language

MagicObject supports multilingual applications. MagicObject allows developers to create entities that support a wide variety of languages that users can choose from. At the same time, different users can use different languages.

To create table with multiple language, create new class from DataTable object. We can copy data from aother object to DataTable easly.

@@ -9554,7 +9602,7 @@

Language

echo $apa;
-
+

Database Migration

MagicObject allows users to import data from a database with different table names and column names between the source database and the destination database. This feature is used by developers who develop applications that are already used in production environments.

On the one hand, the application requires a new database structure according to what is defined by the developer. On the other hand, users want to use existing data.

diff --git a/manual/index.html.md b/manual/index.html.md index 6e740113..c8babc2f 100644 --- a/manual/index.html.md +++ b/manual/index.html.md @@ -12,6 +12,7 @@ --- includes: + - intro - installation - implementation - simple-object diff --git a/tutorial.md b/tutorial.md index 8825f6ca..71de1813 100644 --- a/tutorial.md +++ b/tutorial.md @@ -1,3 +1,93 @@ +# Introduction + +## What Is MagicObject + +MagicObject is a powerful library designed to simplify object management and data handling in PHP applications. It provides a set of features that enhance flexibility, efficiency, and maintainability, making it easier for developers to create and manage complex applications. + +In modern application development, managing objects efficiently is paramount. The **MagicObject** library provides an extensive suite of features that simplify object creation, data handling, and database interactions. Below, we’ll explore some of the core functionalities that make MagicObject a powerful tool for developers. + +## Key Features + +### Dynamic Object Creation + +MagicObject allows for **dynamic object creation**, enabling developers to instantiate objects at runtime easily. This flexibility is crucial for applications that require variable object structures based on user input or external data sources. + +### 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. + +### 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 + +Defining **native queries** within the library increases flexibility and resource efficiency in database access. This feature allows developers to leverage the full power of SQL while benefiting from MagicObject's abstraction layer. + +### Multiple Database Connections + +MagicObject supports the configuration of **multiple database connections**, enabling applications to interact with different databases simultaneously. This capability is vital for applications that aggregate data from various sources or require connections to multiple environments. + +### Database Dumping + +Efficiently exporting database contents is made possible through **database dumping** features. This functionality aids in backup processes, data migrations, and reporting. + +### Serialization/Deserialization + +Handling JSON and YAML formats is straightforward with built-in **serialization and deserialization** methods. This feature is essential for applications that communicate with APIs or require data interchange formats. + +### Data Importing + +MagicObject provides robust support for **data importing**, allowing users to bring data into the application even if the source and destination schemas differ. This flexibility is crucial in data migration and integration scenarios. + +### File Reading + +The library supports reading configuration files in various formats, including **INI, YAML, and JSON**. This feature simplifies application configuration management, making it easier to maintain different environments. + +### Environment Variable Access + +MagicObject enables easy fetching of **environment variable values**, promoting better configuration management and enhancing security by separating sensitive information from code. + +### Configuration Encryption + +To secure application settings, MagicObject offers **configuration encryption** features. This ensures that sensitive data, such as API keys and database credentials, are protected from unauthorized access. + +### HTTP Data Handling + +Creating objects from global request variables (e.g., POST, GET) is simplified with built-in **HTTP data handling** capabilities. This feature enhances the ease of integrating with web forms and APIs. + +### Session Management + +Integrating with **PHP sessions** allows MagicObject to maintain state effectively across user interactions. This functionality is crucial for applications that rely on user sessions for personalized experiences. + +### Object Labeling + +Enhancing object identification through **object labeling** improves the clarity of code and debugging processes. Labels allow developers to categorize and reference objects more easily. + +### Multi-Language Support + +Facilitating **localization** is a key feature of MagicObject, allowing developers to create applications that can serve multiple languages and regions. This capability is essential for reaching a global audience. + +### File Uploads + +Handling file uploads efficiently is another strength of MagicObject. The library provides tools to manage file uploads securely and effectively, making it easier to incorporate user-generated content. + +### Annotations + +Adding **metadata to objects** through annotations allows for better structure and organization within the code. This feature can be leveraged for documentation, validation, and configuration purposes. + +### Debugging + +Finally, MagicObject includes comprehensive **debugging tools** to inspect and analyze objects during development. This feature is invaluable for troubleshooting and ensuring that applications run smoothly. + # MagicObject Installation To install **MagicObbject**