How to use assert() in PHP

In this article, I’ll teach you about the assert() function in PHP. I will teach you what exactly it is, how it works, and the right context to use it in your code. Along the way, I’ll use simple example code snippets that will help you to understand the assert concept even better.

Let’s begin!

What is the assert() Function in PHP? 

assert() is a function statement that is used to verify that a condition is always true. PHP uses this function as a debugging tool to trigger errors whenever a certain defined condition is not satisfied.

The assert() Syntax

assert() takes two arguments: the assertion and an error message.

assert(mixed $assertion, Throwable $exception = ?): bool

The first argument is the condition that must be satisfied for the rest of the code to continue running. The second argument is normally an error message that is triggered when the condition (which is the first argument) is not satisfied.

The assert() function evaluates the first argument—$assertion—which is either a string containing an expression to be evaluated, a bool, or an expression. The program continues to run through smoothly if this evaluates to true, meaning the asserted condition has been fully met. Otherwise, it throws an exception.

The $assertion Expression

The assertion is either a string containing an expression, a boolean value, or since PHP 7, an expression. This is executed and its result is used to indicate the success or the failure of the assertion.

The Exception or Description Message

In PHP 5, this was a string describing the error that has occurred. If this argument isn’t defined, then a default description that is basically equal to the source code for the invocation of assert() is provided instead.

Example of How to Use assert() in PHP

Now, let me show you some simple code that uses assert().

<?php

function firstLetter($string) {
    assert(strlen($string) > 0);
    
    return substr($string, 0, 1);
}

echo firstLetter("Hello!");
echo firstLetter("");

The above code snippet defines a function to return the first letter of a string. If the string doesn’t have any letters however, the function will throw an exception.

Our localhost server would display this:

WARNING assert(): assert(strlen($string) > 0) failed on line number 4

How to Use assert()

PHP uses assert() as a native debugging tool. In other words, assert() is used to check the parts of code ensuring that they meet some required criteria or a defined condition. Like we saw in our example above.

Using the assert() tool, you can make sure the internal data that is being passed around in your application is of the correct type. For example, let’s consider an example where assert() validates a variable type.

In the following example, I will define a function and pass to it two variables. I will then use assert to check whether these variables are of float value. assert() should throw an exception when a different variable type is passed instead.

<?php

function doSomeMath($x, $y){
    assert(is_float($x), '$x must be a float value');
    assert(is_float($y), '$y must be a float value');
    //...
}
doSomeMath(1.00, 6);

?>

On calling the function, I passed in values for $x and $y of 1.00 and 6 respectively.

Running this code would return the following:

Warning: assert(): $y must be a float value failed in C:\xampp\htdocs\PHPlogin\asserrt.php on line 5

The output of the code indicates that the exception $y must be a float value has been thrown because the value 6 passed to the $y parameter is not of float type but is of integer type instead.

Let us consider another example where a default exception is thrown because of not defining our own exception.

<?php
function variableTypes($x, $y){
    assert(is_int($x), '$x must be an integer value');
    assert(is_int($y), '$y must be an integer value');
    assert($x === 0, 'The value of $x cannot be zero');

    return $x / $y;

}
variableTypes(1, 0);
?>

I added a condition setting the $x parameter value to 0. We then return the division of $x with $y. We already expect a default ZeroDivisionError exception since, by default, you cannot divide an integer by zero.

Run the code and you should see this now:

Warning: assert(): The value of $x cannot be zero failed in C:\xampp\htdocs\PHPlogin\asserrt.php on line 5

Warning: Division by zero in C:\xampp\htdocs\PHPlogin\asserrt.php on line 7

The first line in the output throws an exception because the condition is not met. The value of $x must not be zero yet that is what has been defined here.

The second line in the output displays a default exception message of ZeroDivisionError because we divided 1 with a 0 value, contrary to the rules of mathematics.

That is basically all you need to know about assert() and its functionality.

Disabling Assertions

As you can see, assertions can be a useful tool for debugging our code. Assertions help you spot errors early and warn you if something unexpected is happening.

It is important to note, however, that the use of assert() is mainly during the development stage.  Don’t use assert() to detect and report errors for your production application, because assertion errors can be turned off with a setting in php.ini. 

Do disable assertions for a production system, use the zend.assertions directive in php.ini.

Conclusion

Now you know how to declare assertions in your code to detect errors and help in debugging. As you’ve seen, it’s also very easy to implement.

Happy coding!