ENH Add generic types (#11108)

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.
silverstripe · Jan 17, 2024 · 357ed7a · 357ed7a
1 parent 583b762
commit 357ed7a
Show file tree

Hide file tree

Showing 100 changed files with 389 additions and 423 deletions.
diff --git a/src/Control/Director.php b/src/Control/Director.php
@@ -164,7 +164,6 @@ public static function mockRequest(
         // Build list of cleanup promises
         $finally = [];
 
-        /** @var Kernel $kernel */
         $kernel = Injector::inst()->get(Kernel::class);
         $kernel->nest();
         $finally[] = function () use ($kernel) {
@@ -1016,7 +1015,6 @@ public static function is_cli()
      */
     public static function get_environment_type()
     {
-        /** @var Kernel $kernel */
         $kernel = Injector::inst()->get(Kernel::class);
         return $kernel->getEnvironment();
     }

diff --git a/src/Control/HTTPResponse.php b/src/Control/HTTPResponse.php
@@ -411,7 +411,6 @@ protected function outputBody()
         // a more specific error description.
         $body = $this->getBody();
         if ($this->isError() && empty($body)) {
-            /** @var HandlerInterface $handler */
             $handler = Injector::inst()->get(HandlerInterface::class);
             $formatter = $handler->getFormatter();
             echo $formatter->format([

diff --git a/src/Control/Middleware/FlushMiddleware.php b/src/Control/Middleware/FlushMiddleware.php
@@ -16,7 +16,6 @@ class FlushMiddleware implements HTTPMiddleware
 {
     public function process(HTTPRequest $request, callable $delegate)
     {
-        /** @var BaseKernel $kernel */
         $kernel = Injector::inst()->get(Kernel::class);
         if ((method_exists($kernel, 'isFlushed') && $kernel->isFlushed())) {
             // Disable cache when flushing

diff --git a/src/Control/Middleware/URLSpecialsMiddleware/FlushScheduler.php b/src/Control/Middleware/URLSpecialsMiddleware/FlushScheduler.php
@@ -30,7 +30,6 @@ public function scheduleFlush(HTTPRequest $request)
     {
         $flush = array_key_exists('flush', $request->getVars() ?? []) || ($request->getURL() === 'dev/build');
 
-        /** @var BaseKernel $kernel */
         $kernel = Injector::inst()->get(Kernel::class);
         if (!$flush || (method_exists($kernel, 'isFlushed') && $kernel->isFlushed())) {
             return false;

diff --git a/src/Core/Extension.php b/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()
     {

diff --git a/src/Core/Injector/Injector.php b/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>|string $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>|string $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>|string $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>|string $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>|string $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)
     {

diff --git a/src/Core/Manifest/ModuleManifest.php b/src/Core/Manifest/ModuleManifest.php
@@ -148,7 +148,6 @@ public function activateConfig()
     {
         $modules = $this->getModules();
         // Work in reverse priority, so the higher priority modules get later execution
-        /** @var Module $module */
         foreach (array_reverse($modules ?? []) as $module) {
             $module->activate();
         }
@@ -262,7 +261,6 @@ public function getModuleByPath($path)
             return null;
         }
 
-        /** @var Module $rootModule */
         $rootModule = null;
 
         // Find based on loaded modules

diff --git a/src/Core/Manifest/ModuleResource.php b/src/Core/Manifest/ModuleResource.php
@@ -88,7 +88,6 @@ public function getRelativePath()
      */
     public function getURL()
     {
-        /** @var ResourceURLGenerator $generator */
         $generator = Injector::inst()->get(ResourceURLGenerator::class);
         return $generator->urlForResource($this);
     }

diff --git a/src/Core/Manifest/ModuleResourceLoader.php b/src/Core/Manifest/ModuleResourceLoader.php
@@ -51,7 +51,6 @@ public function resolveURL($resource)
         $resource = $this->resolveResource($resource);
 
         // Resolve resource to url
-        /** @var ResourceURLGenerator $generator */
         $generator = Injector::inst()->get(ResourceURLGenerator::class);
         return $generator->urlForResource($resource);
     }

diff --git a/src/Dev/FixtureFactory.php b/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)
     {

diff --git a/src/Dev/FunctionalTest.php b/src/Dev/FunctionalTest.php
@@ -337,7 +337,6 @@ public function assertPartialHTMLMatchBySelector($selector, $expectedMatches, $m
 
         $actuals = [];
         if ($items) {
-            /** @var SimpleXMLElement $item */
             foreach ($items as $item) {
                 $actuals[$item->asXML()] = true;
             }
@@ -371,7 +370,6 @@ public function assertExactHTMLMatchBySelector($selector, $expectedMatches, $mes
 
         $actuals = [];
         if ($items) {
-            /** @var SimpleXMLElement $item */
             foreach ($items as $item) {
                 $actuals[] = $item->asXML();
             }

diff --git a/src/Dev/SapphireTest.php b/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)
     {
@@ -563,7 +564,6 @@ protected function tearDown(): void
      */
     public function clearEmails()
     {
-        /** @var MailerInterface $mailer */
         $mailer = Injector::inst()->get(MailerInterface::class);
         if ($mailer instanceof TestMailer) {
             $mailer->clearEmails();
@@ -584,7 +584,6 @@ public function clearEmails()
      */
     public static function findEmail($to, $from = null, $subject = null, $content = null)
     {
-        /** @var MailerInterface $mailer */
         $mailer = Injector::inst()->get(MailerInterface::class);
         if ($mailer instanceof TestMailer) {
             return $mailer->findEmail($to, $from, $subject, $content);
@@ -1041,7 +1040,6 @@ public function logInAs($member)
      */
     public function logOut()
     {
-        /** @var IdentityStore $store */
         $store = Injector::inst()->get(IdentityStore::class);
         $store->logOut();
     }

diff --git a/src/Dev/State/FixtureTestState.php b/src/Dev/State/FixtureTestState.php
@@ -175,7 +175,6 @@ protected function loadFixtures(SapphireTest $test)
      */
     protected function loadFixture($fixtureFile, SapphireTest $test)
     {
-        /** @var YamlFixture $fixture */
         $fixture = Injector::inst()->create(YamlFixture::class, $fixtureFile);
         $fixture->writeInto($this->getFixtureFactory(get_class($test)));
     }

diff --git a/src/Dev/State/LoggerState.php b/src/Dev/State/LoggerState.php
@@ -18,7 +18,6 @@ class LoggerState implements TestState
 {
     public function setUp(SapphireTest $test)
     {
-        /** @var Logger $userLogger */
         $userLogger = Injector::inst()->get(LoggerInterface::class);
         if ($userLogger && $userLogger instanceof Logger) {
             $userLogger->setHandlers([new NullHandler()]);

diff --git a/src/Dev/State/SapphireTestState.php b/src/Dev/State/SapphireTestState.php
@@ -72,7 +72,6 @@ public function setUp(SapphireTest $test)
     public function tearDown(SapphireTest $test)
     {
         // Tear down in reverse order
-        /** @var TestState $state */
         foreach (array_reverse($this->states ?? []) as $state) {
             $state->tearDown($test);
         }
@@ -93,7 +92,6 @@ public function setUpOnce($class)
     public function tearDownOnce($class)
     {
         // Tear down in reverse order
-        /** @var TestState $state */
         foreach (array_reverse($this->states ?? []) as $state) {
             $state->tearDownOnce($class);
         }

diff --git a/src/Dev/TestSession.php b/src/Dev/TestSession.php
@@ -208,7 +208,6 @@ public function sendRequest($method, $url, $data, $headers = null, $session = nu
      */
     public function submitForm(string $formID, string $button = null, array $data = [], bool $withSecurityToken = true): HTTPResponse
     {
-        /** @var Crawler $page */
         $page = $this->lastPage();
         if ($page) {
             try {

diff --git a/src/Dev/Validation/DatabaseAdminExtension.php b/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
 {

diff --git a/src/Forms/CheckboxSetField.php b/src/Forms/CheckboxSetField.php
@@ -58,7 +58,7 @@ public function Field($properties = [])
     /**
      * Gets the list of options to render in this formfield
      *
-     * @return ArrayList
+     * @return ArrayList<ArrayData>
      */
     public function getOptions()
     {

diff --git a/src/Forms/CompositeField.php b/src/Forms/CompositeField.php
@@ -76,7 +76,6 @@ public function getSchemaDataDefaults()
         $children = $this->getChildren();
         if ($children && $children->count()) {
             $childSchema = [];
-            /** @var FormField $child */
             foreach ($children as $child) {
                 $childSchema[] = $child->getSchemaData();
             }
@@ -132,7 +131,6 @@ public function getName()
         $fieldList = $this->FieldList();
         $compositeTitle = '';
         $count = 0;
-        /** @var FormField $subfield */
         foreach ($fieldList as $subfield) {
             $compositeTitle .= $subfield->getName();
             if ($subfield->getName()) {
@@ -415,7 +413,6 @@ public function performReadonlyTransformation()
         $clone = clone $this;
         if ($clone->getChildren()) {
             foreach ($clone->getChildren() as $child) {
-                        /** @var FormField $child */
                 $child = $child->transform(new ReadonlyTransformation());
                 $newChildren->push($child);
             }
@@ -441,7 +438,6 @@ public function performDisabledTransformation()
         $clone = clone $this;
         if ($clone->getChildren()) {
             foreach ($clone->getChildren() as $child) {
-                        /** @var FormField $child */
                 $child = $child->transform(new DisabledTransformation());
                 $newChildren->push($child);
             }
@@ -482,7 +478,6 @@ public function fieldPosition($field)
 
         $i = 0;
         foreach ($this->children as $child) {
-            /** @var FormField $child */
             if ($child->getName() == $field->getName()) {
                 return $i;
             }
@@ -540,7 +535,6 @@ public function validate($validator)
     {
         $valid = true;
         foreach ($this->children as $child) {
-            /** @var FormField $child */
             $valid = ($child && $child->validate($validator) && $valid);
         }
         return $this->extendValidationResult($valid, $validator);
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,6 +9,7 @@ @@
     /**
      * Hook up static validation to the deb/build process
      *
+     * @extends Extension<DatabaseAdmin>
      */
     class DatabaseAdminExtension extends Extension
     {
@@ Expand Down @@