MNT Use generics with EagerLoadedList

src/ORM/EagerLoadedList.php

@@ -21,6 +21,13 @@ use Traversable;
  *
  * Note that when this list represents a relation, adding items to or removing items from this list will NOT
  * affect the underlying relation in the database. This list is read-only.
+ *
+ * @template T of DataObject
+ * @implements Relation<T>
+ * @implements SS_List<T>
+ * @implements Filterable<T>
+ * @implements Sortable<T>
+ * @implements Limitable<T>
  */
 class EagerLoadedList extends ViewableData implements Relation, SS_List, Filterable, Sortable, Limitable
 {
@@ -28,11 +35,13 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
 
     /**
      * List responsible for instantiating the actual DataObject objects from eager-loaded data
+     * @var DataList<T>
      */
     private DataList $dataList;
 
     /**
      * Underlying DataObject class for this list
+     * @var class-string<T>
      */
     private string $dataClass;
 
@@ -65,6 +74,9 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
      */
     private array $manyManyComponent = [];
 
+    /**
+     * @param class-string<T> $dataClass
+     */
     public function __construct(string $dataClass, string $dataListClass, int|array|null $foreignID = null, array $manyManyComponent = [])
     {
         if (!is_a($dataListClass, DataList::class, true)) {
@@ -134,7 +146,7 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
     /**
      * Pass in any eager-loaded data which applies to relations on a specific record in this list
      *
-     * @return $this
+     * @return static<T> $this
      */
     public function addEagerLoadedData(string $relation, int $id, self|DataObject $data): static
     {
@@ -144,6 +156,8 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
 
     /**
      * Get the dataClass name for this list, ie the DataObject ClassName
+     *
+     * @return class-string<T>
      */
     public function dataClass(): string
     {
@@ -179,6 +193,9 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
         throw new BadMethodCallException("Can't change the foreign ID for an EagerLoadedList");
     }
 
+    /**
+     * @return iterator<T>
+     */
     public function getIterator(): Traversable
     {
         $limitedRows = $this->getFinalisedRows();
@@ -493,6 +510,8 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
 
     /**
      * Return a copy of this list which does not contain any items with any of these params
+     *
+     * @return static<T>
      */
     public function excludeAny(...$args): static
     {
@@ -509,6 +528,7 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
      * Return a new instance of the list with an added filter
      *
      * @param array $filterArray
+     * @return static<T>
      */
     public function addFilter($filterArray): static
     {
@@ -522,6 +542,7 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
      *
      * The $list passed needs to contain the same dataclass as $this
      *
+     * @return static<T>
      * @throws InvalidArgumentException
      */
     public function subtract(DataList $list): static
@@ -708,6 +729,8 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
 
     /**
      * Shuffle the items in this list
+     *
+     * @return static<T>
      */
     public function shuffle(): static
     {
@@ -862,6 +885,8 @@ class EagerLoadedList extends ViewableData implements Relation, SS_List, Filtera
      * At a minimum, $row['ID'] must be set. Unsaved records cannot be eager loaded.
      *
      * @param array $row
+     * @return T
+     * @throws InvalidArgumentException if $row has no "ID" key
      */
     public function createDataObject($row): DataObject
     {

src/ORM/Relation.php

@@ -12,6 +12,12 @@ use SilverStripe\ORM\FieldType\DBField;
  * @method Relation relation($relationName)
  * @method Relation forForeignID($id)
  * @method string dataClass()
+ *
+ * @template T
+ * @extends SS_List<T>
+ * @extends Filterable<T>
+ * @extends Sortable<T>
+ * @extends Limitable<T>
  */
 interface Relation extends SS_List, Filterable, Sortable, Limitable
 {