Skip to content
Cline

Assertion Chains

Assertion chains provide a fluent interface for validating values with multiple assertions.

Basic Chain Usage

Section titled “Basic Chain Usage”

Instead of multiple static calls:

Assertion::string($email);
Assertion::notEmpty($email);
Assertion::email($email);

Use a fluent chain:

Assert::that($email)
    ->string()
    ->notEmpty()
    ->email();

Creating Chains

Section titled “Creating Chains”

Basic Chain

Section titled “Basic Chain”
use Cline\Assert\Assert;


Assert::that($value)
    ->assertion1()
    ->assertion2()
    ->assertion3();

With Custom Message

Section titled “With Custom Message”
Assert::that($age, 'Age must be valid')
    ->integer()
    ->greaterOrEqualThan(18);

With Property Path

Section titled “With Property Path”
Assert::that($user->email, null, 'user.email')
    ->notEmpty()
    ->email();

Available Modifiers

Section titled “Available Modifiers”

nullOr() - Allow Null Values

Section titled “nullOr() - Allow Null Values”

Skip all subsequent assertions if the value is null:

Assert::thatNullOr($middleName)
    ->string()
    ->minLength(2)
    ->maxLength(50);


// Equivalent to:
if ($middleName !== null) {
    Assert::that($middleName)
        ->string()
        ->minLength(2);
}

all() - Validate Array Elements

Section titled “all() - Validate Array Elements”

Validate every element in an array:

Assert::thatAll($emailList)->email();


Assert::thatAll($userIds)
    ->integer()
    ->greaterThan(0);

Common Patterns

Section titled “Common Patterns”

String Validation

Section titled “String Validation”
Assert::that($username)
    ->string()
    ->notEmpty()
    ->minLength(3)
    ->maxLength(20)
    ->regex('/^[a-z0-9_]+$/');

Number Validation

Section titled “Number Validation”
Assert::that($price)
    ->float()
    ->greaterThan(0, 'Price must be positive')
    ->lessThan(1000000, 'Price too high');

Email Validation

Section titled “Email Validation”
Assert::that($email)
    ->string()
    ->notEmpty('Email is required')
    ->email('Invalid email format')
    ->maxLength(255, 'Email too long');

Password Validation

Section titled “Password Validation”
Assert::that($password)
    ->string()
    ->minLength(8, 'Password must be at least 8 characters')
    ->regex('/[A-Z]/', 'Must contain uppercase letter')
    ->regex('/[a-z]/', 'Must contain lowercase letter')
    ->regex('/[0-9]/', 'Must contain number');

Object Validation

Section titled “Object Validation”
Assert::that($user)
    ->notNull('User not found')
    ->isObject()
    ->isInstanceOf(User::class)
    ->propertyExists('email');

Array Validation

Section titled “Array Validation”
Assert::that($items)
    ->isArray()
    ->notEmpty('Items cannot be empty')
    ->minCount(1)
    ->maxCount(100);

Using nullOr()

Section titled “Using nullOr()”

Optional Fields

Section titled “Optional Fields”
// Required field
Assert::that($email)->notEmpty()->email();


// Optional field (can be null)
Assert::thatNullOr($phoneNumber)
    ->string()
    ->e164('Invalid phone format');

Configuration Values

Section titled “Configuration Values”
Assert::thatNullOr($config['timeout'])
    ->integer()
    ->greaterThan(0);

Using all()

Section titled “Using all()”

Validate Array of Values

Section titled “Validate Array of Values”
Assert::thatAll($recipientEmails)
    ->email('All recipients must have valid emails');


Assert::thatAll($quantities)
    ->integer()
    ->greaterThan(0);

With Type Checks

Section titled “With Type Checks”
Assert::thatAll($tags)
    ->string()
    ->notEmpty()
    ->minLength(2)
    ->maxLength(30);

Error Messages

Section titled “Error Messages”

Default Messages

Section titled “Default Messages”
Assert::that($email)
    ->notEmpty()  // "Value is required"
    ->email();    // "Value is not a valid email"

Custom Messages per Assertion

Section titled “Custom Messages per Assertion”
Assert::that($password)
    ->notEmpty('Password is required')
    ->minLength(8, 'Password must be at least 8 characters');

Default Message for Chain

Section titled “Default Message for Chain”
Assert::that($username, 'Username is invalid')
    ->notEmpty()
    ->minLength(3);

Best Practices

Section titled “Best Practices”

Order Assertions Logically

Section titled “Order Assertions Logically”
// Good order: type → null/empty → format → constraints
Assert::that($email)
    ->string()           // 1. Type check first
    ->notEmpty()         // 2. Then null/empty
    ->email()            // 3. Then format
    ->maxLength(255);    // 4. Finally constraints

Fail Fast with Type Checks

Section titled “Fail Fast with Type Checks”
Assert::that($count)
    ->integer()          // Ensures numeric operations work
    ->greaterThan(0);
Section titled “Group Related Validations”
Assert::that($name)
    ->string()
    ->notEmpty()
    ->minLength(2)
    ->maxLength(100)
    ->regex('/^[\p{L}\s]+$/u', 'Name can only contain letters');

Common Mistakes

Section titled “Common Mistakes”

Wrong Order

Section titled “Wrong Order”
// Bad - length check before type check
Assert::that($name)
    ->minLength(3)
    ->string();


// Good - type check first
Assert::that($name)
    ->string()
    ->minLength(3);

Next Steps

Section titled “Next Steps”