PHP 8.3: Assert: assert_options(), ASSERT_* constants, and assert.* INI settings deprecated

Version8.3
TypeDeprecation

PHP 8.3 deprecates all assert.* INI directives, ASSET_* constants, and the assert_options() function.

PHP's assert() function allows defining expectations that provide "spot-checks" to assert application state. They can be enabled in development or testing environments, but when disabled (e.g. in production systems), these assertions have zero cost at execution time.

assert(!str_contains($db_name, 'prod'));

Since the introduction of AST in PHP 7.0, PHP's Assert feature received several improvements, and with the stronger focus in PHP to use Exceptions, the existing assert.* INI directives were no longer necessary to short-circuit, halt, or throw exceptions upon assertion failures.

This behavior can be changed with assert.* INI settings, which can be set from INI files, as well as the assert_options()function:

assert_options(ASSERT_CALLBACK, 'my_assert_failure_callback');
INI Directive assert_options key Default value Description
assert.exception ASSERT_EXCEPTION Enabled Added in PHP 7. When enabled, assert() failures throw an \AssertionError exception.
assert.bail ASSERT_BAIL Disabled When enabled, and assert.exception disabled, assert() failures immediately halt the execution.
assert.warning ASSERT_WARNING Enabled When enabled, and assert.exception disabled, assert() failures emit a PHP warning
assert.callback ASSERT_CALLBACK null Provides a way to have a custom callback called in addition to \AssertionError Exception.
assert.active ASSERT_ACTIVE Enabled Toggles the assert calls. If disabled, assert immediately returns true (i.e bypassing the assertion)

In PHP 8.3, all of the INI directives, ASSERT_* constants, and the assert_options() function are deprecated.

Since PHP 7.0 and later, the recommended way to enable assertions is by setting the zend.assertions INI directive. The assert.* INI, class constants, and the assert_options() function deprecations are in favor of the zend.assertions INI setting.

All of the assert.* INI directives, all of the ASSERT_* constants, and the assert_options() function will be removed in PHP 9.0.

Deprecated Functionality

  • assert_options() function
  • assert.exception INI directive
  • assert.bail INI directive
  • assert.warning INI directive
  • assert.callback INI directive
  • assert.active INI directive
  • ASSERT_EXCEPTION PHP constant
  • ASSERT_BAIL PHP constant
  • ASSERT_WARNING PHP constant
  • ASSERT_CALLBACK PHP constant
  • ASSERT_ACTIVE PHP constant

Attempting to use these functions/INI directives/constants result in PHP Deprecation warnings:

assert_options(ASSERT_ACTIVE, true);
Constant ASSERT_ACTIVE is deprecated
Function assert_options() is deprecated

Similarly, assert.* INI directives result in a PHP Deprecation notice at start-up time:

php -d assert.active=1 test.php
Deprecated: PHP Startup: assert.active INI setting is deprecated

Recommended Replacement

There are no replacements to mimic the functionality of assert.callback and assert.warning INI directives, which means calling custom callables and emitting PHP warnings is deprecated, and will not be possible in PHP 9.0 and later.

To enable or disable assert() calls, replace assert.active INI with zend.assertions INI directive.

Enabling assert() (not recommended for production systems)

- assert.active=On
+ zend.assertions=1

Disabling assert()

- assert.active=Off
+ zend.assertions=-1

The recommended replacement is to use zend.assertions INI directive that accepts one of the following three values:

  • -1: assertion code will not be generated, making the assertions zero-cost. Recommended for production systems.
  • 0: assertion code will be generated but it will be skipped (not executed) at runtime
  • 1: assertion code will be generated and executed

Backward Compatibility Impact

PHP 8.3 deprecates all of the assert.* INI directives, ASSERT_* constants, and assert_options() function. The zend.assertions INI directive works as a replacement to enable or disable assert() functionality.

This also means that the ability to execute custom callbacks is also deprecated, with no replacement functionality provided.

Related Changes

RFC Discussion Implementation