From 3847b3ea19529f08f313891c5ec5c015e407ec8a Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Fri, 19 Jan 2024 10:00:46 +1300 Subject: [PATCH] ENH Add generic types (#2914) --- code/Controllers/CMSMain.php | 14 -------------- code/Controllers/ContentController.php | 15 +++++++++------ .../LeftAndMainBatchActionsExtension.php | 4 ++++ .../LeftAndMainPageIconsExtension.php | 4 +++- code/Controllers/ModelAsController.php | 1 - code/Controllers/OldPageRedirector.php | 5 +++-- code/Forms/InternalLinkModalExtension.php | 14 ++------------ code/Model/RedirectorPage.php | 1 - code/Model/RedirectorPageController.php | 3 ++- code/Model/SiteTree.php | 16 ++++------------ code/Model/SiteTreeExtension.php | 3 +++ code/Model/SiteTreeLinkTracking.php | 2 ++ code/Model/SiteTreeLinkTracking_Parser.php | 1 - code/Reports/EmptyPagesReport.php | 3 +-- code/Search/ContentControllerSearchExtension.php | 3 +++ 15 files changed, 36 insertions(+), 53 deletions(-) diff --git a/code/Controllers/CMSMain.php b/code/Controllers/CMSMain.php index 8dc694bb..a30c7982 100644 --- a/code/Controllers/CMSMain.php +++ b/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( diff --git a/code/Controllers/ContentController.php b/code/Controllers/ContentController.php index d4c6ca56..97cb3a2d 100644 --- a/code/Controllers/ContentController.php +++ b/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 */ 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 */ 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 + */ public function Menu($level) { return $this->getMenu($level); diff --git a/code/Controllers/LeftAndMainBatchActionsExtension.php b/code/Controllers/LeftAndMainBatchActionsExtension.php index 8e582972..5e629421 100644 --- a/code/Controllers/LeftAndMainBatchActionsExtension.php +++ b/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 + */ class LeftAndMainBatchActionsExtension extends Extension { public function updateBatchActionsForm(&$form) diff --git a/code/Controllers/LeftAndMainPageIconsExtension.php b/code/Controllers/LeftAndMainPageIconsExtension.php index a7359654..e962322f 100644 --- a/code/Controllers/LeftAndMainPageIconsExtension.php +++ b/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 */ class LeftAndMainPageIconsExtension extends Extension implements Flushable { - /** * @throws InvalidArgumentException * @throws ReflectionException diff --git a/code/Controllers/ModelAsController.php b/code/Controllers/ModelAsController.php index 36200e34..edafeab6 100644 --- a/code/Controllers/ModelAsController.php +++ b/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) { diff --git a/code/Controllers/OldPageRedirector.php b/code/Controllers/OldPageRedirector.php index 0ff0de60..6d64725d 100644 --- a/code/Controllers/OldPageRedirector.php +++ b/code/Controllers/OldPageRedirector.php @@ -10,9 +10,11 @@ use SilverStripe\Control\HTTPResponse; use SilverStripe\Control\HTTPResponse_Exception; use SilverStripe\Core\Extension; +/** + * @extends Extension + */ 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 diff --git a/code/Forms/InternalLinkModalExtension.php b/code/Forms/InternalLinkModalExtension.php index 069de906..071c2efb 100644 --- a/code/Forms/InternalLinkModalExtension.php +++ b/code/Forms/InternalLinkModalExtension.php @@ -9,7 +9,8 @@ use SilverStripe\Forms\Form; /** * Decorates ModalController with insert internal link - * @see ModalController + * + * @extends Extension */ 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 * diff --git a/code/Model/RedirectorPage.php b/code/Model/RedirectorPage.php index 1aabd763..bb4ea2b7 100644 --- a/code/Model/RedirectorPage.php +++ b/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)) { diff --git a/code/Model/RedirectorPageController.php b/code/Model/RedirectorPageController.php index 51dce80d..79d1446b 100644 --- a/code/Model/RedirectorPageController.php +++ b/code/Model/RedirectorPageController.php @@ -7,6 +7,8 @@ use SilverStripe\Control\HTTPResponse_Exception; /** * Controller for the {@link RedirectorPage}. + * + * @extends PageController */ 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 diff --git a/code/Model/SiteTree.php b/code/Model/SiteTree.php index f8e2b9d1..7891be26 100755 --- a/code/Model/SiteTree.php +++ b/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 */ 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 */ 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 */ 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 */ 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(); diff --git a/code/Model/SiteTreeExtension.php b/code/Model/SiteTreeExtension.php index dd1cfab2..e1b73a5c 100644 --- a/code/Model/SiteTreeExtension.php +++ b/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 */ abstract class SiteTreeExtension extends DataExtension { diff --git a/code/Model/SiteTreeLinkTracking.php b/code/Model/SiteTreeLinkTracking.php index 15283596..8adb8aa9 100644 --- a/code/Model/SiteTreeLinkTracking.php +++ b/code/Model/SiteTreeLinkTracking.php @@ -28,6 +28,8 @@ use SilverStripe\View\Parsers\HTMLValue; * * @property DataObject|SiteTreeLinkTracking $owner * @method ManyManyThroughList LinkTracking() + * + * @extends DataExtension */ class SiteTreeLinkTracking extends DataExtension { diff --git a/code/Model/SiteTreeLinkTracking_Parser.php b/code/Model/SiteTreeLinkTracking_Parser.php index 857c6c12..f50813e5 100644 --- a/code/Model/SiteTreeLinkTracking_Parser.php +++ b/code/Model/SiteTreeLinkTracking_Parser.php @@ -61,7 +61,6 @@ class SiteTreeLinkTracking_Parser $matches = []; if (preg_match('/\[sitetree_link(?:\s*|%20|,)?id=(?[0-9]+)\](#(?.*))?/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. diff --git a/code/Reports/EmptyPagesReport.php b/code/Reports/EmptyPagesReport.php index 814e5183..cf6f7add 100644 --- a/code/Reports/EmptyPagesReport.php +++ b/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 */ public function sourceRecords($params = null) { diff --git a/code/Search/ContentControllerSearchExtension.php b/code/Search/ContentControllerSearchExtension.php index 64091f17..6cfae5a8 100644 --- a/code/Search/ContentControllerSearchExtension.php +++ b/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 */ class ContentControllerSearchExtension extends Extension {