uniwebsidad

Cómo crear tu propio repositorio de Composer

13 de junio de 2013
programación PHP composer

Satis es un generador estático de repositorios de tipo composer. En otras palabras, es una versión ultra-ligera y ultra-simplificada de Packagist que funciona mediante archivos estáticos. Satis se utiliza para crear repositorios de Composer para los paquetes privados de tu empresa.

Satis es una herramienta gratuita y de software libre, que puedes descargar en github.com/composer/satis o instalarla mediante Composer ejecutando el siguiente comando:

$ composer.phar create-project composer/satis --stability=dev

Configuración

Supongamos que dispones de varios paquetes que quieres utilizar en los proyectos de tu empresa pero que no quieres o no puedes publicarlos libremente. En primer lugar, define la configuración de Satis en un archivo de tipo JSON que puedes llamar como quieras.

En este archivo defines los repositorios donde se encuentran tus paquetes privados, tal y como se explica en el capítulo de repositorios del libro de Composer.

A continuación se muestra un ejemplo de este archivo de configuración, donde se definen tres repositorios de tipo VCS (también puedes definir cualquier otro tipo de repositorio). Después, se define la propiedad "require-all": true para indicar que se deben seleccionar todas las versiones de todos los paquetes que se encuentren en esos repositorios.

The default file Satis looks for is satis.json in the root of the repository.

{
    "name": "Mi Repositorio",
    "homepage": "http://packages.example.org",
    "repositories": [
        { "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
    ],
    "require-all": true
}

Si quieres seleccionar con más precisión los paquetes del repositorio, puedes definir el listado de paquetes utilizando la habitual opción require de Composer. Para cada paquete puedes indicar una versión específica o utilizar el valor "*" para seleccionar todas las versiones disponibles.

{
    "repositories": [
        { "type": "vcs", "url": "http://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" }
    ],
    "require": {
        "company/package": "*",
        "company/package2": "*",
        "company/package3": "2.0.0"
    }
}

Una vez creado el archivo de configuración, ejecuta el siguiente comando para crear el repositorio de paquetes:

$ php bin/satis build <archivo_configuracion> <directorio>

Si ejecutas por ejemplo el comando php bin/satis build config.json web/, Satis lee el archivo de configuración config.json y crea un repositorio estático de paquetes dentro del directorio web/.

Después de ejecutar a mano el comando anterior para comprobar que todo funciona bien, lo normal es que ejecutes este comando mediante una tarea programada en el servidor, de forma que el repositorio de paquetes esté siempre actualizado.

Si los paquetes privados se encuentran alojados en Github, tu servidor tiene que tener la clave SSH que le permita acceder a esos paquetes. Además, tienes que ejecutar el comando con la opción --no-interaction (o -n) para que no te pregunte por la contraseña y así utilice esa clave SSH. Este truco también es muy útil para los servidores de integración continua.

Por último, crea un virtual host en tu servidor web que apunte al directorio web/ anterior y ya dispondrás de tu propio mini-Packagist. Si dispones de PHP 5.4 o superior, puedes incluso utilizar el servidor web que viene incluido con PHP. Para ello, ejecuta el comando php -S localhost:port -t web/.

Usando paquetes privados en tus proyectos

Para utilizar los paquetes privados en tus proyectos, lo único que debes hacer es añadir una línea de configuración indicando la URL de tu repositorio privado. Suponiendo que la URL del repositorio de tu empresa sea packages.example.org, la configuración sería:

{
    "repositories": [
        { "type": "composer", "url": "http://packages.example.org/" }
    ],

    "require": {
        "company/package": "1.2.0",
        "company/package2": "1.5.2",
        "company/package3": "dev-master"
    }
}

Simplemente añadiendo el repositorio en la propiedad repositories de tu archivo composer.json ya tienes acceso a todos los paquetes privados del repositorio creado con Satis. Y como es habitual regenerar con frecuencia el repositorio, tus proyectos tendrán acceso a todos los nuevos paquetes y nuevas versiones sin tener que hacer ningún cambio.

Protegiendo los repositorios privados

Si quieres proteger el acceso a tu repositorio privado, puedes utilizar un certificado para protegerlo con SSH o SSL. Configura los datos de acceso al servidor en la propiedad options del archivo composer.json de tus proyectos.

El siguiente ejemplo muestra cómo configurar el acceso vía SSH, que a su vez requiere disponer de la extensión SSH2 de PHP instalada mediante PECL (ver más opciones de configuración SSH):

{
    "repositories": [
        {
            "type": "composer",
            "url": "ssh2.sftp://example.org",
            "options": {
                "ssh2": {
                    "username": "composer",
                    "pubkey_file": "/home/composer/.ssh/id_rsa.pub",
                    "privkey_file": "/home/composer/.ssh/id_rsa"
                }
            }
        }
    ]
}

Y el siguiente ejemplo muestra la configuración necesaria para acceder a un repositorio a través de SSL con un certificado (ver más opciones de configuración SSL):

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://example.org",
            "options": {
                "ssl": {
                    "local_cert": "/home/composer/.ssl/composer.pem",
                }
            }
        }
    ]
}

Creando paquetes descargables

Cuando Satis crea el repositorio para los paquetes alojados en Github o BitBucket, utiliza la dirección original de descarga de los paquetes. Esto significa que si Github o Bitbucket tienen problemas o están caídos, no podrás instalar ni actualizar tus paquetes privados.

Para hacer que Satis cree paquetes descargables para los repositorios de tipo Git, Mercurial y Subversion, añade la siguiente configuración en el archivo satis.json:

{
    "archive": {
        "directory": "dist",
        "format": "tar",
        "prefix-url": "https://amazing.cdn.example.org",
        "skip-dev": true
    }
}

Cada una de las opciones de configuración se interpreta de la siguiente manera:

  • directory: indica el directorio donde se guardan los paquetes descargables (en este caso, dist/). Este ruta es relativa respecto al directorio indicado en la propiedad output-dir.
  • format: (opcional) formato de los paquetes descargables. Su valor por defecto es zip y el otro valor permitido es tar.
  • prefix-url: (opcional) prefijo que se añade a las URL de los paquetes, lo que permite alojarlos en CDNs y otros servidores especiales.
  • skip-dev: (opcional) su valor por defecto es false. Cuando vale true, Satis no crea paquetes descargables de las ramas de cada repositorio.

La opción prefix-url es muy útil para alojar los paquetes en una CDN o en el servicio Amazon S3. De esta forma puedes reducir drásticamente el tiempo necesario para descargar, y por tanto instalar, los paquetes.

Si por ejemplo la propiedad prefix-url es http://my-bucket.s3.amazonaws.com y la propiedad directory es dist, las URL completas de los paquetes descargables serán del tipo: http://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip.