Patch DB select return types and Redis mixin for Laravel

Author: AJenbo

docs/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **`DB::select()` return type.** `DB::select()`, `DB::selectFromWriteConnection()`, and `DB::selectResultSets()` now return `array<int, stdClass>` instead of bare `array`, and `DB::selectOne()` returns `?stdClass` instead of `mixed`. Property access on query results (e.g. `$result[0]->column_name`) no longer produces false-positive diagnostics. The same fix applies to the underlying `Illuminate\Database\Connection` class.
+- **Redis `Connection` method resolution.** `Illuminate\Redis\Connections\Connection` now has `@mixin \Redis` applied automatically, so Redis commands like `del()`, `get()`, `set()`, etc. resolve through the phpredis stubs instead of producing false-positive diagnostics.
+
 ### Added
 
 - **Foreach over arrays with non-class element types.** When iterating over a generic array whose value type is an array shape (e.g. `array<int, array{tool: Pen, count: int}>`), the foreach iteration variable now carries the full shape type. Bracket access on the iteration variable (`$entry['tool']->`) resolves each key to its declared type. Previously the element type was silently dropped when it was not a class name, leaving the iteration variable untyped.

docs/todo.md

@@ -27,7 +27,6 @@ within the same impact tier.
 | B11 | [`static` return type not resolved through `class-string<T>` context](todo/bugs.md#b11-static-return-type-not-resolved-through-class-stringt-context)     | Low    | Medium     |
 | B12 | [`Collection::reduce()` generic return type not inferred](todo/bugs.md#b12-collectionreduce-generic-return-type-not-inferred)                             | Low    | Medium     |
 | B13 | [Array shape tracking from keyed literal assignments in loops](todo/bugs.md#b13-array-shape-tracking-from-keyed-literal-assignments-in-loops)             | Low    | High       |
-| B14 | [`DB::select()` returns bare `array`, element type unresolvable](todo/bugs.md#b14-dbselect-returns-bare-array-element-type-unresolvable)                  | Low    | Low        |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union)          | Medium | Medium     |
 | H6  | `return.type` — update return type to match actual returns                                                                                                | Medium | Medium     |
 |     | **Release 0.7.0**                                                                                                                                         |        |            |

docs/todo/bugs.md

@@ -136,41 +136,3 @@ unresolvable because the shape is lost.
 a basic array shape inference that preserves `array{key: Type}` from
 literal array constructors and propagates it through foreach.
 
----
-
-## B14. `DB::select()` returns bare `array`, element type unresolvable
-**Impact: Low · Effort: Low**
-
-Pattern:
-```php
-$result = DB::select('select sum(...) as incoming_qty from ...');
-if ($result[0] instanceof stdClass && $result[0]->incoming_qty) {
-    return Convert::toInt($result[0]->incoming_qty);  // unresolved
-}
-```
-
-The `DB` facade's `@method` annotation declares `select()` as
-returning bare `array` rather than `array<int, stdClass>`. Since the
-return type has no element type, `$result[0]` is untyped and
-`->incoming_qty` is unresolvable.
-
-Two compounding issues:
-
-1. **Stub/facade return type gap:** `DB::select()` should return
-   `array<int, stdClass>` (which is what the underlying
-   `Connection::select()` actually returns), but the facade
-   annotation only says `array`.
-
-2. **`instanceof` narrowing on array element access:** Even if the
-   array element type were known, `$result[0] instanceof stdClass`
-   should narrow `$result[0]` to `stdClass` within the condition.
-   The narrowing system only matches bare variable names (`$var`),
-   not subscript expressions (`$var[0]`). This is a T20 concern.
-
-**Observed in:** `PurchaseFileService:1087,1089`.
-
-**Partial workaround:** PHPantom could patch `DB::select()` to return
-`array<int, stdClass>` via framework-specific return type overrides
-(similar to how scope methods are handled). The `instanceof`
-narrowing gap (issue 2) would remain but would no longer trigger
-here because `stdClass` property access is already suppressed.

docs/todo/type-inference.md

@@ -518,10 +518,12 @@ design.
 This fixed `Order:646,647` (`json_decode` → `mixed` → `is_object`
 guard → property access).
 
-**Remaining:** `PurchaseFileService:1087,1089` — `$result[0]
-instanceof stdClass` where `$result` is bare `array` from
-`DB::select()`. This requires `instanceof` narrowing on array
-element access expressions, which is a T20 concern (the narrowing
-system only matches bare variable names, not `$arr[0]`).
+**Remaining:** `instanceof` narrowing on array element access
+expressions (T20 concern). The narrowing system only matches bare
+variable names (`$var`), not subscript expressions (`$arr[0]`).
+The `PurchaseFileService` case that originally motivated this item
+is now resolved by the `DB::select()` return type patch (B14) combined
+with `stdClass` property access suppression, but the general gap
+remains for any `$arr[$i] instanceof Foo` pattern.
 
 ---

src/virtual_members/laravel/patches.rs

@@ -29,6 +29,26 @@
 //!    patch runs at scope-injection time (post-generic-substitution),
 //!    not during `resolve_class_fully_inner`.  It is documented here
 //!    as part of the patch inventory but not dispatched from this module.
+//!
+//! 4. **`Redis\Connections\Connection` mixin.**
+//!    The base `Connection` class delegates all Redis commands to the
+//!    underlying `\Redis` client via `__call`, but lacks a `@mixin`
+//!    annotation.  The patch injects `@mixin \Redis` **pre-resolution**
+//!    (in `resolve_class_fully_inner`, before virtual member providers
+//!    run) so that `collect_mixin_members` picks it up and merges
+//!    `del()`, `get()`, `set()`, etc. from the stubs.  This patch is
+//!    not dispatched from `apply_laravel_patches` because that runs
+//!    post-resolution, after mixin collection has already completed.
+//!
+//! 5. **`DB` facade / `Connection` select method return types.**
+//!    The facade's `@method` annotations and the underlying
+//!    `Connection` class both declare `select()`,
+//!    `selectFromWriteConnection()`, and `selectResultSets()` as
+//!    returning bare `array`.  The actual return type is
+//!    `array<int, stdClass>`.  Similarly, `selectOne()` is declared as
+//!    `mixed` but actually returns `stdClass|null`.  The patch
+//!    overrides these return types so that downstream property access
+//!    on query results resolves correctly.
 
 use crate::php_type::PhpType;
 use crate::types::ClassInfo;
@@ -38,6 +58,12 @@ use super::ELOQUENT_BUILDER_FQN;
 /// FQN of the `Conditionable` trait from `illuminate/support`.
 const CONDITIONABLE_FQN: &str = "Illuminate\\Support\\Traits\\Conditionable";
 
+/// FQN of the `DB` facade from `illuminate/support`.
+const DB_FACADE_FQN: &str = "Illuminate\\Support\\Facades\\DB";
+
+/// FQN of the base `Connection` class from `illuminate/database`.
+const DB_CONNECTION_FQN: &str = "Illuminate\\Database\\Connection";
+
 /// Apply all registered Laravel class patches to a fully-resolved class.
 ///
 /// Called from [`resolve_class_fully_inner`] after virtual members have
@@ -57,6 +83,10 @@ pub fn apply_laravel_patches(class: &mut ClassInfo, fqn: &str) {
     } else if fqn == CONDITIONABLE_FQN || class_uses_conditionable(class) {
         patch_conditionable_when_unless(class);
     }
+
+    if fqn == DB_FACADE_FQN || fqn == DB_CONNECTION_FQN {
+        patch_db_select_return_types(class);
+    }
 }
 
 /// Override `__call` and `__callStatic` return types on Eloquent Builder
@@ -192,6 +222,51 @@ fn is_likely_template_param(ty: &PhpType) -> bool {
     false
 }
 
+/// Patch `select()`, `selectFromWriteConnection()`, `selectResultSets()`
+/// return types from bare `array` to `array<int, stdClass>`, and
+/// `selectOne()` from `mixed` to `stdClass|null`.
+///
+/// Both the `DB` facade (`@method` annotations) and the underlying
+/// `Illuminate\Database\Connection` class declare these methods with
+/// imprecise return types.  The actual runtime return is always an
+/// array of `stdClass` rows (or a single `stdClass|null` for
+/// `selectOne`).  Patching this here lets property access on query
+/// results resolve correctly across the codebase.
+fn patch_db_select_return_types(class: &mut ClassInfo) {
+    let array_of_std = PhpType::Generic(
+        "array".to_string(),
+        vec![
+            PhpType::Named("int".to_string()),
+            PhpType::Named("stdClass".to_string()),
+        ],
+    );
+    let std_or_null = PhpType::Nullable(Box::new(PhpType::Named("stdClass".to_string())));
+
+    for method in class.methods.make_mut().iter_mut() {
+        match method.name.as_str() {
+            "select" | "selectFromWriteConnection" | "selectResultSets" => {
+                if method
+                    .return_type
+                    .as_ref()
+                    .is_some_and(|rt| rt.to_string() == "array")
+                {
+                    method.return_type = Some(array_of_std.clone());
+                }
+            }
+            "selectOne" => {
+                if method
+                    .return_type
+                    .as_ref()
+                    .is_some_and(|rt| rt.to_string() == "mixed")
+                {
+                    method.return_type = Some(std_or_null.clone());
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
 /// Check whether a class uses the `Conditionable` trait (directly or
 /// through its trait list / parent chain markers).
 ///