6.3. El tipo de repositorio composer

El principal tipo de repositorio es composer, que utiliza un único archivo llamado packages.json para describir todos los metadatos de los paquetes. Este es el tipo de repositorio que utiliza Packagist.

Para hacer referencia a un repositorio de tipo composer, simplemente indica la ruta del archivo packages.json. En el caso de Packagist, el archivo se encuentra directamente en la ruta /packages.json, por lo que la URL del repositorio es simplemente packagist.org. Si tuvieras un repositorio propio con el archivo en la ruta example.org/packages.json, la URL del repositorio sería example.org.

6.3.1. La propiedad packages

La única propiedad obligatoria es packages y su estructura JSON es la siguiente:

{
    "packages": {
        "vendor/package-name": {
            "dev-master": { @composer.json },
            "1.0.x-dev": { @composer.json },
            "0.0.1": { @composer.json },
            "1.0.0": { @composer.json }
        }
    }
}

El valor @composer.json hace referencia al contenido del archivo composer.json de esa versión del paquete y debe incluir como mínimo las siguientes propiedades:

• name
• version
• dist o source

Este es un ejemplo de la configuración mínima de un paquete:

{
    "name": "smarty/smarty",
    "version": "3.1.7",
    "dist": {
        "url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
        "type": "zip"
    }
}

Este archivo puede definir cualquiera de las propiedades del esquema JSON de Composer explicadas en el capítulo anterior.

6.3.2. La propiedad notify-batch

La propiedad notify-batch indica la URL a la que se realizará una petición cada vez que un usuario instale este paquete. La URL puede ser absoluta (siempre dentro del mismo dominio que el repositorio) o relativa. Ejemplo:

{
    "notify-batch": "/downloads/"
}

Si el repositorio es example.org/packages.json y se descarga el paquete monolog/monolog, el resultado será una petición de tipo POST a la URL example.org/downloads/ con el siguiente contenido:

{
    "downloads": [
        {"name": "monolog/monolog", "version": "1.2.1.0"},
    ]
}

El valor de la propiedad versión es la representación normalizada del número de versión.

Esta propiedad es opcional.

6.3.3. La propiedad includes

Si un repositorio tiene muchos paquetes, es posible dividir los contenidos del archivo packages.json en varios archivos más pequeños. La propiedad fields te permite incluir todos estos archivos individuales para formar el archivo packages.json completo. Ejemplo:

{
    "includes": {
        "packages-2011.json": {
            "sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17"
        },
        "packages-2012-01.json": {
            "sha1": "897cde726f8a3918faf27c803b336da223d400dd"
        },
        "packages-2012-02.json": {
            "sha1": "26f911ad717da26bbcac3f8f435280d13917efa5"
        }
    }
}

El hash SHA-1 permite que el archivo sea cacheado y sólo se vuelva a solicitar si han cambiado sus contenidos.

Eta propiedad es opcional y resulta difícil que la necesites utilizar en tus propios repositorios.

6.3.4. Las propiedades provider-includes y providers-url

En los repositorios que contienen muchos paquetes (como Packagist por ejemplo) es mejor utilizar estas propiedades. La propiedad provider-includes permite definir una serie de archivos que contienen los listados de todos los paquetes que proporciona este repositorio. El hash utilizado en este caso es de tipo SHA 256.

La propiedad providers-url describe cómo encontrar estos archivos en el servidor. Su valor se considera la ruta absoluta respecto a la raíz del repositorio. Ejemplo:

{
    "provider-includes": {
        "providers-a.json": {
            "sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c"
        },
        "providers-b.json": {
            "sha256": "b38372163fac0573053536f5b8ef11b86f804ea8b016d239e706191203f6efac"
        }
    },
    "providers-url": "/p/%package%$%hash%.json"
}

Cada uno de estos archivos contiene un listado de paquetes y hashes para poder verificar su integridad. Ejemplo:

{
    "providers": {
        "acme/foo": {
            "sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82"
        },
        "acme/bar": {
            "sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233"
        }
    }
}

El archivo del ejemplo anterior declara que los paquetes acme/foo y acme/bar se pueden encontrar en este repositorio si se carga el archivo siguendo el formato descrito por la propiead providers-url (reemplazando el valor %name% por el nombre del paquete y el valor %hash% por su hash). El contenido de cada archivo es simplemente la definición de cada paquete, tal y como se describió en las secciones anteriores de este mismo capítulo.

Eta propiedad es opcional y resulta difícil que la necesites utilizar en tus propios repositorios.

6.3.5. Las opciones para el stream

El archivo packages.json se descarga utilizando un stream de PHP. Si añades la propiedad options puedes configurar las opciones de ese stream. Consulta las opciones para streams en el manual oficial de PHP para obtener más información.