Add Str::isEmpty()

src/Str.php

@@ -2,6 +2,8 @@
 
 namespace ipl\Stdlib;
 
+use Stringable;
+
 /**
  * Collection of string manipulation functions
  */
@@ -90,4 +92,19 @@ public static function trimSplit(?string $subject, string $delimiter = ',', ?int
 
         return array_map('trim', $exploded);
     }
+
+    /**
+     * Check if the given string is empty
+     *
+     * Null is considered empty, and strings consisting only of whitespace or visually
+     * empty characters are considered empty.
+     *
+     * @param string|Stringable|null $subject
+     *
+     * @return bool
+     */
+    public static function isEmpty(string|Stringable|null $subject): bool
+    {
+        return $subject === null || preg_match('/^[\s\x{3164}\x{1160}]*$/u', $subject) === 1;
+    }
 }

tests/StrTest.php

@@ -47,6 +47,80 @@ public function testStartsWithReturnsFalseIfStringDoesNotStartWithTheSpecifiedSu
         $this->assertFalse(Str::startsWith('FOOBAR', 'foo', true));
     }
 
+    public function testIsEmptyReturnsTrueForNull()
+    {
+        $this->assertTrue(Str::isEmpty(null));
+    }
+
+    public function testIsEmptyReturnsTrueForEmptyString()
+    {
+        $this->assertTrue(Str::isEmpty(''));
+    }
+
+    public function testIsEmptyReturnsTrueForStringWithLeadingAndTrailingWhitespace()
+    {
+        $this->assertTrue(Str::isEmpty('   '));
+    }
+
+    public function testIsEmptyReturnsTrueForStringWithOnlyWhitespace()
+    {
+        $this->assertTrue(Str::isEmpty("\t\n"));
+    }
+
+    public function testIsEmptyReturnsFalseForZero()
+    {
+        $this->assertFalse(Str::isEmpty('0'));
+    }
+
+    public function testIsEmptyReturnsFalseForNonEmptyString()
+    {
+        $this->assertFalse(Str::isEmpty('Warning'));
+    }
+
+    public function testIsEmptyReturnsFalseForStringWithContentAndSurroundingWhitespace()
+    {
+        $this->assertFalse(Str::isEmpty('  Warning  '));
+    }
+
+    public function testIsEmptyReturnsFalseForUtf8String()
+    {
+        $this->assertFalse(Str::isEmpty('接続エラー'));
+    }
+
+    public function testIsEmptyReturnsFalseForUtf8StringWithSurroundingWhitespace()
+    {
+        $this->assertFalse(Str::isEmpty('  接続エラー  '));
+    }
+
+    public function testIsEmptyReturnsTrueForVisuallyEmptyUtf8String()
+    {
+        $this->assertTrue(Str::isEmpty("\u{3164}\u{1160}"));
+    }
+
+    public function testIsEmptyReturnsFalseForStringable()
+    {
+        $subject = new class {
+            public function __toString(): string
+            {
+                return 'Warning';
+            }
+        };
+
+        $this->assertFalse(Str::isEmpty($subject));
+    }
+
+    public function testIsEmptyReturnsTrueForStringableWithWhitespaceOnly()
+    {
+        $subject = new class {
+            public function __toString(): string
+            {
+                return '   ';
+            }
+        };
+
+        $this->assertTrue(Str::isEmpty($subject));
+    }
+
     public function testSymmetricSplitReturnsArrayPaddedToTheSizeSpecifiedByLimitUsingNullAsValueByDefault()
     {
         $this->assertSame(['foo', 'bar', null, null], Str::symmetricSplit('foo,bar', ',', 4));