Merge pull request #25 from byjg/6.0

# Micro ORM 6.0 - Major Release

Author: byjg

.github/workflows/phpunit.yml

@@ -12,13 +12,15 @@ on:
 jobs:
   Build:
     runs-on: 'ubuntu-latest'
-    container: 'byjg/php:${{ matrix.php-version }}-cli'
+    container:
+      image: 'byjg/php:${{ matrix.php-version }}-cli'
+      options: --user root --privileged
     strategy:
       matrix:
         php-version:
+          - "8.5"
+          - "8.4"
           - "8.3"
-          - "8.2"
-          - "8.1"
 
     services:
       mysql:
@@ -38,10 +40,39 @@ jobs:
       MYSQL_TEST_HOST: mysql
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - run: composer install
-      - run: ./vendor/bin/phpunit
-      - run: ./vendor/bin/psalm
+      - run: composer test
+
+  Psalm:
+    name: Psalm Static Analyzer
+    runs-on: ubuntu-latest
+    permissions:
+      # for github/codeql-action/upload-sarif to upload SARIF results
+      security-events: write
+    container:
+      image: byjg/php:8.4-cli
+      options: --user root --privileged
+
+    steps:
+      - name: Git checkout
+        uses: actions/checkout@v4
+
+      - name: Composer
+        run: composer install
+
+      - name: Psalm
+        # Note: Ignoring error code 2, which just signals that some
+        # flaws were found, not that Psalm itself failed to run.
+        run: ./vendor/bin/psalm
+          --show-info=true
+          --report=psalm-results.sarif || [ $? = 2 ]
+
+      - name: Upload Analysis results to GitHub
+        uses: github/codeql-action/upload-sarif@v4
+        if: github.ref == 'refs/heads/master'
+        with:
+          sarif_file: psalm-results.sarif
 
   Documentation:
     if: github.ref == 'refs/heads/master'
@@ -50,5 +81,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 

.idea/runConfigurations/psalm.xml

@@ -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}"
+      }
+    }
+  ]
+} 

.vscode/launch.json

@@ -1,5 +1,6 @@
 # MicroOrm for PHP
 
+[![Sponsor](https://img.shields.io/badge/Sponsor-%23ea4aaa?logo=githubsponsors&logoColor=white&labelColor=0d1117)](https://github.com/sponsors/byjg)
 [![Build Status](https://github.com/byjg/php-micro-orm/actions/workflows/phpunit.yml/badge.svg?branch=master)](https://github.com/byjg/php-micro-orm/actions/workflows/phpunit.yml)
 [![Opensource ByJG](https://img.shields.io/badge/opensource-byjg-success.svg)](http://opensource.byjg.com)
 [![GitHub source](https://img.shields.io/badge/Github-source-informational?logo=github)](https://github.com/byjg/php-micro-orm/)
@@ -14,10 +15,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 +47,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 +110,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 +133,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 +174,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 +189,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 +229,4 @@ flowchart TD
 ```
 
 ----
-[Open source ByJG](http://opensource.byjg.com)
+[Open source ByJG](http://opensource.byjg.com)

README.md

@@ -1,6 +1,6 @@
 {
   "name": "byjg/micro-orm",
-  "description": "A micro framework for create a very simple decoupled ORM (sqlite, mysql, postgres, sqlserver)",
+  "description": "A micro framework for create a very simple decoupled ORM. This library intended to be very small and very simple to use",
   "autoload": {
     "psr-4": {
       "ByJG\\MicroOrm\\": "src/"
@@ -14,19 +14,23 @@
   "prefer-stable": true,
   "minimum-stability": "dev",
   "require": {
-    "php": ">=8.1 <8.4",
+    "php": ">=8.3 <8.6",
     "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.13"
   },
   "suggest": {
     "ext-curl": "*",
     "ext-pdo_mysql": "*"
   },
+  "scripts": {
+    "test": "vendor/bin/phpunit",
+    "psalm": "vendor/bin/psalm --threads=1"
+  },
   "license": "MIT"
 }