Using PHP assert for Inline Debugging and Testing

This article explains how to use the PHP assert() function to perform inline debugging and test logic assumptions during development. You will learn how to configure assertions, write effective checks to verify code behavior, and understand the difference between using assertions in development versus production environments.

Understanding the PHP assert() Function

The assert() function in PHP is a language construct used to define expectations in your code. It checks whether a given condition evaluates to true. If the condition is met, your program continues executing normally. If the condition is false, PHP triggers an assertion failure, which can either raise a warning or throw an AssertionError.

Using assert() is highly effective for inline debugging because it allows you to document and verify internal program states (invariants) as the code runs, without needing to write heavy unit testing boilerplate for small, specific logic checks.

Basic Syntax and Usage

The basic syntax for assert() in PHP 7 and PHP 8 is:

assert(mixed $assertion, Throwable|string|null $description = null): bool

$assertion: The expression or condition you want to test.
$description: An optional error message or a custom Throwable exception to throw if the assertion fails.

Here is a simple example checking if a variable meets a specific condition:

function divide($dividend, $divisor) {
    // Assert that the divisor is never zero
    assert($divisor !== 0, "Divisor cannot be zero");
    
    return $dividend / $divisor;
}

echo divide(10, 2); // Works fine
echo divide(10, 0); // Fails the assertion

Configuring assert() in php.ini

The behavior of assert() depends on your PHP configuration, specifically the zend.assertions and assert.exception directives in your php.ini file.

1. zend.assertions

This directive controls whether assertions are compiled into the execution code. * 1: (Development mode) Assertions are generated and executed. * 0: Assertions are generated but bypassed at runtime. * -1: (Production mode) Assertions are not generated at all, resulting in zero performance overhead.

2. assert.exception

This directive defines what happens when an assertion fails. * 1: PHP throws an AssertionError exception when an assertion fails. This is highly recommended for modern PHP development. * 0: PHP issues a traditional PHP warning instead of throwing an exception.

To enable strict assertions with exceptions during development, configure your php.ini like this:

zend.assertions = 1
assert.exception = 1

Custom Exceptions with assert()

Instead of a simple string description, you can pass a custom exception object as the second argument to assert(). This is useful for integrating assertion failures into your application’s error-handling architecture.

class InvalidUserStatusException extends Exception {}

function activateUser($status) {
    assert($status === 'pending', new InvalidUserStatusException("User must be in pending status to activate."));
    
    // Activation logic here
}

Best Practices for Using assert()

To get the most out of inline debugging and testing with assert(), follow these guidelines:

Do not use assertions for input validation: Use standard conditional statements (if, try/catch) for user-input validation, API responses, and run-time errors. Assertions should only be used to detect programming errors and logical inconsistencies.
Avoid side effects inside assertions: Since assertions are disabled in production (zend.assertions = -1), any code inside the assert() statement will not run. Avoid modifying variables or executing database queries inside an assertion.
Disable assertions in production: Always set zend.assertions = -1 in production environments to ensure maximum application performance and to prevent sensitive internal debug messages from exposing details to end-users.