Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Exceptions and Errors

PHP assert() function

Reference for PHP assert(): check conditions during development, AssertionError, custom exceptions, the zend.assertions setting and why not to validate input with it.

assert() checks that a condition you believe is always true really is. If it is false, PHP throws an AssertionError. Assertions document assumptions in the code ("this list is never empty here") and catch programming mistakes during development and testing.

In production they are normally switched off with the zend.assertions setting, in which case the expression is not even evaluated. That is the key rule: use assert() for things that can only be false because of a bug, never for checking user input.

PHP
assert(is_array($rows));
assert($count >= 0, "count went negative");

Try it

PHP A failing assertion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Custom exceptions and turning assertions off

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
assert(mixed $assertion, Throwable|string|null $description = null): bool
Name Description
$assertion The expression that should be true.
$description A message for the AssertionError, or a Throwable object that is thrown instead.

Return value: true when the assertion holds (or assertions are disabled).

Throws: AssertionError when the assertion fails, or the exception object you passed as $description, as long as assert.exception is on (the default since PHP 8).

Usage notes

  • zend.assertions has three values: 1 (generate and run the code, the development setting), 0 (generated but skipped at runtime) and -1 (not compiled at all, the production setting). You can switch between 1 and 0 at runtime, but not into or out of -1.
  • No side effects inside assert(). When assertions are disabled the expression disappears, so the program behaves differently in production. Compute first, assert on the result.
  • Not for validation. User input, files and network data can be wrong in perfectly normal programs. Validate those with checks that throw InvalidArgumentException or similar.
  • The default message repeats the source code of the expression, for example assert(1 + 1 === 3), which is useful for debugging.
  • AssertionError extends Error, so catch (Exception $e) does not catch it.
  • PHP 8 removed the string form. Passing a string to be evaluated was deprecated in PHP 7.2 and is gone; always pass an expression.
  • The assert.* options (assert.active, assert.warning, assert.callback, assert.bail) are deprecated since PHP 8.3, and assert_options() with them.
  • Tests are the better home for most checks. Use assertions for cheap invariants inside code paths.