ENH Add generic types (#2914)

code/Controllers/CMSMain.php

@@ -1038,10 +1038,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
             ->Link;
     }
 
-    /**
-     * @param bool $unlinked
-     * @return ArrayList
-     */
     public function Breadcrumbs($unlinked = false)
     {
         $items = new ArrayList();
@@ -1293,7 +1289,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
         if (!$id) {
             $id = $this->currentPageID();
         }
-        /** @var SiteTree $record */
         $record = $this->getRecord($id);
 
         // Check parent form can be generated
@@ -1639,7 +1634,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
         }
         $gridField = GridField::create('Page', 'Pages', $list, $gridFieldConfig);
         $gridField->setAttribute('cms-loading-ignore-url-params', true);
-        /** @var GridFieldDataColumns $columns */
         $columns = $gridField->getConfig()->getComponentByType(GridFieldDataColumns::class);
 
         // Don't allow navigating into children nodes on filtered lists
@@ -1648,7 +1642,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
             'i18n_singular_name' => _t('SilverStripe\\CMS\\Model\\SiteTree.PAGETYPE', 'Page Type'),
             'LastEdited' => _t('SilverStripe\\CMS\\Model\\SiteTree.LASTUPDATED', 'Last Updated'),
         ];
-        /** @var GridFieldSortableHeader $sortableHeader */
         $sortableHeader = $gridField->getConfig()->getComponentByType(GridFieldSortableHeader::class);
         $sortableHeader->setFieldSorting(['getTreeTitle' => 'Title']);
         $gridField->getState()->ParentID = $parentID;
@@ -1891,7 +1884,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
             throw new HTTPResponse_Exception("SiteTree #$id not found", 400);
         }
 
-        /** @var SiteTree $record */
         $table = DataObject::singleton(SiteTree::class)->baseTable();
         $liveTable = DataObject::singleton(SiteTree::class)->stageTable($table, Versioned::LIVE);
         $record = Versioned::get_one_by_stage(SiteTree::class, Versioned::LIVE, [
@@ -1964,7 +1956,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
     public function archive(array $data, Form $form): HTTPResponse
     {
         $id = $data['ID'];
-        /** @var SiteTree $record */
         $record = SiteTree::get()->byID($id);
         if (!$record || !$record->exists()) {
             throw new HTTPResponse_Exception("Bad record ID #$id", 404);
@@ -2141,7 +2132,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
         }
 
         $id = (int)$data['ID'];
-        /** @var SiteTree $restoredPage */
         $restoredPage = Versioned::get_latest_version(SiteTree::class, $id);
         if (!$restoredPage) {
             return new HTTPResponse("SiteTree #$id not found", 400);
@@ -2169,7 +2159,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
         }
 
         if (($id = $this->urlParams['ID']) && is_numeric($id)) {
-            /** @var SiteTree $page */
             $page = SiteTree::get()->byID($id);
             if ($page && !$page->canCreate(null, ['Parent' => $page->Parent()])) {
                 return Security::permissionFailure($this);
@@ -2178,7 +2167,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
                 throw new HTTPResponse_Exception("Bad record ID #$id", 404);
             }
 
-            /** @var SiteTree $newPage */
             $newPage = $page->duplicate();
 
             // ParentID can be hard-set in the URL.  This is useful for pages with multiple parents
@@ -2213,7 +2201,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
         }
         Environment::increaseTimeLimitTo();
         if (($id = $this->urlParams['ID']) && is_numeric($id)) {
-            /** @var SiteTree $page */
             $page = SiteTree::get()->byID($id);
             if ($page && !$page->canCreate(null, ['Parent' => $page->Parent()])) {
                 return Security::permissionFailure($this);
@@ -2222,7 +2209,6 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
                 throw new HTTPResponse_Exception("Bad record ID #$id", 404);
             }
 
-            /** @var SiteTree $newPage */
             $newPage = $page->duplicateWithChildren();
 
             $this->getResponse()->addHeader(

code/Controllers/ContentController.php

@@ -45,11 +45,12 @@ use SilverStripe\View\SSViewer;
  * Subclasses of ContentController are generally instantiated by ModelAsController; this will create
  * a controller based on the URLSegment action variable, by looking in the SiteTree table.
  *
+ * @template T of SiteTree
  */
 class ContentController extends Controller
 {
     /**
-     * @var SiteTree
+     * @var T
      */
     protected $dataRecord;
 
@@ -71,7 +72,7 @@ class ContentController extends Controller
      * The ContentController will take the URLSegment parameter from the URL and use that to look
      * up a SiteTree record.
      *
-     * @param SiteTree $dataRecord
+     * @param T|null $dataRecord
      */
     public function __construct($dataRecord = null)
     {
@@ -110,7 +111,7 @@ class ContentController extends Controller
      * Return the children of a given page. The parent reference can either be a page link or an ID.
      *
      * @param string|int $parentRef
-     * @return SS_List
+     * @return SS_List<SiteTree>
      */
     public function ChildrenOf($parentRef)
     {
@@ -188,7 +189,6 @@ class ContentController extends Controller
      */
     public function handleRequest(HTTPRequest $request): HTTPResponse
     {
-        /** @var SiteTree $child */
         $child = null;
         $action = $request->param('Action');
 
@@ -243,6 +243,7 @@ class ContentController extends Controller
 
     /**
      * Returns the associated database record
+     * @return T
      */
     public function data()
     {
@@ -254,7 +255,7 @@ class ContentController extends Controller
     /**
      * Returns a fixed navigation menu of the given level.
      * @param int $level Menu level to return.
-     * @return ArrayList
+     * @return ArrayList<SiteTree>
      */
     public function getMenu($level = 1)
     {
@@ -284,7 +285,6 @@ class ContentController extends Controller
         // We might need to create a show in menu permission
         if (isset($result)) {
             foreach ($result as $page) {
-                /** @var SiteTree $page */
                 if ($page->canView()) {
                     $visible[] = $page;
                 }
@@ -294,6 +294,9 @@ class ContentController extends Controller
         return new ArrayList($visible);
     }
 
+    /**
+     * @return ArrayList<SiteTree>
+     */
     public function Menu($level)
     {
         return $this->getMenu($level);

code/Controllers/LeftAndMainBatchActionsExtension.php

@@ -2,9 +2,13 @@
 
 namespace SilverStripe\CMS\Controllers;
 
+use SilverStripe\Admin\LeftAndMain;
 use SilverStripe\CMS\Controllers\CMSMain;
 use SilverStripe\Core\Extension;
 
+/**
+ * @extends Extension<LeftAndMain>
+ */
 class LeftAndMainBatchActionsExtension extends Extension
 {
     public function updateBatchActionsForm(&$form)

code/Controllers/LeftAndMainPageIconsExtension.php

@@ -5,6 +5,7 @@ namespace SilverStripe\CMS\Controllers;
 use Psr\SimpleCache\CacheInterface;
 use Psr\SimpleCache\InvalidArgumentException;
 use ReflectionException;
+use SilverStripe\Admin\LeftAndMain;
 use SilverStripe\CMS\Model\SiteTree;
 use SilverStripe\Core\ClassInfo;
 use SilverStripe\Core\Config\Config;
@@ -16,10 +17,11 @@ use SilverStripe\View\Requirements;
 
 /**
  * Extension to include custom page icons
+ *
+ * @extends Extension<LeftAndMain>
  */
 class LeftAndMainPageIconsExtension extends Extension implements Flushable
 {
-
     /**
      * @throws InvalidArgumentException
      * @throws ReflectionException

code/Controllers/ModelAsController.php

@@ -123,7 +123,6 @@ class ModelAsController extends Controller implements NestedController
         if (SiteTree::config()->get('nested_urls')) {
             $conditions[] = [sprintf('"%s"."ParentID"', $tableName) => 0];
         }
-        /** @var SiteTree $sitetree */
         $sitetree = DataObject::get_one(SiteTree::class, $conditions);
 
         if (!$sitetree) {

code/Controllers/OldPageRedirector.php

@@ -10,9 +10,11 @@ use SilverStripe\Control\HTTPResponse;
 use SilverStripe\Control\HTTPResponse_Exception;
 use SilverStripe\Core\Extension;
 
+/**
+ * @extends Extension<ContentController|ModelAsController>
+ */
 class OldPageRedirector extends Extension
 {
-
     /**
      * On every URL that generates a 404, we'll capture it here and see if we can
      * find an old URL that it should be redirecting to.
@@ -75,7 +77,6 @@ class OldPageRedirector extends Extension
                 'ParentID' => is_numeric($parent) ? $parent : $parent->ID,
             ]);
         }
-        /** @var SiteTree $page */
         $page = $pages->first();
         if (!$page) {
             // If we haven't found a candidate, lets resort to finding an old page with this URL segment

code/Forms/InternalLinkModalExtension.php

@@ -9,7 +9,8 @@ use SilverStripe\Forms\Form;
 
 /**
  * Decorates ModalController with insert internal link
- * @see ModalController
+ *
+ * @extends Extension<ModalController>
  */
 class InternalLinkModalExtension extends Extension
 {
@@ -22,17 +23,6 @@ class InternalLinkModalExtension extends Extension
         'editorAnchorLink',
     ];
 
-    /**
-     * @return ModalController
-     */
-    public function getOwner()
-    {
-        /** @var ModalController $owner */
-        $owner = $this->owner;
-        return $owner;
-    }
-
-
     /**
      * Form for inserting internal link pages
      *

code/Model/RedirectorPage.php

@@ -120,7 +120,6 @@ class RedirectorPage extends Page
         }
 
         // Check internal redirect
-        /** @var SiteTree $linkTo */
         $linkTo = $this->LinkToID ? SiteTree::get()->byID($this->LinkToID) : null;
 
         if (empty($linkTo)) {

code/Model/RedirectorPageController.php

@@ -7,6 +7,8 @@ use SilverStripe\Control\HTTPResponse_Exception;
 
 /**
  * Controller for the {@link RedirectorPage}.
+ *
+ * @extends PageController<RedirectorPage>
  */
 class RedirectorPageController extends PageController
 {
@@ -26,7 +28,6 @@ class RedirectorPageController extends PageController
      */
     public function index(HTTPRequest $request)
     {
-        /** @var RedirectorPage $page */
         $page = $this->data();
 
         // Redirect if we can

code/Model/SiteTree.php

@@ -608,7 +608,6 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
             return null; // There were no suitable matches at all.
         }
 
-        /** @var SiteTree $page */
         $link = Convert::raw2att($page->Link());
 
         if ($content) {
@@ -886,12 +885,10 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
      */
     public function duplicateWithChildren()
     {
-        /** @var SiteTree $clone */
         $clone = $this->duplicate();
         $children = $this->AllChildren();
 
         if ($children) {
-            /** @var SiteTree $child */
             $sort = 0;
             foreach ($children as $child) {
                 $childClone = method_exists($child, 'duplicateWithChildren')
@@ -914,7 +911,6 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
      */
     public function duplicateAsChild($id)
     {
-        /** @var SiteTree $newSiteTree */
         $newSiteTree = $this->duplicate();
         $newSiteTree->ParentID = $id;
         $newSiteTree->Sort = 0;
@@ -950,7 +946,7 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
      * @param boolean|string $stopAtPageType ClassName of a page to stop the upwards traversal.
      * @param boolean $showHidden Include pages marked with the attribute ShowInMenus = 0
      *
-     * @return ArrayList
+     * @return ArrayList<SiteTree>
     */
     public function getBreadcrumbItems($maxDepth = 20, $stopAtPageType = false, $showHidden = false)
     {
@@ -1416,7 +1412,6 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
                 if (eval("return $condition;")) {
                     $collator[] = $item;
                 }
-                /** @var SiteTree $item */
                 $item->collateDescendants($condition, $collator);
             }
             return true;
@@ -1768,7 +1763,6 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
         // If deleting this page, delete all its children.
         if ($this->isInDB() && SiteTree::config()->get('enforce_strict_hierarchy')) {
             foreach ($this->AllChildren() as $child) {
-                /** @var SiteTree $child */
                 $child->delete();
             }
         }
@@ -1966,7 +1960,7 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
     /**
      * Get the back-link tracking objects that link to this page
      *
-     * @return ArrayList|DataObject[]
+     * @return ArrayList<DataObject>
      */
     public function BackLinkTracking()
     {
@@ -2007,7 +2001,7 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
      * Returns the pages that depend on this page. This includes virtual pages, pages that link to it, etc.
      *
      * @param bool $includeVirtuals Set to false to exlcude virtual pages.
-     * @return ArrayList|SiteTree[]
+     * @return ArrayList<SiteTree>
      */
     public function DependentPages($includeVirtuals = true)
     {
@@ -2057,7 +2051,7 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
     /**
      * Return all virtual pages that link to this page.
      *
-     * @return DataList
+     * @return DataList<SiteTree>
      */
     public function VirtualPages()
     {
@@ -2104,7 +2098,6 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
                 false,
                 $dependentPages
             );
-            /** @var GridFieldDataColumns $dataColumns */
             $dataColumns = $dependentTable->getConfig()->getComponentByType(GridFieldDataColumns::class);
             $dataColumns
                 ->setDisplayFields($dependentColumns)
@@ -3333,7 +3326,6 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
         $this->flushCache();
 
         // Need to mark pages depending to this one as broken
-        /** @var Page $page */
         foreach ($this->DependentPages() as $page) {
             // Update sync link tracking
             $page->syncLinkTracking();

code/Model/SiteTreeExtension.php

@@ -7,6 +7,9 @@ use SilverStripe\Security\Member;
 
 /**
  * Plug-ins for additional functionality in your SiteTree classes.
+ *
+ * @template T of SiteTree
+ * @extends DataExtension<T>
  */
 abstract class SiteTreeExtension extends DataExtension
 {

code/Model/SiteTreeLinkTracking.php

@@ -28,6 +28,8 @@ use SilverStripe\View\Parsers\HTMLValue;
  *
  * @property DataObject|SiteTreeLinkTracking $owner
  * @method ManyManyThroughList<SiteTree> LinkTracking()
+ *
+ * @extends DataExtension<DataObject>
  */
 class SiteTreeLinkTracking extends DataExtension
 {

code/Model/SiteTreeLinkTracking_Parser.php

@@ -61,7 +61,6 @@ class SiteTreeLinkTracking_Parser
             $matches = [];
             if (preg_match('/\[sitetree_link(?:\s*|%20|,)?id=(?<id>[0-9]+)\](#(?<anchor>.*))?/i', $href ?? '', $matches)) {
                 // Check if page link is broken
-                /** @var SiteTree $page */
                 $page = DataObject::get_by_id(SiteTree::class, $matches['id']);
                 if (!$page) {
                     // Page doesn't exist.

code/Reports/EmptyPagesReport.php

@@ -9,7 +9,6 @@ use SilverStripe\Reports\Report;
 
 class EmptyPagesReport extends Report
 {
-
     public function title()
     {
         return _t(__CLASS__.'.EMPTYPAGES', "Pages without content");
@@ -29,7 +28,7 @@ class EmptyPagesReport extends Report
      * Gets the source records
      *
      * @param array $params
-     * @return DataList
+     * @return DataList<SiteTree>
      */
     public function sourceRecords($params = null)
     {

code/Search/ContentControllerSearchExtension.php

@@ -2,6 +2,7 @@
 
 namespace SilverStripe\CMS\Search;
 
+use SilverStripe\CMS\Controllers\ContentController;
 use SilverStripe\Control\HTTPRequest;
 use SilverStripe\Core\Extension;
 use SilverStripe\Forms\TextField;
@@ -12,6 +13,8 @@ use SilverStripe\ORM\Search\FulltextSearchable;
 
 /**
  * Extension to provide a search interface when applied to ContentController
+ *
+ * @extends Extension<ContentController>
  */
 class ContentControllerSearchExtension extends Extension
 {