language/functions.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ae8e5c871b1a71ea77f5b97f7929d76d4ca724ab Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: andresdzphp -->
<chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook">
 <title>Funciones</title>

 <sect1 xml:id="functions.user-defined">
  <title>Funciones definidas por el usuario</title>

  <para>
   Una función puede ser definida empleando una sintaxis como la siguiente:
  </para>
  <para>
   <example>
    <title>Seudocódigo para demostrar el uso de funciones</title>
    <programlisting role="php">
<![CDATA[
<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
    echo "Función de ejemplo.\n";
    return $retval;
}
?>
]]>
    </programlisting>
   </example>
  </para>

  <simpara>
   Cualquier código PHP válido puede aparecer dentro de una función, incluso otras
   funciones y definiciones de
   <link linkend="language.oop5.basic.class">clases</link>.
  </simpara>
  <para>
   Los nombres de las funciones siguen las mismas reglas que las demás etiquetas de PHP. Un
   nombre de función válido comienza con una letra o guión bajo, seguido de
   cualquier número de letras, números o guiones bajos. Como expresión regular
   se expresaría así:
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>.
  </para>
  &tip.userlandnaming;
  <simpara>
   No es necesario definir una función antes de que sea referenciada,
   <emphasis>excepto</emphasis> cuando esta esté condicionalmente definida como
   se muestra en los dos ejemplos de abajo.
  </simpara>
  <para>
   Cuando una función está definida de una forma condicional como en los dos
   ejemplos siguientes, sus definiciones deben ser procesadas <emphasis>antes</emphasis>
   de ser llamadas.
  </para>
  <para>
   <example>
    <title>Funciones condicionales</title>
    <programlisting role="php">
<![CDATA[
<?php

$hacer_algo = true;

/* No podemos llamar a foo() desde aquí
   ya que no existe aún,
   pero podemos llamar a bar() */

bar();

if ($hacer_algo) {
  function foo()
  {
    echo "No existo hasta que la ejecución del programa llegue hasta mí.\n";
  }
}

/* Ahora podemos llamar de forma segura a foo()
   ya que $hacer_algo se evaluó como verdadero */

if ($hacer_algo) foo();

function bar()
{
  echo "Existo desde el momento inmediato que comenzó el programa.\n";
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Funciones dentro de funciones</title>
    <programlisting role="php">
<![CDATA[
<?php
function foo()
{
  function bar()
  {
    echo "No existo hasta que se llame a foo().\n";
  }
}

/* No podemos llamar aún a bar()
   ya que no existe. */

foo();

/* Ahora podemos llamar a bar(),
   el procesamiento de foo()
   la ha hecho accesible. */

bar();

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Todas las funciones y clases de PHP tienen ámbito global. Se pueden
   llamar desde fuera de una función incluso si fueron definidas dentro, y viceversa.
  </para>
  <simpara>
   PHP no admite la sobrecarga de funciones, ni es posible
   'desdefinir' ni redefinir funciones previamente declaradas.
  </simpara>
  <note>
   <simpara>
    Los nombres de las fuciones son insensibles a mayúsculas-minúsculas para el rango
    de caracteres <literal>A</literal> a la <literal>Z</literal>, aunque es una buena
    práctica llamar a las funciones tal y como aparecen en sus declaraciones.
   </simpara>
  </note>
  <simpara>
   Las funciones admiten un <link linkend="functions.variable-arg-list">número variable de
   argumentos</link> y <link linkend="functions.arguments.default">argumentos
   predeterminados</link>. Véanse también las referencias
   de funciones para
   <function>func_num_args</function>,
   <function>func_get_arg</function>, y
   <function>func_get_args</function> para más información.
  </simpara>

  <para>
   En PHP es posible llamar a funciones recursivas.
   <example>
    <title>Funciones recursivas</title>
    <programlisting role="php">
<![CDATA[
<?php
function recursividad($a)
{
    if ($a < 20) {
        echo "$a\n";
        recursividad($a + 1);
    }
}
?>
]]>
    </programlisting>
   </example>
   <note>
    <simpara>
     Las llamadas a funciones/métodos recursivos con más de 100-200 niveles de recursividad pueden
     agotar la pila y ocasionar la finalización del script en curso. Especialmente,
     las recurisvidades infinitas están consideradas un error de programación.
    </simpara>
   </note>
  </para>

 </sect1>

 <sect1 xml:id="functions.arguments">
  <title>Parámetros y argumentos de funciones</title>

  <simpara>
   Los parámetros de una función son declarados en la firma de dicha función.
   Cualquier información puede ser pasada a las funciones mediante la lista de argumentos,
   la cual es una lista de expresiones delimitadas por comas. Los argumentos son
   evaluados de izquierda a derecha y el resultado es asignado a los parámetros
   de la función, antes de que la función sea llamada
   (evaluación <emphasis>ansiosa</emphasis>).
  </simpara>

  <para>
   PHP admite el paso de argumentos por valor (lo predeterminado), <link
   linkend="functions.arguments.by-reference">el paso por
   referencia</link>, y <link
   linkend="functions.arguments.default">valores de argumentos
   predeterminados</link>. Las <link linkend="functions.variable-arg-list">Listas de argumentos
   de longitud variable</link> y <link linkend="functions.named-arguments">Argumentos por nombre</link>
   también están soportados.
  </para>
  <para>
   <example>
    <title>Pasar arrays a funciones</title>
    <programlisting role="php">
<![CDATA[
<?php
function tomar_array($entrada)
{
    echo "$entrada[0] + $entrada[1] = ", $entrada[0]+$entrada[1];
}
?>
]]>
    </programlisting>
    </example>
   </para>
   <para>
    Desde PHP 8.0.0, la lista de argumentos de una función puede incluir una coma final, la cual
    será ignorada. Esto es particularmente útil en casos donde la lista de argumentos es
    larga o contiene nombres de variables extensos, lo que facilita listar los argumentos de forma vertical.
   </para>
   <example>
    <title>Lista de argumentos de función con coma final</title>
    <programlisting role="php">
<![CDATA[
<?php
function recibe_muchos_args(
    $primer_arg,
    $segundo_arg,
    $un_nombre_de_argumento_muy_largo,
    $arg_con_valor_por_defecto = 5,
    $otra_vez = 'un string por defecto', // Esta coma final no era permitida antes de PHP 8.0.0.
)
{
    // ...
}
?>
]]>
    </programlisting>
   </example>

   <sect2 xml:id="functions.arguments.by-reference">
   <title>Paso de argumentos por referencia</title>

   <simpara>
    Por defecto, los argumentos de las funciones son pasados por valor (así, si
    el valor del argumento dentro de la función cambia, este no
    cambia fuera de la función). Para permitir a una función modificar sus
    argumentos, éstos deben pasarse por referencia.
   </simpara>
   <para>
    Para hacer que un argumento a una función sea siempre pasado por referencia hay que anteponer
    al nombre del argumento el signo 'et' (&amp;) en la definición de la función:
   </para>
   <para>
    <example>
     <title>Paso de parámetros de una función por referencia</title>
     <programlisting role="php">
<![CDATA[
<?php
function añadir_algo(&$cadena)
{
    $cadena .= 'y algo más.';
}
$cad = 'Esto es un string, ';
añadir_algo($cad);
echo $cad;    // imprime 'Esto es un string, y algo más.'
?>
]]>
     </programlisting>
    </example>
   </para>
    <para>
     Es un error pasar una expresión constante como argumento a un parámetro que espera ser pasado por referencia.
    </para>
  </sect2>
  <sect2 xml:id="functions.arguments.default">
   <title>Valores de argumentos predeterminados</title>

   <para>
    Una función puede definir valores predeterminados para argumentos usando
    una sintaxis similar a la asignación de una variable. El valor predeterminado
    es usado solo cuando no se pasa el argumento del parametro. Nota que cuando se
    pasa &null; <emphasis>no</emphasis> se usa el valor predeterminado.
   </para>
   <para>
    <example>
     <title>Uso de parámetros predeterminados en funciones</title>
     <programlisting role="php">
<![CDATA[
<?php
function hacer_café($tipo = "capuchino")
{
    return "Hacer una taza de $tipo.\n";
}
echo hacer_café();
echo hacer_café(null);
echo hacer_café("espresso");
?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
Hacer una taza de capuchino.
Hacer una taza de .
Hacer una taza de espresso.
]]>
     </screen>
    </example>
   </para>
   <para>
    Los parámetros predeterminados puedes ser valores, <type>array</type>s,
    el tipo especial &null;, y desde PHP 8.1.0, objetos usando la
    sintaxis <link linkend="language.oop5.basic.new">new ClassName()</link>.
   </para>
   <para>
    <example>
     <title>Usar tipos no escalares como valores predeterminados</title>
     <programlisting role="php">
<![CDATA[
<?php
function hacer_café($tipos = array("capuchino"), $fabricanteCafé = NULL)
{
    $aparato = is_null($fabricanteCafé) ? "las manos" : $fabricanteCafé;
    return "Hacer una taza de ".join(", ", $tipos)." con $aparato.\n";
}
echo hacer_café();
echo hacer_café(array("capuchino", "lavazza"), "una tetera");
?>
]]>
     </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Hacer una taza de capuchino con las manos.
Hacer una taza de capuchino, lavazza con una tetera.
]]>
      </screen>
    </example>
    </para>
    <para>
     <example>
      <title>Usando objetos como valores predeterminados (desde PHP 8.1.0)</title>
      <programlisting role="php">
<![CDATA[
<?php
class CafeteraNormal {
    public function infusionar() {
        return "Haciendo café.\n";
    }
}
class CafeteraElegante {
    public function infusionar() {
        return "Elaboramos un café delicioso solo para ti.\n";
    }
}
function hacerCafe($coffeeMaker = new CafeteraNormal)
{
    return $coffeeMaker->infusionar();
}
echo hacerCafe();
echo hacerCafe(new CafeteraElegante);
?>
]]>
      </programlisting>

      &example.outputs;
      <screen>
<![CDATA[
Haciendo café.
Elaboramos un café delicioso solo para ti.
]]>
      </screen>
     </example>
    </para>

    <simpara>
     El valor predeterminado debe ser una expresión constante, no (por
     ejemplo) una variable, un miembro de una clase o una llamada a una función.
    </simpara>
    <para>
     Obsérvese que cuando se emplean argumentos predeterminados, cualquiera de ellos debería estar a
     la derecha de los argumentos no predeterminados; si no, las cosas
     pueden no funcionar como se espera. Observe el siguiente ejemplo:
    </para>
    <para>
     <example>
      <title>Uso incorrecto de argumentos predeterminados en una función</title>
      <programlisting role="php">
<![CDATA[
<?php
function hacerYogur($container = "bol", $flavour)
{
    return "Hacer un $container de yogur $tipo de $flavour.\n";
}

echo hacerYogur("frambuesa"); // "frambuesa" es $container, no $flavour
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Fatal error: Uncaught ArgumentCountError: Too few arguments
 to function hacerYogur(), 1 passed ...
]]>
      </screen>
     </example>
    </para>
    <para>
     Ahora, compare el ejemplo de arriba con este:
    </para>
    <para>
     <example>
      <title>Uso correcto de argumentos predeterminados en una función</title>
      <programlisting role="php">
<![CDATA[
<?php
function hacerYogur($flavour, $container = "bol")
{
    return "Haciendo un $container de yogur de $flavour.\n";
}

echo hacerYogur("frambuesa"); // "frambuesa" es $flavour
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Haciendo un bol de yogur de frambuesa.
]]>
      </screen>
     </example>
    </para>
    <para>
     Desde PHP 8.0.0, los <link linkend="functions.named-arguments">argumentos con nombre</link>
     pueden ser usados para omitir varios parámetros opcionales.
    </para>
    <para>
     <example>
      <title>Uso correcto de funciones con parámetros opcionales</title>
      <programlisting role="php">
<![CDATA[
<?php
function hacerYogur($container = "bol", $flavour = "frambuesa", $style = "griego")
{
    return "Haciendo un $container de yogurt $style de $flavour.\n";
}

echo hacerYogur(style: "natural");
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Haciendo un bol de yogurt natural de frambuesa.
]]>
      </screen>
     </example>
    </para>
    <para>
     Desde PHP 8.0.0, declarar parámetros obligatorios despues de
     parámetros opcionales se considera <emphasis>obsoleto</emphasis>.
     Esto normalmente suele resolverse eliminando el valor predeterminado,
     ya que nunca se utilizará.
     La única excepción a esta regla son los parámetros de la forma
     <code>Tipo $param = null</code>, cuando el valor &null; es el valor
     predeterminado explicamente de un tipo nullable.
     Este uso está obsoleto desde PHP 8.4.0, y se debería usar
     explicatemente un <link linkend="language.types.declarations.nullable">tipo nullable</link>
     en su lugar.
     <example>
      <title>Declarando parámetros opcionales despues de parámetros obligatorios</title>
      <programlisting role="php">
<![CDATA[
<?php

function foo($a = [], $b) {}     // No usado por omisión; obsoleto desde PHP 8.0.0
function foo($a, $b) {}          // Funcionalidad equivalente, sin notificación de obsolescencia

function bar(A $a = null, $b) {} // Desde PHP 8.1.0, $a es requerido implicitamente
                                 // (porque está antes del requerido),
                                 // pero nullable implicicamente (obsoleto desde PHP 8.4.0),
                                 // porque el valor predeterminado es null
function bar(?A $a, $b) {}       // Forma recomendada

?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <simpara>
      Desde PHP 7.1.0, omitir un parámetro que no especifique un valor predeterminado
      lanza un <classname>ArgumentCountError</classname>; en versiones anteriores
      lanzaba un <constant>E_WARNING</constant>.
     </simpara>
    </note>
    <note>
     <simpara>
      Los parámetros que esperan los argumentos pasados por referencia pueden tener un valor predeterminado.
     </simpara>
    </note>
   </sect2>

   <sect2 xml:id="functions.variable-arg-list">
    <title>Listas de argumentos de longitud variable</title>

    <simpara>
     PHP tiene soporte para argumentos de longitud variable en
     funciones definidas por el usuario mediante el uso del
     símbolo <literal>...</literal>.
    </simpara>

    <para>
     La lista de parámetros puede incluir el símbolo <literal>...</literal>
     para indicar que la función acepta un número variable de argumentos.
     Los argumentos serán pasados a la variable dada como un &array;:

     <example>
      <title>Usando <literal>...</literal> para acceder a argumentos variables</title>
      <programlisting role="php">
<![CDATA[
<?php
function suma(...$numbers) {
    $acc = 0;
    foreach ($numbers as $n) {
        $acc += $n;
    }
    return $acc;
}

echo suma(1, 2, 3, 4);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
10
]]>
      </screen>
     </example>
    </para>

    <para>
     <literal>...</literal> puede ser usado tambien llamando a funciones
     para convertir un <type>array</type>, un <classname>Traversable</classname>
     o un literal entre la lista de argumentos:

     <example>
      <title>Usando <literal>...</literal> para proporcionar los argumentos</title>
      <programlisting role="php">
<![CDATA[
<?php
function suma($a, $b) {
    return $a + $b;
}

echo suma(...[1, 2])."\n";

$a = [1, 2];
echo suma(...$a);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
3
3
]]>
      </screen>
     </example>
    </para>

    <para>
     Puedes especificar parámetros posicionales normales antes del
     símbolo <literal>...</literal>. En este caso, solo los argumentos
     finales que no coincidan con un argumento posicional serán añadidos
     al <type>array</type> generado por <literal>...</literal>.
    </para>

    <para>
     También es posible añadir una
     <link linkend="language.types.declarations">declaración de tipo</link>
     antes del símbolo <literal>...</literal>. Si esta está presente,
     entonces todos los argumentos capturados por <literal>...</literal>
     deben coincidir con el tipo de parámetro indicado.

     <example>
      <title>Argumentos variables con declaración de tipo</title>
      <programlisting role="php">
<![CDATA[
<?php
function totalIntervalos($unit, DateInterval ...$intervals) {
    $time = 0;
    foreach ($intervals as $interval) {
        $time += $interval->$unit;
    }
    return $time;
}

$a = new DateInterval('P1D');
$b = new DateInterval('P2D');
echo totalIntervalos('d', $a, $b).' días';

// Esto fallará, ya que null no es un objeto del tipo DateInterval.
echo totalIntervalos('d', null);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
3 días
Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2
]]>
      </screen>
     </example>
    </para>

    <para>
     Por último, los argumentos variables tambien pueden ser pasados
     <link linkend="functions.arguments.by-reference">por referencia</link>,
     usando el simbolo 'et' (<literal>&amp;</literal>) antes de
     <literal>...</literal>.
    </para>

   </sect2>

<sect2 xml:id="functions.named-arguments">
    <title>Argumentos con nombre</title>

    <para>
     PHP 8.0.0 introdujo argumentos con nombre como una extensión de los
     parámetros posicionales existentes. Los argumentos con nombre permiten
     pasar argumentos a una función con el nombre del parámetro,
     en lugar de su posición.
     Esto hace que el significado del argumento sea autodocumentado,
     hace que los argumentos sean independientes del orden y permite omitir
     valores predeterminados de forma arbitraria.
    </para>

    <para>
     Los argumentos con nombre se pasan anteponiendo el valor con el nombre
     del parámetro seguido de dos puntos. Se permite el uso de palabras clave
     reservadas como nombres de parámetros.
     El nombre del parámetro debe ser un identificador, no se puede especificar dinámicamente
    </para>

    <example>
     <title>Sintaxis de argumentos con nombre</title>
     <programlisting role="php">
<![CDATA[
<?php
myFuncion(paramName: $value);
array_foobar(array: $value);

// NO válido.
function_name($variableStoringParamName: $value);
?>
]]>
     </programlisting>
    </example>

    <example>
     <title>Argumentos posicionales vs argumentos con nombre</title>
     <programlisting role="php">
<![CDATA[
<?php
// Usando argumentos posicionales:
array_fill(0, 100, 50);

// Usando argumentos con nombre:
array_fill(start_index: 0, count: 100, value: 50);
?>
]]>
     </programlisting>
    </example>

    <para>
     No importa el orden en que se pasan los argumentos con nombre.
    </para>

    <example>
     <title>El mismo ejemplo que el anterior con un orden diferente de parámetros.</title>
     <programlisting role="php">
<![CDATA[
<?php
array_fill(value: 50, count: 100, start_index: 0);
?>
]]>
     </programlisting>
    </example>

    <para>
     Los argumentos con nombre se pueden combinar con argumentos
     posicionales. En este caso, los argumentos con nombre deben ir
     después de los argumentos posicionales.
     También es posible especificar solo algunos de los argumentos opcionales
     de una función, independientemente de su orden.
    </para>

    <example>
     <title>Combinando argumentos con nombre con argumentos posicionales</title>
     <programlisting role="php">
<![CDATA[
<?php
htmlspecialchars($string, double_encode: false);
// Es lo mismo que
htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);
?>
]]>
     </programlisting>
    </example>

    <para>
     Pasar un argumento al mismo parámetro con nombre varias veces da como
     resultado una excepción <classname>Error</classname>.
    </para>

    <example>
     <title>Se produce un error al pasar un argumento al mismo parámetro con nombre varias veces</title>
     <programlisting role="php">
<![CDATA[
<?php

function foo($param) { ... }

foo(param: 1, param: 2);
// Error: Named parameter $param overwrites previous argument

foo(1, param: 2);
// Error: Named parameter $param overwrites previous argument

?>
]]>
     </programlisting>
    </example>

    <para>
     Desde PHP 8.1.0, es posible utilizar argumentos con nombre después de desempaquetarlos.
     Un argumento con nombre <emphasis>no debe</emphasis> sobrescribir un argumento ya desempaquetado.
    </para>

    <example>
     <title>Uso de argumentos con nombre después de desempaquetar</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo($a, $b, $c = 3, $d = 4) {
  return $a + $b + $c + $d;
}

var_dump(foo(...[1, 2], d: 40)); // 46
var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

var_dump(foo(...[1, 2], b: 20)); // Error. El parámetro con nombre $b sobrescribe el argumento anterior
?>
]]>
     </programlisting>
    </example>

   </sect2>
  </sect1>

  <sect1 xml:id="functions.returning-values">
   <title>Devolver valores</title>

   <para>
    Los valores son devueltos usando la sentencia opcional return. Se
    puede devolver cualquier tipo, incluidos arrays y objetos. Esto causa que la
    función finalice su ejecución inmediatamente y pase el control de nuevo a
    la línea desde la que fue llamada. Véase <function>return</function>
    para más información.
   </para>

   <note>
    <para>
     Si se omite <function>return</function>, el valor devuelto será
     &null;.
    </para>
   </note>

   <sect2>
    <title>Empleo de return</title>
    <para>
     <example>
      <title>Empleo de <function>return</function></title>
      <programlisting role="php">
<![CDATA[
<?php
function cuadrado($núm)
{
    return $núm * $núm;
}
echo cuadrado(4);   // imprime '16'.
?>
]]>
      </programlisting>
     </example>
    </para>

    <para>
     Una función no puede devolver múltiples valores, pero se pueden obtener resultados
     similares devolviendo un array.
    </para>
    <para>
     <example>
      <title>Devolver un array para obtener múltiples valores</title>
      <programlisting role="php">
<![CDATA[
<?php
function numerosPequeños()
{
    return [0, 1, 2];
}
// La desestructuración arrays recopilará cada miembro del array individualmente.
[$zero, $one, $two] = numerosPequeños();

// Antes de PHP 7.1.0, la única alternativa equivalente era el uso del constructor list()
list($zero, $one, $two) = numerosPequeños();

?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     Para devolver una referencia desde una función use el operador de referencia &amp;,
     tanto en la declaración de la función y cuando se asigne el valor devuelto a una
     variable:
    </para>
    <para>
     <example>
      <title>Devolver una referencia desde una función</title>
      <programlisting role="php">
<![CDATA[
<?php
function &devolver_referencia()
{
    return $algunaref;
}

$nuevaref =& devolver_referencia();
?>
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     Para más información sobre referencias, por favor, lea las <link
     linkend="language.references">Referencias explicadas</link>.
    </simpara>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.variable-functions">
   <title>Funciones variables</title>

   <para>
    PHP admite el concepto de funciones variables. Esto significa que si
    un nombre de variable tiene paréntesis anexos a él, PHP buscará
    una función con el mismo nombre que lo evaluado por la variable,
    e intentará ejecutarla. Entre otras cosas, esto se puede
    usar para implementar llamadas de retorno, tablas de funciones, y así sucesivamente.
   </para>
   <para>
    Las funciones variables no funcionarán con constructores de lenguaje como
    <function>echo</function>, <function>print</function>,
    <function>unset</function>, <function>isset</function>,
    <function>empty</function>, <function>include</function>,
    <function>require</function> y similares. Utilice funciones de envoltura para hacer
    uso de cualquiera de estos constructores como funciones variables.
   </para>
   <para>
    <example>
     <title>Ejemplo de función variable</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo() {
    echo "En foo()<br />\n";
}

function bar($arg = '')
{
    echo "En bar(); el argumento era '$arg'.<br />\n";
}

// Esta es una función de envoltura alrededor de echo
function hacerecho($string)
{
    echo $string;
}

$func = 'foo';
$func();        // Esto llama a foo()

$func = 'bar';
$func('prueba');  // Esto llama a bar()

$func = 'hacerecho';
$func('prueba');  // Esto llama a hacerecho()
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Los métodos de objetos también puede ser llamados con la sintaxis de funciones variables.
    <example>
     <title>Ejemplo de método variable</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo
{
    function Variable()
    {
        $nombre = 'Bar';
        $this->$nombre(); // Esto llama al método Bar()
    }

    function Bar()
    {
        echo "Esto es Bar";
    }
}

$foo = new Foo();
$nombrefunc = "Variable";
$foo->$nombrefunc();  // Esto llama a $foo->Variable()

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Cuando se llaman a métodos estáticos, la llamada a la función es más fuerte que el
    operador de propiedad estática:
    <example>
     <title>Ejemplo de método variable con propiedades estáticas</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo
{
    static $variable = 'propiedad estática';
    static function Variable()
    {
        echo 'Método Variable llamado';
    }
}

echo Foo::$variable; // Esto imprime 'propiedad estática'. No necesita una $variable en este ámbito.
$variable = "Variable";
Foo::$variable();  // Esto llama a $foo->Variable() leyendo $variable en este ámbito.

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    <example>
     <title>Llamables complejos</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo
{
    static function bar()
    {
        echo "bar\n";
    }
    function baz()
    {
        echo "baz\n";
    }
}

$func = array("Foo", "bar");
$func(); // Imprime "bar"
$func = array(new Foo, "baz");
$func(); // Imprime "baz"
$func = "Foo::bar";
$func(); // Imprime "bar"
?>
]]>
     </programlisting>
    </example>
   </para>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><function>is_callable</function></member>
      <member><function>call_user_func</function></member>
      <member><function>function_exists</function></member>
      <member><link linkend="language.variables.variable">variables variables</link></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.internal">
   <title>Funciones internas (incluidas)</title>

   <para>
    PHP se estandariza con muchas funciones y construcciones. También existen
    funciones que necesitan extensiones específicas de PHP compiladas, si no,
    aparecerán errores fatales "undefined function" ("función no definida"). Por ejemplo,
    para usar las funciones de <link linkend="ref.image">image</link> tales como
    <function>imagecreatetruecolor</function>, PHP debe ser compilado con
    soporte para <productname>GD</productname>. O para usar
    <function>mysql_connect</function>, PHP debe ser compilado con
    soporte para <link linkend="book.mysqli">MySQLi</link>. Hay muchas funciones de núcleo
    que está incluidas en cada versión de PHP, tales como las
    funciones de <link linkend="ref.strings">string</link> y de
    <link linkend="ref.var">variable</link>. Una llamada
    a <function>phpinfo</function> o
    <function>get_loaded_extensions</function> mostrará las extensiones que están
    cargadas en PHP. Observe también que muchas extensiones están habilitadas por defecto y
    que el manual de PHP está dividido por extensiones. Véase
    <link linkend="configuration">configuración</link>,
    <link linkend="install">instalación</link>, y capítulos individuales
    de extensiones para más información sobre cómo configurar PHP.
   </para>
   <para>
    Interpretar y comprender un prototipo de una función está explicado dentro de
    la sección del manual titulada <link linkend="about.prototypes">cómo interpretar
    la definición de una función</link>. Es importante comprender lo que devuelve una
    función o si una función funciona directamente con un valor pasado. Por ejemplo,
    <function>str_replace</function> devolverá la cadena modificada mientras que
    <function>usort</function> funciona con la variable actual pasada.
    Cada página del manual también tiene información específica para cada
    función, como información sobre parámetros de funciones, cambios de comportamiento,
    valores devueltos en caso de éxito o fallo, e información de disponibilidad.
    Conocer estas importantes diferencias (a menudo imperceptibles) es crucial para
    escribir código PHP correcto.
   </para>
   <note>
    <simpara>
     Si los parámetros dados a una función no son los que se esperaban, como
     pasar un <type>array</type> donde se esperaba un <type>string</type>,
     el valor devuelto de la función será indefinido. En este caso lo más probable
     es que devuelva &null; pero esto es sólo una convención, y no se puede confiar
     en ello.
     Desde PHP 8.0.0, se supone que se lanzará una excepción
     <classname>TypeError</classname> en estos casos.
    </simpara>
   </note>

   <note>
    <para>
     Los tipos escalares para funciones internas son nullable por omisión en modo no estricto.
     Desde PHP 8.1.0, pasar &null; como parámetro de función interna que no está declarado como
     nullable se desaconseja y emite un aviso de obsolescencia en modo no estrico, para alinearse
     con el comportamiento de las funciones definidas por el usuario, donde los tipos escalares
     deben marcarse como nullable explícitamente.
    </para>

    <para>
     Por ejemplo, la función <function>strlen</function> espera que el parámetro <literal>$string</literal>
     no sea un &string; nullable.
     Por razones históricas, PHP permite pasar &null; como ese parámetro en modo no estricto,
     y el parámetro es implícitamente convertido a <type>string</type>, resultando en un valor
     <literal>""</literal>.
     En cambio, se produce un <classname>TypeError</classname> en modo estricto.
    </para>

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
var_dump(strlen(null));
// "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" desde PHP 8.1.0
// int(0)

var_dump(str_contains("foobar", null));
// "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" desde PHP 8.1.0
// bool(true)
?>
]]>
     </programlisting>
    </informalexample>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><function>function_exists</function></member>
      <member><link linkend="funcref">la referencia de funciones</link></member>
      <member><function>get_extension_funcs</function></member>
      <member><function>dl</function></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.anonymous">
   <title>Funciones anónimas</title>

   <simpara>
    Las funciones anónimas, también conocidas como <literal>closures</literal>, permiten
    la creación de funciones que no tienen un nombre especificado. Son más útiles como
    valor de los parámetros de <literal>llamadas de retorno</literal>,
    pero tienen muchos otros usos.
   </simpara>
   <simpara>
    Las funciones anónimas están implementadas utilizando la clase <link linkend="class.closure">
    <classname>Closure</classname></link>.
   </simpara>

   <example>
    <title>Ejemplo de función anónima</title>
    <programlisting role="php">
<![CDATA[
<?php
echo preg_replace_callback('~-([a-z])~', function ($match) {
    return strtoupper($match[1]);
}, 'hola-mundo');
// imprime holaMundo
?>
]]>
    </programlisting>
   </example>

   <simpara>
    Las funciones anónimas también se pueden usar como valores de variables;
    PHP automáticamente convierte tales expresiones en instancias de la
    clase interna <classname>Closure</classname>. La asignación de una función
    anónima a una variable emplea la misma sintaxis que cualquier otra asignación,
    incluido el punto y coma final:
   </simpara>

   <example>
    <title>Ejemplo de asignación de variable de una función anónima</title>
    <programlisting role="php">
<![CDATA[
<?php
$greet = function($name)
{
    printf("Hola %s\r\n", $name);
};

$greet('Mundo');
$greet('PHP');
?>
]]>
    </programlisting>
   </example>

   <simpara>
    Las funciones anónimas también pueden heredar variables del ámbito padre.
    Cualquier variable debe ser pasada mediante el constructor de lenguaje
    <literal>use</literal>.
    Desde PHP 7.1, estas variables no deben incluir &link.superglobals;,
    <varname>$this</varname>, o variables con el mismo nombre que un parámetro.
    La declaración del tipo de retorno de la función debe ser puesta
    <emphasis>despues</emphasis> del constructor de lenguaje <literal>use</literal>.
   </simpara>

   <example>
    <title>Heredar variables de un ámbito padre</title>
    <programlisting role="php">
<![CDATA[
<?php
$message = 'hola';

// Sin "use"
$example = function () {
    var_dump($message);
};
$example();

// Heredar $message
$example = function () use ($message) {
    var_dump($message);
};
$example();

// El valor de la variable heredada está cuando la función
// está definida, no cuando se le invoca
$message = 'mundo';
$example();

// Reiniciar el mensaje
$message = 'hola';

// Heredar por referencia
$example = function () use (&$message) {
    var_dump($message);
};
$example();

// El valor cambiado en el ámbito padre
// se refleja dentro de la llamada a la función
$message = 'mundo';
$example();

// Las funciones anónimas también aceptan argumentos normales
$example = function ($arg) use ($message) {
    var_dump($arg . ' ' . $message);
};
$example("hola");
?>

// El tipo de retorno se declara despues de la expresión use
$example = function () use ($message): string {
    return "hola $message";
};
var_dump($example());
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Notice: Undefined variable: message in /example.php on line 6
NULL
string(4) "hola"
string(4) "hola"
string(4) "hola"
string(5) "mundo"
string(10) "hola mundo"
string(10) "hola mundo"
]]>
    </screen>
   </example>

   <para>
    Desde PHP 8.0.0, la lista de variables heredadas del ámbito padre puede
    incluir una coma final, la cual será ignorada.
   </para>

   <simpara>
    Heredar variables del ámbito padre <emphasis>no</emphasis>
    es lo mismo que usar variables globales.
    Las variables globales existen en el ámbito global, lo que implica que no
    importa qué función se esté ejecutando. El ámbito padre de un cierre es la
    función en la que dicho cierre fue declarado (no necesariamente la función
    desde la que se llamó). Vea el siguiente ejemplo:
   </simpara>

   <example>
    <title>Cierres y ámbito</title>
    <programlisting role="php">
<![CDATA[
<?php
// Un carro de compras básico que contiene una lista de productos añadidos
// y la cantidad de cada producto. Incluye un método que
// calcula el precio total de los artículos del carro usando un
// cierre como llamada de retorno.
class Carro
{
    const PRECIO_MANTEQUILLA = 1.00;
    const PRECIO_LECHE       = 3.00;
    const PRECIO_HUEVOS      = 6.95;

    protected $productos = array();

    public function añadir($producto, $cantidad)
    {
        $this->productos[$producto] = $cantidad;
    }

    public function obtenerCantidad($producto)
    {
        return isset($this->productos[$producto]) ? $this->productos[$producto] :
               FALSE;
    }

    public function obtenerTotal($impuesto)
    {
        $total = 0.00;

        $llamadaDeRetorno =
            function ($cantidad, $producto) use ($impuesto, &$total)
            {
                $precioUnidad = constant(__CLASS__ . "::PRECIO_" .
                    strtoupper($producto));
                $total += ($precioUnidad * $cantidad) * ($impuesto + 1.0);
            };

        array_walk($this->productos, $llamadaDeRetorno);
        return round($total, 2);
    }
}

$mi_carro = new Carro;

// Añadir algunos artículos al carro
$mi_carro->añadir('mantequilla', 1);
$mi_carro->añadir('leche', 3);
$mi_carro->añadir('huevos', 6);

// Imprimir el total con un impuesto de venta del 5%.
print $mi_carro->obtenerTotal(0.05) . "\n";
// El resultado es 54.29
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Vinculación automática de <literal>$this</literal></title>
    <programlisting role="php">
<![CDATA[
<?php

class Test
{
    public function testing()
    {
        return function() {
            var_dump($this);
        };
    }
}

$object = new Test;
$function = $object->testing();
$function();

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
object(Test)#1 (0) {
}
]]>
    </screen>
   </example>

   <para>
    Cuando se declara en el contexto de una clase, la clase actual está
    vinculada a ella automáticamente, haciendo que <literal>$this</literal>
    esté disponible dentro del ámbito de la función. Si no se desea esta
    vinculación automática de la clase actual, se deberían usar
    <link linkend="functions.anonymous-functions.static">funciones anónimas
    estáticas</link> en su lugar.
   </para>

   <sect2 xml:id="functions.anonymous-functions.static">
    <title>Funciones anónimas estáticas</title>
    <para>
     Las funciones anónimas pueden ser declaradas estáticamente. Esto
     evita tener la clase actual vinculada automáticamente a
     ellas. Los objetos tampoco podrían vincularse a ellas durante la ejecución.
    </para>
    <para>
     <example>
      <title>Intentar usar <literal>$this</literal> dentro de una función anónima estática</title>
      <programlisting role="php">
<![CDATA[
<?php

class Foo
{
    function __construct()
    {
        $func = static function() {
            var_dump($this);
        };
        $func();
    }
};
new Foo();

?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Notice: Undefined variable: this in %s on line %d
NULL
]]>
      </screen>
     </example>
    </para>

    <para>
     <example>
      <title>Intentar vincular un objeto a una función anónima estática</title>
      <programlisting role="php">
<![CDATA[
<?php

$func = static function() {
    // cuerpo de la función
};
$func = $func->bindTo(new StdClass);
$func();

?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Warning: Cannot bind an instance to a static closure in %s on line %d
]]>
      </screen>
     </example>
    </para>
   </sect2>

   <sect2 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>
          Las funciones anónimas creadas desde
          <link linkend="language.oop5.magic">Métodos mágicos</link> pueden aceptar parametros con nombre.
         </entry>
        </row>
        <row>
         <entry>7.1.0</entry>
         <entry>
          Las funciones anónimas no pueden tener un cierre sobre &link.superglobals;,
          <varname>$this</varname>, o cualquier variable con el mismo nombre que un
          parámetro.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </sect2>

   <sect2 role="notes">
    &reftitle.notes;
    <note>
     <simpara>
      Es posible utilizar <function>func_num_args</function>,
      <function>func_get_arg</function>, y <function>func_get_args</function>
      desde dentro de una función anónima.
     </simpara>
    </note>
   </sect2>

  </sect1>
  <sect1 xml:id="functions.arrow">
   <title>Funciones de flecha</title>

   <simpara>
    Las funciones de flecha fueron introducidas en PHP 7.4 como una sintaxis más concisa para
    <link linkend="functions.anonymous">las funciones anónimas</link>.
   </simpara>
   <simpara>
    Tanto las funciones anónimas como las funciones de flecha se implementan utilizando la
    clase <link linkend="class.closure"><classname>Closure</classname></link>.
   </simpara>

   <simpara>
    Las funciones de las flechas tienen la forma básica
    <code>fn (argument_list) =&gt; expr</code>.
   </simpara>

   <simpara>
    Las funciones de las flechas soportan las mismas características que
    <link linkend="functions.anonymous">las funciones anónimas</link>,
    excepto que el uso de variables del ámbito padre siempre es automático.
   </simpara>

   <simpara>
    Cuando una variable utilizada en la expresión se define en el ámbito padre
    será implícitamente capturada por valor.
    En el siguiente ejemplo, las funciones <varname>$fn1</varname> y
    <varname>$fn2</varname> se comportan de la misma manera.
   </simpara>

   <para>
    <example>
     <title>Las funciones de flecha capturan las variables por valor automáticamente</title>
     <programlisting role="php">
<![CDATA[
<?php

$y = 1;

$fn1 = fn($x) => $x + $y;
// equivale a pasar $y por valor:
$fn2 = function ($x) use ($y) {
    return $x + $y;
};

var_export($fn1(3));
?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
4
]]>
      </screen>
    </example>
   </para>
   <simpara>
    Esto también funciona si las funciones de la flecha están anidadas:
   </simpara>
   <para>
    <example>
     <title>Las funciones de flecha capturan variables por valor automáticamente,
      incluso cuando están anidadas</title>
     <programlisting role="php">
<![CDATA[
<?php

$z = 1;
$fn = fn($x) => fn($y) => $x * $y + $z;
// Imprime 51
var_export($fn(5)(10));
?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    De manera similar a las funciones anónimas,
    la sintaxis de la función de la flecha permite firmas de funciones arbitrarias,
    incluyendo los tipos de parámetros y de retorno, valores por defecto, variadades,
    así como por referencia al pasar y al regresar.
    Todos los siguientes son ejemplos válidos de las funciones de las flechas:
   </simpara>
   <para>
    <example>
     <title>Ejemplos de funciones de flecha</title>
     <programlisting role="php">
<![CDATA[
<?php

fn(array $x) => $x;
static fn(): int => $x;
fn($x = 42) => $x;
fn(&$x) => $x;
fn&($x) => $x;
fn($x, ...$rest) => $rest;

?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    Las funciones de flecha utilizan la unión variable por valor.
    Esto es aproximadamente equivalente a realizar un <code>use($x)</code> para cada
    variable  <varname>$x</varname> usada dentro de la función de la flecha.
    Una unión por valores significa que no es posible modificar ningún valor
    desde el ámbito exterior.
    <link linkend="functions.anonymous">Funciones anónimas</link>
    se pueden utilizar en su lugar para las asignaciones por referencia.
   </simpara>
   <para>
    <example>
     <title>Los valores del ámbito exterior no pueden ser modificados por las funciones de flecha</title>
     <programlisting role="php">
<![CDATA[
<?php

$x = 1;
$fn = fn() => $x++; // No tiene ningún efecto
$fn();
var_export($x);  // Imprime 1

?>
]]>
     </programlisting>
    </example>
   </para>

   <sect2 role="changelog">
    &reftitle.changelog;
    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>&Version;</entry>
         <entry>&Description;</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>7.4.0</entry>
         <entry>
          Las funciones de flecha se hicieron disponibles.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </sect2>

   <sect2 role="notes">
    &reftitle.notes;
    <note>
     <simpara>
      Es posible utilizar <function>func_num_args</function>,
      <function>func_get_arg</function>, y <function>func_get_args</function>
      desde dentro de una función de flecha.
     </simpara>
    </note>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.first_class_callable_syntax">
   <title>Sintaxis de llamadas de retorno de primera clase</title>

   <para>
    La sintaxis de llamadas de retorno de primera clase fue introducida desde PHP 8.1.0,
    como una forma de creación de
    <link linkend="functions.anonymous">funciones anónimas</link> a partir de una
    <link linkend="language.types.callable">llamada de retorno</link>.
    Reemplaza la sintaxis de invocación existente que utiliza cadenas y arrays.
    La ventaja de esta sintaxis es que es accesible para el análisis estático
    y utiliza el alcance en el punto donde se adquiere la invocación.
   </para>

   <para>
    La sintaxis <code>CallableExpr(...)</code> es usada para crear un objeto
    <classname>Closure</classname> a partir de una llamada de retorno.
    <code>CallableExpr</code> acepta cualquier expersión que pueda ser
    llamada en la sintaxis de PHP.
    <example>
     <title>Sintaxis de llamadas de retorno de primera clase</title>
     <programlisting role="php">
<![CDATA[
<?php

class Foo {
   public function method() {}
   public static function staticmethod() {}
   public function __invoke() {}
}

$obj = new Foo();
$classStr = 'Foo';
$methodStr = 'method';
$staticmethodStr = 'staticmethod';


$f1 = strlen(...);
$f2 = $obj(...);  // Objeto invocable
$f3 = $obj->method(...);
$f4 = $obj->$methodStr(...);
$f5 = Foo::staticmethod(...);
$f6 = $classStr::$staticmethodStr(...);

// traditional callable using string, array
$f7 = 'strlen'(...);
$f8 = [$obj, 'method'](...);
$f9 = [Foo::class, 'staticmethod'](...);
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
      El <code>...</code> es parte de la sintaxis, y no una omisión.
    </para>
   </note>

   <para>
    <code>CallableExpr(...)</code> tiene la misma sintaxis que <methodname>Closure::fromCallable</methodname>.
    Es decir, a diferencia de las llamadas que utilizan cadenas y arrays, <code>CallableExpr(...)</code>
    respeta el ámbito en el punto donde se crea:
    <example>
     <title>Comparación del ámbito de <code>CallableExpr(...)</code> y una llamada de retorno tradicional</title>
     <programlisting role="php">
<![CDATA[
<?php

class Foo {
    public function getPrivateMethod() {
        return [$this, 'privateMethod'];
    }

    private function privateMethod() {
        echo __METHOD__, "\n";
    }
}

$foo = new Foo;
$privateMethod = $foo->getPrivateMethod();
$privateMethod();
// Fatal error: Call to private method Foo::privateMethod() from global scope
// Esto es porque la llamada es realizada fuera de Foo y la visibilidad es comprobada en ese momento.

class Foo1 {
    public function getPrivateMethod() {
        // Usa el ámbito donde la llamada de retorno es creada.
        return $this->privateMethod(...); // Identico a Closure::fromCallable([$this, 'privateMethod']);
    }

    private function privateMethod() {
        echo __METHOD__, "\n";
    }
}

$foo1 = new Foo1;
$privateMethod = $foo1->getPrivateMethod();
$privateMethod();  // Foo1::privateMethod
?>
]]>
     </programlisting>
    </example>

   </para>

   <note>
    <para>
     La creación de objetos mediante esta sintaxis (por ejemplo, <code>new Foo(...)</code>)
     no está soportada, porque la sintaxis <code>new Foo()</code> no se considera una llamada.
    </para>
   </note>

   <note>
    <para>
     La sintaxis de llamada de retorno de primera clase no se puede combinar
     con el <link linkend="language.oop5.basic.nullsafe">operador nullsafe</link>.
     Ambos de los siguientes resultan en un error en tiempo de compilación:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$obj?->method(...);
$obj?->prop->method(...);
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </note>
  </sect1>

 </chapter>

<!-- 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
-->