8. SESION: FUNCIONES DEFINIDAS POR USUARIOS

Funciones definidas por el usuario

Una función puede ser definida usando una sintaxis como la siguiente:

Ejemplo #1 Pseudo código para demostrar el uso de funciones

<?phpfunction foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
    echo "Función de ejemplo.\n";
    return $valordevuelto;
}?>

Cualquier código PHP válido puede aparecer dentro de una función, incluso otras funciones y definiciones de clases.

Los nombres de las funciones siguen las mismas reglas que otras 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í: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.

Sugerencia

Vea también Guia de Entorno de Usuario para Nombres.

Las funciones no necesitan ser definidas antes de que se referencien, excepto cuando una función está condicionalmente definida como se muestra en los dos ejemplos de abajo.

Cuando una función está definida de una forma condicional como en los dos ejemplos mostrados, sus definiciones deben ser procesadas antes de ser llamadas.

Ejemplo #2 Funciones condicionales

<?php

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

if ($haceralgo) {
  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 $haceralgo se evaluó como verdadero */
if ($haceralgo) foo();

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

Ejemplo #3 Funciones dentro de funciones

<?phpfunction 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();
?>

Todas las funciones y las clases de PHP tienen ámbito global - pueden ser llamadas fuera de una función incluso si fueron definidas dentro, y viceversa.

PHP no soporta la sobrecarga de funciones, ni es posible 'desdefinir' ni redefinir funciones previamente declaradas.

Nota: Los nombres de las fuciones son insensibles a mayúsculas-minúsculas, por lo que es una buena idea llamar a las funciones tal y como aparecen en sus declaraciones.

El número variable de argumentos y los argumentos predeterminados están soportados por las funciones. Vea también las referencias de funciones para func_num_args(), func_get_arg(), y func_get_args() para más información.

En PHP es posible llamar a funciones recursivas. Sin embargo, evite las llamadas a funciones/métodos recursivos con más de 100-200 niveles de recursividad ya que pueden agotar la pila y causar la terminación del script actual.

Ejemplo #4 Funciones recursivas

<?phpfunction recursividad($a)
{
    if ($a < 20) {
        echo "$a\n";
        recursividad($a + 1);
    }
}?>

 

 

 

 

 

 

 funciones

Argumentos

La 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.

PHP soporta argumentos pasados por valor (por defecto), pasados por referencia, y valores de argumentos predeterminados. Las Listas de argumentos de longitud variable también están soportadas, vea también las referencias de funciones para func_num_args(), func_get_arg(), y func_get_args() para más información.

Ejemplo #1 Pasar arrays a funciones

<?phpfunction tomar_array($entrada)
{
    echo "$entrada[0] + $entrada[1] = ".$entrada[0]+$entrada[1];
}?>

Hacer que los argumentos sean pasados por referencia

Por defecto, los argumentos de las funciones son pasados por valor (por lo que si el valor del argumento dentro de la función se cambia, no se cambia fuera de la función). Para permitir a una función modificar sus argumentos, éstos deben pasarse por referencia.

Para hacer que un argumento a una función sea siempre pasado por referencia hay que poner delante del nombre del argumento el signo 'ampersand' (&) en la definición de la función:

Ejemplo #2 Pasar parámetros de una función por referencia

<?phpfunction añadir_algo(&$cadena)
{
    $cadena .= 'y algo más.';
}$cad = 'Esto es una cadena, ';añadir_algo($cad);
echo $cad;    // imprime 'Esto es una cadena, y algo más.'?>

Valores de argumentos predeterminados

Una función puede definir valores predeterminados al estilo C++ para argumentos escalares como sigue:

Ejemplo #3 Uso de parámetros predeterminados en funciones

<?phpfunction hacercafé($tipo = "capuchino")
{
    return "Hacer una taza de $tipo.\n";
}
echo hacercafé();
echo hacercafé(null);
echo hacercafé("espresso");?>

El resultado del ejemplo sería:

Hacer una taza de capuchino.
Hacer una taza de .
Hacer una taza de espresso.

PHP también permite el uso de arrays y del tipo especial NULL como valores predeterminados, por ejemplo:

Ejemplo #4 Usar tipos no escalares como valores predeterminados

<?phpfunction hacercafé($tipos = array("capuchino"), $fabricanteCafé = NULL)
{
    $aparato = is_null($fabricanteCafé) ? "las manos" : $fabricanteCafé;
    return "Hacer una taza de ".join(", ", $tipos)." con $aparato.\n";
}
echo hacercafé();
echo hacercafé(array("capuchino", "lavazza"), "una tetera");?>

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.

Observe que cuando se usan argumentos predeterminados, cualquiera de ellos debería estar a la derecha de los argumentos no predeterminados; si no, las cosas no funcionarán como se esperaba. Considere el siguiente trozo de código:

Ejemplo #5 Uso incorrecto de argumentos predeterminados en una función

<?phpfunction haceryogur($tipo = "acidófilo", $sabor)
{
    return "Hacer un tazón de yogur $tipo de $sabor.\n";
}

echo haceryogur("frambuesa");   // no funcionará como se esperaba?>

El resultado del ejemplo sería:

Warning: Missing argument 2 in call to haceryogur() in 
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Hacer un tazón de yogur frambuesa de .

Ahora compare el ejemplo de arriba con este:

Ejemplo #6 Uso correcto de argumentos predeterminados en una función

<?phpfunction haceryogur($sabor, $tipo = "acidófilo")
{
    return "Hacer un tazón de yogur $tipo de $sabor.\n";
}

echo haceryogur("frambuesa");   // funciona como se esperaba?>

El resultado del ejemplo sería:

Hacer un tazón de yogur acidófilo de frambuensa.

Nota: A partir de PHP 5, los valores predeterminados se pueden pasar por referencia.

Listas de argumentos de longitud variable

PHP tiene soporte para listas de argumentos de longitud variable en funciones definidas por el usuario. Esto realmente es bastante fácil si se usan las funciones func_num_args(), func_get_arg(), y func_get_args().

No se necesita una sintaxis especial, y la lista de argumentos aún puede ser proporcionada explícitamente con definiciones de funciones, y se comportará con normalidad.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

include

La sentencia include incluye y evalúa el archivo especificado.

La siguiente documentación también se aplica a require.

Los archivos son incluidos con base en la ruta de acceso dada o, si ninguna es dada, el include_path especificado. Si el archivo no se encuentra en el include_path, include finalmente verificará en el propio directorio del script que hace el llamado y en el directorio de trabajo actual, antes de fallar. El constructor include emitirá una advertencia si no puede encontrar un archivo, éste es un comportamiento diferente al de require, el cual emitirá un error fatal..

Si una ruta es definida — ya sea absoluta (comenzando con una letra de unidad o \ en Windows o / en sistemas Unix/Linux) o relativa al directorio actual (comenzando con . o ..) — el include_path será ignorado por completo. Por ejemplo, si un nombre de archivo comienza con ../, el interprete buscará en el directorio padre para encontrar el archivo solicitado.

Para más información sobre como PHP maneja la inclusión de archivos y la ruta de accesos para incluir, ver la documentación de include_path.

Cuando se incluye un archivo, el código que contiene hereda el ámbito de las variables de la línea en la cual ocurre la inclusión. Cualquier variable disponible en esa línea del archivo que hace el llamado, estará disponible en el archivo llamado, desde ese punto en adelante. Sin embargo, todas las funciones y clases definidas en el archivo incluido tienen el ámbito global.

Ejemplo #1 Ejemplo básico de include

vars.php
<?php

$color = 'verde';$fruta = 'manzana';
?>
test.php
<?php
echo "Una $fruta $color"; // Una
include 'vars.php';

echo "Una $fruta $color"; // Una manzana verde
?>

Si la inclusión ocurre al interior de una función dentro del archivo que hace el llamado, entonces todo el código contenido en el archivo llamado se comportará como si hubiera sido definida dentro de esa función. Por lo tanto, seguirá el ámbito de las variables de esa función. Una excepción a esta regla son las constantes mágicas las cuales son evaluadas por el intérprete antes que ocurra la inclusión.

Ejemplo #2 Incluyendo dentro de funciones

<?php
function foo()
{
    global $color;

    include 'vars.php';

    echo "Una $fruta $color";
}
/* vars.php está en el ámbito de foo() así que *
* $fruta NO está disponible por fuera de éste  *
* ámbito. $color sí está porque fue declarado *
* como global.                                 */
foo();                      // Una manzana verdeecho "Una $fruta $color";   // Una verde
?>

Cuando un archivo es incluido, el intérprete abandona el modo PHP e ingresa al modo HTML al comienzo del archivo objetivo y se reanuda de nuevo al final. Por esta razón, cualquier código al interior del archivo objetivo que deba ser ejecutado como código PHP, tendrá que ser encerrado dentro de etiquetas válidas de comienzo y terminación de PHP.

Si las "envolturas URL fopen" están activadas en PHP (las cuales lo están en la configuración predeterminada), se puede especificar el archivo a ser incluido usando una URL (vía HTTP u otra envoltura soportada - ver Protocolos y Envolturas soportados para una lista de protocolos) en lugar de una ruta de acceso local. Si el servidor objetivo interpreta el archivo objetivo como código PHP, las variables se pueden pasar al archivo incluido usando una string de petición como la usada con HTTP GET. Esto no es, en estricto rigor, lo mismo que haber incluido el archivo y que haya heredado el ámbito de variables del archivo padre; el script realmente está siendo ejecutado en el servidor remoto y el resultado entonces se incluye dentro del script local.

Advertencia

Versiones de PHP para Windows anteriores a 4.3.0, no soportan el acceso remoto a archivos para esta función, no funcionará ni activando siquiera allow_url_fopen.

Ejemplo #3 include por medio de HTTP

<?php
/* Este ejemplo asume que www.example.com está configurado para interpretar archivos
* .php y no archivos .txt. Además, aquí 'Funciona' quiere decir que las variables
* $foo y $bar están disponibles dentro del archivo incluido. */

// No funciona; file.txt no puede ser manejado por www.example.com como PHPinclude 'http://www.example.com/file.txt?foo=1&bar=2';
// No funciona; busca por un archivo llamado 'file.php?foo=1&bar=2' en el
// sistema de archivos local.include 'file.php?foo=1&bar=2';
// Si funciona.include 'http://www.example.com/file.php?foo=1&bar=2';
$foo = 1;$bar = 2;
include 'file.txt';  // Funciona.include 'file.php';  // Funciona.
?>

Advertencia

Advertencia de seguridad

El archivo remoto puede ser procesado en el servidor remoto (dependiendo de la extensión del archivo y del hecho de si el servidor remoto corre PHP o no) pero aun así tiene que producir un script PHP válido, porque será procesado en el servidor local. Si el archivo desde el servidor remoto debe ser procesado allá y entregar la salida solamente, readfile() es la mejor función para usar. De lo contrario, debe tenerse especial cuidado para asegurar que el script remoto produce un código válido y deseado.

Ver también Archivos remotos, fopen() y file() para información relacionada.

Manejando retornos: Es posible ejecutar una sentencia return dentro de un archivo incluido con el fin de terminar el procesamiento en ese archivo y volver a script que lo llamó. Además, es posible retornar valores desde los archivos incluidos. Se puede tomar el valor de la llamada "include" de la misma forma como se haría con una función normal. Esto no es, sin embargo, posible si se incluyen archivos remotos, a menos que la salida del archivo remoto tenga unas etiquetas válidas de inicio y terminación de PHP (igual que con cualquier archivo local). Se pueden declarar la variables necesarias dentro de esas etiquetas y serán introducidas en el punto del archivo en el cual fue incluido.

Debido a que include es un constructor especial del lenguaje, los paréntesis no son necesarios en torno a su argumento. Se debe tener cuidado cuando se compara el valor de retorno.

Ejemplo #4 Comparando el valor de retorno de include

<?php// no funciona, evaluado como include(('vars.php') == 'OK'), es decir include('')if (include('vars.php') == 'OK') {
    echo 'OK';
}
// si funcionaif ((include 'vars.php') == 'OK') {
    echo 'OK';
}?>

Ejemplo #5 include y la sentencia return

return.php
<?php

$var = 'PHP';

return $var;
?>
noreturn.php
<?php

$var = 'PHP';
?>
testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // muestra 'PHP'
$bar = include 'noreturn.php';

echo $bar; // muestra 1
?>

$bar tiene el valor 1 debido a que el include fue exitoso. Nótese la diferencia entre los ejemplos anteriores. El primero usa return dentro del archivo incluido, mientras que el otro no. Si el archivo no se pueden incluir, se retorna FALSE y se emite un E_WARNING.

Si hay funciones definidas en el archivo incluido, se pueden utilizar en el archivo principal independientemente que hayan return antes o después. Si el archivo se incluye dos veces, PHP 5 arrojará un error fatal ya que las funciones ya han sido declaradas, mientras que PHP 4 no se queja acerca de las funciones definidas después de un return. Se recomienda el uso de include_once en lugar de comprobar si el archivo ya estaba incluido y hacer el retorno de forma condicionada dentro del archivo incluido.

Otra forma de "incluir" un archivo PHP en una variable es capturar la salida mediante el uso de Funciones de control de salida con include. Por ejemplo:

Ejemplo #6 Usando buffering de salida para incluir un archivo PHP dentro de una cadena

<?php
$string = get_include_contents('somefile.php');

function get_include_contents($filename) {
    if (is_file($filename)) {
        ob_start();
        include $filename;
        return ob_get_clean();
    }
    return false;
}
?>

Con el fin de incluir archivos de forma automática dentro de scripts, véase también las opciones de configuración auto_prepend_file y auto_append_file en php.ini.

Nota: Puesto que esto es una construcción del lenguaje y no una función, no puede ser llamada usando funciones variables.

 

require

require es idéntico a include excepto que en caso de fallo producirá un error fatal de nivel E_COMPILE_ERROR. En otras palabras, éste detiene el script mientras que include sólo emitirá una advertencia (E_WARNING) lo cual permite continuar el script.

 

 

 <?php
// file and get, if you need to include a file.php?query_string.

function pinclude($file, $type, $get = null) {
    $p = explode('/', $file);
    $file = end($p);
    $dir = '';
    $n = count($p) - 1;

    for($i = 0; $i < $n; $i++)
        $dir .= $p[$i] . '/';

    if($get !== null) {
        $tmp = $_GET; // back up
        $_GET = array();
        $get = explode('&', $get);
        $n = count($get);

        for($i = 0; $i < $n; $i++) {
            if(strpos($get[$i], '=') === false)
                $_GET[$get[$i]] = 1;
            else {
                list($name, $val) = explode('=', $get[$i], 2);
                $_GET[$name] = $val;
            }
        }
    }

    ob_start();
    chdir($dir);
    require $file;
    $out = ob_get_clean();

    if($tmp)
        $_GET = $tmp;

    return $out;
}

$out = pinclude('./dir/yourfile.php', 'a=b&c=d&e');
echo $out;
// i'm sorry but i forgot post requests...
?>

 

 

 

Por qué usar los includes?

El uso de includes es excepcionalmente bueno para ahorrarte trabajo. Puedes hacer un header o un menú generico y cargarlo con el include.

Uso:

La utilización del include es muy simple:

<?php include("tuarchivo.htm"); ?>

Ejemplo:

Vamos a usar tres archivos, que fusionaremos. Luego observaremos el codigo de salida.

Archivo 1 : header.php :

<html>
<head>
<title> Muestra de includes </title>

</head>
<body>

Archivo 2: footer.php :

</body>
</html>

Archivo 3: union.php :

<?php include("header.php"); ?>
<p>
Hola, este es el contenido.
</p>
<?php include("footer.php"); ?>

Y el resultado:

<html>
<head>
<title> Muestra de includes </title>
</head>
<body>

<p>
Hola, este es el contenido.
</p>
</body>
</html>

Nota: Los archivos a incluír no tienen que ser obligatoriamente archivos PHP. Pueden ser de cualquier tipo

Diferenciación:

PHP contiene otra funcion con caracteristicas muy similares, que es la funcion require(). Las caracteristicas y el modo de uso de include y de require son identicas, salvo por una cosa: El mensaje de error generado si falta un documento:

Con include, si el nombre de archivo no existe, recibiras una advertencia (warning) y el script seguirá. Con require en cambio el script se detendrá, pues se marcará un error fatal.

Ejemplo:

Include:

<?php
include("noexiste.php");
echo ("Hola. El script siguió!");
?>

Y lo que obtendremos:

Warning: include(noexiste.php) [function.include]:
failed to open stream:
No such file or directory in C:\tutorial\probando.php on line 2

Warning: include() [function.include]:
Failed opening 'noexiste.php' for inclusion
(include_path='.;C:\php5\pear')
in C:\tutorial\probando.php on line 2

Hola. El script siguió!

Require:

<?php
require("noexiste.php");
echo ("Hola. El script siguió!");
?>

Y aqui obtenemos:

Warning: require(noexiste.php) [function.require]:
failed to open stream:
No such file or directory in C:\tutorial\probando.php on line 2

Fatal error: require() [function.require]:
Failed opening required 'noexiste.php'
(include_path='.;C:\php5\pear')
in C:\tutorial\probando.php on line 2

Vemos que con require no se ejecutó la siguiente parte del script. Atención: En php 3 y anteriores, las funciones include y require se diferenciaban por un asunto aún mayor: Include podía ser usado condicionalmente, mientras que require se ejecutaba "a la fuerza". Un ejemplo:

<?php
        $gatito= "Lo odio";
        if($gatito=="Lo amo"){
                include("condicionado-asi-que-si-no-es-verdad-no-me-incluyo.php");
        }else{
                require("igual-me-voy-a-incluir-bwahahaha.php");
        }
?>

En el output, veremos que se incluiría lo del require y no lo del include. Sin embargo, reitero, esto ya no funciona asi.