Composer (II). Uso básico.

Facebooktwittergoogle_pluslinkedinmailFacebooktwittergoogle_pluslinkedinmail

En el artículo anterior hemos descrito lo qué es composer, para que sirve, y cómo nos puede ayudar. Hemos aprendido a descargarlo e instalarlo.

En este artículo vamos a aprender lo básico para usarlo “a lo bruto”. En realidad, la mejor manera de usarlo, ahorrándonos trabajo y complicaciones, la aprenderemos en el próximo artículo de esta serie. La razón por la que vamos a usar ahora composer de una forma que no es las más óptima es porque nos permitirá sentar algunas bases teóricas que necesitaremos para entender lo que tenemos entre manos, y cómo funciona.

USANDO COMPOSER EN UN PROYECTO

Vamos a detallar cómo usar composer en un proyecto PHP para que nos cargue todas las dependencias necesarias. Lo primero que tenemos que tener es, por supuesto, la carpeta donde tendremos el proyecto. Puede que ni siquiera tengamos aún la estructura de archivos y directorios dentro de esa carpeta. No importa. Vamos a verlo creando un proyecto nuevo que va a usar, por poner un ejemplo, las dos librerías que hemos mencionado más arriba: el phpMailer y el HTML2PDF.

Creamos la carpeta del proyecto, donde tenemos que tener tres cosas:

  • El archivo index.php, que será la página principal, o punto de entrada a nuestro proyecto. De momento, ni siquiera tiene por qué tener aún ningún código. En realidad, este no es imprescindible, pero me gusta tenerlo, por empezar a estructurar.
  • Un archivo llamado composer.json, que contendrá la lista de dependencias que composer deberá instalar. La lista de dependencias de cada proyecto siempre debe llamarse composer.json. En seguida hablaremos de lo que contiene.
  • Muy aconsejable, tener en la misma carpeta del proyecto un acceso directo a la consola de comandos (si, esa, la ventana negra donde se teclean los comandos a mano). Si ya tienes el acceso directo, haz clic derecho sobre él, selecciona Propiedades y, en la pestaña Acceso Directo, en la casilla Iniciar en: escribes la ruta completa de la carpeta de tu proyecto.

EL ARCHIVO composer.json

El archivo composer.json es único para cada proyecto PHP y debe estar en la carpeta raíz de dicho proyecto. En este archivo se informa a composer de las dependencias que queremos, para que el gestor se encargue de todo. La estructura mínima imprescindible de composer.json obedece al siguiente esquema:

En el apartado require incluímos una línea por cada dependencia que queramos. Si alguna de las librerías necesita, a su vez, de otras dependencias, no tenemos que preocuparnos de ello. Composer lo detectará e instalará las sub-dependencias necesarias.

Veamos un ejemplo real, para el proyecto hipotético que hemos comentado arriba:

Cómo ves, lo que tenemos son referencias a ubicaciones en Internet de las librerías que vamos a emplear. Luego veremos cómo hemos conseguido esas referencias. Ahora abre el acceso directo a tu consola. Cómo le pusiste que se abriera en la carpeta de tu proyecto, el indicador que ves en la ventana negra es del tipo C:/Mis proyectos/proyecto prueba/prueba con composer> (o la ruta que tengas hasta tu carpeta de proyecto, por supuesto. Esto es sólo un ejemplo).

En el indicador de la consola escribe lo siguiente:

composer install

Tras pulsar Enter, composer lee el archivo composer.json que está en la carpeta actual y ya sabe lo que necesitas en tu proyecto. Tras unos segundos y algunos mensajes informativos de composer, te sale de nuevo el indicador de la consola. Ya puedes cerrarla. Ahora mira en la carpeta de tu proyecto. Ooooppps, la de cosas nuevas que hay.

Hay una carpeta llamada vendor. Dentro están, en sus correspondientes directorios, todas las dependencias que necesitas. También, dentro de la carpeta vendor, encuentras un archivo llamado autoload.php. Incluye una llamada a este en el archivo principal de tu sitio (index.php), así:

require_once ($_SERVER['DOCUMENT_ROOT'].'/vendor/autoload.php');

En cada script de tu sitio incluye una referencia similar a vendor/autoload.php, teniendo en cuenta, por supuesto, especificar $_SERVER[‘DOCUMENT_ROOT’], cómo en el ejemplo. De este modo, no tendrás que preocuparte de rutas relativas, si estás trabajando en subdirectorios.

Y ya está. El sistema de autoload de PHP es muy eficiente, ya que se cargarán únicamente las librerías si son llamadas en el script. Si no, no se cargan y no consumen recursos.

Si, más adelante, quieres que composer actualice, si procede, las librerías a la última versión (con las salvedades de que hablaremos en seguida), sólo tienes que abrir de nuevo la consola de comandos y teclear:

composer update

Y en pocos segundos, todas las librerías quedarán actualizadas. Si has añadido nuevas líneas al epígrafe require de composer.json (por necesitar nuevas librerías en las que no habías pensado), al hacer la actualización también se instalan las nuevas.

ANATOMÍA DE composer.json

Cómo seguro que has comprendido, el archivo composer.json es la clave para que composer instale las librerías necesarias, las actualice, y mantenga correctamente al día el autoloader. En el apartado anterior hemos visto un ejemplo de composer.json con lo mínimo imprescindible para funcionar. Aquí vamos a ver cómo formar completa y correctamente este archivo.

El archivo composer.json se divide en una serie de apartados o epígrafes, de los que sólo require (el que hemos visto antes, es realmente obligatorio, pero que están para proporcionar información adicional que, en ocasiones, es necesaria:

El apartado authors. Indica los autores materiales del proyecto PHP en el que trabajamos, con distintos datos identificativos y de contacto. En la actualidad, esto es de vital importancia a efectos, entre otros, de SEO.

El apartado name. Indica el nombre de la empresa, organismo o entidad creadora del proyecto, así cómo el nombre de dicho proyecto.

Aquí ves una muestra del archivo composer.json del proyecto hipotético que estamos creando:

Hay otras muchas claves, más o menos relevantes, que puedes agregar a este archivo, pero estás son las más habituales. Si quieres ver una lista más detallada, visita https://getcomposer.org/doc/04-schema.md.

EL EPÍGRAFE require

Este es, cómo hemos dicho ya, imprescindible, ya que le dice a composer que dependencias necesita el proyecto. Hay una línea por cada dependencia (cómo hemos comentado, no es necesario indicar las subdependencias, ya que composer las identifica y carga sin problemas).

En cada línea encontramos dos cadenas. La primera en el nombre del fabricante y, tras un slash (/), el nombre de la librería que queremos. La segunda, separada por dos puntos (:) es la versión que queremos. Hablemos de esto. La versión se puede indicar cómo una versión única (por ejemplo, "4.6.1"). En ese caso, composer instalará esa versión y no actualizará nunca a ninguna otra. También se pueden usar determinados comodines, si queremos actualizar a ciertas versiones.

COMIDÍN SIGNIFICADO COMPORTAMIENTO
* Cualquier número Un asterisco sustituye a cualquier valor. Por ejemplo "4.6.*" le dice a composer que instale la última revisión de la versión 4.6 y que si sale otra revisión de esa versión, actualice. Así, por ejemplo, si en el momento de usar composer, la última revisisión disponible de la librería es 4.6.1, esa es la que instalará. Si al hacer composer update se encuentra la 4.6.8, la instalará sustituyendo a la 4.6.1. Sin embargo, si encuentra la 4.7.2 no la instalará, porque no se ciñe al patrón indicado.
Operadores Definen un rango de versiones. Si le indicamos a composer, como versión, “>=4.6.0”, instalará la última versión estable de la librería buscada que encuentre que sea mayor o igual a la 4.6.0.
Virgulilla de la eñe. Última versión relevante. Este es un cómodín un poco extraño de entender. Si le indicas, por ejemplo “~6.3” la próxima actualización buscará la 6.4 o superior, pero no actualizará si tienes la 6.3.1 y encuentra la 6.3.2.

Y respecto al fabricante y el nombre exacto de la librería ¿Cómo los conseguimos? Existe un repositorio en Internet dónde puedes encontrar cualquier libería de PHP. En la pagina de cada una se encuentra el literal exacto que necesita composer para cargar esa librería. El repositorio se llama packagist y está en este enlace.

En la parte superior verás un buscador. Puedes teclear el nombre de una librería que te interese, o el aspecto que desees cubrir. Por ejemplo, si buscas alguna librería para validación de formularios, pero no sabes el nombre de ninguna, teclea Validation (tienes que usar el inglés). Te saldrá una lista de librerías relativas a este tema. Si pulsas sobre el nombre de alguna de ellas, verás una página con un enlace a la página oficial de la librería, lo que te permitirá comprobar si cumple con lo que necesitas. También verás el literal para composer. Así, si dentro de validation pulsas sobre la primera, (illuminate/validation, en el momento de escribir esto) verás algo una página cómo que hemos capturado un fragmento en la siguiente imagen:

composer

Así que ya tienes todo lo que necesitas para usar composer en tus proyectos, y facilitarte la vida un poquito.

     

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *