feature: postgresql - condition builder (#2113)

* feature: postgresql - condition builder

* fix: missing dsl definitions

Author: norberttech

documentation/components/libs/postgresql.md

@@ -238,6 +238,10 @@ echo $query->toSQL();
   RETURNING
 - [Merge Query Builder](/documentation/components/libs/postgresql/merge-query-builder.md) - MERGE (SQL:2008 upsert)
 
+**Query Building Utilities**
+
+- [Condition Builder](/documentation/components/libs/postgresql/condition-builder.md) - Build WHERE conditions incrementally with fluent API
+
 **Schema Management (DDL)**
 
 - [Table Query Builder](/documentation/components/libs/postgresql/table-query-builder.md) - CREATE/ALTER/DROP TABLE

documentation/components/libs/postgresql/condition-builder.md

@@ -0,0 +1,173 @@
+# Condition Builder
+
+- [⬅️ Back](/documentation/components/libs/postgresql.md)
+
+[TOC]
+
+The Condition Builder provides a fluent API for building WHERE conditions incrementally. It's particularly useful when conditions need to be constructed dynamically based on runtime logic, such as building filter queries from user input.
+
+## Basic Usage
+
+```php
+<?php
+
+use function Flow\PostgreSql\DSL\{
+    conditions, select, table, col, eq, gt, param, literal
+};
+
+// Create a condition builder and add conditions fluently
+$conditions = conditions()
+    ->and(eq(col('status'), literal('active')))
+    ->and(gt(col('age'), literal(18)));
+
+// Use in a query
+$query = select()->from(table('users'))->where($conditions);
+
+echo $query->toSQL();
+// SELECT * FROM users WHERE status = 'active' AND age > 18
+```
+
+## Building Conditions Incrementally
+
+The real power of `ConditionBuilder` is building conditions based on runtime logic:
+
+```php
+<?php
+
+use function Flow\PostgreSql\DSL\{
+    conditions, select, table, col, eq, gte, like, param
+};
+
+function buildUserQuery(array $filters): SelectFinalStep
+{
+    $conditions = conditions();
+
+    if (array_key_exists('status', $filters)) {
+        $conditions = $conditions->and(eq(col('status'), param($filters['status'])));
+    }
+
+    if (array_key_exists('min_age', $filters)) {
+        $conditions = $conditions->and(gte(col('age'), param($filters['min_age'])));
+    }
+
+    if (array_key_exists('email_domain', $filters)) {
+        $conditions = $conditions->and(like(col('email'), param('%@' . $filters['email_domain'])));
+    }
+
+    $query = select()->from(table('users'));
+
+    // Only add WHERE clause if we have conditions
+    if (!$conditions->isEmpty()) {
+        $query = $query->where($conditions);
+    }
+
+    return $query;
+}
+
+// Usage
+$query = buildUserQuery(['status' => 'active', 'min_age' => 21]);
+echo $query->toSQL();
+// SELECT * FROM users WHERE status = $1 AND age >= $2
+```
+
+## Nested Conditions
+
+Build complex nested conditions with OR groups inside AND:
+
+```php
+<?php
+
+use function Flow\PostgreSql\DSL\{
+    conditions, select, table, col, eq, gt, literal
+};
+
+// WHERE status = 'active' AND (role = 'admin' OR role = 'moderator') AND age > 18
+$conditions = conditions()
+    ->and(eq(col('status'), literal('active')))
+    ->and(
+        conditions()
+            ->or(eq(col('role'), literal('admin')))
+            ->or(eq(col('role'), literal('moderator')))
+    )
+    ->and(gt(col('age'), literal(18)));
+
+$query = select()->from(table('users'))->where($conditions);
+
+echo $query->toSQL();
+// SELECT * FROM users WHERE status = 'active' AND (role = 'admin' OR role = 'moderator') AND age > 18
+```
+
+## Immutability
+
+`ConditionBuilder` is immutable - each `and()` or `or()` call returns a new builder instance:
+
+```php
+<?php
+
+use function Flow\PostgreSql\DSL\{conditions, eq, gt, col, literal};
+
+$base = conditions()->and(eq(col('active'), literal(true)));
+
+// Each branch creates a new builder
+$withRole = $base->and(eq(col('role'), literal('admin')));
+$withAge = $base->and(gt(col('age'), literal(18)));
+
+// $base is unchanged
+```
+
+## Empty Builder Behavior
+
+- `isEmpty()` returns `true` when no conditions have been added
+- `getCondition()` returns `null` for empty builders
+- Passing an empty builder to `where()` throws `InvalidBuilderStateException`
+- Empty nested builders are ignored (no-op) when combined with `and()` or `or()`
+
+```php
+<?php
+
+use function Flow\PostgreSql\DSL\{conditions, eq, col, literal};
+
+$conditions = conditions();
+
+// Safe pattern: check before using
+if (!$conditions->isEmpty()) {
+    $query = $query->where($conditions);
+}
+
+// Empty nested builders are safely ignored
+$conditions = conditions()
+    ->and(eq(col('status'), literal('active')))
+    ->and(conditions()); // Empty conditions is ignored
+
+// Result: only "status = 'active'" condition
+```
+
+## Method Reference
+
+| Method | Description |
+|--------|-------------|
+| `conditions()` | DSL function - creates a new empty `ConditionBuilder` |
+| `and(Condition\|ConditionBuilder $condition)` | Add a condition with AND logic |
+| `or(Condition\|ConditionBuilder $condition)` | Add a condition with OR logic |
+| `getCondition()` | Returns the built `Condition` or `null` if empty |
+| `isEmpty()` | Returns `true` if no conditions have been added |
+
+## Comparison with cond_and/cond_or
+
+For static conditions known at build time, `cond_and()` and `cond_or()` are simpler:
+
+```php
+// Static conditions - use cond_and/cond_or
+$query = select()
+    ->from(table('users'))
+    ->where(cond_and(
+        eq(col('active'), literal(true)),
+        gt(col('age'), literal(18))
+    ));
+
+// Dynamic conditions - use ConditionBuilder
+$conditions = conditions();
+foreach ($filters as $filter) {
+    $conditions = $conditions->and($filter->toCondition());
+}
+```

documentation/components/libs/postgresql/select-query-builder.md

@@ -107,6 +107,8 @@ echo $query->toSQL();
 // SELECT * FROM users WHERE email LIKE '%@example.com'
 ```
 
+> **Tip:** For building WHERE conditions dynamically based on runtime logic (e.g., user filters), see [Condition Builder](/documentation/components/libs/postgresql/condition-builder.md).
+
 ## JOINs
 
 ```php

src/lib/postgresql/src/Flow/PostgreSql/DSL/functions.php

@@ -46,6 +46,7 @@
     Comparison,
     ComparisonOperator,
     Condition,
+    ConditionBuilder,
     Exists,
     In,
     IsDistinctFrom,
@@ -1346,6 +1347,29 @@ function all_sub_select(Expression $left, ComparisonOperator $operator, SelectFi
     return new All($left, $operator, $node);
 }
 
+/**
+ * Create a condition builder for fluent condition composition.
+ *
+ * This builder allows incremental condition building with a fluent API:
+ *
+ * ```php
+ * $builder = conditions();
+ *
+ * if ($hasFilter) {
+ *     $builder = $builder->and(eq(col('status'), literal('active')));
+ * }
+ *
+ * if (!$builder->isEmpty()) {
+ *     $query = select()->from(table('users'))->where($builder);
+ * }
+ * ```
+ */
+#[DocumentationDSL(module: Module::PG_QUERY, type: DSLType::HELPER)]
+function conditions() : ConditionBuilder
+{
+    return ConditionBuilder::create();
+}
+
 /**
  * Combine conditions with AND.
  *

src/lib/postgresql/src/Flow/PostgreSql/QueryBuilder/Condition/ConditionBuilder.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PostgreSql\QueryBuilder\Condition;
+
+final readonly class ConditionBuilder
+{
+    private function __construct(
+        private ?Condition $condition = null,
+    ) {
+    }
+
+    public static function create() : self
+    {
+        return new self();
+    }
+
+    public function and(Condition|self $condition) : self
+    {
+        $resolved = $condition instanceof self ? $condition->condition : $condition;
+
+        if ($resolved === null) {
+            return $this;
+        }
+
+        if ($this->condition === null) {
+            return new self($resolved);
+        }
+
+        return new self($this->condition->and($resolved));
+    }
+
+    public function getCondition() : ?Condition
+    {
+        return $this->condition;
+    }
+
+    public function isEmpty() : bool
+    {
+        return $this->condition === null;
+    }
+
+    public function or(Condition|self $condition) : self
+    {
+        $resolved = $condition instanceof self ? $condition->condition : $condition;
+
+        if ($resolved === null) {
+            return $this;
+        }
+
+        if ($this->condition === null) {
+            return new self($resolved);
+        }
+
+        return new self($this->condition->or($resolved));
+    }
+}

src/lib/postgresql/src/Flow/PostgreSql/QueryBuilder/Exception/InvalidBuilderStateException.php

@@ -6,6 +6,11 @@
 
 final class InvalidBuilderStateException extends \InvalidArgumentException
 {
+    public static function emptyConditionBuilder() : self
+    {
+        return new self('Cannot use empty ConditionBuilder in where clause, use isEmpty() to check before passing to where()');
+    }
+
     public static function mutuallyExclusiveOptions(string $option1, string $option2) : self
     {
         return new self(\sprintf(

src/lib/postgresql/src/Flow/PostgreSql/QueryBuilder/Select/SelectBuilder.php

@@ -7,8 +7,8 @@
 use Flow\PostgreSql\Protobuf\AST\{LimitOption, Node, ResTarget, SelectStmt as ProtobufSelectStmt};
 use Flow\PostgreSql\QueryBuilder\AstToSql;
 use Flow\PostgreSql\QueryBuilder\Clause\{LockingClause, OrderBy, WindowDefinition, WithClause};
-use Flow\PostgreSql\QueryBuilder\Condition\{Condition, ConditionFactory};
-use Flow\PostgreSql\QueryBuilder\Exception\InvalidAstException;
+use Flow\PostgreSql\QueryBuilder\Condition\{Condition, ConditionBuilder, ConditionFactory};
+use Flow\PostgreSql\QueryBuilder\Exception\{InvalidAstException, InvalidBuilderStateException};
 use Flow\PostgreSql\QueryBuilder\Expression\{AliasedExpression, Expression, ExpressionFactory, Literal};
 use Flow\PostgreSql\QueryBuilder\Table\{AliasedTable, DerivedTable, JoinType, JoinedTable, Table, TableFunction, TableReference};
 
@@ -773,8 +773,18 @@ public function unionAll(SelectFinalStep $other) : SelectOrderByStep
         );
     }
 
-    public function where(Condition $condition) : SelectGroupByStep
+    public function where(Condition|ConditionBuilder $condition) : SelectGroupByStep
     {
+        if ($condition instanceof ConditionBuilder) {
+            $resolved = $condition->getCondition();
+
+            if ($resolved === null) {
+                throw InvalidBuilderStateException::emptyConditionBuilder();
+            }
+
+            $condition = $resolved;
+        }
+
         return new self(
             with: $this->with,
             selectList: $this->selectList,

src/lib/postgresql/src/Flow/PostgreSql/QueryBuilder/Select/SelectWhereStep.php

@@ -4,9 +4,9 @@
 
 namespace Flow\PostgreSql\QueryBuilder\Select;
 
-use Flow\PostgreSql\QueryBuilder\Condition\Condition;
+use Flow\PostgreSql\QueryBuilder\Condition\{Condition, ConditionBuilder};
 
 interface SelectWhereStep extends SelectGroupByStep
 {
-    public function where(Condition $condition) : SelectGroupByStep;
+    public function where(Condition|ConditionBuilder $condition) : SelectGroupByStep;
 }