Refactor/relations static access

[abdul-kaioum]

No description provided.

[gemini-code-assist]

Code Review

This pull request introduces major updates to the database package, including returning a new Collection class for multi-row query results, adding model lifecycle events, and relocating relation eager-loading methods to the QueryBuilder to support static access and improve IDE navigation. It also adds new query builder features like upsert(), when(), and a guard against empty WHERE clauses in deletes. While these changes significantly improve the library, several critical issues were identified: QueryBuilder::upsert() contains bugs where ksort() is incorrectly applied to numerically indexed columns and array_key_exists() is used on a list of values; Collection::pluck() can fail to load dynamic attributes or relations due to null coalescing; the documented 'boolean' cast is unimplemented; calling withCast() on the builder breaks fluent chaining; and unsetting bindings leaves non-contiguous array keys.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The use of ksort($columns) here is a critical bug. Since $columns is a numerically indexed array of column names (e.g., [0 => 'email', 1 => 'first_name']), sorting it by keys (ksort) does not change the order of the column names. However, in the loop below, each row is sorted alphabetically by its keys (ksort($row)). This mismatch causes the generated SQL to align values with the wrong columns if the input keys are not already sorted alphabetically. Use sort($columns) instead to sort the column names alphabetically.

        $columns        = array_keys($values[0]);
        sort($columns);

[gemini-code-assist]

Using \array_key_exists('created_at', $update) is incorrect because $update is a list of column names (values), not keys. This check will always return false, meaning 'created_at' is never replaced with 'updated_at'. Consequently, on duplicate key, created_at will be incorrectly overwritten instead of updating updated_at. Use \in_array('created_at', $update, true) instead.

        if (\in_array('created_at', $update, true)) {

[gemini-code-assist]

Using $item->{$key} ?? null on a Model instance will return null for relations or dynamic attributes that haven't been loaded yet. This is because the null coalescing operator (??) triggers __isset(), which only checks $this->attributes. To safely resolve relations and dynamic attributes, check if the item is an instance of Model and use getAttribute($key).

        return new static(array_map(function ($item) use ($key) {
            if (is_array($item)) {
                return $item[$key] ?? null;
            }
            if (is_object($item)) {
                if ($item instanceof Model) {
                    return $item->getAttribute($key);
                }
                return $item->{$key} ?? null;
            }
            return null;
        }, $this->items));

[gemini-code-assist]

The documentation states that 'boolean' is a supported cast type, but castToBoolean() is not implemented in the Model class. As a result, 'boolean' casts are silently ignored and return raw values. Implement castToBoolean() to delegate to castToBool().

    private function castToBool($value)
    {
        return \boolval($value);
    }

    private function castToBoolean($value)
    {
        return $this->castToBool($value);
    }

[gemini-code-assist]

Currently, calling withCast() on a QueryBuilder forwards the call to the Model instance, which returns the Model instance instead of the QueryBuilder. This breaks fluent chaining on the builder. Adding a withCast() method directly to QueryBuilder that delegates to the model and returns $this keeps the builder interface consistent.

    /**
     * Clone this class with all conditions
     */
    public function clone()
    {
        return clone $this;
    }

    /**
     * Add casts to the bound model at runtime.
     *
     * @param array $casts
     * @return $this
     */
    public function withCast(array $casts)
    {
        $this->_model->withCast($casts);

        return $this;
    }

[gemini-code-assist]

Unsetting elements from $this->bindings during prepareInsert() or prepareUpdate() leaves gaps in the array keys (non-contiguous keys). This can cause issues with custom wpdb mocks or potential future changes in PHP/WordPress. Re-indexing $this->bindings using array_values() right before preparing the query ensures a clean, packed array.

    public function prepare($sql = null)
    {
        if (\is_null($sql)) {
            $sql = $this->toSql();
        }

        $this->bindings = array_values($this->bindings);

        return empty($this->bindings)
         || strpos($sql, '%') === false
         ? $sql : Connection::prepare($sql, $this->bindings);
    }

[abdul-kaioum]

Superseded by #16, which contains every commit on this branch plus the namespace/Query\Grammar restructure and the Gemini Code Assist review fixes (upsert ksort/array_key_exists, boolean cast, pluck, withCast). #16 now targets main directly. Closing in favor of #16.