Consejos de uso de Composer

Instalación

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

Windows

Utilice el instalador oficial Composer-Setup.exe.

Linux, macOS

Todo lo que necesitas son 4 comandos, que puedes copiar de esta página.

Además, al copiar en la carpeta que se encuentra en el sistema PATH, Composer se convierte en accesible a nivel mundial:

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

Uso en el proyecto

Para empezar a utilizar Composer en su proyecto, todo lo que necesita es un archivo composer.json. Este archivo describe las dependencias de tu proyecto y puede contener también otros metadatos. El composer.json más simple puede tener este aspecto:

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

Estamos diciendo aquí, que nuestra aplicación (o biblioteca) depende del paquete nette/database (el nombre del paquete consiste en un nombre de proveedor y el nombre del proyecto) y quiere la versión que coincida con la restricción de versión ^3.0.

Entonces, cuando tenemos el archivo composer.json en la raíz del proyecto y ejecutamos:

composer update

Composer descargará la base de datos Nette en el directorio vendor. También creará un archivo composer.lock, que contiene información sobre las versiones exactas de las librerías que ha instalado.

Composer genera un archivo vendor/autoload.php. Puedes simplemente incluir este archivo y empezar a usar las clases que esas librerías proporcionan sin ningún trabajo extra:

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

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

Actualizar paquetes a las últimas versiones

Para actualizar todos los paquetes utilizados a la última versión según las restricciones de versión definidas en composer.json utilice el comando composer update. Por ejemplo, para la dependencia "nette/database": "^3.0" instalará la última versión 3.x.x, pero no la versión 4.

Para actualizar las restricciones de versión en el archivo composer.json a, por ejemplo, "nette/database": "^4.1", para permitir la instalación de la última versión, utilice el comando composer require nette/database.

Para actualizar todos los paquetes Nette utilizados, sería necesario listarlos 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. Por lo tanto, utilice un simple script Composer Frontline que lo hará por usted:

php composer-frontline.php

Crear nuevo proyecto

Se puede crear un nuevo proyecto Nette ejecutando un simple comando:

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

En lugar de name-of-the-project debe proporcionar el nombre del directorio para su proyecto y ejecutar el comando. Composer obtendrá el repositorio nette/web-project de GitHub, que ya contiene el archivo composer.json, y justo después instalará el propio Nette Framework. La única cosa que queda es comprobar los permisos de escritura en los directorios temp/ y log/ y ya está listo para ir.

Si sabes en qué versión de PHP se alojará el proyecto, asegúrate de configurarlo.

Versión PHP

Composer siempre instala las versiones de los paquetes que son compatibles con la versión de PHP que está utilizando actualmente (o más bien, la versión de PHP utilizada en la línea de comandos cuando se ejecuta Composer). Que probablemente no es la misma versión que utiliza su proveedor de alojamiento web. Por eso es muy importante añadir información sobre la versión de PHP de tu alojamiento a tu archivo composer.json. Después de eso, sólo se instalarán las versiones de paquetes compatibles con el host.

Por ejemplo, para configurar el proyecto para que se ejecute en PHP 8.2.3, utilice 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 también aparece en otra parte del archivo, en la sección require. Mientras que el primer número especifica la versión para la que se instalarán los paquetes, el segundo indica para qué versión está escrita la aplicación. (Por supuesto, no tiene sentido que estas versiones sean diferentes, así que la doble entrada es una redundancia). Esta versión se establece con el comando

composer require php 8.2.3 --no-update

O directamente en el archivo composer.json:

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

Ignorando la versión de PHP

Los paquetes suelen especificar tanto la versión más baja de PHP con la que son compatibles como la versión más alta con la que han sido probados. Si planea usar una versión aún más nueva de PHP, quizás para propósitos de prueba, Composer se rehusará a instalar dicho paquete. La solución es utilizar la opción --ignore-platform-req=php+, que hace que Composer ignore los límites superiores de la versión PHP requerida.

Informes falsos

Cuando se actualizan paquetes o se cambian los números de versión, surgen conflictos. Un paquete tiene requisitos que entran en conflicto con otro y así sucesivamente. Sin embargo, Composer ocasionalmente imprime un mensaje falso. Informa de un conflicto que realmente no existe. En este caso, ayuda borrar el archivo composer.lock e intentarlo de nuevo.

Si el mensaje de error persiste, entonces va en serio y hay que leer en él qué modificar y cómo.

Packagist.org – Repositorio global

Packagist es el repositorio principal de paquetes, en el que Composer intenta buscar paquetes, si no se le indica lo contrario. También puede publicar sus propios paquetes aquí.

¿Y si no queremos el repositorio central?

Si tenemos aplicaciones o librerías internas en nuestra empresa, que no pueden ser alojadas públicamente en Packagist, podemos crear nuestros propios repositorios para esos proyectos.

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

Carga automática

Una característica clave de Composer es que proporciona autoloading para todas las clases que instala, que se inicia mediante la inclusión de un archivo vendor/autoload.php.

Sin embargo, también es posible utilizar Composer para cargar otras clases 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. Para ello, configure autoload > classmap en composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}

Posteriormente, es necesario ejecutar el comando composer dumpautoload con cada cambio y dejar que se regeneren las tablas de autocarga. 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 seguir PSR-4. En pocas palabras, se trata de 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, es decir, App\Core\RouterFactory se encuentra en el archivo /path/to/App/Core/RouterFactory.php. Ejemplo de configuración:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}

Ver Documentación de Composer para saber exactamente cómo configurar este comportamiento.

Probar nuevas versiones

Desea probar una nueva versión de desarrollo de un paquete. ¿Cómo hacerlo? En primer lugar, añada este par de opciones al archivo composer.json, que le permitirán instalar versiones de desarrollo de paquetes, pero sólo lo harán si no existe una combinación de versiones estables que cumpla los requisitos:

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

También recomendamos borrar el archivo composer.lock, porque a veces Composer rechaza incomprensiblemente la instalación y esto solucionará el problema.

Digamos que el paquete es nette/utils y la nueva versión es 4.0. Lo instalas con el comando

composer require nette/utils:4.0.x-dev

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

composer require nette/utils:4.0.0-RC2

Si otro paquete depende de la biblioteca y está bloqueado a una versión anterior (por ejemplo ^3.1), lo ideal es actualizar el paquete para que funcione con la nueva versión. Sin embargo, si sólo quieres evitar la limitación y forzar a Composer a instalar la versión de desarrollo y fingir que es una versión anterior (por ejemplo, 3.1.6), puedes utilizar la palabra clave as:

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

Llamada a comandos

Puede llamar a sus propios comandos y scripts personalizados a través de Composer como si fueran comandos nativos de Composer. Los scripts ubicados en la carpeta vendor/bin no necesitan especificar esta carpeta.

Como ejemplo, definimos un script en el archivo composer.json que utiliza Nette Tester para ejecutar pruebas:

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

A continuación, ejecutamos las pruebas con composer tester. Podemos invocar el comando aunque no nos encontremos en la carpeta raíz del proyecto, sino en un subdirectorio.

Enviar Gracias

Te vamos a enseñar un truco que hará felices a los autores de código abierto. Puedes dar fácilmente una estrella en GitHub a las bibliotecas que utiliza tu proyecto. Sólo tienes que instalar la biblioteca symfony/thanks:

composer global require symfony/thanks

Y luego ejecuta

composer thanks

¡Inténtalo!

Configuración

Composer está estrechamente integrado con la herramienta de control de versiones Git. Si no utiliza Git, es necesario indicárselo a Composer:

composer -g config preferred-install dist