fix: critical Db::concat() bugs and improve test organization

Fixed 2 critical bugs in Db::concat() helper:
- Bug #1: ConcatValue not initializing parent RawValue
- Bug #2: String literals not auto-quoted

Changes:
- src/helpers/ConcatValue.php: Added parent::__construct(''), protective getValue()
- src/dialects/DialectAbstract.php: Enhanced concat() string literal detection
- tests/SharedCoverageTest.php: Added setUp() for auto-cleanup, 8 new concat tests
- examples/: Updated 14 files to use Db helpers over Db::raw()

Tests: 334 total (+17), 1499 assertions (+35), all passing ✅
Coverage: 90%+ (improved from 83%)

Author: tommyknocker

CHANGELOG.md

@@ -22,13 +22,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `Db::jsonGet()`, `Db::jsonLength()`, `Db::jsonKeys()`, `Db::jsonType()`
   - Unified API across MySQL, PostgreSQL, and SQLite
   - Edge-case testing for JSON operations
-- **Comprehensive examples directory** (`examples/`) with 18 runnable examples:
+- **Comprehensive examples directory** (`examples/`) with 21 runnable examples:
   - Basic operations (connection, CRUD, WHERE conditions)
   - Intermediate patterns (JOINs, aggregations, pagination, transactions)
   - Advanced features (connection pooling, bulk operations, UPSERT)
   - JSON operations (complete guide with real-world usage)
   - Helper functions (string, math, date/time, NULL handling)
-  - Real-world applications (blog system with posts, comments, tags)
+  - Real-world applications:
+    - Blog system with posts, comments, tags, analytics
+    - User authentication with sessions, RBAC, password hashing
+    - Advanced search & filters with facets, sorting, pagination
+    - Multi-tenant SaaS with resource tracking and quota management
 - **Dialect coverage tests** for better test coverage (300 total tests):
   - `buildLoadCsvSql()` - CSV loading SQL generation with temp file handling
   - `buildLoadXML()` - XML loading SQL generation with temp file handling
@@ -55,6 +59,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Improved error messages**: Property hooks now provide clearer guidance for uninitialized connections
 - **Updated .gitignore**: Cleaned up and added examples-related ignores, coverage reports
 - **README.md improvements**: Removed `ALL_TESTS=1` requirement - tests now run without environment variables
+- **Enhanced examples** (14 files updated): Maximized use of `Db::` helpers over `Db::raw()` for better code clarity:
+  - Replaced 30+ raw SQL expressions with helper functions
+  - `Db::inc()`/`Db::dec()` for increments/decrements
+  - `Db::count()`, `Db::sum()`, `Db::avg()`, `Db::coalesce()` for aggregations
+  - `Db::case()` for conditional logic
+  - `Db::concat()` with automatic string literal quoting
+- **Improved test organization**: Added `setUp()` method in `SharedCoverageTest` for automatic table cleanup before each test
+  - Removed 26+ redundant cleanup statements
+  - Better test isolation and reliability
 
 ### Removed
 - **Deprecated helper methods from PdoDb** (~130 lines removed):
@@ -69,6 +82,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `buildInsertMultiSql()` now correctly uses first column when `id` not present (matches `insert()` behavior)
   - Enables proper bulk UPSERT operations across all dialects
   - Without this fix, bulk inserts with `onDuplicate` parameter would fail on PostgreSQL/SQLite
+- **CRITICAL: Db::concat() helper bugs** (2 major issues fixed):
+  - **Bug #1**: `ConcatValue` not initializing parent `RawValue` class causing "Typed property not initialized" error
+    - Added `parent::__construct('')` call in `ConcatValue` constructor
+    - Added protective `getValue()` override with clear error message to prevent misuse
+  - **Bug #2**: String literals (spaces, special chars) not auto-quoted, treated as column names
+    - Enhanced `DialectAbstract::concat()` logic to auto-detect and quote string literals
+    - Supports spaces, colons, pipes, dashes, emoji, and unicode characters
+    - Examples: `Db::concat('first_name', ' ', 'last_name')` now works without `Db::raw()`
+  - Added 8 comprehensive edge-case tests in `SharedCoverageTest`:
+    - `testConcatWithStringLiterals()` - spaces and simple literals
+    - `testConcatWithSpecialCharacters()` - colon, pipe, dash
+    - `testConcatWithNestedHelpers()` - `Db::upper/lower` inside concat
+    - `testConcatNestedInHelperThrowsException()` - protection from incorrect usage
+    - `testConcatWithQuotedLiterals()` - already-quoted strings
+    - `testConcatWithNumericValues()` - number handling
+    - `testConcatWithEmptyString()` - empty string edge case
+    - `testConcatWithMixedTypes()` - mixed type concatenation
 - Restored `RawValue` union type support in `rawQuery()`, `rawQueryOne()`, `rawQueryValue()` methods
 - Corrected method calls in `lock()`, `unlock()`, `loadData()`, `loadXml()` to use `prepare()->execute()` pattern
 - SQLite JSON support fixes for edge cases (array indexing, value encoding, numeric sorting)
@@ -78,8 +108,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **PostgreSQL formatSelectOptions test**: Fixed to test actual supported features (FOR UPDATE/FOR SHARE)
 
 ### Technical Details
-- **All tests passing**: 317 tests, 1464 assertions across MySQL, PostgreSQL, and SQLite (3 skipped for live testing)
-- **Test coverage**: 83%+ with comprehensive dialect-specific and edge-case testing
+- **All tests passing**: 334 tests, 1499 assertions across MySQL, PostgreSQL, and SQLite (3 skipped for live testing)
+  - **68 tests** in SharedCoverageTest (dialect-independent code)
+  - **8 new edge-case tests** for `Db::concat()` bug fixes
+  - Added `setUp()` method for automatic table cleanup before each test
+- **Test coverage**: 90%+ with comprehensive dialect-specific and edge-case testing
 - **Full backward compatibility maintained**: Zero breaking changes (deprecated methods removal is non-breaking)
 - Examples tested and verified on PHP 8.4.13
 - **Performance**: Optimized QueryBuilder reduces code duplication and improves maintainability

README.md

@@ -93,6 +93,9 @@ composer require tommyknocker/pdo-database-class
 For specific versions:
 
 ```bash
+# Latest 2.x version
+composer require tommyknocker/pdo-database-class:^2.0
+
 # Latest 1.x version
 composer require tommyknocker/pdo-database-class:^1.0
 

examples/01-basic/04-insert-update.php

@@ -107,7 +107,7 @@
     ->table('counters')
     ->where('name', 'page_views')
     ->update([
-        'value' => Db::raw('value + 50'),
+        'value' => Db::inc(50),
         'name' => Db::raw('name || "_total"'),
         'updated_at' => Db::now()
     ]);

examples/02-intermediate/01-joins.php

@@ -83,8 +83,8 @@
     ->leftJoin('reviews AS r', 'r.user_id = u.id')
     ->select([
         'u.name',
-        'order_count' => Db::raw('COUNT(DISTINCT o.id)'),
-        'review_count' => Db::raw('COUNT(DISTINCT r.id)')
+        'order_count' => Db::count('DISTINCT o.id'),
+        'review_count' => Db::count('DISTINCT r.id')
     ])
     ->groupBy('u.id')
     ->get();
@@ -102,10 +102,10 @@
     ->leftJoin('orders AS o', 'o.user_id = u.id')
     ->select([
         'u.name',
-        'total_spent' => Db::raw('COALESCE(SUM(o.amount), 0)')
+        'total_spent' => Db::coalesce(Db::sum('o.amount'), '0')
     ])
     ->groupBy('u.id')
-    ->orderBy(Db::raw('total_spent'), 'DESC')
+    ->orderBy('total_spent', 'DESC')
     ->get();
 
 echo "  User spending:\n";
@@ -122,12 +122,12 @@
     ->select([
         'u.name',
         'u.city',
-        'order_count' => Db::raw('COUNT(*)'),
-        'total' => Db::raw('SUM(o.amount)')
+        'order_count' => Db::count(),
+        'total' => Db::sum('o.amount')
     ])
     ->where('u.city', 'NYC')
     ->groupBy('u.id')
-    ->having(Db::raw('SUM(o.amount)'), 500, '>')
+    ->having(Db::sum('o.amount'), 500, '>')
     ->get();
 
 echo "  High-value NYC customers:\n";

examples/02-intermediate/04-transactions.php

@@ -35,13 +35,13 @@
     $db->find()
         ->table('accounts')
         ->where('name', 'Alice')
-        ->update(['balance' => Db::raw('balance - 200')]);
+        ->update(['balance' => Db::dec(200)]);
 
     // Add to Bob
     $db->find()
         ->table('accounts')
         ->where('name', 'Bob')
-        ->update(['balance' => Db::raw('balance + 200')]);
+        ->update(['balance' => Db::inc(200)]);
 
     // Record transaction
     $db->find()->table('transactions')->insert([
@@ -82,7 +82,7 @@
     $db->find()
         ->table('accounts')
         ->where('name', 'Bob')
-        ->update(['balance' => Db::raw('balance - 2000')]);
+        ->update(['balance' => Db::dec(2000)]);
 
     $db->commit();
 
@@ -110,13 +110,13 @@
         $db->find()
             ->table('accounts')
             ->where('name', $transfer['from'])
-            ->update(['balance' => Db::raw("balance - {$transfer['amount']}")]);
+            ->update(['balance' => Db::dec($transfer['amount'])]);
 
         // Add
         $db->find()
             ->table('accounts')
             ->where('name', $transfer['to'])
-            ->update(['balance' => Db::raw("balance + {$transfer['amount']}")]);
+            ->update(['balance' => Db::inc($transfer['amount'])]);
 
         // Log
         $fromId = $db->find()->from('accounts')->where('name', $transfer['from'])->getValue('id');

examples/03-advanced/01-connection-pooling.php

@@ -113,7 +113,7 @@
     ->from('events')
     ->select([
         'user_id',
-        'event_count' => Db::raw('COUNT(*)')
+        'event_count' => Db::count()
     ])
     ->groupBy('user_id')
     ->get();

examples/03-advanced/02-bulk-operations.php

@@ -119,7 +119,7 @@
 $affected = $db->find()
     ->table('users')
     ->where('age', 50, '>=')
-    ->update(['age' => Db::raw('age - 10')]);
+    ->update(['age' => Db::dec(10)]);
 
 $elapsed = round((microtime(true) - $start) * 1000, 2);
 echo "✓ Updated $affected rows in {$elapsed}ms\n\n";

examples/05-helpers/01-string-helpers.php

@@ -31,7 +31,7 @@
     ->from('users')
     ->select([
         'id',
-        'full_name' => Db::concat(Db::upper('first_name'), Db::raw("' '"), Db::upper('last_name'))
+        'full_name' => Db::concat(Db::upper('first_name'), ' ', Db::upper('last_name'))
     ])
     ->get();
 

examples/05-helpers/02-math-helpers.php

@@ -71,7 +71,7 @@
     ->select([
         'name',
         'reading',
-        'remainder' => Db::mod('reading', Db::raw('2'))
+        'remainder' => Db::mod('reading', '2')
     ])
     ->get();
 

examples/05-helpers/03-date-helpers.php

@@ -127,7 +127,7 @@
     ->from('events')
     ->select([
         'month' => Db::month('event_date'),
-        'event_count' => Db::raw('COUNT(*)')
+        'event_count' => Db::count()
     ])
     ->groupBy(Db::month('event_date'))
     ->orderBy(Db::month('event_date'))