Composer: consejos de uso

Instalación

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

Windows

Use el instalador oficial Composer-Setup.exe.

Linux, macOS

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

Además, copiándolo a una carpeta que esté en el PATH del sistema, Composer pasa a estar disponible globalmente:

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

Uso en un proyecto

Para empezar a usar Composer en su proyecto solo necesita un archivo composer.json. Este archivo describe las dependencias de su proyecto y puede contener también otros metadatos. El composer.json más sencillo puede tener este aspecto:

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

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

Así pues, con el archivo composer.json en la raíz del proyecto, ejecute:

composer update

Composer descargará Nette Database en el directorio vendor/. También crea el archivo composer.lock, que contiene información sobre qué versiones exactas de las bibliotecas ha instalado.

Composer genera el archivo vendor/autoload.php. Basta con incluir este archivo y podrá empezar a usar las clases de las bibliotecas sin ningún trabajo adicional:

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

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

Actualizar los paquetes a las últimas versiones

Para actualizar las bibliotecas usadas a las últimas versiones según las restricciones definidas en composer.json, use el comando composer update. Por ejemplo, con la dependencia "nette/database": "^3.0" instalará la última versión 3.x.x, pero no la versión 4.

Para actualizar las restricciones del archivo composer.json, por ejemplo a "nette/database": "^4.1", permitiendo así instalar la última versión, use el comando composer require nette/database.

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

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

Esto es poco práctico. Por eso, use el sencillo script Composer Frontline, que lo hará por usted:

php composer-frontline.php

Crear un proyecto nuevo

Puede crear un proyecto nuevo de Nette con un solo comando:

composer create-project nette/web-project name-of-the-project

Sustituya name-of-the-project por el nombre del directorio de su proyecto y ejecute el comando. Composer descargará de GitHub el repositorio nette/web-project, que ya contiene el archivo composer.json, y después instalará el propio Nette Framework. Solo queda establecer los permisos de los directorios temp/ y log/ y el proyecto debería estar en marcha.

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

Versión de PHP

Composer instala siempre versiones de los paquetes compatibles con la versión de PHP que usted usa en ese momento (en concreto, la versión de PHP usada en la línea de comandos al ejecutar Composer). Puede que no sea la misma versión que usa su hosting. Por eso es crucial añadir al archivo composer.json la información sobre la versión de PHP de su hosting. Entonces solo se instalarán versiones de los paquetes compatibles con él.

Por ejemplo, para indicar que el proyecto funcionará en PHP 8.2.3, use el comando:

composer config platform.php 8.2.3

La versión se escribirá en el archivo composer.json así:

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

El número de la versión de PHP se indica, sin embargo, también en otro lugar del archivo, en la sección require. Mientras que el primer número determina la versión para la que se instalan los paquetes, el segundo indica la versión para la que está escrita la propia aplicación. PhpStorm, por ejemplo, lo usa para establecer el PHP language level. (Naturalmente, no tiene sentido que estas versiones difieran, así que la doble entrada es un descuido.) Establezca esta versión 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 suelen indicar tanto la versión mínima de PHP con la que son compatibles como la versión máxima con la que se han probado. Si tiene pensado usar una versión de PHP aún más nueva, quizá para hacer pruebas, Composer se negará a instalar un paquete así. 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.

Avisos falsos

Al actualizar paquetes o cambiar números de versión se producen a veces conflictos. Un paquete tiene requisitos que chocan con los de otro, y así sucesivamente. Pero Composer emite a veces avisos falsos. Informa de un conflicto que en realidad no existe. En esos casos puede ayudar borrar el archivo composer.lock y volver a intentarlo.

Si el mensaje de error persiste, es real y hay que leerlo para entender qué hay que modificar y cómo.

Packagist.org: el repositorio global

Packagist es el repositorio principal en el que Composer busca los paquetes de forma predeterminada. También puede publicar aquí sus propios paquetes.

¿Y si no queremos el repositorio central?

Si dentro de nuestra empresa tenemos aplicaciones o bibliotecas internas que no se pueden alojar públicamente, podemos crear nuestros propios repositorios para ellas.

Más sobre los repositorios en la documentación oficial.

Autoloading

Una característica clave de Composer es que proporciona autoloading para todas las clases que instala. Se activa incluyendo el archivo vendor/autoload.php.

Pero también puede usar Composer para cargar otras clases de fuera del directorio vendor/. La primera opción es dejar que Composer recorra los directorios y subdirectorios definidos, encuentre todas las clases y las incluya en el autoloader. Para conseguirlo, configure autoload > classmap en composer.json:

{
	"autoload": {
		"classmap": [
		"src/",      # incluye el directorio src/ y sus subdirectorios
		]
	}
}

Después hay que ejecutar el comando composer dumpautoload tras cada cambio para regenerar las tablas de autoloading. Esto es extremadamente incómodo. Es mucho mejor encomendar esta tarea a RobotLoader, que hace lo mismo automáticamente en segundo plano y mucho más rápido.

La segunda opción es atenerse a PSR-4. Dicho de forma simple, es un sistema en el que los espacios de nombres y los nombres de las clases se corresponden con la estructura de directorios y los nombres de los archivos, 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/
		}
	}
}

Consulte la documentación de Composer para saber cómo configurar este comportamiento.

Probar versiones nuevas

¿Quiere probar una nueva versión de desarrollo de un paquete? Así se hace. Primero, añada este par de opciones a su archivo composer.json. Eso permite instalar versiones de desarrollo, pero Composer solo recurrirá a ellas si ninguna combinación de versiones estables cumple los requisitos:

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

También recomendamos borrar el archivo composer.lock, porque Composer a veces se niega a instalar sin explicación y esto puede resolverlo.

Digamos que el paquete es nette/utils y la nueva versión es la 4.0. Instálelo con el comando:

composer require nette/utils:4.0.x-dev

O puede instalar una versión concreta, por ejemplo la 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Sin embargo, si otro paquete depende de la biblioteca y está fijado a una versión más antigua (p. ej. ^3.1), la solución ideal es actualizar ese paquete dependiente para que funcione con la nueva versión. Pero si solo quiere saltarse la restricción y forzar a Composer a instalar la versión de desarrollo haciéndola pasar por una versión más antigua (p. ej. la 3.1.6), puede usar la palabra clave as:

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

Llamar a comandos

Puede llamar a sus propios comandos y scripts predefinidos a través de Composer como si fueran comandos nativos de Composer. Para los scripts que están en el directorio vendor/bin no hace falta indicar esa ruta.

Como ejemplo, definamos en composer.json un script que use Nette Tester para ejecutar los tests:

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

Después ejecutamos los tests con composer tester. Puede llamar al comando aunque no esté en el directorio raíz del proyecto, sino en alguno de sus subdirectorios.

Dar las gracias

Le enseñamos un truco para alegrar a los autores de código abierto. Puede dar fácilmente estrellas en GitHub a las bibliotecas que usa su proyecto. Basta con instalar la biblioteca symfony/thanks:

composer global require symfony/thanks

Y después ejecutar:

composer thanks

¡Pruébelo!

Configuración

Composer está estrechamente integrado con la herramienta de control de versiones Git. Si no tiene Git instalado, hay que decirle a Composer que no lo use:

composer -g config preferred-install dist