PHP: Hypertext Preprocessor (original) (raw)

assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — Checks an assertion

Description

Assertions can be used to aid debugging. One use case for them is to act as sanity-checks for preconditions that should always be [true](reserved.constants.php#constant.true) and that if they aren't upheld this indicates some programming errors. Another use case is to ensure the presence of certain features like extension functions or certain system limits and features.

As assertions can be configured to be eliminated, they should_not_ be used for normal runtime operations like input parameter checks. As a rule of thumb code should behave as expected even if assertion checking is deactivated.

assert() will check that the expectation given inassertion holds. If not, and thus the result is [false](reserved.constants.php#constant.false), it will take the appropriate action depending on how assert() was configured.

The behaviour of assert() is dictated by the following INI settings:

Assert Configure Options

Parameters

assertion

This is any expression that returns a value, which will be executed and the result is used to indicate whether the assertion succeeded or failed.

Warning

Prior to PHP 8.0.0, if assertion was astring it was interpreted as PHP code and executed viaeval(). This string would be passed to the callback as the third argument. This behaviour was DEPRECATED in PHP 7.2.0, and REMOVED in PHP 8.0.0.

description

If description is an instance ofThrowable, it will be thrown only if theassertion is executed and fails.

Note:

As of PHP 8.0.0, this is done prior to calling the potentially defined assertion callback.

Note:

As of PHP 8.0.0, the object will be thrown regardless of the configuration ofassert.exception.

Note:

As of PHP 8.0.0, theassert.bail setting has no effect in this case.

If description is a string this message will be used if an exception or a warning is emitted. An optional description that will be included in the failure message if the assertion fails.

If description is omitted. A default description equal to the source code for the invocation ofassert() is created at compile time.

Return Values

assert() will always return [true](reserved.constants.php#constant.true) if at least one of the following is true:

• zend.assertions=0
• zend.assertions=-1
• assert.exception=1
• assert.bail=1
• A custom exception object is passed to description.

If none of the conditions are true assert() will return [true](reserved.constants.php#constant.true) ifassertion is truthy and [false](reserved.constants.php#constant.false) otherwise.

Changelog

Examples

Example #1 assert() example

<?php assert(1 > 2); echo 'Hi!';

If assertions are enabled (zend.assertions=1) the above example will output:

Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2 Stack trace: #0 example.php(2): assert(false, 'assert(1 > 2)') #1 {main} thrown in example.php on line 2

If assertions are disabled (zend.assertions=0 or zend.assertions=-1) the above example will output:

Example #2 Using a custom message

<?php assert(1 > 2, "Expected one to be greater than two"); echo 'Hi!';

If assertions are enabled the above example will output:

Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2 Stack trace: #0 example.php(2): assert(false, 'Expected one to...') #1 {main} thrown in example.php on line 2

If assertions are disabled the above example will output:

Example #3 Using a custom exception class

<?php class ArithmeticAssertionError extends AssertionError {}assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two")); echo 'Hi!';

If assertions are enabled the above example will output:

Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4 Stack trace: #0 {main} thrown in example.php on line 4

If assertions are disabled the above example will output:

Found A Problem?

hodgman at ali dot com dot au ¶

16 years ago

`As noted on Wikipedia - "assertions are primarily a development tool, they are often disabled when a program is released to the public." and "Assertions should be used to document logically impossible situations and discover programming errors— if the 'impossible' occurs, then something fundamental is clearly wrong. This is distinct from error handling: most error conditions are possible, although some may be extremely unlikely to occur in practice. Using assertions as a general-purpose error handling mechanism is usually unwise: assertions do not allow for graceful recovery from errors, and an assertion failure will often halt the program's execution abruptly. Assertions also do not display a user-friendly error message."

This means that the advice given by "gk at proliberty dot com" to force assertions to be enabled, even when they have been disabled manually, goes against best practices of only using them as a development tool.

`

sven at rtbg dot de ¶

1 year ago

`` With the current changes made in PHP 8.3 (deprecating the INI settings affecting assertions) and the increasing amount of open source libraries utilizing assert() as an easy means to ensure obscure return cases of PHP core function calls are in fact not triggered (e.g. no NULL or FALSE has been returned, but the useful value), the comment made about assertions only being a tool used during development should be considered invalid.

In addition, static code analysis tools use the knowledge gained from assert($x instanceof MyClass) to know the type or types that are possible.

Assertions are actively being used in production code, they are useful, and disabling them would only gain minimal performance benefits because the asserted expression usually is very small.

Use this tool where applicable!

``