ENH Add generic types

There are also a few general corrections to PHPDocs that I noticed along
the way (e.g. adding `|null` when the method is returning a null value.

There are some cases where either the return type or the whole PHPDoc
was duplicated from the parent class - in those cases I've simply
removed the duplication.

src/Core/Extension.php

@@ -13,6 +13,8 @@
  * Every object instance gets its own set of extension instances,
  * meaning you can set parameters specific to the "owner instance"
  * in new Extension instances.
+ *
+ * @template T of object
  */
 abstract class Extension
 {
@@ -25,14 +27,14 @@ abstract class Extension
     /**
      * The object this extension is applied to.
      *
-     * @var Object
+     * @var T
      */
     protected $owner;
 
     /**
      * Stack of all parent owners, not including current owner
      *
-     * @var array
+     * @var array<T>
      */
     private $ownerStack = [];
 
@@ -95,7 +97,7 @@ public function clearOwner()
     /**
      * Returns the owner of this extension.
      *
-     * @return Object
+     * @return T
      */
     public function getOwner()
     {

src/Core/Injector/Injector.php

@@ -966,12 +966,13 @@ public function unregisterObjects($types)
      *
      * @throws NotFoundExceptionInterface  No entry was found for **this** identifier.
      *
-     * @param string $name The name of the service to retrieve. If not a registered
+     * @template T of object
+     * @param class-string<T> $name The name of the service to retrieve. If not a registered
      * service, then a class of the given name is instantiated
      * @param bool $asSingleton If set to false a new instance will be returned.
      * If true a singleton will be returned unless the spec is type=prototype'
      * @param array $constructorArgs Args to pass in to the constructor. Note: Ignored for singletons
-     * @return mixed Instance of the specified object
+     * @return T|mixed Instance of the specified object
      */
     public function get($name, $asSingleton = true, $constructorArgs = [])
     {
@@ -987,12 +988,13 @@ public function get($name, $asSingleton = true, $constructorArgs = [])
     /**
      * Returns the service, or `null` if it doesnt' exist. See {@link get()} for main usage.
      *
-     * @param string $name The name of the service to retrieve. If not a registered
+     * @template T of object
+     * @param class-string<T> $name The name of the service to retrieve. If not a registered
      * service, then a class of the given name is instantiated
      * @param bool $asSingleton If set to false a new instance will be returned.
      * If true a singleton will be returned unless the spec is type=prototype'
      * @param array $constructorArgs Args to pass in to the constructor. Note: Ignored for singletons
-     * @return mixed Instance of the specified object
+     * @return T|mixed Instance of the specified object
      */
     protected function getNamedService($name, $asSingleton = true, $constructorArgs = [])
     {
@@ -1111,9 +1113,9 @@ public function getServiceSpec($name, $inherit = true)
     /**
      * Magic method to return an item directly
      *
-     * @param string $name
-     *              The named object to retrieve
-     * @return mixed
+     * @template T of object
+     * @param class-string<T> $name The named object to retrieve
+     * @return T|mixed
      */
     public function __get($name)
     {
@@ -1125,9 +1127,10 @@ public function __get($name)
      *
      * Additional parameters are passed through as
      *
-     * @param string $name
+     * @template T of object
+     * @param class-string<T> $name
      * @param mixed ...$argument arguments to pass to the constructor
-     * @return mixed A new instance of the specified object
+     * @return T|mixed A new instance of the specified object
      */
     public function create($name, $argument = null)
     {
@@ -1139,9 +1142,10 @@ public function create($name, $argument = null)
     /**
      * Creates an object with the supplied argument array
      *
-     * @param string $name Name of the class to create an object of
+     * @template T of object
+     * @param class-string<T> $name Name of the class to create an object of
      * @param array $constructorArgs Arguments to pass to the constructor
-     * @return mixed
+     * @return T|mixed
      */
     public function createWithArgs($name, $constructorArgs)
     {

src/Dev/FixtureFactory.php

@@ -121,7 +121,7 @@ public function createRaw($table, $identifier, $data)
      *
      * @param string $class The data class, as specified in your fixture file.  Parent classes won't work
      * @param string $identifier The identifier string, as provided in your fixture file
-     * @return int
+     * @return int|false
      */
     public function getId($class, $identifier)
     {
@@ -162,9 +162,10 @@ public function setId($class, $identifier, $databaseId)
     /**
      * Get an object from the fixture.
      *
-     * @param string $class The data class or table name, as specified in your fixture file.  Parent classes won't work
+     * @template T of DataObject
+     * @param class-string<T> $class The data class or table name, as specified in your fixture file.  Parent classes won't work
      * @param string $identifier The identifier string, as provided in your fixture file
-     * @return DataObject
+     * @return T|null
      */
     public function get($class, $identifier)
     {

src/Dev/SapphireTest.php

@@ -464,10 +464,11 @@ protected function allFixtureIDs($className)
     /**
      * Get an object from the fixture.
      *
-     * @param string $className The data class or table name, as specified in your fixture file. Parent classes won't work
+     * @template T of DataObject
+     * @param class-string<T> $className The data class or table name, as specified in your fixture file. Parent classes won't work
      * @param string $identifier The identifier string, as provided in your fixture file
      *
-     * @return DataObject
+     * @return T
      */
     protected function objFromFixture($className, $identifier)
     {

src/Dev/Validation/DatabaseAdminExtension.php

@@ -9,6 +9,7 @@
 /**
  * Hook up static validation to the deb/build process
  *
+ * @extends Extension<DatabaseAdmin>
  */
 class DatabaseAdminExtension extends Extension
 {

src/Forms/CompositeValidator.php

@@ -30,22 +30,18 @@
  * {
  *   $compositeValidator->addValidator(RequiredFields::create(['AdditionalContent']));
  * }
- *
- * Class CompositeValidator
- *
- * @package SilverStripe\Forms
  */
 class CompositeValidator extends Validator
 {
     /**
-     * @var array|Validator[]
+     * @var array<Validator>
      */
     private $validators;
 
     /**
      * CompositeValidator constructor.
      *
-     * @param array|Validator[] $validators
+     * @param array<Validator> $validators
      */
     public function __construct(array $validators = [])
     {
@@ -146,7 +142,7 @@ public function fieldIsRequired($fieldName)
     }
 
     /**
-     * @return array|Validator[]
+     * @return array<Validator>
      */
     public function getValidators(): array
     {
@@ -159,8 +155,9 @@ public function getValidators(): array
      * The keys for the return array match the keys in the unfiltered array. You cannot assume the keys will be
      * sequential or that the first key will be ZERO.
      *
-     * @param string $className
-     * @return array|Validator[]
+     * @template T of Validator
+     * @param class-string<T> $className
+     * @return T[]
      */
     public function getValidatorsByType(string $className): array
     {

src/Forms/FieldList.php

@@ -7,7 +7,7 @@
 /**
  * A list designed to hold form field instances.
  *
- * @method FormField[] getIterator()
+ * @extends ArrayList<FormField>
  */
 class FieldList extends ArrayList
 {

src/Forms/GridField/GridFieldConfig.php

@@ -31,7 +31,7 @@ class GridFieldConfig
     use Configurable;
 
     /**
-     * @var ArrayList
+     * @var ArrayList<GridFieldComponent>
      */
     protected $components = null;
 
@@ -111,7 +111,7 @@ public function removeComponentsByType($types)
     }
 
     /**
-     * @return ArrayList Of GridFieldComponent
+     * @return ArrayList<GridFieldComponent> Of GridFieldComponent
      */
     public function getComponents()
     {
@@ -124,8 +124,9 @@ public function getComponents()
     /**
      * Returns all components extending a certain class, or implementing a certain interface.
      *
-     * @param string $type Class name or interface
-     * @return ArrayList Of GridFieldComponent
+     * @template T of GridFieldComponent
+     * @param class-string<T> $type Class name or interface
+     * @return ArrayList<T> Of GridFieldComponent
      */
     public function getComponentsByType($type)
     {
@@ -141,8 +142,9 @@ public function getComponentsByType($type)
     /**
      * Returns the first available component with the given class or interface.
      *
-     * @param string $type ClassName
-     * @return GridFieldComponent
+     * @template T of GridFieldComponent
+     * @param class-string<T> $type ClassName
+     * @return T|null
      */
     public function getComponentByType($type)
     {