Composer: consejos para su uso

Instalación

Composer es un archivo .phar ejecutable, que descarga e instala de la siguiente manera:

Windows

Use el instalador oficial Composer-Setup.exe.

Linux, macOS

Bastarán 4 comandos, que puede copiar de esta página.

Además, insertándolo en una carpeta que esté en el PATH del sistema, Composer se volverá accesible globalmente:

$ mv ./composer.phar ~/bin/composer # o /usr/local/bin/composer

Uso en el proyecto

Para poder empezar a usar Composer en su proyecto, necesita solo el archivo composer.json. Este describe las dependencias de nuestro proyecto y también puede contener otros metadatos. Un composer.json básico, por lo tanto, puede verse así:

{
	"require": {
		"nette/database": "^3.0"
	}
}

Aquí decimos que nuestra aplicación (o librería) requiere el paquete nette/database (el nombre del paquete se compone del nombre de la organización y el nombre del proyecto) y quiere una versión que cumpla la condición ^3.0 (es decir, la última versión 3).

Tenemos, por lo tanto, en la raíz del proyecto el archivo composer.json y ejecutamos la instalación:

composer update

Composer descargará Nette Database en la carpeta vendor/. Además, creará el archivo composer.lock, que contiene información sobre qué versiones exactas de las librerías instaló.

Composer generará el archivo vendor/autoload.php, que podemos simplemente incluir y empezar a usar las librerías sin ningún trabajo adicional:

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

$db = new Nette\Database\Connection('sqlite::memory:');

Actualización de paquetes a las últimas versiones

La actualización de las librerías usadas a las últimas versiones según las condiciones definidas en composer.json está a cargo del comando composer update. Por ejemplo, para la dependencia "nette/database": "^3.0" instalará la última versión 3.x.x, pero ya no la versión 4.

Para actualizar las condiciones en el archivo composer.json, por ejemplo a "nette/database": "^4.1", para poder instalar la última versión, use el comando composer require nette/database.

Para actualizar todos los paquetes Nette usados sería necesario enumerarlos todos en la línea de comandos, p. ej.:

composer require nette/application nette/forms latte/latte tracy/tracy ...

Lo cual es poco práctico. Use por lo tanto el script simple Composer Frontline, que lo hará por usted:

php composer-frontline.php

Creación de un nuevo proyecto

Creará un nuevo proyecto en Nette con un solo comando:

composer create-project nette/web-project nombre-proyecto

Como nombre-proyecto inserte el nombre del directorio para su proyecto y confirme. Composer descargará el repositorio nette/web-project de GitHub, que ya contiene el archivo composer.json, e inmediatamente después Nette Framework. Ya debería bastar con establecer los permisos de escritura en las carpetas temp/ y log/ y el proyecto debería cobrar vida.

Si sabe en qué versión de PHP se alojará el proyecto, no olvide configurarla.

Versión de PHP

Composer siempre instala aquellas versiones de paquetes que son compatibles con la versión de PHP que está usando actualmente (mejor dicho, con la versión de PHP usada en la línea de comandos al ejecutar Composer). Lo cual, sin embargo, probablemente no sea la misma versión que usa su hosting. Por lo tanto, es muy importante agregar al archivo composer.json información sobre la versión de PHP en el hosting. Después, solo se instalarán versiones de paquetes compatibles con el hosting.

Que el proyecto se ejecutará, por ejemplo, en PHP 8.2.3, lo configuramos con el comando:

composer config platform.php 8.2.3

Así se escribe la versión en el archivo composer.json:

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

Sin embargo, el número de versión de PHP se indica también en otro lugar del archivo, en la sección require. Mientras que el primer número determina para qué versión se instalarán los paquetes, el segundo número dice para qué versión está escrita la propia aplicación. Y según él, por ejemplo, PhpStorm establece el PHP language level. (Por supuesto, no tiene sentido que estas versiones difieran, por lo que la doble escritura es una falta de previsión.) Esta versión la establece con el comando:

composer require php 8.2.3 --no-update

O directamente en el archivo composer.json:

{
	"require": {
		"php": "8.2.3"
	}
}

Ignorar la versión de PHP

Los paquetes generalmente suelen tener indicada tanto la versión más baja de PHP con la que son compatibles, como la más alta con la que están probados. Si se dispone a usar una versión de PHP aún más nueva, por ejemplo, con fines de prueba, Composer se negará a instalar tal paquete. La solución es la opción --ignore-platform-req=php+, que hace que Composer ignore los límites superiores de la versión de PHP requerida.

Informes falsos

Al actualizar paquetes o cambiar números de versión, sucede que se produce un conflicto. Un paquete tiene requisitos que están en conflicto con otro y similares. Composer, sin embargo, a veces emite informes falsos. Informa de un conflicto que realmente no existe. En tal caso, ayuda eliminar el archivo composer.lock e intentarlo de nuevo.

Si el mensaje de error persiste, entonces se toma en serio y es necesario leer de él qué y cómo modificar.

Packagist.org – repositorio central

Packagist es el repositorio principal en el que Composer intenta buscar paquetes, si no le decimos lo contrario. Aquí también podemos publicar nuestros propios paquetes.

¿Y si no queremos usar el repositorio central?

Si tenemos aplicaciones internas de la empresa, que simplemente no podemos alojar públicamente, entonces crearemos un repositorio de empresa para ellas.

Más sobre el tema de repositorios en la documentación oficial.

Autoloading

Una característica fundamental de Composer es que proporciona autoloading para todas las clases instaladas por él, que inicia incluyendo el archivo vendor/autoload.php.

Sin embargo, es posible usar Composer también para cargar otras clases incluso fuera de la carpeta vendor. La primera opción es dejar que Composer explore las carpetas y subcarpetas definidas, encuentre todas las clases y las incluya en el autoloader. Esto se logra configurando autoload > classmap en composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      # incluye la carpeta src/ y sus subcarpetas
		]
	}
}

Posteriormente, es necesario ejecutar el comando composer dumpautoload cada vez que se realice un cambio y dejar que las tablas de autoloading se regeneren. Esto es extremadamente incómodo y es mucho mejor confiar esta tarea a RobotLoader, que realiza la misma actividad automáticamente en segundo plano y mucho más rápido.

La segunda opción es cumplir con PSR-4. Simplificando, se trata de un sistema donde los espacios de nombres y los nombres de las clases corresponden a la estructura de directorios y los nombres de los archivos, es decir, p. ej., App\Core\RouterFactory estará en el archivo /path/to/App/Core/RouterFactory.php. Ejemplo de configuración:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # el espacio de nombres App\ está en el directorio app/
		}
	}
}

Cómo configurar exactamente el comportamiento se aprende en la documentación de Composer.

Prueba de nuevas versiones

Quiere probar una nueva versión de desarrollo de un paquete. ¿Cómo hacerlo? Primero, agregue al archivo composer.json este par de opciones, que permiten instalar versiones de desarrollo de paquetes, pero recurrirá a ello solo si no existe ninguna combinación de versiones estables que cumpla los requisitos:

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

Además, recomendamos eliminar el archivo composer.lock, a veces Composer inexplicablemente se niega a la instalación y esto resuelve el problema.

Supongamos que se trata del paquete nette/utils y la nueva versión tiene el número 4.0. La instala con el comando:

composer require nette/utils:4.0.x-dev

O puede instalar una versión específica, por ejemplo 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Pero si otro paquete depende de la librería, que está bloqueado en una versión anterior (p. ej., ^3.1), entonces lo ideal es actualizar el paquete para que funcione con la nueva versión. Sin embargo, si solo quiere eludir la restricción y forzar a Composer a instalar la versión de desarrollo y fingir que es una versión anterior (p. ej., 3.1.6), puede usar la palabra clave as:

composer require nette/utils "4.0.x-dev as 3.1.6"

Llamada de comandos

A través de Composer se pueden llamar comandos y scripts propios pre-preparados, como si fueran comandos nativos de Composer. Para los scripts que se encuentran en la carpeta vendor/bin, no es necesario indicar esta carpeta.

Como ejemplo, definimos en el archivo composer.json un script que usando Nette Tester ejecuta las pruebas:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

Las pruebas luego las ejecutamos con composer tester. El comando podemos llamarlo incluso si no estamos en la carpeta raíz del proyecto, sino en algún subdirectorio.

Envíe un agradecimiento

Le mostraremos un truco con el que complacerá a los autores de código abierto. De manera simple, dará una estrella en GitHub a las librerías que usa su proyecto. Basta con instalar la librería symfony/thanks:

composer global require symfony/thanks

Y luego ejecutar:

composer thanks

¡Pruébelo!

Configuración

Composer está estrechamente vinculado con la herramienta de versionado Git. Si no la tiene instalada, es necesario decirle a Composer que no la use:

composer -g config preferred-install dist