Bibliotecas

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:

Cuando una página incluye una biblioteca ... pagina.php <?php include "biblioteca.php"; print "<p>¡Adios!</p>; include biblioteca.php <?php print "<p>¡Hola!</p>; ... el contenido de la biblioteca se inserta íntegro en la posición en la que encuentra el include. pagina.php <?php print "<p>¡Hola!</p>; print "<p>¡Adios!</p>;

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:

Potenciales problemas en la carga de bibliotecas

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

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:

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.