API Deprecate and update code in preparation for CMS 6 (#3023)

Author: GuySartorelli

code/Model/RedirectorPage.php

@@ -23,8 +23,13 @@
  */
 class RedirectorPage extends Page
 {
+    /**
+     * @deprecated 5.4.0 use class_description instead.
+     */
     private static $description = 'Redirects requests to another location';
 
+    private static string $class_description = 'Redirects requests to another location';
+
     private static $icon_class = 'font-icon-p-redirect';
 
     private static $show_stage_link = false;

code/Model/SiteTree.php

@@ -136,6 +136,7 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
      * Used as a cache for `SiteTree::allowedChildren()`
      * Drastically reduces admin page load when there are a lot of page types
      * @var array
+     * @deprecated 5.4.0 will be moved to SilverStripe\ORM\Hierarchy\Hierarchy->cache_allowedChildren
      */
     protected static $_allowedChildren = [];
 
@@ -419,6 +420,7 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
      *
      * @config
      * @var string
+     * @deprecated 5.4.0 use class_description instead.
      */
     private static $description = null;
 
@@ -431,9 +433,15 @@ class SiteTree extends DataObject implements PermissionProvider, i18nEntityProvi
      *
      * @config
      * @var string
+     * @deprecated 5.4.0 use base_class_description instead.
      */
     private static $base_description = 'Generic content page';
 
+    /**
+     * Description for Page and SiteTree classes, but not inherited by subclasses.
+     */
+    private static string $base_class_description = 'Generic content page';
+
     /**
      * @var array
      */
@@ -3248,25 +3256,24 @@ public function getPageIconURL()
      */
     public function classDescription()
     {
+        // Ensure base class has an appropriate description if not explicitly set,
+        // since we can't set that config for projects.
         $base = in_array(static::class, [Page::class, SiteTree::class]);
         if ($base) {
-            return $this->config()->get('base_description');
+            $baseDescription = static::config()->get('base_class_description');
+            // Fall back to the deprecated config
+            if (!$baseDescription) {
+                $baseDescription = static::config('base_description');
+            }
+            return $baseDescription;
         }
-        return $this->config()->get('description');
-    }
-
-    /**
-     * Get localised description for this page
-     *
-     * @return string|null
-     */
-    public function i18n_classDescription()
-    {
-        $description = $this->classDescription();
-        if ($description) {
-            return _t(static::class.'.DESCRIPTION', $description);
+        // For all other classes, use the direct class_description config
+        $description = parent::classDescription();
+        if (!$description) {
+            // Fall back to the deprecated config
+            $description = static::config()->get('description');
         }
-        return null;
+        return $description;
     }
 
     /**

code/Model/VirtualPage.php

@@ -26,8 +26,13 @@
  */
 class VirtualPage extends Page
 {
+    /**
+     * @deprecated 5.4.0 use class_description instead.
+     */
     private static $description = 'Displays the content of another page';
 
+    private static string $class_description = 'Displays the content of another page';
+
     private static $icon_class = 'font-icon-p-virtual';
 
     public static $virtualFields;

lang/en.yml

@@ -149,6 +149,7 @@ en:
     HelpChars: ' Special characters are automatically converted or removed.'
     OK: OK
   SilverStripe\CMS\Model\RedirectorPage:
+    CLASS_DESCRIPTION: 'Redirects to an internal page or an external URL'
     DESCRIPTION: 'Redirects to an internal page or an external URL'
     FILE: File
     HEADER: 'This page will redirect users to another page'
@@ -188,6 +189,7 @@ en:
     BUTTONSAVEPUBLISH: Publish
     BUTTONUNPUBLISH: Unpublish
     BUTTONUNPUBLISHDESC: 'Remove this page from the published site'
+    CLASS_DESCRIPTION: 'Generic content page'
     Comments: Comments
     Content: Content
     DEFAULTABOUTCONTENT: '<p>You can fill this page out with your own content, or delete it and create your own pages.</p>'
@@ -332,6 +334,7 @@ en:
     many_many_LinkTracking: 'Link tracking'
   SilverStripe\CMS\Model\VirtualPage:
     CHOOSE: 'Linked Page'
+    CLASS_DESCRIPTION: 'Displays the content of another page'
     DESCRIPTION: 'Displays the content of another page'
     EditLink: edit
     HEADER: 'This is a virtual page'