Descripción

assert(mixed $assertion, Throwable|string|null $description = null): bool

assert() permite definir expectativas: aserciones que tienen efecto en los entornos de desarrollo y prueba, pero que están optimizadas para no tener costo en producción.

Las aserciones pueden ser utilizadas para ayudar en la depuración. Un caso de uso para las aserciones es servir como verificaciones de coherencia para precondiciones que deberían siempre ser true, y si no lo son, esto indica errores de programación. Otro caso de uso es garantizar la presencia de ciertas funcionalidades tales como funciones de extensión o ciertos límites y funcionalidades del sistema.

Como las aserciones pueden ser configuradas para ser eliminadas, no deben ser utilizadas para operaciones normales en tiempo de ejecución, tales como verificaciones de parámetros de entrada. En general, el código debe comportarse como se espera incluso si la verificación de aserciones está desactivada.

assert() verificará que la expectativa dada en assertion sea satisfecha. Si no lo es y por lo tanto el resultado es false, tomará la acción apropiada según la configuración de assert().

El comportamiento de assert() está dictado por los siguientes parámetros INI:
Assert Opciones de configuración

Nombre Por defecto Descripción Historial de cambios

zend.assertions 1

1 : genera y ejecuta el código (modo desarrollo)

0 : genera el código pero lo evita en tiempo de ejecución

-1 : no genera el código (modo producción)

assert.active true Si false, assert() no verifica la expectativa y siempre devuelve true, sin condición. Deprecado a partir de PHP 8.3.0.

assert.callback null
Una función definida por el usuario a llamar cuando una aserción falla. Su firma debería ser:
assert_callback(
    string $file,
    int $line,
    null $assertion,
    string $description = ?
): void

Anterior a PHP 8.0.0, la firma de la función de devolución de llamada debería ser:
assert_callback(
    string $file,
    int $line,
    string $assertion,
    string $description = ?
): void

Deprecado a partir de PHP 8.3.0.

assert.exception true Si true, lanzará una AssertionError si la expectativa no es cumplida. Deprecado a partir de PHP 8.3.0.

assert.bail false Si true, interrumpirá la ejecución del script PHP si la expectativa no es cumplida. Deprecado a partir de PHP 8.3.0.

assert.warning true Si true, emitirá un E_WARNING si la expectativa no es cumplida. Este parámetro INI es ineficaz si assert.exception está activado. Deprecado a partir de PHP 8.3.0.

**Assert Opciones de configuración**
Nombre	Por defecto	Descripción	Historial de cambios
zend.assertions	`1`	`1` : genera y ejecuta el código (modo desarrollo) `0` : genera el código pero lo evita en tiempo de ejecución `-1` : no genera el código (modo producción)
assert.active	`true`	Si `false`, assert() no verifica la expectativa y siempre devuelve `true`, sin condición.	Deprecado a partir de PHP 8.3.0.
assert.callback	`null`	Una función definida por el usuario a llamar cuando una aserción falla. Su firma debería ser: assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void	Anterior a PHP 8.0.0, la firma de la función de devolución de llamada debería ser: assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void Deprecado a partir de PHP 8.3.0.
assert.exception	`true`	Si `true`, lanzará una AssertionError si la expectativa no es cumplida.	Deprecado a partir de PHP 8.3.0.
assert.bail	`false`	Si `true`, interrumpirá la ejecución del script PHP si la expectativa no es cumplida.	Deprecado a partir de PHP 8.3.0.
assert.warning	`true`	Si `true`, emitirá un `E_WARNING` si la expectativa no es cumplida. Este parámetro INI es ineficaz si assert.exception está activado.	Deprecado a partir de PHP 8.3.0.

Parámetros

assertion

Esta es cualquier expresión que devuelve un valor, que será ejecutada y cuyo resultado será utilizado para indicar si la aserción tuvo éxito o falló.

Advertencia

Anterior a PHP 8.0.0, si assertion era una string, era interpretada como código PHP y ejecutada vía eval(). Esta cadena era pasada a la función de devolución de llamada como tercer argumento. Este comportamiento estaba DEPRECADO en PHP 7.2.0, y es ELIMINADO a partir de PHP 8.0.0

description

Si description es una instancia de Throwable, será lanzada únicamente si assertion es ejecutada y falla.

Nota:
A partir de PHP 8.0.0, esto se hace antes de llamar a la función de devolución de llamada de aserción eventualmente definida

Nota:
A partir de PHP 8.0.0, el objeto object será lanzado independientemente de la configuración de assert.exception.

Nota:
A partir de PHP 8.0.0, el parámetro assert.bail no tiene ningún efecto en este caso.

Si description es una string, este mensaje será utilizado si se emite una excepción o advertencia. Una descripción opcional, que será incluida en el mensaje de fallo si la assertion falla.

Si description es omitido. Se crea una descripción por defecto equivalente al código fuente de la llamada a assert() en tiempo de compilación.

Valores devueltos

assert() siempre devolverá true si al menos una de las siguientes condiciones es verdadera:

zend.assertions=0
zend.assertions=-1
assert.active=0
assert.exception=1
assert.bail=1
Un objeto de excepción personalizado es pasado a description.

Si ninguna de las condiciones es verdadera, assert() devolverá true si assertion es verdadero, y false de lo contrario.

Historial de cambios

Versión Descripción

8.3.0 Todas las configuraciones INI assert. han sido depreciadas.

8.0.0 La función assert() ya no evaluará argumentos de tipo string, en su lugar, serán tratados como cualquier otro argumento. assert($a == $b) debería ser utilizado en lugar de assert('$a == $b'). La directiva assert.quiet_eval php.ini y la constante ASSERT_QUIET_EVAL también han sido eliminadas, ya que no tendrían ningún efecto.

8.0.0 Si description es una instancia de Throwable, el objeto es lanzado si la aserción falla, independientemente del valor de assert.exception.

8.0.0 Si description es una instancia de Throwable, ninguna función de devolución de llamada de usuario es llamada incluso si está definida.

8.0.0 Declarar una función que se llame assert() dentro de un espacio de nombres ya no es permitido, y genera una E_COMPILE_ERROR.

7.3.0 Declarar una función que se llame assert() dentro de un espacio de nombres se ha depreciado. Tales declaraciones generan ahora una E_DEPRECATED.

7.2.0 El uso de una string como assertion se ha depreciado. Esto emite ahora una advertencia E_DEPRECATED cuando assert.active y zend.assertions están ambos definidos a 1.

Versión	Descripción
8.3.0	Todas las configuraciones INI `assert.` han sido depreciadas.
8.0.0	La función assert() ya no evaluará argumentos de tipo string, en su lugar, serán tratados como cualquier otro argumento. `assert($a == $b)` debería ser utilizado en lugar de `assert('$a == $b')`. La directiva `assert.quiet_eval` `php.ini` y la constante `ASSERT_QUIET_EVAL` también han sido eliminadas, ya que no tendrían ningún efecto.
8.0.0	Si `description` es una instancia de Throwable, el objeto es lanzado si la aserción falla, independientemente del valor de assert.exception.
8.0.0	Si `description` es una instancia de Throwable, ninguna función de devolución de llamada de usuario es llamada incluso si está definida.
8.0.0	Declarar una función que se llame `assert()` dentro de un espacio de nombres ya no es permitido, y genera una `E_COMPILE_ERROR`.
7.3.0	Declarar una función que se llame `assert()` dentro de un espacio de nombres se ha depreciado. Tales declaraciones generan ahora una `E_DEPRECATED`.
7.2.0	El uso de una string como `assertion` se ha depreciado. Esto emite ahora una advertencia `E_DEPRECATED` cuando assert.active y zend.assertions están ambos definidos a `1`.

Ejemplos

Ejemplo #1 Ejemplo de assert()

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

Si las aserciones están activadas (zend.assertions=1) el ejemplo anterior mostraría:

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

Si las aserciones están desactivadas (zend.assertions=0 o zend.assertions=-1) el ejemplo anterior mostraría:

¡Hola!

Ejemplo #2 Uso de un mensaje personalizado

<?php
assert(1 > 2, "Se esperaba que uno fuera mayor que dos");
echo '¡Hola!';
?>

Si las aserciones están activadas, el ejemplo anterior mostraría: el ejemplo anterior mostraría:

Fatal error: Uncaught AssertionError: Se esperaba que uno fuera mayor que dos in example.php:2
Stack trace:
#0 example.php(2): assert(false, 'Se esperaba que uno...')
#1 {main}
  thrown in example.php on line 2

Si las aserciones están desactivadas, el ejemplo anterior mostraría: el ejemplo anterior mostraría:

¡Hola!

Ejemplo #3 Uso de una clase de excepción personalizada

<?php
      class ArithmeticAssertionError extends AssertionError {}

      assert(1 > 2, new ArithmeticAssertionError("Se esperaba que uno fuera mayor que dos"));
      echo '¡Hola!';

Si las aserciones están activadas, el ejemplo anterior mostraría: el ejemplo anterior mostraría:

Fatal error: Uncaught ArithmeticAssertionError: Se esperaba que uno fuera mayor que dos in example.php:4
Stack trace:
#0 {main}
  thrown in example.php on line 4

Si las aserciones están desactivadas, el ejemplo anterior mostraría:

¡Hola!

Ver también

assert_options() - Define/recupere diferentes opciones de aserciones