Drupal  8.2.6
API documentation
Data Structures
PHP Runtime Assert Statements

Data Structures

class  Handle
class  Inspector

Detailed Description

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.

When runtime assertions fail in PHP 7 an is thrown. Drupal uses an assertion callback to do the same in PHP 5.x so that unit tests involving runtime assertions will work uniformly across both versions.

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 datatypes. They also verify that objects have been properly configured and set up by the service container. Runtime assertions are checked throughout development. They supplement unit tests by checking scenarios that do not have unit tests written for them, and by testing the API calls made by all the code in the system.

When using assert() keep the following in mind:

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