From 95828060a8c96d0d4145dd964ae6beaf066a35a9 Mon Sep 17 00:00:00 2001
From: petrdobr <dobrokhotovp@gmail.com>
Date: Tue, 4 Nov 2025 20:02:52 +0100
Subject: [PATCH] feat(assert): add `Assert::blank()` method

---
 src/Assert.php                    | 30 +++++++++++++++++++++
 tests/Assert/Self/AssertBlank.php | 44 +++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 tests/Assert/Self/AssertBlank.php

diff --git a/src/Assert.php b/src/Assert.php
index 20ad6b8..3f19f52 100644
--- a/src/Assert.php
+++ b/src/Assert.php
@@ -189,6 +189,36 @@ public static function null(
             : StaticState::fail(AssertException::compare(null, $actual, $message));
     }
 
+    /**
+     * Checks if a value is blank.
+     *
+     * Successful only for values representing absence of data:
+     * null, empty string, empty array or countable object with no elements.
+     *
+     * Unlike empty(), does not consider false, 0, and "0" as blank,
+     * since they represent valid data.
+     * @param mixed $actual The actual value to check for blank.
+     * @param string $message Short description about what exactly is being asserted.
+     * @throws AssertException when the assertion fails.
+     */
+    public static function blank(
+        mixed $actual,
+        string $message = '',
+    ): void {
+        if (
+            $actual === null || $actual === '' || $actual === [] || ($actual instanceof \Countable && \count($actual) === 0)
+        ) {
+            StaticState::log('Assert `blank`', $message);
+            return;
+        }
+        StaticState::fail(AssertException::compare(
+            null,
+            $actual,
+            $message,
+            'Failed asserting that `%2$s` does not contain any data',
+        ));
+    }
+
     /**
      * Fails the test.
      *
diff --git a/tests/Assert/Self/AssertBlank.php b/tests/Assert/Self/AssertBlank.php
new file mode 100644
index 0000000..d37c97a
--- /dev/null
+++ b/tests/Assert/Self/AssertBlank.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Assert\Self;
+
+use Testo\Assert;
+use Testo\Attribute\Test;
+
+/**
+ * Assertion examples.
+ */
+final class AssertBlank
+{
+    #[Test]
+    public function checkBlankData(): void
+    {
+        Assert::blank([]);
+        Assert::blank("");
+        Assert::blank(null);
+        Assert::blank(new \ArrayIterator());
+    }
+
+    #[Test]
+    public function checkZeroIsNotBlank(): void
+    {
+        Assert::exception(Assert\State\AssertException::class);
+        Assert::blank(0);
+    }
+
+    #[Test]
+    public function checkZeroStringIsNotBlank(): void
+    {
+        Assert::exception(Assert\State\AssertException::class);
+        Assert::blank("0");
+    }
+
+    #[Test]
+    public function checkFalseIsNotBlank(): void
+    {
+        Assert::exception(Assert\State\AssertException::class);
+        Assert::blank(false);
+    }
+}