Generics Template

[JiriSmach]

Feature Suggestion: Enhance Fluent Class with Generics for Superior IDE Auto-completion

🙏 Description

I would like to suggest a significant quality-of-life improvement for the Fluent class (and related query builder methods) by utilizing PHP Generics via PHPDoc annotations (@template, @return, @var).

Currently, when specifying a custom row class using the setRowClass($class) method, the type information for the resulting objects is often lost to the IDE. This forces developers to manually add verbose inline @var comments, which clutter the codebase.

It would be highly beneficial if the Fluent class and other classes could internally track this custom row class type. This change would allow IDEs (like PhpStorm) to correctly and automatically suggest methods and properties of the custom class when results are retrieved.

---

💡 Proposed Implementation Enhancement

The core idea is to introduce a generic type parameter (e.g., T) to the relevant classes/methods to track the type set by setRowClass.

1. Introduce a Template:

   • Add a @template T to the relevant class or methods that initiate the query chain.

2. Update setRowClass PHPDoc to Capture Type T:

   • Modify the setRowClass method's PHPDoc to accept and register the class name as the generic type T.

   /**
    * Set the class name to use for the row when fetching results.
    *
    * @param  class-string<T>  $class
    * @return $this
    */
   public function setRowClass($class)
   {
       $this->rowClass = $class;
       return $this;
   }

3. Reflect Generic Type in Result Methods:

   • Ensure methods that return single rows or collections use this generic type T.

     /**
      * Execute the query and get the results.
      *
      * @return T[]|Row[]|array[]
      */
     public function fetchAll(): array
     {
         // ...
     }

✅ Benefits and Rationale

• Superior Developer Experience (DX): Provides accurate, instantaneous auto-completion for custom row objects, drastically simplifying development.
• Cleaner Codebase: Eliminates the need for verbose, manually added @var comments for IDE hinting.
• Enhanced Static Analysis: Brings better type support for tools like PHPStan, enabling more effective type checking across the application.

I believe this update would be a highly valuable addition and significantly improve the development flow for those using custom row objects.

Thank you very much for considering this suggestion!