assert.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 2916fa4160bdf53bb316a5c7c018fc91df7cd951 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.assert" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>assert</refname>
  <refpurpose>Verifica una aserción</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>assert</methodname>
   <methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>Throwable</type><type>string</type><type>null</type></type><parameter>description</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>assert</function>
   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.
  </para>
  <para>
   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.
  </para>
  <para>
   Como las aserciones pueden ser configuradas para ser eliminadas, no deben
   <emphasis>ser</emphasis> 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.
  </para>
  <para>
   <function>assert</function> verificará que la expectativa dada en
   <parameter>assertion</parameter> 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 <function>assert</function>.
  </para>
  <para>
   El comportamiento de <function>assert</function> está dictado por los siguientes parámetros INI:
   <table>
    <title>Assert &ConfigureOptions;</title>
     <tgroup cols="4">
     <thead>
      <row>
       <entry>&Name;</entry>
       <entry>&Default;</entry>
       <entry>&Description;</entry>
       <entry>&Changelog;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><link linkend="ini.zend.assertions">zend.assertions</link></entry>
       <entry><literal>1</literal></entry>
       <entry>
        <simplelist>
         <member>
          <literal>1</literal> : genera y ejecuta el código (modo desarrollo)
         </member>
         <member>
          <literal>0</literal> : genera el código pero lo evita en tiempo de ejecución
         </member>
         <member>
          <literal>-1</literal> : no genera el código (modo producción)
         </member>
        </simplelist>
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.active">assert.active</link></entry>
       <entry>&true;</entry>
       <entry>
        Si &false;, <function>assert</function> no verifica la expectativa
        y siempre devuelve &true;, sin condición.
       </entry>
       <entry>
        Deprecado a partir de PHP 8.3.0.
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.callback">assert.callback</link></entry>
       <entry>&null;</entry>
       <entry>
        <para>
         Una función definida por el usuario a llamar cuando una aserción falla.
         Su firma debería ser:
         <methodsynopsis role="procedural">
          <type>void</type><methodname>assert_callback</methodname>
          <methodparam><type>string</type><parameter>file</parameter></methodparam>
          <methodparam><type>int</type><parameter>line</parameter></methodparam>
          <methodparam><type>null</type><parameter>assertion</parameter></methodparam>
          <methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
         </methodsynopsis>
        </para>
       </entry>
       <entry>
        <para>
         Anterior a PHP 8.0.0, la firma de la función de devolución de llamada debería ser:
         <methodsynopsis role="procedural">
          <type>void</type><methodname>assert_callback</methodname>
          <methodparam><type>string</type><parameter>file</parameter></methodparam>
          <methodparam><type>int</type><parameter>line</parameter></methodparam>
          <methodparam><type>string</type><parameter>assertion</parameter></methodparam>
          <methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
         </methodsynopsis>
        </para>
        <simpara>
         Deprecado a partir de PHP 8.3.0.
        </simpara>
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.exception">assert.exception</link></entry>
       <entry>&true;</entry>
       <entry>
        Si &true;, lanzará una <classname>AssertionError</classname> si la expectativa no es cumplida.
       </entry>
       <entry>
        Deprecado a partir de PHP 8.3.0.
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.bail">assert.bail</link></entry>
       <entry>&false;</entry>
       <entry>
        Si &true;, interrumpirá la ejecución del script PHP si la expectativa no es cumplida.
       </entry>
       <entry>
        Deprecado a partir de PHP 8.3.0.
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.warning">assert.warning</link></entry>
       <entry>&true;</entry>
       <entry>
        Si &true;, emitirá un <constant>E_WARNING</constant> si la expectativa no es cumplida.
        Este parámetro INI es ineficaz si
        <link linkend="ini.assert.exception">assert.exception</link>
        está activado.
       </entry>
       <entry>
        Deprecado a partir de PHP 8.3.0.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>assertion</parameter></term>
     <listitem>
      <para>
       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ó.
      </para>

      <warning>
       <para>
        Anterior a PHP 8.0.0, si <parameter>assertion</parameter> era una
        <type>string</type>, era interpretada como código PHP y ejecutada vía
        <function>eval</function>.
        Esta cadena era pasada a la función de devolución de llamada como tercer argumento.
        Este comportamiento estaba <emphasis>DEPRECADO</emphasis> en PHP 7.2.0,
        y es <emphasis>ELIMINADO</emphasis> a partir de PHP 8.0.0
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>description</parameter></term>
     <listitem>
      <para>
       Si <parameter>description</parameter> es una instancia de
       <classname>Throwable</classname>, será lanzada únicamente si
       <parameter>assertion</parameter> es ejecutada y falla.
       <note>
        <para>
         A partir de PHP 8.0.0, esto se hace <emphasis>antes</emphasis> de llamar
         a la función de devolución de llamada de aserción eventualmente definida
        </para>
       </note>
       <note>
        <para>
         A partir de PHP 8.0.0, el objeto &object; será lanzado independientemente de la configuración de
         <link linkend="ini.assert.exception">assert.exception</link>.
        </para>
       </note>
       <note>
        <para>
         A partir de PHP 8.0.0, el parámetro
         <link linkend="ini.assert.bail">assert.bail</link>
         no tiene ningún efecto en este caso.
        </para>
       </note>
      </para>
      <para>
       Si <parameter>description</parameter> 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 <parameter>assertion</parameter> falla.
      </para>
      <para>
       Si <parameter>description</parameter> es omitido.
       <!-- Esto no ocurre si &null; es pasado ... -->
       Se crea una descripción por defecto equivalente al código fuente de la llamada a
       <function>assert</function> en tiempo de compilación.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>assert</function> siempre devolverá &true; si al menos una de las siguientes condiciones es verdadera:
  </para>
  <simplelist>
   <member><literal>zend.assertions=0</literal></member>
   <member><literal>zend.assertions=-1</literal></member>
   <member><literal>assert.active=0</literal></member>
   <member><literal>assert.exception=1</literal></member>
   <member><literal>assert.bail=1</literal></member>
   <member>Un objeto de excepción personalizado es pasado a <parameter>description</parameter>.</member>
  </simplelist>
  <para>
   Si ninguna de las condiciones es verdadera, <function>assert</function> devolverá &true; si
   <parameter>assertion</parameter> es verdadero, y &false; de lo contrario.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.3.0</entry>
       <entry>
        Todas las configuraciones INI <literal>assert.</literal> han sido depreciadas.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        La función <function>assert</function> ya no evaluará argumentos de tipo string,
        en su lugar, serán tratados como cualquier otro argumento.
        <code>assert($a == $b)</code> debería ser utilizado en lugar de <code>assert('$a == $b')</code>.
        La directiva <literal>assert.quiet_eval</literal> &php.ini; y la constante <constant>ASSERT_QUIET_EVAL</constant>
        también han sido eliminadas, ya que no tendrían ningún efecto.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Si <parameter>description</parameter> es una instancia de
        <classname>Throwable</classname>, el objeto es lanzado si la aserción falla, independientemente del valor de
        <link linkend="ini.assert.exception">assert.exception</link>.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Si <parameter>description</parameter> es una instancia de
        <classname>Throwable</classname>, ninguna función de devolución de llamada de usuario
        es llamada incluso si está definida.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Declarar una función que se llame <literal>assert()</literal> dentro
        de un espacio de nombres ya no es permitido, y genera
        una <constant>E_COMPILE_ERROR</constant>.
       </entry>
      </row>
      <row>
       <entry>7.3.0</entry>
       <entry>
        Declarar una función que se llame <literal>assert()</literal> dentro
        de un espacio de nombres se ha depreciado. Tales
        declaraciones generan ahora una <constant>E_DEPRECATED</constant>.
       </entry>
      </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        El uso de una &string; como <parameter>assertion</parameter> se
        ha depreciado. Esto emite ahora una advertencia
        <constant>E_DEPRECATED</constant> cuando
        <link linkend="ini.assert.active">assert.active</link> y
        <link linkend="ini.zend.assertions">zend.assertions</link> están
        ambos definidos a <literal>1</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
   <example>
    <title>Ejemplo de <function>assert</function></title>
    <programlisting role="php">
<![CDATA[
<?php
assert(1 > 2);
echo '¡Hola!';
?>
]]>
    </programlisting>
    <para>
     Si las aserciones están activadas (<link linkend="ini.zend.assertions"><literal>zend.assertions=1</literal></link>)
     el ejemplo anterior mostraría:
    </para>
    <screen>
<![CDATA[
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
]]>
    </screen>
    <para>
     Si las aserciones están desactivadas (<literal>zend.assertions=0</literal> o <literal>zend.assertions=-1</literal>)
     el ejemplo anterior mostraría:
    </para>
    <screen>
<![CDATA[
¡Hola!
]]>
    </screen>
   </example>
   <example>
    <title>Uso de un mensaje personalizado</title>
    <programlisting role="php">
<![CDATA[
<?php
assert(1 > 2, "Se esperaba que uno fuera mayor que dos");
echo '¡Hola!';
?>
]]>
    </programlisting>
    <para>
     Si las aserciones están activadas, el ejemplo anterior mostraría:
     el ejemplo anterior mostraría:
    </para>
    <screen>
<![CDATA[
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
]]>
    </screen>
    <para>
     Si las aserciones están desactivadas, el ejemplo anterior mostraría:
     el ejemplo anterior mostraría:
    </para>
    <screen>
<![CDATA[
¡Hola!
]]>
    </screen>
    </example>
    <example>
     <title>Uso de una clase de excepción personalizada</title>
     <programlisting role="php">
      <![CDATA[
      <?php
      class ArithmeticAssertionError extends AssertionError {}

      assert(1 > 2, new ArithmeticAssertionError("Se esperaba que uno fuera mayor que dos"));
      echo '¡Hola!';
      ]]>
     </programlisting>
    <para>
     Si las aserciones están activadas, el ejemplo anterior mostraría:
     el ejemplo anterior mostraría:
    </para>
    <screen>
<![CDATA[
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
]]>
    </screen>
     <para>
      Si las aserciones están desactivadas, el ejemplo anterior mostraría:
     </para>
     <screen>
<![CDATA[
¡Hola!
]]>
     </screen>
    </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>assert_options</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->