refactor: eliminate code duplication in QueryBuilder and related classes

- Extract common functionality into reusable traits:
  - CommonDependenciesTrait: shared dependency injection
  - ExternalReferenceProcessingTrait: external table reference detection
  - IdentifierQuotingTrait: database-specific identifier quoting
  - RawValueResolutionTrait: RawValue handling and resolution
  - TableManagementTrait: table name and prefix management

- Move query interfaces to query/interfaces/ directory for better organization
- Update all classes to use traits instead of duplicated code
- Remove JsonIntegrationTrait (over-abstraction, logic inlined back)
- Fix PHPStan type hints to use concrete QueryBuilder class in callable types
- Add missing properties and imports to resolve PHP 8.4 compatibility issues

All tests pass, no breaking changes to public API, maintains backward compatibility.

Author: tommyknocker

src/query/BatchProcessor.php

@@ -9,6 +9,9 @@
 use PDO;
 use PDOException;
 use tommyknocker\pdodb\connection\ConnectionInterface;
+use tommyknocker\pdodb\query\interfaces\BatchProcessorInterface;
+use tommyknocker\pdodb\query\interfaces\ExecutionEngineInterface;
+use tommyknocker\pdodb\query\interfaces\ParameterManagerInterface;
 
 class BatchProcessor implements BatchProcessorInterface
 {

src/query/ConditionBuilder.php

@@ -7,16 +7,23 @@
 use InvalidArgumentException;
 use PDOException;
 use tommyknocker\pdodb\connection\ConnectionInterface;
-use tommyknocker\pdodb\dialects\DialectInterface;
 use tommyknocker\pdodb\helpers\RawValue;
+use tommyknocker\pdodb\query\interfaces\ConditionBuilderInterface;
+use tommyknocker\pdodb\query\interfaces\ExecutionEngineInterface;
+use tommyknocker\pdodb\query\interfaces\ParameterManagerInterface;
+use tommyknocker\pdodb\query\traits\CommonDependenciesTrait;
+use tommyknocker\pdodb\query\traits\ExternalReferenceProcessingTrait;
+use tommyknocker\pdodb\query\traits\IdentifierQuotingTrait;
+use tommyknocker\pdodb\query\traits\RawValueResolutionTrait;
+use tommyknocker\pdodb\query\traits\TableManagementTrait;
 
 class ConditionBuilder implements ConditionBuilderInterface
 {
-    protected ConnectionInterface $connection;
-    protected DialectInterface $dialect;
-    protected ParameterManagerInterface $parameterManager;
-    protected ExecutionEngineInterface $executionEngine;
-    protected RawValueResolver $rawValueResolver;
+    use CommonDependenciesTrait;
+    use RawValueResolutionTrait;
+    use TableManagementTrait;
+    use IdentifierQuotingTrait;
+    use ExternalReferenceProcessingTrait;
 
     /** @var array<int, string|array<string, mixed>> */
     protected array $where = [];
@@ -27,9 +34,6 @@ class ConditionBuilder implements ConditionBuilderInterface
     /** @var string|null table name */
     protected ?string $table = null;
 
-    /** @var string|null Table prefix */
-    protected ?string $prefix = null;
-
     /** @var array<int, string> ORDER BY expressions */
     protected array $order = [];
 
@@ -42,37 +46,7 @@ public function __construct(
         ExecutionEngineInterface $executionEngine,
         RawValueResolver $rawValueResolver
     ) {
-        $this->connection = $connection;
-        $this->dialect = $connection->getDialect();
-        $this->parameterManager = $parameterManager;
-        $this->executionEngine = $executionEngine;
-        $this->rawValueResolver = $rawValueResolver;
-    }
-
-    /**
-     * Set table name.
-     *
-     * @param string $table
-     *
-     * @return self
-     */
-    public function setTable(string $table): self
-    {
-        $this->table = $table;
-        return $this;
-    }
-
-    /**
-     * Set table prefix.
-     *
-     * @param string|null $prefix
-     *
-     * @return self
-     */
-    public function setPrefix(?string $prefix): self
-    {
-        $this->prefix = $prefix;
-        return $this;
+        $this->initializeCommonDependencies($connection, $parameterManager, $executionEngine, $rawValueResolver);
     }
 
     /**
@@ -547,37 +521,6 @@ protected function buildSelectSql(): string
         return trim($sql);
     }
 
-    /**
-     * Quote qualified identifier.
-     *
-     * @param string $name
-     *
-     * @return string
-     */
-    protected function quoteQualifiedIdentifier(string $name): string
-    {
-        // If looks like an expression (contains spaces, parentheses, commas or quotes)
-        // treat as raw expression but DO NOT accept suspicious unquoted parts silently.
-        if (preg_match('/[`\["\'\s\(\),]/', $name)) {
-            // allow already-quoted or complex expressions to pass through,
-            // but still protect obvious injection attempts by checking for dangerous tokens
-            if (preg_match('/;|--|\bDROP\b|\bDELETE\b|\bINSERT\b|\bUPDATE\b|\bSELECT\b|\bUNION\b/i', $name)) {
-                throw new InvalidArgumentException('Unsafe SQL expression provided as identifier/expression.');
-            }
-            return $name;
-        }
-
-        $parts = explode('.', $name);
-        foreach ($parts as $p) {
-            // require valid simple identifier parts
-            if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $p)) {
-                throw new InvalidArgumentException("Invalid identifier part: {$p}");
-            }
-        }
-        $quoted = array_map(fn ($p) => $this->dialect->quoteIdentifier($p), $parts);
-        return implode('.', $quoted);
-    }
-
     /**
      * Normalize operator (trim and uppercase).
      *
@@ -589,75 +532,4 @@ protected function normalizeOperator(string $operator): string
     {
         return strtoupper(trim($operator));
     }
-
-    /**
-     * Resolve RawValue instances.
-     *
-     * @param string|RawValue $value
-     *
-     * @return string
-     */
-    protected function resolveRawValue(string|RawValue $value): string
-    {
-        return $this->rawValueResolver->resolveRawValue($value);
-    }
-
-    /**
-     * Normalizes a table name by prefixing it with the database prefix if it is set.
-     *
-     * @param string|null $table
-     *
-     * @return string The normalized table name.
-     */
-    protected function normalizeTable(?string $table = null): string
-    {
-        $table = $table ?: $this->table;
-        return $this->dialect->quoteTable($this->prefix . $table);
-    }
-
-    /**
-     * Check if a string represents an external table reference.
-     *
-     * @param string $reference The reference to check (e.g., 'users.id')
-     *
-     * @return bool True if it's an external reference
-     */
-    protected function isExternalReference(string $reference): bool
-    {
-        // Check if it matches table.column pattern
-        if (!preg_match('/^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$/', $reference)) {
-            return false;
-        }
-
-        $table = explode('.', $reference)[0];
-        return !$this->isTableInCurrentQuery($table);
-    }
-
-    /**
-     * Check if a table is referenced in the current query.
-     *
-     * @param string $tableName The table name to check
-     *
-     * @return bool True if table is in current query
-     */
-    protected function isTableInCurrentQuery(string $tableName): bool
-    {
-        return $this->table === $tableName;
-    }
-
-    /**
-     * Automatically convert external references to RawValue.
-     *
-     * @param mixed $value The value to process
-     *
-     * @return mixed Processed value
-     */
-    protected function processExternalReferences(mixed $value): mixed
-    {
-        if (is_string($value) && $this->isExternalReference($value)) {
-            return new RawValue($value);
-        }
-
-        return $value;
-    }
 }

src/query/DmlQueryBuilder.php

@@ -8,17 +8,20 @@
 use PDOException;
 use RuntimeException;
 use tommyknocker\pdodb\connection\ConnectionInterface;
-use tommyknocker\pdodb\dialects\DialectInterface;
 use tommyknocker\pdodb\helpers\RawValue;
+use tommyknocker\pdodb\query\interfaces\ConditionBuilderInterface;
+use tommyknocker\pdodb\query\interfaces\DmlQueryBuilderInterface;
+use tommyknocker\pdodb\query\interfaces\ExecutionEngineInterface;
+use tommyknocker\pdodb\query\interfaces\ParameterManagerInterface;
+use tommyknocker\pdodb\query\traits\CommonDependenciesTrait;
+use tommyknocker\pdodb\query\traits\RawValueResolutionTrait;
+use tommyknocker\pdodb\query\traits\TableManagementTrait;
 
 class DmlQueryBuilder implements DmlQueryBuilderInterface
 {
-    protected ConnectionInterface $connection;
-    protected DialectInterface $dialect;
-    protected ParameterManagerInterface $parameterManager;
-    protected ExecutionEngineInterface $executionEngine;
-    protected ConditionBuilderInterface $conditionBuilder;
-    protected RawValueResolver $rawValueResolver;
+    use CommonDependenciesTrait;
+    use RawValueResolutionTrait;
+    use TableManagementTrait;
 
     /** @var string|null table name */
     protected ?string $table = null {
@@ -39,28 +42,23 @@ class DmlQueryBuilder implements DmlQueryBuilderInterface
     /** @var array<string, string|int|float|bool|null|RawValue> */
     protected array $onDuplicate = [];
 
-    /** @var string|null Table prefix */
-    protected ?string $prefix = null;
-
     /** @var array<int|string, mixed> Query options (e.g., FOR UPDATE, IGNORE) */
     protected array $options = [];
 
     /** @var int|null LIMIT value */
     protected ?int $limit = null;
 
+    protected ConditionBuilderInterface $conditionBuilder;
+
     public function __construct(
         ConnectionInterface $connection,
         ParameterManagerInterface $parameterManager,
         ExecutionEngineInterface $executionEngine,
         ConditionBuilderInterface $conditionBuilder,
         RawValueResolver $rawValueResolver
     ) {
-        $this->connection = $connection;
-        $this->dialect = $connection->getDialect();
-        $this->parameterManager = $parameterManager;
-        $this->executionEngine = $executionEngine;
+        $this->initializeCommonDependencies($connection, $parameterManager, $executionEngine, $rawValueResolver);
         $this->conditionBuilder = $conditionBuilder;
-        $this->rawValueResolver = $rawValueResolver;
     }
 
     /**
@@ -471,29 +469,4 @@ protected function processValueForSql(mixed $value, string $columnName, string $
         $this->parameterManager->setParam($paramName, $value);
         return ['sql' => $paramName, 'params' => []];
     }
-
-    /**
-     * Resolve RawValue instances.
-     *
-     * @param string|RawValue $value
-     *
-     * @return string
-     */
-    protected function resolveRawValue(string|RawValue $value): string
-    {
-        return $this->rawValueResolver->resolveRawValue($value);
-    }
-
-    /**
-     * Normalizes a table name by prefixing it with the database prefix if it is set.
-     *
-     * @param string|null $table
-     *
-     * @return string The normalized table name.
-     */
-    protected function normalizeTable(?string $table = null): string
-    {
-        $table = $table ?: $this->table;
-        return $this->dialect->quoteTable($this->prefix . $table);
-    }
 }

src/query/ExecutionEngine.php

@@ -10,6 +10,8 @@
 use tommyknocker\pdodb\connection\ConnectionInterface;
 use tommyknocker\pdodb\exceptions\ExceptionFactory;
 use tommyknocker\pdodb\helpers\RawValue;
+use tommyknocker\pdodb\query\interfaces\ExecutionEngineInterface;
+use tommyknocker\pdodb\query\interfaces\ParameterManagerInterface;
 
 class ExecutionEngine implements ExecutionEngineInterface
 {

src/query/FileLoader.php

@@ -6,47 +6,25 @@
 
 use PDOException;
 use tommyknocker\pdodb\connection\ConnectionInterface;
+use tommyknocker\pdodb\dialects\DialectInterface;
 use tommyknocker\pdodb\exceptions\ExceptionFactory;
+use tommyknocker\pdodb\query\interfaces\FileLoaderInterface;
+use tommyknocker\pdodb\query\traits\TableManagementTrait;
 
 class FileLoader implements FileLoaderInterface
 {
+    use TableManagementTrait;
+
     protected ConnectionInterface $connection;
+    protected DialectInterface $dialect;
 
     /** @var string|null table name */
     protected ?string $table = null;
 
-    /** @var string|null Table prefix */
-    protected ?string $prefix = null;
-
     public function __construct(ConnectionInterface $connection)
     {
         $this->connection = $connection;
-    }
-
-    /**
-     * Set table name.
-     *
-     * @param string $table
-     *
-     * @return self
-     */
-    public function setTable(string $table): self
-    {
-        $this->table = $table;
-        return $this;
-    }
-
-    /**
-     * Set table prefix.
-     *
-     * @param string|null $prefix
-     *
-     * @return self
-     */
-    public function setPrefix(?string $prefix): self
-    {
-        $this->prefix = $prefix;
-        return $this;
+        $this->dialect = $connection->getDialect();
     }
 
     /**