Ver índice de contenidos del libro

5.3. Las propiedades básicas del archivo composer.json

5.3.1. La propiedad name

Establece el nombre del paquete, formado por una primera parte que hace referencia a su creador y una segunda parte que describe el nombre del proyecto. Las dos partes tienen que estar separadas por el carácter /. Ejemplos:

  • monolog/monolog
  • igorw/event-source

Esta propiedad es obligatoria para los paquetes publicados como librerías instalables por terceros.

5.3.2. La propiedad description

Se emplea para definir brevemente el propósito del paquete. Suele ser suficiente con una descripción de una sola línea.

Esta propiedad es obligatoria para los paquetes publicados como librerías instalables por terceros.

5.3.3. La propiedad version

Indica la versión del paquete, siguiendo la notación X.Y.Z y añadiendo opcionalmente un uno de estos sufijos: -dev, -alphaN, -betaN o -RCN. Ejemplos:

  • 1.0.0
  • 1.0.2
  • 1.1.0
  • 0.2.5
  • 1.0.0-dev
  • 1.0.0-alpha3
  • 1.0.0-beta2
  • 1.0.0-RC5

Esta propiedad es opcional si la versión se puede inferir a partir de la información del repositorio de código, como por ejemplo con el nombre de una etiqueta. En estos casos, no sólo la propiedad es opcional sino que se recomienda no establecerla a mano.

Nota Packagist también utiliza repositorios de código, por lo que la frase anterior también se puede aplicar a Packagist. Establecer la versión a mano seguramente acabará generando problemas en un futuro próximo cuando te equivoques al cambiar el número de versión.

5.3.4. La propiedad type

Indica el tipo de paquete, que por defecto se establece a library.

El valor de esta propiedad se utiliza para adaptar la lógica de instalación del paquete. Si tienes un paquete que requiere de una lógica muy concreta para su instalación, puedes incluso crear tu propio tipo de paquete. Un ejemplo de este caso sería la creación del tipo symfony-bundle para los bundles de Symfony, el tipo wordpress-plugin para los plugins de WordPress o el tipo typo3-module para los módulos de Typo3. El problema es que estos tipos de paquete propios sólo funcionan en los proyectos que los han definido. Por lo tanto, será necesario incluir también un instalador capaz de instalar esos tipos propios.

Composer soporta por defecto los siguientes cuatro tipos:

  • library: este es el tipo por defecto y simplemente copia los archivos en el directorio vendor/.
  • project: este tipo es adecuado para aplicaciones enteras como la edición estándar de Symfony, gestores de contenidos como el instalador de SilverStripe y otro tipo de aplicaciones completas distribuidas como paquetes. Este tipo de paquetes los pueden usar por ejemplo los IDEs para listar todos los tipos de proyectos que pueden crear al iniciar un nuevo proyecto.
  • metapackage: se trata de un paquete vacío que contiene una lista de dependencias que se instalarán, pero que no contiene ningún archivo y no escribe nada en el sistema de archivos. No requiere ni la opción dist ni la opción source para poder instalarse.
  • composer-installer: los paquetes de este tipo proporcionan el instalador necesario para instalar otros paquetes. Consulta el artículo Los instaladores propios de Composer para obtener más información.

Crea un tipo de paquete propio solamente si necesitas ejecutar cierta lógica compleja al instalar ese paquete. La recomendación es no definir esta propiedad y dejar que se utilice su valor por defecto library.

5.3.5. La propiedad keywords

Se trata de un array de palabras clave o etiquetas con las que el paquete está relacionado. Esta propiedad es útil cuando se buscan y filtran paquetes. Ejemplos:

  • logging
  • events
  • database
  • redis
  • templating

Esta propiedad es opcional.

5.3.6. La propiedad homepage

Establece la URL del sitio web oficial del paquete.

Esta propiedad es opcional.

5.3.7. La propiedad time

Indica la fecha en la que se publicó esta versión. Su formato debe ser YYYY-MM-DD o YYYY-MM-DD HH:MM:SS.

Esta propiedad es opcional.

5.3.8. La propiedad license

Indica la licencia bajo la que se publica el paquete. Su formato es o bien una cadena de texto o bien un array de cadenas de texto. A continuación se muestra la notación recomendada para las licencias más utilizadas (por orden alfabético):

  • Apache-2.0
  • BSD-2-Clause
  • BSD-3-Clause
  • BSD-4-Clause
  • GPL-2.0
  • GPL-2.0+
  • GPL-3.0
  • GPL-3.0+
  • LGPL-2.1
  • LGPL-2.1+
  • LGPL-3.0
  • LGPL-3.0+
  • MIT

Aunque esta propiedad es opcional, se recomienda incluirla. Si la licencia que utilizas no está en la lista anterior, puedes encontrar la tuya en el SPDX Open Source License Registry. Si tu proyecto no es de código abierto, utilizar el valor "proprietary" como identificador de la licencia.

Ejemplo de licencia de paquete:

{
    "license": "MIT"
}

Si un paquete se distribuye con varias licencias a elegir (lo que se conoce como licencia disyuntiva), indica todas ellas mediante un array. Un ejemplo de paquete con varias licencias disyuntivas:

{
    "license": [
       "LGPL-2.1",
       "GPL-3.0+"
    ]
}

También puedes indicarlas entre paréntesis y separadas por el operador or:

{
    "license": "(LGPL-2.1 or GPL-3.0+)"
}

Si el paquete se distribuye bajo varias licencias a la vez (lo que se conoce como licencia conjuntiva) puedes indicarlas todas ellas entre paréntesis y separadas con el operador and.

5.3.9. La propiedad authors

Indica el autor o autores del paquete. El formato de esta propiedad es el de array de objetos JSON. Cada uno de los autores puede definir las siguientes cuatro propiedades:

  • name: el nombre del autor (normalmente su nombre y apellidos reales).
  • email: la dirección de email del autor.
  • homepage: la URL del sitio web personal del autor.
  • role: la responsabilidad de este autor dentro del proyecto (por ejemplo, developer, translator, etc.)

An example:

{
    "authors": [
        {
            "name": "Nils Adermann",
            "email": "[email protected]",
            "homepage": "http://www.naderman.de",
            "role": "Developer"
        },
        {
            "name": "Jordi Boggiano",
            "email": "[email protected]",
            "homepage": "http://seld.be",
            "role": "Developer"
        }
    ]
}

Esta propiedad es opcional, pero se recomienda establecerla.

5.3.10. La propiedad support

Indica las diferentes formas en las que los usuarios pueden obtener soporte. La información de soporte puede incluir las siguientes propiedades:

  • email: dirección de email en la que solicitar soporte.
  • issues: URL del gestor de errores del proyecto.
  • forum: URL del foro de soporte.
  • wiki: URL de la wiki principal del proyecto.
  • irc: canal IRC de soporte, como por ejemplo irc://server/channel.
  • source: URL donde ver o descargar el código fuente.

Ejemplo de esta propiedad:

{
    "support": {
        "email": "[email protected]",
        "irc": "irc://irc.freenode.org/composer"
    }
}

Esta propiedad es opcional.