Add query builder and more

[brianlmoon]

• Adds a new query builder class
• Updates to type hinting
• Updates to property and method visibility

[Copilot]

Pull request overview

This PR adds a comprehensive SQL query builder utility class along with extensive type hinting improvements and property visibility updates throughout the codebase.

• Introduces Query and Raw classes providing a fluent interface for building complex SELECT queries with JOINs, aggregations, and nested conditions
• Adds strict type declarations to all method parameters and return types across PDO, CRUD, and mapper classes
• Updates property visibility to use public readonly where appropriate, removing magic getter methods in favor of direct property access

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/Util/Query.php	New fluent query builder with driver-aware SQL generation, parameter binding, and comprehensive clause support
src/Util/Raw.php	Value object for raw SQL fragments to bypass query builder escaping
tests/Util/QueryTest.php	Comprehensive test suite with 35 test cases covering all query builder features and edge cases
src/PDO.php	Added type hints for parameters and return values; updated property type declarations
src/PDOStatement.php	Added strict type hints to all methods including __call and __get magic methods
src/CRUD.php	Changed $pdo to public readonly, removed __get method, added return type to quoteField (now public)
src/AbstractMapper.php	Changed $crud to public readonly, added parent::__construct() call
src/ColumnMapper.php	Fixed spelling of "Primary" in PHPDoc comments
src/Util/Search/Text.php	Fixed typo ("there there" → "there") and adjusted wildcard comment wording
tests/PDOTest.php	Updated type hints in test mock classes to match updated interfaces
tests/CRUDTest.php	Removed testBadGetter test as __get method was removed from CRUD
tests/CRUDMock.php	Added type hints to magic methods and updated property types
bin/create_objects.php	Changed generated MAPPING constant from protected to public for accessibility
composer.json	Added explicit ext-pdo dependency requirement
README.md	Added comprehensive Query Builder documentation with usage examples and method reference table
AGENTS.md	New extensive AI agent context document covering architecture, patterns, and usage guidelines
.phan/config.php	Added suppressions for unreferenced classes and annotation suffixes

Comments suppressed due to low confidence (1)

src/PDO.php:306

• The variable $stmt may be undefined if none of the retry attempts succeed without throwing an exception but also without entering the if block on line 295. The return type union 'PDOStatement|\PDOStatement' is also confusing since PDOStatement (without namespace) refers to \DealNews\DB\PDOStatement. Consider simplifying the return type to just 'PDOStatement' since the method always converts \PDOStatement to DealNews\DB\PDOStatement before returning.

    public function query(string $statement): PDOStatement|\PDOStatement {
        for ($x = 1; $x <= $this::RETRY_LIMIT; $x++) {
            try {
                $stmt = $this->__call(__FUNCTION__, func_get_args());

                // Convert \PDOStatement to a DealNews\DB\PDOStatement
                if ($stmt instanceof \PDOStatement) {
                    $stmt = new PDOStatement($stmt, $this);
                    break;
                }
            } catch (\PDOException $e) {
                if ($x >= $this::RETRY_LIMIT || !$this->checkErrorCode($e->getCode())) {
                    throw $e;
                }
            }
        }

        return $stmt;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.