PHP Runtime Assert Statements in Drupal 10

Same name and namespace in other branches

1. 8 core/core.api.php \php_assert
2. 9 core/core.api.php \php_assert

Use of the assert() statement in Drupal.

Unit tests also use the term "assertion" to refer to test conditions, so to avoid confusion the term "runtime assertion" will be used for the assert() statement throughout the documentation.

A runtime assertion is a statement that is expected to always be true at the point in the code it appears at. They are tested using PHP's internal assert() statement. If an assertion is ever FALSE it indicates an error in the code or in module or theme configuration files. User-provided configuration files should be verified with standard control structures at all times, not just checked in development environments with assert() statements on.

The Drupal project primarily uses runtime assertions to enforce the expectations of the API by failing when incorrect calls are made by code under development. While PHP type hinting does this for objects and arrays, runtime assertions do this for scalars (strings, integers, floats, etc.) and complex data structures such as cache and render arrays. They ensure that methods' return values are the documented data types. They also verify that objects have been properly configured and set up by the service container. They supplement unit tests by checking scenarios that do not have unit tests written for them.

There are two php settings which affect runtime assertions. The first, assert.exception, should always be set to 1. The second is zend.assertions. Set this to -1 in production and 1 in development.

See https://www.drupal.org/node/2492225 for more information on runtime assertions.

File

core/core.api.php, line 1168

Documentation landing page and topics, plus core library hooks.

Classes