Database Modernization (insertOrIgnore, Upsert, Interfaces, PDO Db Capabilities [centralization], unit tests)

.github/workflows/prado.yml

@@ -38,7 +38,7 @@ jobs:
         uses: shivammathur/setup-php@v2 #https://github.com/shivammathur/setup-php
         with:
           php-version: ${{ matrix.php-versions }}
-          extensions: ctype, dom, intl, json, mbstring, memcached, pdo_mysql, pdo_pgsql, pdo_sqlite, openssl, pcre, spl, zlib
+          extensions: ctype, dom, intl, json, mbstring, memcached, pdo_mysql, pdo_pgsql, pdo_sqlite, openssl, pcre, spl, zlib, :pdo_firebird, :pdo_sqlsrv
           tools: php-cs-fixer, phpstan, cs2pr
 
       - name: Validate composer.json and composer.lock
@@ -306,10 +306,130 @@ jobs:
           & "$env:PGBIN\pg_ctl.exe" start -D $env:PGDATA -w
           & "$env:PGBIN\createdb.exe" -h 127.0.0.1 -U postgres prado_unitest
           & "$env:PGBIN\psql.exe" -h 127.0.0.1 -U postgres prado_unitest -f .\tests\initdb_pgsql.sql
+          # Windows PostgreSQL uses scram-sha-256 (no trust); set the password so
+          # setupPgsqlConnection('prado_unitest', 'prado_unitest') can authenticate.
+          & "$env:PGBIN\psql.exe" -h 127.0.0.1 -U postgres -c "ALTER ROLE prado_unitest WITH PASSWORD 'prado_unitest';"
 
       - name: Run Unit Tests
         run: composer unittest
 
+  db-mysql:
+    name: Prado Data (MySQL)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP with MySQL extensions
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          extensions: ctype, dom, intl, json, mbstring, pdo_mysql, openssl, pcre, spl, zlib
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Install Composer dependencies
+        run: composer install --no-progress --prefer-dist --optimize-autoloader
+
+      - name: Setup MySQL schema
+        run: |
+          sudo systemctl start mysql.service
+          mysql -uroot -proot < ./tests/initdb_mysql.sql
+
+      - name: Run MySQL tests
+        run: php vendor/bin/phpunit --testsuite db-mysql
+
+  db-pgsql:
+    name: Prado Data (PostgreSQL)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres
+        env:
+          POSTGRES_DB: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_HOST_AUTH_METHOD: trust
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP with PostgreSQL extensions
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          extensions: ctype, dom, intl, json, mbstring, pdo_pgsql, openssl, pcre, spl, zlib
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Install Composer dependencies
+        run: composer install --no-progress --prefer-dist --optimize-autoloader
+
+      - name: Setup PostgreSQL schema
+        run: |
+          createdb -h 127.0.0.1 -U postgres prado_unitest
+          psql -h 127.0.0.1 -U postgres -a -w prado_unitest -f ./tests/initdb_pgsql.sql
+        env:
+          PGPASSWORD: postgres
+
+      - name: Run PostgreSQL tests
+        run: php vendor/bin/phpunit --testsuite db-pgsql
+
+  db-sqlite:
+    name: Prado Data (SQLite)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP with SQLite extensions
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          extensions: ctype, dom, intl, json, mbstring, pdo_sqlite, openssl, pcre, spl, zlib
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Install Composer dependencies
+        run: composer install --no-progress --prefer-dist --optimize-autoloader
+
+      - name: Run SQLite tests
+        run: php vendor/bin/phpunit --testsuite db-sqlite
+
   db-sqlsrv:
     name: Prado Data (Microsoft SQL Server)
     runs-on: ubuntu-latest
@@ -361,10 +481,10 @@ jobs:
         run: >-
           /opt/mssql-tools18/bin/sqlcmd -C
           -U sa -P Prado_Unitest1
-          -i ./tests/initdb_mssql.sql
+          -i ./tests/initdb_sqlsrv.sql
 
       - name: Run SQL Server tests
-        run: php vendor/bin/phpunit tests/unit/Data/DbSpecific/Mssql/
+        run: php vendor/bin/phpunit --testsuite db-sqlsrv
 
   db-firebird:
     name: Prado Data (Firebird)
@@ -425,7 +545,7 @@ jobs:
           "
 
       - name: Run Firebird tests
-        run: php vendor/bin/phpunit tests/unit/Data/DbSpecific/Firebird/
+        run: php vendor/bin/phpunit --testsuite db-firebird
 
   db-oracle:
     name: Prado Data (Oracle)
@@ -498,14 +618,12 @@ jobs:
             bash -c 'source ~/.bash_profile && sqlplus -S prado_unitest/prado_unitest@//localhost/FREEPDB1 @/tmp/initdb_oracle.sql'
 
       - name: Run Oracle tests
-        run: php vendor/bin/phpunit tests/unit/Data/DbSpecific/Oracle/
+        run: php vendor/bin/phpunit --testsuite db-oracle
         env:
           ORACLE_SERVICE_NAME: FREEPDB1
 
   db-ibm:
     name: Prado Data (IBM DB2)
-    # DB2 image takes 2-3 minutes to start; only run on explicit manual dispatch.
-    # if: github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     services:
       db2:
@@ -554,7 +672,7 @@ jobs:
             su - db2inst1 -c "db2 connect to pradount && db2 -td@ -f /tmp/initdb.sql"
 
       - name: Run IBM DB2 tests
-        run: php vendor/bin/phpunit tests/unit/Data/DbSpecific/Ibm/
+        run: php vendor/bin/phpunit --testsuite db-ibm
         env:
           DB2_USER: db2inst1
           DB2_PASSWORD: Prado_Unitest1

composer.json

@@ -103,11 +103,13 @@
 			"npm run playwright:install",
 			"@setup-demos"
 		],
+		"dbinit": "php tests/test_tools/initdb.php",
 		"setup-demos": "bash tests/setup-demos.sh",
         "gendoc": "phpdoc --template=./vendor/pradosoft/prado-phpdoc-template",
 		"fix": "vendor/bin/php-cs-fixer fix",
 		"stan": "vendor/bin/phpstan analyse --memory-limit=512M",
-        "unittest": "vendor/bin/phpunit --testsuite unit",
+        "unittest": "vendor/bin/phpunit --testsuite unit,db-mysql,db-pgsql,db-sqlite",
+		"dbtest": "vendor/bin/phpunit --testsuite db-mysql,db-pgsql,db-sqlite",
 		"fulltest": [
 			"@fix",
 			"@stan",

framework/Caching/TDbCache.php

@@ -14,6 +14,7 @@
 use Prado\Data\TDataSourceConfig;
 use Prado\Data\TDbConnection;
 use Prado\Data\TDbDriver;
+use Prado\Data\TDbDriverCapabilities;
 use Prado\Data\TDbPropertiesTrait;
 use Prado\Exceptions\TConfigurationException;
 use Prado\TPropertyValue;
@@ -130,8 +131,11 @@ class TDbCache extends TCache implements \Prado\Util\IDbModule
 	 */
 	public function init($config)
 	{
-		$this->getApplication()->attachEventHandler('OnLoadStateComplete', [$this, 'doInitializeCache']);
-		$this->getApplication()->attachEventHandler('OnSaveState', [$this, 'doFlushCacheExpired']);
+		$app = $this->getApplication();
+		if ($app) {
+			$app->attachEventHandler('OnLoadStateComplete', [$this, 'doInitializeCache']);
+			$app->attachEventHandler('OnSaveState', [$this, 'doFlushCacheExpired']);
+		}
 		parent::init($config);
 	}
 
@@ -194,7 +198,7 @@ protected function initializeCache($force = false)
 			if ($this->_autoCreate) {
 				Prado::trace('Autocreate: ' . $this->_cacheTable, TDbCache::class);
 
-				$driver = $db->getDriverName();
+				$driver = TDbDriverCapabilities::normalizeDriver($db->getDriverName());
 				if ($driver === TDbDriver::DRIVER_MYSQL) {
 					$blob = 'LONGBLOB';
 				} elseif ($driver === TDbDriver::DRIVER_PGSQL) {
@@ -456,10 +460,10 @@ protected function setValue($key, $value, $expire)
 			$this->initializeCache();
 		}
 		$db = $this->getDbConnection();
-		$driver = $db->getDriverName();
-		if (in_array($driver, [TDbDriver::DRIVER_MYSQL, TDbDriver::EXTENSION_MYSQLI, TDbDriver::DRIVER_SQLITE, TDbDriver::DRIVER_IBM, TDbDriver::DRIVER_OCI, TDbDriver::DRIVER_SQLSRV, TDbDriver::EXTENSION_MSSQL, TDbDriver::DRIVER_DBLIB, TDbDriver::DRIVER_PGSQL])) {
+		$driver = TDbDriverCapabilities::normalizeDriver($db->getDriverName());
+		if (in_array($driver, [TDbDriver::DRIVER_MYSQL, TDbDriver::DRIVER_SQLITE, TDbDriver::DRIVER_IBM, TDbDriver::DRIVER_OCI, TDbDriver::DRIVER_SQLSRV, TDbDriver::DRIVER_DBLIB, TDbDriver::DRIVER_PGSQL])) {
 			$expire = ($expire <= 0) ? 0 : time() + $expire;
-			if (in_array($driver, [TDbDriver::DRIVER_MYSQL, TDbDriver::EXTENSION_MYSQLI, TDbDriver::DRIVER_SQLITE])) {
+			if (in_array($driver, [TDbDriver::DRIVER_MYSQL, TDbDriver::DRIVER_SQLITE])) {
 				$sql = "REPLACE INTO {$this->_cacheTable} (itemkey,value,expire) VALUES (:key,:value,$expire)";
 			} elseif ($driver === TDbDriver::DRIVER_PGSQL) {
 				$sql = "INSERT INTO {$this->_cacheTable} (itemkey, value, expire) VALUES (:key, :value, :expire) " .

framework/Data/ActiveRecord/Exceptions/TActiveRecordConfigurationException.php

@@ -11,7 +11,7 @@
 namespace Prado\Data\ActiveRecord\Exceptions;
 
 /**
- * TActiveRecordConfigurationException class.
+ * TActiveRecordConfigurationException class
  *
  * @author Wei Zhuo <weizho[at]gmail[dot]com>
  * @since 3.1

framework/Data/ActiveRecord/Exceptions/TActiveRecordException.php

@@ -14,6 +14,8 @@
 use Prado\Prado;
 
 /**
+ * TActiveRecordException class
+ *
  * Base exception class for Active Records.
  *
  * @author Wei Zhuo <weizho[at]gmail[dot]com>

framework/Data/ActiveRecord/Exceptions/messages.txt

@@ -24,3 +24,6 @@ ar_relations_undefined						= Unable to determine Active Record relationships be
 ar_undefined_relation_prop					= Unable to find {1}::${2}['{0}'], Active Record relationship definition for property "{0}" not found in entries of {1}::${2}.
 ar_invalid_relationship						= Invalid active record relationship.
 ar_relations_missing_fk						= Unable to find foreign key relationships in table '{0}' that corresponds to table '{1}'.
+ar_belongs_to_multiple_result				= BelongsTo/HasOne relationship returned more than one result but exactly one was expected.
+scaffold_unable_to_find_edit_view			= Unable to find scaffold edit view control with ID '{0}'.
+scaffold_unable_to_find_list_view			= Unable to find scaffold list view control with ID '{0}'.

framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php

@@ -16,6 +16,8 @@
 use Prado\Data\ActiveRecord\Exceptions\TActiveRecordException;
 
 /**
+ * TActiveRecordBelongsTo class
+ *
  * Implements the foreign key relationship (TActiveRecord::BELONGS_TO) between
  * the source objects and the related foreign object. Consider the
  * <b>entity</b> relationship between a Team and a Player.

framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php

@@ -11,6 +11,8 @@
 namespace Prado\Data\ActiveRecord\Relations;
 
 /**
+ * TActiveRecordHasMany class
+ *
  * Implements TActiveRecord::HAS_MANY relationship between the source object having zero or
  * more foreign objects. Consider the <b>entity</b> relationship between a Team and a Player.
  * ```php

framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php

@@ -17,6 +17,8 @@
 use Prado\Prado;
 
 /**
+ * TActiveRecordHasManyAssociation class
+ *
  * Implements the M-N (many to many) relationship via association table.
  * Consider the <b>entity</b> relationship between Articles and Categories
  * via the association table <tt>Article_Category</tt>.

framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php

@@ -17,6 +17,8 @@
 use Prado\Prado;
 
 /**
+ * TActiveRecordHasOne class
+ *
  * TActiveRecordHasOne models the object relationship that a record (the source object)
  * property is an instance of foreign record object having a foreign key
  * related to the source object. The HAS_ONE relation is very similar to the

framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php

@@ -18,7 +18,67 @@
 use Prado\Prado;
 
 /**
- * Base class for active record relationships.
+ * TActiveRecordRelation class
+ *
+ * Abstract base class for all Active Record relationship handlers.
+ *
+ * Active Record relationships are declared via the static `$RELATIONS` array on
+ * each {@see TActiveRecord} subclass. Each entry maps a property name to an
+ * array whose first element is one of the four relationship constants and whose
+ * second element is the foreign record class name:
+ *
+ * ```php
+ * public static $RELATIONS = [
+ *     'profile'    => [self::HAS_ONE,              'ProfileRecord'],
+ *     'orders'     => [self::HAS_MANY,             'OrderRecord'],
+ *     'team'       => [self::BELONGS_TO,           'TeamRecord'],
+ *     'categories' => [self::HAS_MANY_ASSOC,       'CategoryRecord', 'Article_Category'],
+ * ];
+ * ```
+ *
+ * The four relationship types are:
+ *
+ * - **HAS_ONE** ({@see TActiveRecordHasOne}) — the foreign table carries a foreign key
+ *   that points back to this record's primary key. The related property is a single
+ *   object (or `null`).
+ * - **HAS_MANY** ({@see TActiveRecordHasMany}) — same foreign-key direction as HAS_ONE,
+ *   but the related property is a collection (array) of foreign objects.
+ * - **BELONGS_TO** ({@see TActiveRecordBelongsTo}) — this record's table carries the
+ *   foreign key that points to the related record's primary key. The related
+ *   property is a single object (or `null`).
+ * - **HAS_MANY_ASSOC** ({@see TActiveRecordHasManyAssociation}) — a many-to-many
+ *   relationship resolved through an intermediate association table. A third
+ *   element in the `$RELATIONS` entry names the association table.
+ *
+ * ## Fetching related objects
+ *
+ * Related objects are fetched lazily by chaining a relationship call onto a
+ * finder method call:
+ *
+ * ```php
+ * // Fetch all teams with their players eagerly loaded.
+ * $teams = TeamRecord::finder()->withPlayers()->findAll();
+ *
+ * // Chain multiple relationships.
+ * $articles = ArticleRecord::finder()->withCategories()->withAuthor()->findAll();
+ * ```
+ *
+ * The {@see __call()} method intercepts `with<Property>()` calls, delegates the
+ * underlying finder call to the source record, then calls
+ * {@see collectForeignObjects()} to populate each result's relationship property.
+ * Multiple chained `with*()` calls are queued via a static stack so that all
+ * relationships are applied to the same result set.
+ *
+ * ## Implementing a new relationship type
+ *
+ * Subclasses must implement:
+ * - {@see collectForeignObjects()} — given the source results, fetch and assign
+ *   the corresponding foreign objects to each source record's relationship
+ *   property.
+ * - {@see getRelationForeignKeys()} — return the foreign key mapping (FK field
+ *   names as keys, source property names as values) used by this relationship.
+ * - {@see updateAssociatedRecords()} — persist any changes to the associated
+ *   foreign objects (e.g. insert/delete rows in an association table).
  *
  * @author Wei Zhuo <weizho[at]gmail[dot]com>
  * @since 3.1

framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php

@@ -17,6 +17,8 @@
 use Prado\Prado;
 
 /**
+ * TActiveRecordRelationContext class
+ *
  * TActiveRecordRelationContext holds information regarding record relationships
  * such as record relation property name, query criteria and foreign object record
  * class names.