Bibliotecas. PHP. Bartolomé Sintes Marco. www.mclibre.org

Las bibliotecas permiten centralizar y reutilizar código, lo que reduce el tamaño y complejidad del código fuente de los programas. El concepto de biblioteca existen en casi todos los lenguajes de programación, pero en PHP están implementadas de una forma sencilla y fácil de utilizar.

Qué son las bibliotecas en PHP

En PHP, una biblioteca es un archivo PHP que se incluye tal cual en otro archivo PHP. Para incluir un archivo, se puede utilizar la expresión include seguida de la ruta hasta el archivo que se quiere incluir, sin necesidad de paréntesis, como muestra la figura siguiente:

Por motivos de seguridad, las bibliotecas deben estar en el mismo servidor que los programas que las incluyen y el acceso se debe hacer mediante rutas relativas.

Nota: PHP permitía también acceder a bibliotecas mediante rutas absolutas por http/https. Para ello se necesitaba activar la directiva de configuración allow_url_include, que estaba desactivada por defecto. Pero desde PHP 7.4 (2019) el uso de esta directiva está desaconsejado y si se activa, al intentar cargar una biblioteca remota se genera un error E_DEPRECATED.

Las bibliotecas puede incluir cualquier tipo de código y pueden ser llamadas en cualquier punto del programa y, en su caso, tantas veces como se quiera. El intérprete de PHP simplemente sustituye las llamadas a las bibliotecas por el contenido de las bibliotecas y ejecuta el resultado obtenido.

En el ejemplo siguiente, un programa incluye dos bibliotecas distintas (una de ellas dos veces). Además las bibliotecas definen y modifican una variable utilizada en el programa. Es importante señalar que al utilizar bibliotecas no se están compartiendo variables entre programas distintos, ya que sólo se está ejecutando un programa, aquel en el que las bibliotecas se incluyen de forma literal. Al ejecutar un programa que incluye bibliotecas, las bibliotecas no se ejecutan de forma independiente, sino únicamente en la medida en que se insertan en el programa ejecutado.

biblioteca-1.php
```
<?php
$i = 1;
```
biblioteca-2.php
```
<?php
$i = $i + 10;
```

Programa:

<?php
include "biblioteca-1.php";
print "<p>Ahora \$i vale $i</p>\n";
include "biblioteca-2.php";
print "<p>Ahora \$i vale $i</p>\n";
include "biblioteca-2.php";
print "<p>Ahora \$i vale $i</p>\n";

<p>Ahora $i vale 1</p>
<p>Ahora $i vale 11</p>
<p>Ahora $i vale 21</p>

Las bibliotecas se pueden llamar unas a otras, como en el ejemplo siguiente. Nótese cómo la primera instrucción print que se ejecuta es la de biblioteca-2, ya que las bibliotecas se incluyen en el punto en que son llamadas.

biblioteca-1.php

<?php
include "biblioteca-2.php";
print "<p>Estoy en la biblioteca 1.</p>";

biblioteca-2.php

<?php
print "<p>Estoy en la biblioteca 2.</p>";

Programa:

<?php
include "biblioteca-1.php";
print "<p>Estoy en el programa.</p>";

<p>Estoy en la biblioteca 2.</p>
<p>Estoy en la biblioteca 1.</p>
<p>Estoy en el programa.</p>

Las bibliotecas pueden contener código php, código html o una mezcla de ambos, sin que esto afecte a la forma de incluirlas.

biblioteca-1.php
```
<p>Estoy en la biblioteca 1.</p>
```

biblioteca-2.php

<?php
print "<p>Estoy en la biblioteca 2.</p>";

biblioteca-3.php

<p>Estoy en la biblioteca 3.</p>
<?php
print "<p>Sigo en la biblioteca 3.</p>";

Programa:

<?php
include "biblioteca-1.php";
include "biblioteca-2.php";
include "biblioteca-3.php";
print "<p>Estoy en el programa.</p>";

<p>Estoy en la biblioteca 1.</p>
<p>Estoy en la biblioteca 2.</p>
<p>Estoy en la biblioteca 3.</p>
<p>Sigo en la biblioteca 3.</p>
<p>Estoy en el programa.</p>

Cómo se utilizan las bibliotecas

Las bibliotecas se suelen utilizar para centralizar en un único lugar fragmentos de código que se utilizan en varias páginas. De esa manera, si se quiere hacer alguna modificación, no es necesario hacer el cambio en todos las páginas sino únicamente en la biblioteca.

El problema es que no es fácil que haya fragmentos de código no triviales que se puedan utilizar sin modificaciones en diversos programas. Por ese motivo, las bibliotecas no suelen contener instrucciones sueltas, como en los ejemplos del apartado anterior, sino que suelen contener definiciones de funciones, definiciones de constantes o inicialización de variables.

Sobre este punto, la guía de estilo PSR-1 comenta que en cualquier fichero de una biblioteca se pueden definir funciones, constantes, clases, etc. o se puede incluir parte de la lógica del programa (generar salida, modificar variables, etc.), pero prescribe que no se hagan las dos cosas en un mismo fichero.

Por ejemplo, si definimos en la biblioteca una función que imprima la cabecera de las páginas, desde cualquier página se puede incluir la biblioteca mediante la construcción include y llamar a la función como si se hubiera definido en la propia página:

biblioteca.php

<?php
function cabecera($titulo)
{
    print "<!DOCTYPE html>\n";
    print "<html lang=\"es\">\n";
    print "<head>\n";
    print "  <meta charset=\"utf-8\">\n";
    print "  <title>$titulo</title>\n";
    print "  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n";
    print "  <link rel=\"stylesheet\" href=\"estilo.css\" title=\"Color\">\n";
    print "</head>\n";
    print "\n";
    print "<body>\n";
    print "  <h1>$titulo</h1>\n";
    print "\n";
}

pagina-1.php

<?php
include "biblioteca.php";
cabecera("Página de ejemplo");
print "  <p>Esta página es válida</p>";

</body>
</html>

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>Página de ejemplo</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="estilo.css" title="Color">
</head>

<body>
  <h1>Página de ejemplo</h1>

  <p>Esta página es válida</p>
</body>
</html>

pagina-2.php

<?php
include "biblioteca.php";
cabecera("Otra página de ejemplo");
print "  <p>Esta página también es válida</p>";

</body>
</html>

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>Otra página de ejemplo</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="estilo.css" title="Color">
</head>

<body>
  <h1>Otra página de ejemplo</h1>

  <p>Esta página también es válida</p>
</body>
</html>

Potenciales problemas en la carga de bibliotecas

Cuando una biblioteca contiene definiciones de elementos (funciones, constantes, etc.), pueden ocurrir dos problemas:

Que por algún motivo, no se encuentre la biblioteca (por ejemplo, porque el camino hasta la biblioteca no sea correcto). Las llamadas posteriores a las funciones o constantes provocarían errores en el programa.
Que por algún motivo, se incluya dos veces a la misma biblioteca (por ejemplo, porque se llame a dos bibliotecas que a su vez llaman a una tercera). Dado que PHP no permite redefinir funciones o constantes con el mismo nombre, la segunda inclusión provocaría errores (E_WARNING en el caso de repetirse la definición de una constante, E_ERROR en el caso de repetirse la definición de una función).

Con relación al primer problema (que no se encuentre la biblioteca), PHP dispone de la expresión require construcciones más, además de include. La diferencia entre ellas es que require produce un error E_COMPILE_ERROR si no se encuentra el archivo (y se interrumpe el programa), mientras que include sólo produce un aviso E_WARNING (y se procesa el resto de la página).

biblioteca-1.php

<?php
print "<p>Estoy en la biblioteca.</p>\n";

Programa:

<?php
include "biblioteca-11.php";
print "<p>Estoy en el programa.</p>";

Warning:  include(biblioteca-11.php): Failed to open stream: No such file or directory in ejemplo.php on line 2

Warning:  include(): Failed opening 'biblioteca-11.php' for inclusion (include_path='...') in ejemplo.php on line 2

Estoy en el programa.

biblioteca-1.php

<?php
print "<p>Estoy en la biblioteca.</p>\n";

Programa:

<?php
require "biblioteca-11.php";
print "<p>Estoy en el programa.</p>";


Warning:  require(biblioteca-11.php): Failed to open stream: No such file or directory in ejemplo.php on line 3

Fatal error:  Uncaught Error: Failed opening required 'biblioteca-11.php' (include_path='...') in ejemplo.php:3
Stack trace: #0 {main} thrown in ejemplo.php on line 3

Con relación al segundo problema (que una misma biblioteca se incluya dos veces), PHP dispone de las expresiones include_once y require_once. Ambas expresiones no incluyen las bibliotecas si ya se han incluido anteriormente. La diferencia entre ellas es la misma que entre include y require, es decir, el error que generan si no encuentran la biblioteca a incluir.

biblioteca-1.php

<?php
function saludo() {
    print "<p>Hola</p>\n";
}

Programa:

<?php
include "biblioteca-1.php";
include "biblioteca-1.php";
saludo();

Fatal error:  Cannot redeclare saludo() (previously declared in biblioteca-1.php:4) in biblioteca-1.php on line 3

biblioteca-1.php

<?php
function saludo() {
    print "<p>Hola</p>\n";
}

Programa:

<?php
include_once "biblioteca-1.php";
include_once "biblioteca-1.php";
saludo();

<p>Hola</p>

La elección de una expresión u otra depende del contenido de la biblioteca y de la estructura de nuestro aplicación:

Si la biblioteca contiene código ejecutable (no únicamente definiciones) y puede ser llamada varias veces en el mismo programa, lógicamente no debe utilizarse ni include_once ni require_once.
Si el contenido de las bibliotecas es imprescindible para el buen funcionamiento de la aplicación, como suele ocurrir en la mayoría de los casos, es preferible usar require o require_once a include o include_once, para evitar que se ejecuten de forma incompleta los programas.

La guía de estilo del proyecto PEAR prescribe el uso de la construcción require_once en el caso de bibliotecas cuya inclusión no dependa de ninguna condición y que no se utilicen paréntesis alrededor de los nombres de las bibliotecas.