Los archivos binarios de Composer

¿Qué es un archivo binario de Composer?

Los archivos ejecutables o "archivos binarios" de Composer están formados por cualquier script de línea de comandos que el paquete quiera poner a disposición de sus usuarios.

Los scripts que no están pensados para los usuarios del paquete, como por ejemplo scripts de instalación o de compilación del propio paquete, no se consideran archivos binarios de Composer.

Cómo definir un archivo binario

Añade la propiedad bin en el archivo composer.json del proyecto e indica en un array la ruta del archivo binario o las rutas de todos ellos si tu paquete define más de un archivo binario:

{
    "bin": ["bin/my-script", "bin/my-other-script"]
}

La configuración anterior le indica a Composer que debe copiar esos dos archivos ejecutables (llamados comúnmente archivos binarios) en el directorio vendor/bin/ del proyecto.

La idea de los binarios es que los paquetes pongan a disposición del usuario de forma fácil scripts y utilidades que de otra forma estarían "enterrados" dentro de la jerarquía de directorios de vendor/.

Funcionamiento

Cuando tu proyecto define dependencias con paquetes que disponen de archivos binarios, Composer analiza en primer lugar todos los binarios de todas las dependencias. Después, crea un enlace simbólico a cada uno de ellos dentro del directorio vendor/bin.

Imagina que un paquete llamado my-vendor/project-a define los siguientes archivos binarios:

{
    "name": "my-vendor/project-a",
    "bin": ["bin/project-a-bin"]
}

Si ejecutas el comando composer install con este archivo composer.json, los archivos binarios se ignoran y no se crea ningún enlace simbólico. El motivo es que los archivos binarios no se tienen en cuenta cuando se instala el paquete principal.

Si ahora por ejemplo otro paquete llamado my-vendor/project-b declara una dependencia con el paquete my-vendor/project-a anterior:

{
    "name": "my-vendor/project-b",
    "requires": {
        "my-vendor/project-a": "*"
    }
}

Cuando ejecutes ahora el comando composer install con este archivo composer.json, Composer buscará los archivos binarios definidos por las dependencias del paquete project-b y las instalará en el directorio vendor/bin.

De esta forma, el archivo vendor/my-vendor/project-a/bin/project-a-bin se podrá ejecutar simplemente como vendor/bin/project-a-bin. Si tu servidor es de tipo Linux, en vez de copiar los archivos binarios se crean enlaces simbólicos.

¿Qué sucede con los sistemas Windows y los archivos .bat?

Los paquetes gestionados con Composer no tienen que crear archivos de tipo .bat para mantener la compatibilidad con Windows. El motivo es que Composer gestiona la instalación de los archivos binarios en Windows de una forma especial:

• Composer crea un archivo .bat automáticamente para ejecutar el archivo binario en Windows.
• Composer crea un archivo con el mismo nombre que el archivo binario original y similar a los enlaces simbólicos de Linux, por si utilizas Composer a través de herramientas como Cygwin.

Si un paquete tiene requerimientos especiales más allá de los que proporciona Composer, puedes crear tus propios archivos .bat. En este caso, no es necesario que incluyas el archivo .bat como binario en la definición del paquete.

Cómo cambiar el directorio de instalación de los binarios

Composer define dos formas diferentes para modificar el directorio en el que se instalan los archivos binarios:

• Utilizando la propiedad bin-dir del archivo composer.json
• Estableciendo la variable de entorno COMPOSER_BIN_DIR

A continuación se muestra un ejemplo de la primera opción:

{
    "config": {
        "bin-dir": "scripts"
    }
}

Con esta configuración, al ejecutar el comando composer install, los archivos binarios de los paquetes se instalarán en el directorio scripts/ del proyecto, en vez del tradicional directorio vendor/bin/.