Utilizar

Introducción

Composer es una herramienta popular de administración de dependencias para PHP, creada principalmente para facilitar la instalación y actualización de dependencias de proyectos. Comprueba los demás paquetes de los que depende un proyecto específico y los instala utilizando las versiones apropiadas según los requisitos de este. Composer también se utiliza comúnmente para iniciar nuevos proyectos en función de marcos PHP populares, como Symfony y Laravel.

A través de este tutorial, instalará y comenzará a utilizar Composer en un sistema Ubuntu 20.04.

Requisitos previos

Para seguir esta guía, necesitará acceso a un servidor de Ubuntu 20.04 como un non-root sudo user y un firewall habilitado en su servidor. Para configurarlo, puede consultar nuestra Guía de configuración inicial de servidores para Ubuntu 20.04.

Paso 1: Instalar PHP y dependencias adicionales

Además de las dependencias que ya deben estar incluidas en su sistema de Ubuntu 20.04, como git y curl, Composer requiere php-cli para ejecutar las secuencias de comandos PHP en la línea de comandos y unzip para extraer los archivos comprimidos. Instalaremos estas dependencias ahora.

Primero, actualice la caché del administrador de paquetes ejecutando lo siguiente:

Luego, ejecute el siguiente comando para instalar los paquetes requeridos:

sudo apt install php-cli unzip

Se le solicitará confirmar la instalación escribiendo Y y luego ENTER.

Una vez que haya instalado lo que se estipula en los requisitos previos, podrá proceder con la instalación de Composer.

Paso 2: Descargar e instalar Composer

Composer ofrece una secuencia de comandos de instalación escrita en PHP. La descargaremos, comprobaremos que no esté dañada y la utilizaremos para instalar Composer.

Asegúrese de posicionarse en su directorio de inicio y obtenga el instalador usando curl:

cd ~
curl -sS https://getcomposer.org/installer -o composer-setup.php

A continuación, verificaremos que el instalador descargado coincida con el hash SHA-384 para el instalador más reciente disponible en la página Composer Public Keys/Signatures. A fin de facilitar el paso de verificación, puede utilizar el siguiente comando para obtener de forma programática el hash más reciente de la página de Composer y almacenarlo en una variable de shell:

HASH=`curl -sS https://composer.github.io/installer.sig`

Si desea verificar el valor obtenido, puede ejecutar lo siguiente:

Output
e0012edf3e80b6978849f5eff0d4b4e4c79ff1609dd1e613307e16318854d24ae64f26d17af3ef0bf7cfb710ca74755a

Ahora, ejecute el siguiente código PHP, como se indica en la página de descarga de Composer, para verificar que la secuencia de comandos de instalación se pueda ejecutar de forma segura:

php -r "if (hash_file('SHA384', 'composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

Verá el siguiente resultado:

Output

Installer verified

Si aparece el mensaje Installer corrupt, tendrá que volver a descargar la secuencia de comandos de instalación y verificar nuevamente si utilizó el hash correcto. Luego, repita el proceso de verificación. Cuando cuente con un instalador verificado, podrá continuar.

Para instalar composer de manera global, utilice el siguiente comando que lo descargará e instalará en todo el sistema como un comando llamado composer, en /usr/local/bin:

sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Verá un resultado similar a este:

Output
All settings correct for using Composer
Downloading...

Composer (version 1.10.5) successfully installed to: /usr/local/bin/composer
Use it: php /usr/local/bin/composer

Para comprobar su instalación, ejecute lo siguiente:

Output
   ______
  / ____/___  ____ ___  ____  ____  ________  _____
 / /   / __ / __ `__ / __ / __ / ___/ _ / ___/
/ /___/ /_/ / / / / / / /_/ / /_/ (__  )  __/ /
____/____/_/ /_/ /_/ .___/____/____/___/_/
                    /_/
Composer version 1.10.5 2020-04-10 11:44:22

Usage:
  command [options] [arguments]

Options:
  -h, --help                     Display this help message
  -q, --quiet                    Do not output any message
  -V, --version                  Display this application version
      --ansi                     Force ANSI output
      --no-ansi                  Disable ANSI output
  -n, --no-interaction           Do not ask any interactive question
      --profile                  Display timing and memory usage information
      --no-plugins               Whether to disable plugins.
  -d, --working-dir=WORKING-DIR  If specified, use the given directory as working directory.
      --no-cache                 Prevent use of the cache
  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
...

Esto comprueba que Composer se instaló con éxito y está disponible en todo el sistema.

Nota: Si prefiere tener ejecutables de Composer separados para cada proyecto que aloje en este servidor, puede instalarlos localmente para cada proyecto. Este método también es útil cuando su usuario de sistema no tiene permisos para instalar software en todo el sistema.

Para ello, utilice el comando php composer-setup.php. Con esto, se generará un archivo composer.phar en su directorio actual que puede ejecutarse con php composer.phar.

Ahora, veamos el uso de Composer para administrar dependencias.

Paso 3: Usar Composer en un proyecto de PHP

Los proyectos de PHP a menudo dependen de bibliotecas externas y la administración de estas dependencias y sus versiones puede ser complicada. Composer resuelve ese problema realizando un seguimiento de las versiones y dependencias del proyecto, al mismo tiempo que facilita el proceso de búsqueda, instalación y actualización de los paquetes que requiere el proyecto.

Para utilizar Composer en su proyecto, necesitará un archivo composer.json. El archivo composer.json indica a Composer las dependencias que debe descargar para su proyecto y las versiones de cada paquete cuya instalación está permitida. Esto es extremadamente importante para preservar la uniformidad de su proyecto y evitar la instalación de versiones inestables que podrían causar problemas de compatibilidad con versiones anteriores.

No necesita crear este archivo de forma manual; hay muchas probabilidades de cometer errores de sintaxis al hacerlo. Composer ofrece una opción interactiva para crear un nuevo archivo composer.json en base a la entrada del usuario, una buena opción si planea compartir su proyecto más adelante como paquete público en Packagist. Composer también genera de forma automática un archivo composer.json​​ barebones cuando ejecuta un comando composer require para incluir una dependencia a un proyecto recién creado.

Para usar Composer en la instalación de un paquete como dependencia en un proyecto, se deben seguir estos pasos:

• Identifique el tipo de biblioteca que requiere la aplicación.
• Busque una biblioteca de código abierto adecuada  en Packagist.org, el repositorio oficial de paquetes de Composer.
• Elija el paquete que desee usar.
• Ejecute composer require para incluir la dependencia en el archivo composer.json e instale el paquete.

Probemos esto con una aplicación de demostración.

El objetivo de esta aplicación es transformar una oración en una cadena compatible con una URL; un slug. Esto se utiliza comúnmente para convertir los títulos de páginas en rutas URL (como la parte final de la URL de este tutorial).

Comencemos creando un directorio para nuestro proyecto. Lo llamaremos slugify:

cd ~
mkdir slugify
cd slugify

Aunque no sea obligatorio, ahora podrá ejecutar un comando composer init a fin de crear un archivo composer.json detallado para su proyecto. Ya que que el único objetivo de nuestro proyecto es demostrar la forma de instalar dependencias con Composer, utilizaremos un archivo composer.json más sencillo que se generará automáticamente cuando necesitemos nuestro primer paquete.

Ahora será el momento de buscar en Packagist.org un paquete que puede servirnos para generar slugs. Si busca el término “slug” en Packagist, obtendrá un resultado similar a este:

Observará dos números en el lado derecho de cada paquete de la lista. El número de la parte superior representa la cantidad de veces que se instaló el paquete a través de Composer y el de la parte inferior la cantidad de veces que se destacó un paquete en GitHub. En general, los paquetes con más instalaciones y más estrellas suelen ser más estables, ya que muchas personas los utilizan. También es importante revisar la descripción del paquete para asegurarse de que se adecue a lo que usted requiere.

Necesitamos un convertidor de cadena a slug. Conforme a los resultados de la búsqueda, el paquete cocur/slugify, que aparece como el primer resultado de esa página, parece ser una buena opción al ofrecer una cantidad razonable de instalaciones y estrellas.

Los paquetes en Packagist tienen un nombre de proveedor y un nombre de paquete. Cada paquete tiene un identificador único (un espacio de nombres) en el mismo formato que GitHub utiliza para sus repositorios: vendor/package​​​. La biblioteca que deseamos instalar utiliza el espacio de nombres cocur/slugify. Necesita el espacio de nombres del paquete para solicitarlo en su proyecto.

Ahora que sabe exactamente qué paquete desea instalar, puede ejecutar composer require para incluirlo como una dependencia y generar también el archivo composer.json para su proyecto: Algo que es importante destacar al requerir paquetes es que Composer realiza un seguimiento tanto de las dependencias a nivel de aplicación como de las dependencias a nivel de sistema. Las dependencias a nivel de sistema son importantes para indicar en qué módulos PHP se basa un paquete. En el caso del paquete cocur/slugify, requiere un módulo PHP que aún no hemos instalado.

Cuando un paquete requerido se basa en una biblioteca del sistema que no esté instalada actualmente en su servidor, recibirá un mensaje de error indicando el requisito que falta:

composer require cocur/slugify

Output
Using version ^4.0 for cocur/slugify
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for cocur/slugify ^4.0 -> satisfiable by cocur/slugify[v4.0.0].
    - cocur/slugify v4.0.0 requires ext-mbstring * -> the requested PHP extension mbstring is missing from your system.
...

Para resolver el problema de dependencia del sistema, podemos buscar el paquete que falta utilizando apt search​​​:

Output
Sorting... Done
Full Text Search... Done
php-mbstring/focal 2:7.4+75 all
  MBSTRING module for PHP [default]

php-patchwork-utf8/focal 1.3.1-1 all
  UTF-8 strings handling for PHP

php7.4-mbstring/focal 7.4.3-4ubuntu1 amd64
  MBSTRING module for PHP

Después de ubicar el nombre del paquete correcto, puede utilizar apt una vez más para instalar la dependencia del sistema:

sudo apt install php-mbstring

Una vez que la instalación haya finalizado, podrá ejecutar el comando composer require de nuevo:

composer require cocur/slugify

Output
Using version ^4.0 for cocur/slugify
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing cocur/slugify (v4.0.0): Downloading (100%)         
Writing lock file
Generating autoload files

Como se observa en el resultado, Composer automáticamente decidió la versión del paquete que utilizará. Si revisa el directorio de su proyecto, este contendrá dos nuevos archivos, composer.json y composer.lock, y un directorio vendor:

Output
total 12
-rw-rw-r-- 1 sammy sammy   59 May  4 13:56 composer.json
-rw-rw-r-- 1 sammy sammy 3229 May  4 13:56 composer.lock
drwxrwxr-x 4 sammy sammy 4096 May  4 13:56 vendor

El archivo composer.lock se utiliza para almacenar información sobre las versiones de cada paquete que están instaladas y garantizar que se utilicen las mismas versiones si otra persona clona su proyecto e instala sus dependencias. En el directorio vendor se ubican las dependencias del proyecto. La carpeta vendor no debe comprometerse con el control de versión; solo debe incluir los archivos composer.json y composer.lock.

Al instalar un proyecto que ya contenga un archivo composer.json, ejecute composer install para descargar las dependencias del proyecto.


Veamos rápidamente las restricciones de versiones. Si verifica los contenidos de su archivo composer.json, verá algo parecido a lo siguiente:

Output
{
    "require": {
        "cocur/slugify": "^4.0"
    }
}

Posiblemente observe el carácter especial ^ antes del número de versión en composer.json. A fin de proporcionar flexibilidad y a su vez mantener la estabilidad de su proyecto, Composer admite diferentes restricciones y formatos para definir la versión requerida del paquete. El operador del símbolo de intercalación (^) utilizado por el archivo de generación automática composer.json es el operador recomendado para una máxima interoperabilidad, seguido del control de versión semántico. En este caso, define la versión 4.0 como la versión de compatibilidad mínima y permite actualizaciones a cualquier versión futura inferior a la 5.0.

En general, no tendrá que alterar las restricciones de versiones de su archivo composer.json. Sin embargo, en algunas situaciones posiblemente deba editar las restricciones manualmente; por ejemplo, cuando se lance una nueva versión importante de su biblioteca requerida y desee actualizarla, o cuando la biblioteca que desee utilizar no siga el control de versión semántico.

Aquí se muestran algunos ejemplos para que comprenda mejor el funcionamiento de las restricciones de versiones de Composer:

Para acceder a una perspectiva más detallada de las restricciones de versiones de Composer, consulte la documentación oficial.

A continuación, veamos la forma de cargar las dependencias automáticamente con Composer.

Paso 4: Incluir la secuencia de comandos de carga automática

Dado que PHP por sí mismo no carga automáticamente las clases, Composer proporciona una secuencia de comandos de carga automática que puede incluir en su proyecto para que la carga automática funcione en su proyecto. Composer genera este archivo de manera automática al añadir su primera dependencia.

Lo único que debe hacer es incluir el archivo vendor/autoload.php en sus secuencias de comandos de PHP antes de cualquier instancia de clase.

Probemos esto en nuestra aplicación de demostración. Abra un archivo nuevo llamado test.php en su editor de texto:

Añada el siguiente código que agrega el archivo vendor/autoload.php, carga la dependencia cocur/slugify y la utiliza para crear un slug:

test.php

<?php
require __DIR__ . '/vendor/autoload.php';

use CocurSlugifySlugify;

$slugify = new Slugify();

echo $slugify->slugify('Hello World, this is a long sentence and I need to make a slug from it!');

Guarde el archivo y cierre el editor.

Ahora ejecute la secuencia de comandos:

El resultado de esto es hello-world-this-is-a-long-sentence-and-i-need-to-make-a-slug-from-it.

Las dependencias necesitan actualizaciones cuando se lanzan nuevas versiones. Veamos la forma de manejar eso.

Paso 5: Actualizar dependencias del proyecto

Cuando desee actualizar las dependencias de proyecto a versiones más recientes, ejecute el comando update:

Con esto, se buscarán versiones más recientes de las bibliotecas que necesitó en su proyecto. Si se encuentra una versión más reciente y es compatible con la restricción de versión definida en el archivo composer.json, Composer sustituirá la versión anterior instalada. El archivo composer.lock se actualizará para reflejar estos cambios.

También puede actualizar una o más bibliotecas determinadas especificándolas de la siguiente manera:

composer update vendor/package vendor2/package2

Después de actualizar sus dependencias, asegúrese de verificar sus archivos composer.json y composer.lock en su sistema de control de versiones para que otros también puedan instalar estas versiones más recientes.

Conclusión

Composer es una herramienta poderosa que puede facilitar mucho el trabajo de gestionar dependencias en proyectos PHP. Ofrece una manera confiable de descubrir, instalar y actualizar los paquetes PHP de los que depende un proyecto. En esta guía, vimos cómo instalar Composer, incluir nuevas dependencias en un proyecto y actualizar estas dependencias una vez que haya nuevas versiones disponibles.