# Micro ORM 6.0 - Major Release

.github/workflows/phpunit.yml

@@ -16,6 +16,7 @@ jobs:
     strategy:
       matrix:
         php-version:
+          - "8.4"
           - "8.3"
           - "8.2"
           - "8.1"
@@ -40,8 +41,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: composer install
-      - run: ./vendor/bin/phpunit
       - run: ./vendor/bin/psalm
+      - run: ./vendor/bin/phpunit
 
   Documentation:
     if: github.ref == 'refs/heads/master'
@@ -50,5 +51,6 @@ jobs:
     with:
       folder: php
       project: ${{ github.event.repository.name }}
-    secrets: inherit
+    secrets:
+      DOC_TOKEN: ${{ secrets.DOC_TOKEN }}
 

.gitpod.yml

@@ -0,0 +1,28 @@
+tasks:
+  - name: Run Composer
+    command: |
+      composer install  
+
+image: byjg/gitpod-image:latest
+
+jetbrains:
+  phpstorm:
+    vmoptions: '-Xmx4g'
+  plugins:
+    - com.github.copilot
+    - com.intellij.kubernetes
+    - com.intellij.mermaid
+    - ru.adelf.idea.dotenv
+    - org.toml.lang
+
+vscode:
+  extensions:
+    - ikappas.composer
+    - hbenl.test-adapter-converter
+    - hbenl.vscode-test-explorer
+    - felixfbecker.php-debug
+    - neilbrayfield.php-docblocker
+    - bmewburn.vscode-intelephense-client
+    - getpsalm.psalm-vscode-plugin
+    - SonarSource.sonarlint-vscode
+    - recca0120.vscode-phpunit 

.vscode/launch.json

@@ -0,0 +1,35 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug current Script in Console",
+      "type": "php",
+      "request": "launch",
+      "program": "${file}",
+      "cwd": "${fileDirname}",
+      "port": 9003,
+      "runtimeArgs": [
+        "-dxdebug.start_with_request=yes"
+      ],
+      "env": {
+        "XDEBUG_MODE": "debug,develop",
+        "XDEBUG_CONFIG": "client_port=${port}"
+      }
+    },
+    {
+      "name": "PHPUnit Debug",
+      "type": "php",
+      "request": "launch",
+      "program": "${workspaceFolder}/vendor/bin/phpunit",
+      "cwd": "${workspaceFolder}",
+      "port": 9003,
+      "runtimeArgs": [
+        "-dxdebug.start_with_request=yes"
+      ],
+      "env": {
+        "XDEBUG_MODE": "debug,develop",
+        "XDEBUG_CONFIG": "client_port=${port}"
+      }
+    }
+  ]
+} 

README.md

@@ -14,10 +14,21 @@ Key Features:
 * Can be used with any DTO, Entity, Model or whatever class with public properties or with getter and setter
 * The repository support a variety of datasources: MySql, Sqlite, Postgres, MySQL, Oracle (see byjg/anydataset)
 * A class Mapper is used for mapping the Entity and the repository
+* Powerful mapper functions for automatic data transformation between models and database
 * Small and simple to use
 
 ## Architecture
 
+MicroORM implements **Martin Fowler's enterprise patterns**:
+
+- **[Repository](https://martinfowler.com/eaaCatalog/repository.html)**: Mediates between domain and data mapping layers
+- **[Data Mapper](https://martinfowler.com/eaaCatalog/dataMapper.html)**: Separates domain objects from database tables
+- **[Active Record](https://martinfowler.com/eaaCatalog/activeRecord.html)**: Wraps database rows with domain logic (
+  alternative approach)
+
+You can choose the pattern that best fits your application: use Repository + Data Mapper for complex domains, or Active
+Record for simpler CRUD-focused applications.
+
 These are the key components:
 
 ```text
@@ -35,26 +46,35 @@ These are the key components:
 │          ┌───────────────┴─────┐
 │          │        Query        │
 │          └───────────────┬─────┘
-│                          │
-│          ┌───────────────┴─────┐
-│          │  DbDriverInterface  │───────────────┐
-│          └───────────────┬─────┘               │
-│                          │                     │
-└──────────────────────────┘                .─────────.
-                                           │           │
-                                           │`─────────'│
-                                           │           │
-                                           │    DB     │
-                                           │           │
-                                           │           │
-                                            `─────────'
+│                     │    │
+│          ┌───────────────┴─────┐        ┌──────────────────────┐  
+│          │  DatabaseExecutor   │────────│   DbDriverInterface  │  
+│          └───────────────┬─────┘        └────────────┬─────────┘  
+│                          │                           │                
+└──────────────────────────┘                      .─────────.           
+                                                 │           │          
+                                                 │`─────────'│          
+                                                 │           │          
+                                                 │    DB     │          
+                                                 │           │          
+                                                 │           │          
+                                                  `─────────'           
 ```
 
-* Model is a get/set class to retrieve or save the data into the database
-* Mapper will create the definitions to map the Model into the Database.
-* Query will use the Mapper to prepare the query to the database based on DbDriverInterface
-* DbDriverIntarce is the implementation to the Database connection.
-* Repository put all this together
+* **Model** can be any class with public properties or with getter and setter. It is used to retrieve or save the data
+  into the database
+* **Mapper** defines the relationship between the Model properties and the database fields
+* **FieldMapping** defines individual field mappings within the Mapper (field names, transformations, relationships via
+  `parentTable`)
+* **Query** defines what to retrieve from/update in the database. It uses the Mapper to prepare the query to the
+  database converting the Model properties to database fields
+* **DatabaseExecutor** (external package) wraps the DbDriver and provides transaction management, query execution, and
+  access to database helpers
+* **DbDriverInterface** (external package) is the actual database driver implementation that connects to the database
+* **Repository** orchestrates all MicroORM components and uses DatabaseExecutor to interact with the database
+
+For a detailed explanation of the architecture and when to use each layer,
+see [Architecture Layers: Infrastructure vs Domain](docs/architecture-layers.md).
 
 
 ## Getting Started
@@ -89,20 +109,21 @@ Let's look at an example:
 class MyModel
 {
     #[FieldAttribute(primaryKey: true)]
-    public ?int $id;
+    public ?int $id = null;
 
     #[FieldAttribute()]
-    public ?string $name;
+    public ?string $name = null;
 
     #[FieldAttribute(fieldName: 'company_id')
-    public ?int $companyId;
+    public ?int $companyId = null;
 }
 ```
 
 In this example, we have a class `MyModel` with three properties: `id`, `name`, and `companyId`.
 
-The `id` property is marked as a primary key. The `name` property is a simple field.
-The `companyId` property is a field with a different name in the database `company_id`.
+* The `id` property is marked as a primary key.
+* The `name` property is a simple field.
+* The `companyId` property is a field with a different name in the database `company_id`.
 
 The `TableAttribute` is used to define the table name in the database.
 
@@ -111,8 +132,7 @@ The `TableAttribute` is used to define the table name in the database.
 After defining the Model, you can connect the Model with the repository.
 
 ```php
-$dbDriver = \ByJG\AnyDataset\Db\Factory::getDbRelationalInstance('mysql://user:password@server/schema');
-
+$dbDriver = \ByJG\AnyDataset\Db\Factory::getDbInstance('mysql://user:password@server/schema');
 $repository = new \ByJG\MicroOrm\Repository($dbDriver, MyModel::class);
 ```
 
@@ -153,6 +173,11 @@ $result = $repository->getByQuery($query);
 * [Querying the Database](docs/querying-the-database.md)
 * [Updating the database](docs/updating-the-database.md)
 * [Using the Mapper Object](docs/using-mapper-object.md)
+* [The Model Attributes](docs/model-attribute.md)
+* [The Repository Class](docs/repository.md)
+* [Common Traits for Timestamp Fields](docs/common-traits.md)
+* [Architecture Layers: Infrastructure vs Domain](docs/architecture-layers.md)
+* [Comparison with Other ORMs (Eloquent, Doctrine)](docs/comparison-with-other-orms.md)
 
 ## Advanced Topics
 
@@ -163,10 +188,14 @@ $result = $repository->getByQuery($query);
 * [Caching the Results](docs/cache.md)
 * [Observing the Database](docs/observers.md)
 * [Controlling the data queried/updated](docs/controlling-the-data.md)
+* [Mapper Functions](docs/mapper-functions.md)
 * [Using FieldAlias](docs/using-fieldalias.md)
 * [Tables without auto increments fields](docs/tables-without-auto-increment-fields.md)
 * [Using With Recursive SQL Command](docs/using-with-recursive-sql-command.md)
 * [QueryRaw (raw SQL)](docs/query-raw.md)
+* [Update Constraints](docs/update-constraints.md)
+* [Building SQL Queries](docs/query-build.md)
+* [UUID Support](docs/uuid-support.md)
 
 ## Install
 
@@ -199,4 +228,4 @@ flowchart TD
 ```
 
 ----
-[Open source ByJG](http://opensource.byjg.com)
+[Open source ByJG](http://opensource.byjg.com)

composer.json

@@ -14,15 +14,15 @@
   "prefer-stable": true,
   "minimum-stability": "dev",
   "require": {
-    "php": ">=8.1 <8.4",
+    "php": ">=8.1 <8.5",
     "ext-json": "*",
     "ext-pdo": "*",
-    "byjg/anydataset-db": "^5.0"
+    "byjg/anydataset-db": "^6.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "^9.6",
-    "byjg/cache-engine": "^5.0",
-    "vimeo/psalm": "^5.9"
+    "phpunit/phpunit": "^10.5|^11.5",
+    "byjg/cache-engine": "^6.0",
+    "vimeo/psalm": "^5.9|^6.2"
   },
   "suggest": {
     "ext-curl": "*",