Publicar un componente PHP con Composer

Posted by victor on May 26th, 2013
composer-logoCuando terminamos un componente/librería PHP pasamos a la fase de publicación y publicar es algo más que exponer el código bajo una licencia (libre o no); Consiste, además, en proveer el todas las facilidades posibles para que los desarrolladores la adopten y en los tiempos actuales y en el mundo PHP todo funciona con Composer. Composer es un gestor de dependencias, es decir, una aplicación que se encarga de obtener las librerías de las que depende un proyecto. Todas estas dependencias quedan descritas en un sencillo fichero llamado composer.json. Para nuestro caso, escribiremos un composer.json que describirá a nuestro componente (nombre, autor, descripción etc...) e indicaremos la las dependencias (si las tiene) y la versión de PHP que necesita.

Estructura básica de composer.json

Como ejemplo, el composer.json del componente Yosymfony/TOML:
{
    "name": "yosymfony/toml",
    "description": "A PHP parser for TOML compatible with TOML v0.1.0",
    "type": "library",
    "keywords": ["toml","parser"],
    "homepage": "http://github.com/yosymfony/toml",
    "license": "MIT",
    "authors": [
	{
		"name": "Victor Puertas",
		"email": "vpgugr@gmail.com",
		"homepage": "http://yosymfony.com"
	}
    ],
    "require": {
	"php": ">=5.3.0"
    },
    "autoload": {
	"psr-0": {
		"Yosymfony\\Toml": "src/"
	}
    }
}
name: Nombre del componente. Se usa el siguiente patrón "vendor/nombre proyecto". Vendor podría ser la entidad/organización o usuario que crea el componente. description: Breve descripción del componente (no más de una línea). type: Información del tipo de componente. El valor por defecto es library. Otros valores muy usados son los siguientes:
  • project: Indica que se trata de un proyecto y no de una librería. Este tipo puede ser útil para que los IDEs carguen el entorno en función del tipo de proyecto: Symfony, Drupal etc...
  • metapackage: Es un paquete especial que hace referencia a otros paquetes, es decir, permite agrupar un conjunto de librerías bajo un mismo nombre.
  • composer-installer: Este es un tipo que se suele emplear cuando requerimos de instalaciones especiales.
En realidad, en el campo type se puede emplear cualquier cadena de  texto como symfony-bundle, wordpress-plugin o cualquier otro nombre identificativo ya que su principal utilidad se produce cuando nuestro componente/librería requiere de un instalador especial que podemos crear para personalizar las acciones que se llevan a cabo durante este proceso. keywords: (opcional) Array de palabras clave que definen al componente. Se emplea en búsquedas y filtrados de contenido. homepage: (opcional) URL de la página web del componente o proyecto. license: (opcional) Nombre de la licencia bajo la que se publica el componente. Puede ser una cadena de texto o un array de las mismas. Aunque esta propiedad es opcional, es muy recomendable usarla ya que la licencia no es un tema de menor importancia. La notación recomendada para las principales licencias es la siguiente: Apache-2.0, BSD-2-Clause, BSD-3-Clause, BSD-4-Clause, LGPL-3.0, LGPL-3.0+, MIT. Puedes encontrar el identificador de todas las licencias libres spdx.org. En caso de desarrollar software propietario, puedes usar el identificador proprietary. En ocasiones, el código lo publicamos bajo los términos de más de una licencia como LGPL y GPL. En este caso, detallamos las licencias como array:
{
    "license": [
       "LGPL-2.1",
       "GPL-3.0+"
    ]
}
También puedes usar esta notación alternativa para definirlas en un solo string:
{
    "license": "(LGPL-2.1 or GPL-3.0+)" // Más humano. También se puede emplear "and"
}
authors: Información acerca de los autores del componente. Es un array de objetos en el que cada uno puede contener las siguientes propiedades:
  • name: nombre del autor.
  • email: dirección email del autor.
  • homepage: página web del autor: blog, github etc...
  • role: rol desempeñado en el proyecto: developer, translator etc...
require: Esta es una de las propiedades más importantes ya que indica el nombre y la versión de componentes que necesita nuestra librería para funcionar. Si no se cumplen todas los requisitos, no se instalará nuestro componente:
{
    "require": {
        "php": ">=5.3.0",
        "monolog/monolog": "1.0.*" // Nuestro componente requiere de Monolog 1.0.x
    }
}
Existe otra propiedad llamada require-dev que describe dependencias para el entorno de desarrollo. Muy útil para realizar unit-tests. Require tiene varias formas de expresar la versión necesaria de un componente así como el nivel mínimo de estabilidad. Lo mejor es visitar la documentación en Composer. autoload: Establece información sobre la carga automática de clases. Lo más aconsejable es desarrollar nuestra librería siguiendo el estándar PSR-0 que establece una relación entre la estructura de directorios y los namespaces de nuestras clases.
{
    "autoload": {
        "psr-0": {
            "Yosymfony\\Toml": "src/",
            "Vendor\\Namespace\\": "src/",
            "Vendor_Namespace_": "src/"
        }
    }
}
El primer elemento de psr-0 indica que el namespace Yosymfony\Toml debe comenzar a resolverse a partir del directorio src. Si no quieres usar PSR-0, Composer admite otros métodos como Classmap o files aunque no es lo más recomendado.

Usar el componente en un proyecto o librería

Para usarlo, simplemente debemos incluirlo como dependencia:
"require": {
    "yosymfony/toml": "dev-master"
}
Esta es la forma más sencilla de incluir una dependencia y para usarla debemos registrar nuestro componente en packagist.org. Packagist es un servicio creado por los autores de Composer que establece la relación entre el nombre del componente, en este caso yosymfony/toml, y el código fuente alojado en un repositorio tipo Git, SVN o Hg que sea accedido mediante URL (con Github lo tienes muy fácil). Si no quieres usar packagist como repositorio, podes crear los tuyos.

Comments

comments powered by Disqus