feat: add automatic REGEXP functions registration for SQLite

- Add registerRegexpFunctions() method to SqliteDialect
- Automatically register REGEXP, regexp_replace, and regexp_extract functions using PHP preg_* functions
- Add enable_regexp configuration option (default: true) to allow disabling automatic registration
- Update SQLite HelpersTests to remove manual REGEXP availability check
- Update documentation with enable_regexp option and automatic registration information

This eliminates the need for external REGEXP extensions in SQLite by using PHP's built-in regex functions.

Author: tommyknocker

README.md

@@ -47,7 +47,7 @@ Built on top of PDO with **zero external dependencies**, it offers:
 - **Enhanced Error Diagnostics** - Query context, sanitized parameters, and debug information in exceptions
 - **Connection Retry** - Automatic retry with exponential backoff
 - **PSR-14 Event Dispatcher** - Event-driven architecture for monitoring, auditing, and middleware
-- **80+ Helper Functions** - SQL helpers for strings, dates, math, JSON, aggregations, and more (REPEAT, REVERSE, LPAD, RPAD emulated for SQLite)
+- **80+ Helper Functions** - SQL helpers for strings, dates, math, JSON, aggregations, and more (REPEAT, REVERSE, LPAD, RPAD emulated for SQLite; REGEXP operations supported across all dialects)
 - **Fully Tested** - 1320 tests, 5249 assertions across all dialects
 - **Type-Safe** - PHPStan level 8 validated, PSR-12 compliant
 

documentation/01-getting-started/configuration.md

@@ -177,12 +177,14 @@ $db = new PdoDb('sqlite', [
 ```php
 $db = new PdoDb('sqlite', [
     // Connection options
-    'pdo'   => null,                       // Optional: Existing PDO object
-    'path'  => '/path/to/database.sqlite', // Required: Path to SQLite file
-                                           // Use ':memory:' for in-memory database
-    'prefix'=> 'sq_',                      // Optional: Table prefix
-    'mode'  => 'rwc',                      // Optional: Open mode (ro, rw, rwc, memory)
-    'cache' => 'shared'                    // Optional: Cache mode (shared, private)
+    'pdo'         => null,                       // Optional: Existing PDO object
+    'path'        => '/path/to/database.sqlite', // Required: Path to SQLite file
+                                                 // Use ':memory:' for in-memory database
+    'prefix'      => 'sq_',                      // Optional: Table prefix
+    'mode'        => 'rwc',                      // Optional: Open mode (ro, rw, rwc, memory)
+    'cache'       => 'shared',                   // Optional: Cache mode (shared, private)
+    'enable_regexp' => true                     // Optional: Enable REGEXP functions (default: true)
+                                                 // Automatically registers REGEXP, regexp_replace, regexp_extract
 ]);
 ```
 

documentation/07-helper-functions/string-helpers.md

@@ -264,6 +264,212 @@ $users = $db->find()
     ->get();
 ```
 
+## Db::regexpMatch() - Pattern Matching
+
+Check if a string matches a regular expression pattern:
+
+```php
+// Find valid email addresses
+$users = $db->find()
+    ->from('users')
+    ->where(Db::regexpMatch('email', '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'))
+    ->get();
+
+// MySQL/MariaDB: (email REGEXP '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$')
+// PostgreSQL: (email ~ '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$')
+// SQLite: (email REGEXP '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$')
+//         REGEXP functions are automatically registered by PDOdb (can be disabled via enable_regexp config)
+```
+
+### Using in WHERE Clause
+
+```php
+// Find users with phone numbers containing dashes
+$users = $db->find()
+    ->from('users')
+    ->where(Db::regexpMatch('phone', '-'))
+    ->get();
+
+// With negation
+$users = $db->find()
+    ->from('users')
+    ->where(Db::not(Db::regexpMatch('email', '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$')))
+    ->get();
+```
+
+## Db::regexpReplace() - Pattern-Based Replacement
+
+Replace all occurrences of a pattern with a replacement string:
+
+```php
+// Replace dashes with spaces in phone numbers
+$users = $db->find()
+    ->from('users')
+    ->select([
+        'phone',
+        'formatted' => Db::regexpReplace('phone', '-', ' ')
+    ])
+    ->get();
+
+// MySQL/MariaDB: REGEXP_REPLACE(phone, '-', ' ')
+// PostgreSQL: regexp_replace(phone, '-', ' ', 'g')
+// SQLite: regexp_replace(phone, '-', ' ')
+//         REGEXP functions are automatically registered by PDOdb
+```
+
+### Multiple Replacements
+
+```php
+// Remove all non-alphanumeric characters
+$users = $db->find()
+    ->from('users')
+    ->select([
+        'name',
+        'clean' => Db::regexpReplace('name', '[^a-zA-Z0-9]', '')
+    ])
+    ->get();
+```
+
+## Db::regexpExtract() - Extract Matched Substrings
+
+Extract matched substring or capture group from a string:
+
+```php
+// Extract domain from email
+$users = $db->find()
+    ->from('users')
+    ->select([
+        'email',
+        'domain' => Db::regexpExtract('email', '@([a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})', 1)
+    ])
+    ->get();
+
+// MySQL/MariaDB: REGEXP_SUBSTR(email, '@([a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})', 1, 1, NULL, 1)
+// PostgreSQL: (regexp_match(email, '@([a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})'))[2]
+// SQLite: regexp_extract(email, '@([a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})', 1)
+//         REGEXP functions are automatically registered by PDOdb
+```
+
+### Extract Full Match
+
+```php
+// Extract username from email (full match)
+$users = $db->find()
+    ->from('users')
+    ->select([
+        'email',
+        'username' => Db::regexpExtract('email', '^([a-zA-Z0-9._%+-]+)@', 1)
+    ])
+    ->get();
+```
+
+### Extract Multiple Groups
+
+```php
+// Extract area code and number from phone
+$users = $db->find()
+    ->from('users')
+    ->select([
+        'phone',
+        'area_code' => Db::regexpExtract('phone', '\\+1-([0-9]{3})', 1),
+        'number' => Db::regexpExtract('phone', '\\+1-[0-9]{3}-([0-9-]+)', 1)
+    ])
+    ->get();
+```
+
+## Dialect Differences
+
+### REGEXP Support
+
+**MySQL/MariaDB:**
+- `REGEXP` operator for matching
+- `REGEXP_REPLACE()` function for replacement
+- `REGEXP_SUBSTR()` function for extraction (MySQL 8.0+, MariaDB 10.0.5+)
+
+**PostgreSQL:**
+- `~` operator for case-sensitive matching (`~*` for case-insensitive)
+- `regexp_replace()` function for replacement
+- `regexp_match()` function returns array, use array indexing for groups
+
+**SQLite:**
+- `REGEXP` operator requires extension to be loaded
+- `regexp_replace()` and `regexp_extract()` functions require REGEXP extension
+- If extension is not available, operations will fail at runtime
+
+### Pattern Syntax
+
+All dialects use POSIX extended regular expressions, but there are some differences:
+
+- **MySQL/MariaDB**: Uses MySQL regex syntax (similar to POSIX)
+- **PostgreSQL**: Uses POSIX extended regex syntax
+- **SQLite**: Uses POSIX extended regex syntax (REGEXP functions are automatically registered by PDOdb)
+
+### Group Indexing
+
+- **MySQL/MariaDB**: Group index starts at 0 (0 = full match, 1+ = capture groups)
+- **PostgreSQL**: Array indexing starts at 1 (1 = first group)
+- **SQLite**: Group index starts at 0 (0 = full match, 1+ = capture groups)
+
+PDOdb handles these differences automatically.
+
+## Best Practices
+
+### 1. Validate Email Addresses
+
+```php
+// ✅ Use regexpMatch for validation
+$validEmails = $db->find()
+    ->from('users')
+    ->where(Db::regexpMatch('email', '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'))
+    ->get();
+```
+
+### 2. Extract Structured Data
+
+```php
+// Extract components from structured strings
+$users = $db->find()
+    ->from('users')
+    ->select([
+        'phone',
+        'country_code' => Db::regexpExtract('phone', '^\\+([0-9]+)', 1),
+        'area_code' => Db::regexpExtract('phone', '\\+[0-9]+-([0-9]+)', 1)
+    ])
+    ->get();
+```
+
+### 3. Normalize Data
+
+```php
+// Normalize phone numbers by removing formatting
+$users = $db->find()
+    ->from('users')
+    ->select([
+        'phone',
+        'normalized' => Db::regexpReplace(
+            Db::regexpReplace('phone', '[^0-9]', ''),
+            '^1',
+            ''
+        )
+    ])
+    ->get();
+```
+
+### 4. SQLite REGEXP Functions
+
+PDOdb automatically registers REGEXP functions (`REGEXP`, `regexp_replace`, `regexp_extract`) for SQLite connections using PHP's `preg_*` functions. This happens automatically when creating a SQLite connection.
+
+To disable automatic REGEXP registration:
+
+```php
+$db = new PdoDb('sqlite', [
+    'path' => '/path/to/database.sqlite',
+    'enable_regexp' => false  // Disable automatic REGEXP registration
+]);
+```
+
+**Note**: If you disable automatic registration, you must manually register REGEXP functions or load a REGEXP extension. The automatic registration uses PHP's `preg_match`, `preg_replace`, and `preg_match` functions, so no external extensions are required.
+
 ## Next Steps
 
 - [Numeric Helpers](numeric-helpers.md) - Math operations

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

@@ -249,6 +249,77 @@
 foreach ($users as $user) {
     echo "  • {$user['email']} → user: {$user['email_user']}, domain: {$user['email_domain']}\n";
 }
+echo "\n";
+
+// Example 14: REGEXP operations
+echo "14. REGEXP operations - Pattern matching and extraction...\n";
+$driver = getCurrentDriver($db);
+
+// Check if REGEXP is supported (SQLite requires extension)
+if ($driver === 'sqlite') {
+    try {
+        $db->rawQuery("SELECT 'test' REGEXP 'test'");
+    } catch (\PDOException $e) {
+        echo "  ⚠ REGEXP extension not available in SQLite, skipping regexp examples\n";
+        echo "\nString helper functions example completed!\n";
+        exit(0);
+    }
+}
+
+// Insert test data with various email formats
+recreateTable($db, 'contacts', ['id' => 'INTEGER PRIMARY KEY AUTOINCREMENT', 'email' => 'TEXT', 'phone' => 'TEXT']);
+$db->find()->table('contacts')->insertMulti([
+    ['email' => 'user@example.com', 'phone' => '+1-555-123-4567'],
+    ['email' => 'admin@test.org', 'phone' => '+44-20-7946-0958'],
+    ['email' => 'invalid-email', 'phone' => '12345'],
+]);
+
+// REGEXP_MATCH - Find valid email addresses
+echo "  a) REGEXP_MATCH - Find valid email addresses:\n";
+$validEmails = $db->find()
+    ->from('contacts')
+    ->select(['email'])
+    ->where(Db::regexpMatch('email', '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'))
+    ->get();
+
+foreach ($validEmails as $contact) {
+    echo "    • {$contact['email']}\n";
+}
+echo "\n";
+
+// REGEXP_REPLACE - Format phone numbers
+echo "  b) REGEXP_REPLACE - Format phone numbers:\n";
+$formattedPhones = $db->find()
+    ->from('contacts')
+    ->select([
+        'phone',
+        'formatted' => Db::regexpReplace('phone', '-', ' ')
+    ])
+    ->where(Db::regexpMatch('phone', '-'))
+    ->get();
+
+foreach ($formattedPhones as $contact) {
+    echo "    • {$contact['phone']} → {$contact['formatted']}\n";
+}
+echo "\n";
+
+// REGEXP_EXTRACT - Extract domain from email
+echo "  c) REGEXP_EXTRACT - Extract domain from email:\n";
+$domains = $db->find()
+    ->from('contacts')
+    ->select([
+        'email',
+        'domain' => Db::regexpExtract('email', '@([a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})', 1)
+    ])
+    ->where(Db::regexpMatch('email', '@'))
+    ->get();
+
+foreach ($domains as $contact) {
+    if ($contact['domain'] !== null) {
+        echo "    • {$contact['email']} → domain: {$contact['domain']}\n";
+    }
+}
+echo "\n";
 
 echo "\nString helper functions example completed!\n";
 

examples/05-helpers/README.md

@@ -20,6 +20,7 @@ String manipulation functions.
 - `replace()` - Replace substring
 - `reverse()` - Reverse string
 - `position()` - Find substring position
+- `regexpMatch()`, `regexpReplace()`, `regexpExtract()` - Regular expression operations
 
 ### 02-math-helpers.php
 Mathematical operations and functions.

src/connection/ConnectionFactory.php

@@ -8,6 +8,7 @@
 use PDO;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
+use tommyknocker\pdodb\dialects\SqliteDialect;
 use tommyknocker\pdodb\events\ConnectionOpenedEvent;
 
 /**
@@ -62,6 +63,14 @@ public function create(array $config, ?LoggerInterface $logger): Connection
 
         $dialect->setPdo($pdo);
 
+        // Register REGEXP functions for SQLite if enabled (default: true)
+        if ($driver === 'sqlite' && $dialect instanceof SqliteDialect) {
+            $enableRegexp = $config['enable_regexp'] ?? true;
+            if ($enableRegexp) {
+                $dialect->registerRegexpFunctions($pdo);
+            }
+        }
+
         // Use RetryableConnection if retry is enabled
         $retryConfig = $config['retry'] ?? [];
         $connection = null;

src/dialects/DialectInterface.php

@@ -592,6 +592,38 @@ public function formatReverse(string|RawValue $value): string;
      */
     public function formatPad(string|RawValue $value, int $length, string $padString, bool $isLeft): string;
 
+    /**
+     * Format REGEXP match expression (returns boolean).
+     *
+     * @param string|RawValue $value Source string.
+     * @param string $pattern Regex pattern.
+     *
+     * @return string SQL expression that returns boolean (true if matches, false otherwise).
+     */
+    public function formatRegexpMatch(string|RawValue $value, string $pattern): string;
+
+    /**
+     * Format REGEXP replace expression.
+     *
+     * @param string|RawValue $value Source string.
+     * @param string $pattern Regex pattern.
+     * @param string $replacement Replacement string.
+     *
+     * @return string SQL expression for regexp replacement.
+     */
+    public function formatRegexpReplace(string|RawValue $value, string $pattern, string $replacement): string;
+
+    /**
+     * Format REGEXP extract expression (extracts matched substring).
+     *
+     * @param string|RawValue $value Source string.
+     * @param string $pattern Regex pattern.
+     * @param int|null $groupIndex Capture group index (0 = full match, 1+ = specific group, null = full match).
+     *
+     * @return string SQL expression for regexp extraction.
+     */
+    public function formatRegexpExtract(string|RawValue $value, string $pattern, ?int $groupIndex = null): string;
+
     /* ---------------- Original SQL helpers and dialect-specific expressions ---------------- */
 
     /**