Consejos de uso de Composer
***************************

<div class=perex>

Composer es una herramienta para la gestión de dependencias en PHP. Te permite declarar las librerías de las que depende tu proyecto y las instalará y actualizará por ti. Aprenderemos:

- cómo instalar Composer
- usarlo en un proyecto nuevo o existente

</div>


Instalación .[#toc-installation]
================================

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


Windows .[#toc-windows]
-----------------------

Utilice el instalador oficial [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe].


Linux, macOS .[#toc-linux-macos]
--------------------------------

Todo lo que necesitas son 4 comandos, que puedes copiar de [esta página |https://getcomposer.org/download/].

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

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


Uso en el proyecto .[#toc-use-in-project]
=========================================

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:

```js
{
	"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:

```shell
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:

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

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


Actualizar paquetes a las últimas versiones .[#toc-update-packages-to-the-latest-versions]
==========================================================================================

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:

```shell
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":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff que lo hará por usted:

```shell
php composer-frontline.php
```


Crear nuevo proyecto .[#toc-creating-new-project]
=================================================

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

```shell
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 |nette:troubleshooting#setting-directory-permissions] 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 |#PHP Version].


Versión PHP .[#toc-php-version]
===============================

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:

```shell
composer config platform.php 8.2.3
```

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

```js
{
	"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

```shell
composer require php 8.2.3 --no-update
```

O directamente en el archivo `composer.json`:

```js
{
	"require": {
		"php": "8.2.3"
	}
}
```


Ignorando la versión de PHP .[#toc-ignoring-php-version]
========================================================

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 .[#toc-false-reports]
=====================================

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 .[#toc-packagist-org-global-repository]
==========================================================================

[Packagist |https://packagist.org] 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? .[#toc-what-if-we-don-t-want-the-central-repository]
----------------------------------------------------------------------------------------------

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 |https://getcomposer.org/doc/05-repositories.md#repositories] oficial.


Carga automática .[#toc-autoloading]
====================================

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`:

```js
{
	"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 |robot-loader:], que realiza la misma actividad automáticamente en segundo plano y mucho más rápido.

La segunda opción es seguir [PSR-4 |https://www.php-fig.org/psr/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:

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

Ver [Documentación de Composer |https://getcomposer.org/doc/04-schema.md#psr-4] para saber exactamente cómo configurar este comportamiento.


Probar nuevas versiones .[#toc-testing-new-versions]
====================================================

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:

```js
{
	"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

```shell
composer require nette/utils:4.0.x-dev
```

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

```shell
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`:

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


Llamada a comandos .[#toc-calling-commands]
===========================================

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 |tester:] para ejecutar pruebas:

```js
{
	"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 .[#toc-send-thanks]
==================================

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`:

```shell
composer global require symfony/thanks
```

Y luego ejecuta

```shell
composer thanks
```

¡Inténtalo!


Configuración .[#toc-configuration]
===================================

Composer está estrechamente integrado con la herramienta de control de versiones [Git |https://git-scm.com]. Si no utiliza Git, es necesario indicárselo a Composer:

```shell
composer -g config preferred-install dist
```

{{sitename: Buenas prácticas}}