API Strong typing for the view layer

silverstripe · Aug 22, 2024 · 3f21132 · 3f21132
1 parent f3ff4e0
commit 3f21132
Show file tree

Hide file tree

Showing 64 changed files with 650 additions and 1,228 deletions.
diff --git a/src/Control/RSS/RSSFeed_Entry.php b/src/Control/RSS/RSSFeed_Entry.php
@@ -17,13 +17,6 @@
  */
 class RSSFeed_Entry extends ViewableData
 {
-    /**
-     * The object that represents the item, it contains all the data.
-     *
-     * @var mixed
-     */
-    protected $failover;
-
     /**
      * Name of the title field of feed entries
      *

diff --git a/src/Dev/TaskRunner.php b/src/Dev/TaskRunner.php
@@ -236,7 +236,7 @@ public function canInit(): bool
         }
         return count($this->getTaskList()) > 0;
     }
-    
+
     public function providePermissions(): array
     {
         return [

diff --git a/src/Forms/CompositeField.php b/src/Forms/CompositeField.php
@@ -514,7 +514,7 @@ public function makeFieldReadonly($field)
         return false;
     }
 
-    public function debug()
+    public function debug(): string
     {
         $class = static::class;
         $result = "$class ($this->name) <ul>";

diff --git a/src/Forms/Form.php b/src/Forms/Form.php
@@ -521,7 +521,7 @@ public function setFieldMessage(
         return $this;
     }
 
-    public function castingHelper($field, bool $useFallback = true)
+    public function castingHelper(string $field, bool $useFallback = true): ?string
     {
         // Override casting for field message
         if (strcasecmp($field ?? '', 'Message') === 0 && ($helper = $this->getMessageCastingHelper())) {
@@ -1547,10 +1547,8 @@ public function getData()
      *
      * This is returned when you access a form as $FormObject rather
      * than <% with FormObject %>
-     *
-     * @return DBHTMLText
      */
-    public function forTemplate()
+    public function forTemplate(): string
     {
         if (!$this->canBeCached()) {
             HTTPCacheControlMiddleware::singleton()->disableCache();
@@ -1750,7 +1748,7 @@ public function removeExtraClass($class)
         return $this;
     }
 
-    public function debug()
+    public function debug(): string
     {
         $class = static::class;
         $result = "<h3>$class</h3><ul>";

diff --git a/src/Forms/FormField.php b/src/Forms/FormField.php
@@ -790,7 +790,7 @@ public function securityTokenEnabled()
         return $form->getSecurityToken()->isEnabled();
     }
 
-    public function castingHelper($field, bool $useFallback = true)
+    public function castingHelper(string $field, bool $useFallback = true): ?string
     {
         // Override casting for field message
         if (strcasecmp($field ?? '', 'Message') === 0 && ($helper = $this->getMessageCastingHelper())) {
@@ -1269,7 +1269,7 @@ public function getDescription()
     /**
      * @return string
      */
-    public function debug()
+    public function debug(): string
     {
         $strValue = is_string($this->value) ? $this->value : print_r($this->value, true);
 
@@ -1286,10 +1286,8 @@ public function debug()
     /**
      * This function is used by the template processor. If you refer to a field as a $ variable, it
      * will return the $Field value.
-     *
-     * @return string
      */
-    public function forTemplate()
+    public function forTemplate(): string
     {
         return $this->Field();
     }

diff --git a/src/Forms/FormRequestHandler.php b/src/Forms/FormRequestHandler.php
@@ -504,7 +504,7 @@ public function validationResult()
         return $result;
     }
 
-    public function forTemplate()
+    public function forTemplate(): string
     {
         return $this->form->forTemplate();
     }

diff --git a/src/Forms/NullableField.php b/src/Forms/NullableField.php
@@ -166,7 +166,7 @@ public function setName($name)
     /**
      * @return string
      */
-    public function debug()
+    public function debug(): string
     {
         $result = sprintf(
             '%s (%s: %s : <span style="color: red">%s</span>) = ',

diff --git a/src/Forms/ReadonlyField.php b/src/Forms/ReadonlyField.php
@@ -56,7 +56,7 @@ public function Type()
         return 'readonly';
     }
 
-    public function castingHelper($field, bool $useFallback = true)
+    public function castingHelper(string $field, bool $useFallback = true): ?string
     {
         // Get dynamic cast for 'Value' field
         if (strcasecmp($field ?? '', 'Value') === 0) {

diff --git a/src/Forms/RequiredFields.php b/src/Forms/RequiredFields.php
@@ -58,7 +58,7 @@ public function removeValidation()
      * Debug helper
      * @return string
      */
-    public function debug()
+    public function debug(): string
     {
         if (!is_array($this->required)) {
             return false;

diff --git a/src/ORM/ArrayList.php b/src/ORM/ArrayList.php
@@ -110,10 +110,8 @@ public function count(): int
 
     /**
      * Returns true if this list has items
-     *
-     * @return bool
      */
-    public function exists()
+    public function exists(): bool
     {
         return !empty($this->items);
     }
@@ -159,7 +157,7 @@ public function each($callback)
         return $this;
     }
 
-    public function debug()
+    public function debug(): string
     {
         $val = "<h2>" . static::class . "</h2><ul>";
         foreach ($this->toNestedArray() as $item) {

diff --git a/src/ORM/DataList.php b/src/ORM/DataList.php
@@ -868,7 +868,7 @@ public function each($callback)
         return $this;
     }
 
-    public function debug()
+    public function debug(): string
     {
         $val = "<h2>" . static::class . "</h2><ul>";
         foreach ($this->toNestedArray() as $item) {
@@ -1702,10 +1702,8 @@ public function last()
 
     /**
      * Returns true if this DataList has items
-     *
-     * @return bool
      */
-    public function exists()
+    public function exists(): bool
     {
         return $this->dataQuery->exists();
     }

diff --git a/src/ORM/DataObject.php b/src/ORM/DataObject.php
@@ -816,10 +816,8 @@ public function defineMethods()
      * Returns true if this object "exists", i.e., has a sensible value.
      * The default behaviour for a DataObject is to return true if
      * the object exists in the database, you can override this in subclasses.
-     *
-     * @return boolean true if this object exists
      */
-    public function exists()
+    public function exists(): bool
     {
         return $this->isInDB();
     }
@@ -2687,19 +2685,16 @@ public function getFrontEndFields($params = null)
         return $untabbedFields;
     }
 
-    public function getViewerTemplates($suffix = '')
+    public function getViewerTemplates(string $suffix = ''): array
     {
         return SSViewer::get_templates_by_class(static::class, $suffix, $this->baseClass());
     }
 
     /**
      * Gets the value of a field.
      * Called by {@link __get()} and any getFieldName() methods you might create.
-     *
-     * @param string $field The name of the field
-     * @return mixed The field value
      */
-    public function getField($field)
+    public function getField(string $field): mixed
     {
         // If we already have a value in $this->record, then we should just return that
         if (isset($this->record[$field])) {
@@ -2910,12 +2905,8 @@ public function isChanged($fieldName = null, $changeLevel = DataObject::CHANGE_S
     /**
      * Set the value of the field
      * Called by {@link __set()} and any setFieldName() methods you might create.
-     *
-     * @param string $fieldName Name of the field
-     * @param mixed $val New field value
-     * @return $this
      */
-    public function setField($fieldName, $val)
+    public function setField(string $fieldName, mixed $value): static
     {
         $this->objCacheClear();
         //if it's a has_one component, destroy the cache
@@ -2934,42 +2925,42 @@ public function setField($fieldName, $val)
         if ($schema->unaryComponent(static::class, $fieldName)) {
             unset($this->components[$fieldName]);
             // Assign component directly
-            if (is_null($val) || $val instanceof DataObject) {
-                return $this->setComponent($fieldName, $val);
+            if (is_null($value) || $value instanceof DataObject) {
+                return $this->setComponent($fieldName, $value);
             }
             // Assign by ID instead of object
-            if (is_numeric($val)) {
+            if (is_numeric($value)) {
                 $fieldName .= 'ID';
             }
         }
 
         // Situation 1: Passing an DBField
-        if ($val instanceof DBField) {
-            $val->setName($fieldName);
-            $val->saveInto($this);
+        if ($value instanceof DBField) {
+            $value->setName($fieldName);
+            $value->saveInto($this);
 
             // Situation 1a: Composite fields should remain bound in case they are
             // later referenced to update the parent dataobject
-            if ($val instanceof DBComposite) {
-                $val->bindTo($this);
-                $this->setFieldValue($fieldName, $val);
+            if ($value instanceof DBComposite) {
+                $value->bindTo($this);
+                $this->setFieldValue($fieldName, $value);
             }
         // Situation 2: Passing a literal or non-DBField object
         } else {
-            $this->setFieldValue($fieldName, $val);
+            $this->setFieldValue($fieldName, $value);
         }
         return $this;
     }
 
-    private function setFieldValue(string $fieldName, mixed $val): void
+    private function setFieldValue(string $fieldName, mixed $value): void
     {
         $schema = static::getSchema();
         // If this is a proper database field, we shouldn't be getting non-DBField objects
-        if (is_object($val) && !($val instanceof DBField) && $schema->fieldSpec(static::class, $fieldName)) {
+        if (is_object($value) && !($value instanceof DBField) && $schema->fieldSpec(static::class, $fieldName)) {
             throw new InvalidArgumentException('DataObject::setFieldValue: passed an object that is not a DBField');
         }
 
-        if (!empty($val) && !is_scalar($val)) {
+        if (!empty($value) && !is_scalar($value)) {
             $dbField = $this->dbObject($fieldName);
             if ($dbField && $dbField->scalarValueOnly()) {
                 throw new InvalidArgumentException(
@@ -2982,12 +2973,12 @@ private function setFieldValue(string $fieldName, mixed $val): void
         }
 
         // if a field is not existing or has strictly changed
-        if (!array_key_exists($fieldName, $this->original ?? []) || $this->original[$fieldName] !== $val) {
+        if (!array_key_exists($fieldName, $this->original ?? []) || $this->original[$fieldName] !== $value) {
             // At the very least, the type has changed
             $this->changed[$fieldName] = DataObject::CHANGE_STRICT;
 
-            if ((!array_key_exists($fieldName, $this->original ?? []) && $val)
-                || (array_key_exists($fieldName, $this->original ?? []) && $this->original[$fieldName] != $val)
+            if ((!array_key_exists($fieldName, $this->original ?? []) && $value)
+                || (array_key_exists($fieldName, $this->original ?? []) && $this->original[$fieldName] != $value)
             ) {
                 // Value has changed as well, not just the type
                 $this->changed[$fieldName] = DataObject::CHANGE_VALUE;
@@ -2998,7 +2989,7 @@ private function setFieldValue(string $fieldName, mixed $val): void
         }
 
         // Value is saved regardless, since the change detection relates to the last write
-        $this->record[$fieldName] = $val;
+        $this->record[$fieldName] = $value;
     }
 
     /**
@@ -3029,7 +3020,7 @@ public function setCastedField($fieldName, $value)
     /**
      * {@inheritdoc}
      */
-    public function castingHelper($field, bool $useFallback = true)
+    public function castingHelper(string $field, bool $useFallback = true): ?string
     {
         $fieldSpec = static::getSchema()->fieldSpec(static::class, $field);
         if ($fieldSpec) {
@@ -3054,19 +3045,16 @@ public function castingHelper($field, bool $useFallback = true)
      * Returns true if the given field exists in a database column on any of
      * the objects tables and optionally look up a dynamic getter with
      * get<fieldName>().
-     *
-     * @param string $field Name of the field
-     * @return boolean True if the given field exists
      */
-    public function hasField($field)
+    public function hasField(string $fieldName): bool
     {
         $schema = static::getSchema();
         return (
-            array_key_exists($field, $this->record ?? [])
-            || array_key_exists($field, $this->components ?? [])
-            || $schema->fieldSpec(static::class, $field)
-            || $schema->unaryComponent(static::class, $field)
-            || $this->hasMethod("get{$field}")
+            array_key_exists($fieldName, $this->record ?? [])
+            || array_key_exists($fieldName, $this->components ?? [])
+            || $schema->fieldSpec(static::class, $fieldName)
+            || $schema->unaryComponent(static::class, $fieldName)
+            || $this->hasMethod("get{$fieldName}")
         );
     }
 
@@ -3214,7 +3202,7 @@ public function canCreate($member = null, $context = [])
      *
      * @return string HTML data representing this object
      */
-    public function debug()
+    public function debug(): string
     {
         $class = static::class;
         $val = "<h3>Database record: {$class}</h3>\n<ul>\n";
@@ -4386,13 +4374,8 @@ public function provideI18nEntities()
     /**
      * Returns true if the given method/parameter has a value
      * (Uses the DBField::hasValue if the parameter is a database field)
-     *
-     * @param string $field The field name
-     * @param array $arguments
-     * @param bool $cache
-     * @return boolean
      */
-    public function hasValue($field, $arguments = null, $cache = true)
+    public function hasValue(string $field, array $arguments = [], bool $cache = true): bool
     {
         // has_one fields should not use dbObject to check if a value is given
         $hasOne = static::getSchema()->hasOneComponent(static::class, $field);

diff --git a/src/ORM/DataObjectInterface.php b/src/ORM/DataObjectInterface.php
@@ -36,7 +36,7 @@ public function delete();
      * @param string $fieldName
      * @return mixed
      */
-    public function __get($fieldName);
+    public function __get(string $property): mixed;
 
     /**
      * Save content from a form into a field on this data object.

diff --git a/src/ORM/EagerLoadedList.php b/src/ORM/EagerLoadedList.php
@@ -341,7 +341,7 @@ public function each($callback): static
         return $this;
     }
 
-    public function debug()
+    public function debug(): string
     {
         // Same implementation as DataList::debug()
         $val = '<h2>' . static::class . '</h2><ul>';

diff --git a/src/ORM/FieldType/DBBigInt.php b/src/ORM/FieldType/DBBigInt.php
@@ -15,7 +15,7 @@
 class DBBigInt extends DBInt
 {
 
-    public function requireField()
+    public function requireField(): void
     {
         $parts = [
             'datatype' => 'bigint',