Skip to content
Cline

Null and Empty Assertions

Assertions for validating null values, empty values, and blank strings.

Available Assertions

Section titled “Available Assertions”

null()

Section titled “null()”

Assert that a value is null.

use Cline\Assert\Assertions\Assertion;


Assertion::null($value);
Assertion::null($optionalField, 'Field must be null');

notNull()

Section titled “notNull()”

Assert that a value is not null.

Assertion::notNull($value);
Assertion::notNull($user, 'User is required');

notEmpty()

Section titled “notEmpty()”

Assert that a value is not empty (using empty() check).

Assertion::notEmpty($value);
Assertion::notEmpty($name, 'Name is required');

noContent()

Section titled “noContent()”

Assert that a value is empty (using empty() check).

Assertion::noContent($value);
Assertion::noContent($deletedField, 'Field must be empty');

notBlank()

Section titled “notBlank()”

Assert that a value is not blank (not empty string or whitespace-only).

Assertion::notBlank($value);
Assertion::notBlank($description, 'Description cannot be blank');

Understanding Empty Checks

Section titled “Understanding Empty Checks”

What empty() Considers Empty

Section titled “What empty() Considers Empty”
Assertion::noContent('');       // empty string
Assertion::noContent(0);        // integer zero
Assertion::noContent(null);     // null
Assertion::noContent(false);    // boolean false
Assertion::noContent([]);       // empty array

Null vs Empty vs Blank

Section titled “Null vs Empty vs Blank”

null() - Strict Null Check

Section titled “null() - Strict Null Check”
Assertion::null(null);      // Pass
Assertion::null('');        // Fail - empty string, not null

noContent() - PHP Empty Check

Section titled “noContent() - PHP Empty Check”
Assertion::noContent(null);     // Pass
Assertion::noContent('');       // Pass
Assertion::noContent(0);        // Pass

notBlank() - Non-Whitespace String

Section titled “notBlank() - Non-Whitespace String”
Assertion::notBlank('hello');   // Pass
Assertion::notBlank(' ');       // Fail - whitespace only
Assertion::notBlank('');        // Fail - empty string

Chaining Null/Empty Assertions

Section titled “Chaining Null/Empty Assertions”
use Cline\Assert\Assert;


Assert::that($username)
    ->notNull('Username is required')
    ->notEmpty('Username cannot be empty')
    ->string();


Assert::that($description)
    ->string()
    ->notBlank('Description cannot be blank');

Common Patterns

Section titled “Common Patterns”

Required Field Validation

Section titled “Required Field Validation”
Assert::that($email)
    ->notNull('Email is required')
    ->notEmpty('Email cannot be empty')
    ->notBlank('Email cannot be blank')
    ->email('Invalid email format');

Optional Field Validation

Section titled “Optional Field Validation”
Assert::thatNullOr($phoneNumber)
    ->string()
    ->e164('Invalid phone format');

Form Input Validation

Section titled “Form Input Validation”
Assert::lazy()
    ->that($form['name'] ?? null, 'name')->notNull()->notBlank()
    ->that($form['email'] ?? null, 'email')->notNull()->notBlank()->email()
    ->verifyNow();

Using nullOr()

Section titled “Using nullOr()”
// Allow null OR validate if not null
Assert::thatNullOr($middleName)
    ->string()
    ->minLength(2);

String Whitespace Handling

Section titled “String Whitespace Handling”
// notEmpty allows whitespace
Assertion::notEmpty(' ');      // Pass


// notBlank rejects whitespace
Assertion::notBlank(' ');      // Fail

Best Practices

Section titled “Best Practices”

Check Null First

Section titled “Check Null First”
Assert::that($user)
    ->notNull('User not found')
    ->isObject();

Use notBlank for User Input

Section titled “Use notBlank for User Input”
Assert::that($comment)
    ->notBlank('Comment cannot be empty');

Combine with Type Checks

Section titled “Combine with Type Checks”
Assert::that($name)
    ->notNull()
    ->string()
    ->notBlank();

Next Steps

Section titled “Next Steps”