PHP Reutilización de código: Include / Require

Introdución

• Cando programamos pode darse o caso de que teñamos código (funcións, variables, constantes ou bloques de código) que teñamos que utilizar en moitas páxinas distintas.

• Nestes casos é conveniente ter ese código gardado nun arquivo separado e poder incorporalo cando o necesitemos.

• En PHP podemos facelo coas construcións da linguaxe: include, include_once, require e require_once.

Include

• Sintaxe:

include '[path/]arquivo.php';

• A sentenza include inclúe e avalía o arquivo indicado.

• A ruta pode ser absoluta ou relativa. Para evitar problemas coa resolución de rutas é recomendable construír a ruta a partir da constante máxica __DIR__, que representa o directorio no que se atopa o arquivo PHP actual.

Por exemplo:

include __DIR__ . '/utilidades/arquivo.php';

• Antigamente empregábase ás veces a extensión .inc.php para este tipo de arquivos, pero actualmente non é necesaria. É habitual empregar simplemente a extensión .php.

• O código PHP do arquivo incluído debe atoparse entre etiquetas PHP.

Se o arquivo contén unicamente código PHP, é recomendable empregar a etiqueta de apertura <?php e omitir a etiqueta de peche ?> ao final do arquivo.

Desta forma evítase que espazos ou saltos de liña situados accidentalmente despois da etiqueta de peche produzan unha saída non desexada.

• Vexamos un exemplo:

Arquivo: FuncionsExternas.php

 1 <?php
 2 
 3 /**
 4  * Crea un array cun número específico de elementos inicializados a null.
 5  *
 6  * @param int $numElementos Número de elementos que terá o array.
 7  *
 8  * @return array Array co número de elementos indicado, todos con valor null.
 9  */
10 function crearArray(int $numElementos): array
11 {
12     $array = [];
13 
14     for ($cont = 0; $cont < $numElementos; $cont++) {
15         $array[$cont] = null;
16     }
17 
18     return $array;
19 }

Arquivo: ReutilizandoCodigo.php

 1 <!DOCTYPE html>
 2 <html lang="gl">
 3 <head>
 4     <meta charset="UTF-8">
 5     <title>Exemplo de reutilización de código</title>
 6 </head>
 7 <body>
 8 <?php
 9 include __DIR__ . '/FuncionsExternas.php';
10 
11 $datos = crearArray(10);
12 
13 foreach ($datos as $clave => $dato) {
14     printf(
15         "Clave:%d - Valor:%s<br>",
16         $clave,
17         $dato === null ? 'Sen dato' : $dato
18     );
19 }
20 ?>
21 </body>
22 </html>

• Todas as funcións e clases definidas nun arquivo incluído teñen ámbito global.

• No caso das variables, o arquivo incluído herda o ámbito do punto no que se realiza a inclusión.

Por exemplo, se facemos un include dentro dunha función, as variables definidas no arquivo incluído pertencerán ao ámbito desa función.

• Cando fagamos unha aplicación con acceso a unha base de datos teremos normalmente información sensible, como credenciais de conexión.

É unha boa práctica gardar esa información fóra do directorio público do servidor web.

Imaxinemos que o servidor web publica por defecto o cartafol:

/var/www/html

Poderiamos gardar un arquivo de configuración, por exemplo, en:

/var/www/configuracions/informacionbd.php

Desta forma o arquivo non pode ser solicitado directamente mediante unha URL coa configuración habitual do servidor web.

include_once

• Sintaxe:

include_once __DIR__ . '/arquivo.php';

• include_once ten o mesmo comportamento que include, pero PHP comproba se o arquivo xa foi incluído previamente. Se xa foi incluído, non volve procesalo.

Isto é especialmente útil cando o arquivo define funcións, clases ou constantes, xa que incluílo máis dunha vez podería provocar erros por declaracións duplicadas.

• Debemos escoller entre include e include_once en función de se queremos permitir ou non que o mesmo arquivo sexa procesado máis dunha vez.

• Pode ser útil cando realizamos inclusións condicionais (por exemplo, dentro dun if) e non sabemos con certeza se o arquivo xa foi cargado anteriormente.

• Os includes, ademais de utilizarse para gardar funcións, constantes ou variables, poden empregarse para ter elementos comúns a todas as páxinas dun sitio web e non repetir o mesmo código.

Por exemplo, unha cabeceira, un menú ou un pé de páxina.

Desta forma, se necesitamos cambiar un destes elementos, só teremos que modificalo nun arquivo.

• En PHP tamén podemos empregar outros patróns para estruturar os elementos comúns dunha aplicación.

Podedes consultalo neste enlace da WIKI.

require

• Sintaxe:

require __DIR__ . '/arquivo.php';

• require inclúe e avalía un arquivo do mesmo xeito que include.

• A diferenza importante aparece cando PHP non pode cargar o arquivo:

• include produce un aviso de tipo E_WARNING e a execución do script pode continuar.
• require produce un erro de tipo Error e, se non se trata, interrómpese a execución do script.

• Por este motivo empregaremos normalmente require cando o arquivo sexa imprescindible para que a aplicación poida funcionar.

Comparación entre include e require

Podemos resumir o seu uso da seguinte forma:

Sentenza	Uso habitual
include	O arquivo é opcional. Se falla, a execución pode continuar.
require	O arquivo é necesario. Se falla, a execución interrómpese se o erro non se trata.
include_once	O arquivo é opcional e só debe procesarse unha vez.
require_once	O arquivo é necesario e só debe procesarse unha vez.

Exemplo con include

 1 <!DOCTYPE html>
 2 <html lang="gl">
 3 <head>
 4     <meta charset="UTF-8">
 5     <title>Exemplo include</title>
 6 </head>
 7 <body>
 8 <?php
 9 include __DIR__ . '/FuncionsExternasNonExiste.php';
10 
11 echo 'Isto aparece porque include permite continuar.';
12 ?>
13 </body>
14 </html>

Se o arquivo non existe, PHP amosará un warning, pero a mensaxe posterior poderá executarse.

Exemplo con require

 1 <!DOCTYPE html>
 2 <html lang="gl">
 3 <head>
 4     <meta charset="UTF-8">
 5     <title>Exemplo require</title>
 6 </head>
 7 <body>
 8 <?php
 9 require __DIR__ . '/FuncionsExternasNonExiste.php';
10 
11 echo 'Esta instrución non chegará a executarse se o erro non se trata.';
12 ?>
13 </body>
14 </html>

require_once

• Sintaxe:

require_once __DIR__ . '/arquivo.php';

• Ten o mesmo comportamento que require, pero se o arquivo xa foi incluído previamente non o volve procesar.

• É unha opción habitual para cargar arquivos imprescindibles que definen funcións, clases, constantes ou configuracións que só deben declararse unha vez.

Configuración da visualización e rexistro de erros

• Durante o desenvolvemento é útil que PHP informe dos erros, warnings e mensaxes de depreciación para poder corrixilos.

• Nun servidor de produción non debemos amosar os erros directamente ao usuario, xa que poderían revelar información sensible da aplicación ou do servidor.

Contorna de desenvolvemento

• Durante o desenvolvemento podemos solicitar que PHP informe de todos os erros:

error_reporting(E_ALL);
ini_set('display_errors', '1');

• E_ALL inclúe todos os niveis de erro dispoñibles na versión actual de PHP.

• O obxectivo non debe ser ocultar os warnings ou notices durante o desenvolvemento, senón detectalos e corrixilos.

Contorna de produción

• En produción é recomendable non amosar os erros na saída HTML e gardalos no rexistro de erros do servidor.

Unha configuración típica en php.ini sería:

error_reporting = E_ALL
display_errors = Off
log_errors = On

• Desta forma os erros poden quedar rexistrados para a súa análise sen expoñelos ao usuario final.

Selección de niveis de erro

• PHP permite combinar constantes de erro empregando operadores de bits.

Por exemplo:

// Informar de erros, warnings e erros de análise.
error_reporting(E_ERROR | E_WARNING | E_PARSE);

// Todos os erros excepto E_NOTICE.
error_reporting(E_ALL & ~E_NOTICE);

Aínda que é posible seleccionar niveis concretos, durante o desenvolvemento é recomendable empregar E_ALL.

A través do arquivo .htaccess cando PHP funciona como módulo de Apache

• Se PHP se executa como módulo de Apache e a configuración do servidor o permite, é posible modificar determinadas opcións de PHP mediante o arquivo .htaccess.

Por exemplo:

php_value error_reporting 2147483647
php_flag display_errors On

• Esta forma de configuración non é válida para todas as formas de executar PHP.

Por exemplo, cando PHP se executa mediante CGI/FastCGI pódense empregar arquivos .user.ini para determinadas opcións de configuración.

Colocar arquivos sensibles

• En unidades posteriores teremos que gardar información sensible, como os datos necesarios para conectarnos a unha base de datos.

• Unha boa práctica é colocar estes arquivos fóra do DocumentRoot do servidor web, é dicir, fóra do directorio que pode ser solicitado directamente mediante unha URL.

Por exemplo, se Apache publica:

/var/www/html

podemos gardar a configuración en:

/var/www/configuracions/informacionbd.php

e cargala dende as páxinas necesarias mediante:

require __DIR__ . '/../configuracions/informacionbd.php';

• Ademais de estar fóra do directorio público, o arquivo debe ter permisos de acceso adecuados.

• Non debemos gardar contrasinais ou credenciais sensibles nun repositorio público.

Exercicios propostos

• Exercicio 1: Define nun arquivo externo dentro dun cartafol de nome utilidades dúas funcións: unha que, a partir dunha cadea, engada a un array dita cadea se non existe previamente, e outra función que dado un array devolva unha copia do array enviado. Xera unha páxina que faga uso das funcións do arquivo anterior. É obrigatorio que exista dito arquivo para que a páxina funcione.

• Exercicio 2: Define nun arquivo externo de nome utilidades2.php dentro do cartafol utilidades as seguintes constantes: NUM_ELEMENTOS igual a 3 e IDADE_MAIOR igual a 18.

Crea tamén unha función que, dado un array numérico, comprobe que o número de elementos do array sexa superior a NUM_ELEMENTOS.

Se non cumpre a condición, a función debe devolver false.

En caso contrario, debe devolver un array cos datos que cumpran a condición de seren maiores que IDADE_MAIOR. Se non existe ningún elemento que cumpra a condición, debe devolver false.

Crea unha páxina de exemplo de uso da función anterior, tendo en conta que dita páxina pode xerarse dinamicamente e non vas saber se o arquivo foi incluído previamente. Para funcionar, a páxina necesita cargar obrigatoriamente o arquivo utilidades2.php.

Solución Exercicios propostos

• Solución Exercicio 1:

Páxina utilidades/utilidades1.php

<?php

/**
 * Engade unha cadea ao array se non existe xa.
 *
 * @param array  &$array Array onde se engadirá a cadea.
 * @param string $cadea  Cadea de texto a engadir.
 *
 * @return void
 */
function engadirCadeaAoArray(array &$array, string $cadea): void
{
    if (!in_array($cadea, $array, true)) {
        $array[] = $cadea;
    }
}

/**
 * Devolve unha copia dun array.
 *
 * En PHP os arrays asígnanse por valor. Polo tanto, devolver o array
 * permite obter unha copia que pode modificarse sen alterar o array
 * orixinal, salvo que se empreguen referencias de forma explícita.
 *
 * @param array $array Array que se quere copiar.
 *
 * @return array Copia do array recibido.
 */
function copiarArray(array $array): array
{
    return $array;
}

Páxina exercicio1_include.php

<!DOCTYPE html>
<html lang="gl">
<head>
    <meta charset="UTF-8">
    <title>Exemplo de include</title>
</head>
<body>
<?php
require __DIR__ . '/utilidades/utilidades1.php';

$meuArray = [];

// Engadir cadeas ao array.
engadirCadeaAoArray($meuArray, 'Ola');
engadirCadeaAoArray($meuArray, 'Mundo');
engadirCadeaAoArray($meuArray, 'Ola'); // Xa existe, non se engade de novo.

// Copiar o array.
$copiaArray = copiarArray($meuArray);

// Modificamos a copia para comprobar que o orixinal non cambia.
$copiaArray[] = 'Novo dato';

// Amosar o array orixinal.
echo '<h2>Array orixinal:</h2>';
echo '<pre>';
print_r($meuArray);
echo '</pre>';

// Amosar a copia.
echo '<h2>Copia do array:</h2>';
echo '<pre>';
print_r($copiaArray);
echo '</pre>';
?>
</body>
</html>

• Solución Exercicio 2:

Páxina utilidades/utilidades2.php

<?php

const NUM_ELEMENTOS = 3;
const IDADE_MAIOR = 18;

/**
 * Comproba as idades dun array e devolve os elementos que superen un límite.
 *
 * @param array $array Array de números (idades) a comprobar.
 *
 * @return array|false Devolve un array cos elementos maiores que IDADE_MAIOR,
 *                     ou false se non hai coincidencias ou non se cumpre
 *                     o tamaño mínimo.
 */
function comprobarIdade(array $array): array|false
{
    if (count($array) <= NUM_ELEMENTOS) {
        return false;
    }

    $elementosCumpridos = [];

    foreach ($array as $idade) {
        if ($idade > IDADE_MAIOR) {
            $elementosCumpridos[] = $idade;
        }
    }

    return $elementosCumpridos !== [] ? $elementosCumpridos : false;
}

Páxina exercicio2_include.php

<!DOCTYPE html>
<html lang="gl">
<head>
    <meta charset="UTF-8">
    <title>Exemplo de require_once</title>
</head>
<body>
<?php
require_once __DIR__ . '/utilidades/utilidades2.php';

$idades = [2, 62, 2, 2, 2]; // Soamente 62 cumpre a condición.

$resultado = comprobarIdade($idades);

if ($resultado !== false) {
    echo '<h2>Idades que cumpren a condición:</h2>';
    echo '<ul>';

    foreach ($resultado as $idade) {
        echo "<li>$idade anos</li>";
    }

    echo '</ul>';
} else {
    echo '<h2>Ningunha idade cumpre a condición</h2>';
}
?>
</body>
</html>

-- Ángel D. Fernández González -- (2026).