NEW Add type declarations to Tip API, add TippableFieldInterface

src/Forms/TextField.php

@@ -7,7 +7,7 @@ use SilverStripe\Dev\Deprecation;
 /**
  * Text input field.
  */
-class TextField extends FormField
+class TextField extends FormField implements TippableFieldInterface
 {
     /**
      * @var int
@@ -19,7 +19,7 @@ class TextField extends FormField
     /**
      * @var Tip|null A tip to render beside the input
      */
-    protected $tip;
+    private $tip;
 
     /**
      * Returns an input field.
@@ -67,7 +67,7 @@ class TextField extends FormField
     /**
      * @return Tip|null
      */
-    public function getTip()
+    public function getTip(): ?Tip
     {
         return $this->tip;
     }
@@ -80,7 +80,7 @@ class TextField extends FormField
      * @param Tip|null $tip The Tip to apply, or null to remove an existing one
      * @return $this
      */
-    public function setTip(Tip $tip = null)
+    public function setTip(?Tip $tip = null): self
     {
         $this->tip = $tip;
 
@@ -112,8 +112,8 @@ class TextField extends FormField
         $data = parent::getSchemaDataDefaults();
         $data['data']['maxlength'] =  $this->getMaxLength();
 
-        if ($this->tip instanceof Tip) {
-            $data['tip'] = $this->tip->getTipSchema();
+        if ($this->getTip() instanceof Tip) {
+            $data['tip'] = $this->getTip()->getTipSchema();
         }
 
         return $data;

src/Forms/Tip.php

@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 
 namespace SilverStripe\Forms;
 
@@ -7,22 +8,20 @@ use InvalidArgumentException;
 /**
  * Represents a Tip which can be rendered alongside a form field in the front-end.
  * See the Tip component in the silverstripe/admin module.
- *
- * @package SilverStripe\Forms
  */
 class Tip
 {
     /**
      * These map to levels in the front-end Tip component
      */
-    const IMPORTANCE_LEVELS = [
+    public const IMPORTANCE_LEVELS = [
         'NORMAL' => 'normal',
         'HIGH' => 'high',
     ];
 
-    const DEFAULT_ICON = 'lamp';
+    private const DEFAULT_ICON = 'lamp';
 
-    const DEFAULT_IMPORTANCE_LEVEL = self::IMPORTANCE_LEVELS['NORMAL'];
+    private const DEFAULT_IMPORTANCE_LEVEL = self::IMPORTANCE_LEVELS['NORMAL'];
 
     /**
      * @var string The icon that should be used on the Tip button
@@ -35,25 +34,24 @@ class Tip
     private $importance_level;
 
     /**
-     * @var string The contents of the Tip UI
+     * @var string The message to display in the tip
      */
     private $message;
 
+    /**
+     * @param string $message The message to display in the tip
+     * @param string $importance_level How important the tip is (normal or high). Informs the color and description.
+     * @param string $icon The icon that should be used on the Tip button
+     * @throws InvalidArgumentException
+     */
     public function __construct(
-        $message,
-        $importance_level = self::DEFAULT_IMPORTANCE_LEVEL,
-        $icon = self::DEFAULT_ICON
-    )
-    {
-        if (!in_array($importance_level, self::IMPORTANCE_LEVELS)) {
-            throw new InvalidArgumentException(
-                'Provided $importance_level must be defined in Tip::IMPORTANCE_LEVELS'
-            );
-        }
-
-        $this->message = $message;
-        $this->icon = $icon;
-        $this->importance_level = $importance_level;
+        string $message,
+        string $importance_level = self::DEFAULT_IMPORTANCE_LEVEL,
+        string $icon = self::DEFAULT_ICON
+    ) {
+        $this->setMessage($message);
+        $this->setIcon($icon);
+        $this->setImportanceLevel($importance_level);
     }
 
     /**
@@ -61,35 +59,39 @@ class Tip
      *
      * @return array
      */
-    public function getTipSchema()
+    public function getTipSchema(): array
     {
         return [
-            'content' => $this->message,
-            'icon' => $this->icon,
-            'importance' => $this->importance_level,
+            'content' => $this->getMessage(),
+            'icon' => $this->getIcon(),
+            'importance' => $this->getImportanceLevel(),
         ];
     }
 
     /**
      * @return string
      */
-    public function getImportanceLevel()
+    public function getImportanceLevel(): string
     {
         return $this->importance_level;
     }
 
     /**
      * @param string $importance_level
+     * @return Tip
+     * @throws InvalidArgumentException
      */
-    public function setImportanceLevel($importance_level)
+    public function setImportanceLevel(string $importance_level): self
     {
         if (!in_array($importance_level, self::IMPORTANCE_LEVELS)) {
             throw new InvalidArgumentException(
-                'Provided $importance_level must be defined in Tip::IMPORTANCE_LEVELS'
+                'Provided importance level must be defined in Tip::IMPORTANCE_LEVELS'
             );
         }
 
         $this->importance_level = $importance_level;
+
+        return $this;
     }
 
     /**
@@ -102,25 +104,31 @@ class Tip
 
     /**
      * @param string $icon
+     * @return Tip
      */
-    public function setIcon($icon)
+    public function setIcon(string $icon): self
     {
         $this->icon = $icon;
+
+        return $this;
     }
 
     /**
      * @return string
      */
-    public function getMessage()
+    public function getMessage(): string
     {
         return $this->message;
     }
 
     /**
      * @param string $message
+     * @return Tip
      */
-    public function setMessage($message)
+    public function setMessage(string $message): self
     {
         $this->message = $message;
+
+        return $this;
     }
 }

src/Forms/TippableFieldInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace SilverStripe\Forms;
+
+/**
+ * Declares that a form field has the ability to accept and render Tips.
+ */
+interface TippableFieldInterface
+{
+    public function getTip(): ?Tip;
+
+    public function setTip(Tip $tip);
+}

tests/php/Forms/TipTest.php

@@ -35,7 +35,7 @@ class TipTest extends SapphireTest
         $tip = new Tip(
             'message',
             Tip::IMPORTANCE_LEVELS['HIGH'],
-        'page'
+            'page'
         );
 
         $schema = $tip->getTipSchema();
@@ -54,7 +54,7 @@ class TipTest extends SapphireTest
      * Ensure passing an invalid importance level to the constructor fails
      *
      * @expectedException InvalidArgumentException
-     * @expectedExceptionMessage Provided $importance_level must be defined in Tip::IMPORTANCE_LEVELS
+     * @expectedExceptionMessage Provided importance level must be defined in Tip::IMPORTANCE_LEVELS
      */
     public function testInvalidImportanceLevelInConstructorCausesException()
     {
@@ -65,7 +65,7 @@ class TipTest extends SapphireTest
      * Ensure setting an invalid importance level fails
      *
      * @expectedException InvalidArgumentException
-     * @expectedExceptionMessage Provided $importance_level must be defined in Tip::IMPORTANCE_LEVELS
+     * @expectedExceptionMessage Provided importance level must be defined in Tip::IMPORTANCE_LEVELS
      */
     public function testInvalidImportanceLevelInSetterCausesException()
     {