Construir con un archivo de configuración específico

June 28, 2026 · View on GitHub

Descarga artefactos fácilmente

Vibe Index

DLoad simplifica la descarga y gestión de artefactos binarios para tus proyectos. Es perfecto para entornos de desarrollo que necesitan herramientas específicas como RoadRunner, Temporal o binarios personalizados.

¿Por qué DLoad?

DLoad resuelve un problema común en proyectos PHP: cómo distribuir e instalar herramientas binarias y recursos necesarios junto con tu código PHP. Con DLoad puedes:

Descargar automáticamente las herramientas que necesitas durante la configuración inicial del proyecto
Asegurar que todo el equipo use exactamente las mismas versiones de las herramientas
Simplificar la incorporación de nuevos desarrolladores automatizando la configuración del entorno
Manejar compatibilidad multiplataforma sin configuración manual
Mantener binarios y recursos fuera de tu control de versiones

Tabla de Contenidos

Instalación
Inicio Rápido
Uso desde Línea de Comandos
Guía de Configuración
Construir RoadRunner Personalizado
Registro de Software Personalizado
- Definir Software
- Elementos de Software
Casos de Uso
Límites de Rate de la API
Configuración de Gitlab CI
Contribuir

Instalación

composer require internal/dload -W

Inicio Rápido

Instala DLoad usando Composer:
```
composer require internal/dload -W
```

También puedes descargar la versión más reciente desde GitHub releases.

Crea tu archivo de configuración de forma interactiva:

./vendor/bin/dload init

Este comando te ayudará a seleccionar paquetes de software y creará un archivo de configuración dload.xml. También puedes crearlo manualmente:

<?xml version="1.0"?>
<dload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/php-internal/dload/refs/heads/1.x/dload.xsd"
>
   <actions>
       <download software="rr" version="^2025.1.0"/>
       <download software="temporal" version="^1.3"/>
   </actions>
</dload>

Descarga el software configurado:
```
./vendor/bin/dload get
```

Integra con Composer (opcional):

{
    "scripts": {
        "post-update-cmd": "dload get --no-interaction -v || \"echo can't dload binaries\""
    }
}

Uso desde Línea de Comandos

Inicializar Configuración

# Crear archivo de configuración de forma interactiva
./vendor/bin/dload init

# Crear configuración en una ubicación específica
./vendor/bin/dload init --config=./custom-dload.xml

# Crear configuración mínima sin preguntas
./vendor/bin/dload init --no-interaction

# Sobrescribir configuración existente sin confirmación
./vendor/bin/dload init --overwrite

Descargar Software

# Descargar usando el archivo de configuración
./vendor/bin/dload get

# Descargar paquetes específicos
./vendor/bin/dload get rr temporal

# Descargar con versiones específicas
./vendor/bin/dload get rr:2025.1.0 dolt:1.44.1 temporal:1.*@alpha

# Descargar con opciones adicionales
./vendor/bin/dload get rr --stability=beta --force

Opciones de Descarga

Opción	Descripción	Valor por defecto
`--path`	Directorio donde guardar los binarios	Directorio actual
`--arch`	Arquitectura de destino (amd64, arm64)	Arquitectura del sistema
`--os`	Sistema operativo de destino (linux, darwin, windows)	SO actual
`--stability`	Estabilidad del release (stable, beta)	stable
`--config`	Ruta al archivo de configuración	./dload.xml
`--force`, `-f`	Forzar descarga aunque el binario ya exista	false

Ver Software

# Listar paquetes de software disponibles
./vendor/bin/dload software

# Mostrar software descargado
./vendor/bin/dload show

# Mostrar detalles de software específico
./vendor/bin/dload show rr

# Mostrar todo el software (descargado y disponible)
./vendor/bin/dload show --all

Construir Software Personalizado

# Construir software personalizado usando el archivo de configuración
./vendor/bin/dload build

# Construir con un archivo de configuración específico
./vendor/bin/dload build --config=./custom-dload.xml

Opciones de Construcción

Opción	Descripción	Valor por defecto
`--config`	Ruta al archivo de configuración	./dload.xml

El comando build ejecuta las acciones de construcción definidas en tu archivo de configuración, como crear binarios personalizados de RoadRunner con plugins específicos. Para información detallada sobre cómo construir RoadRunner personalizado, consulta la sección Construir RoadRunner Personalizado.

Guía de Configuración

Configuración Interactiva

La forma más sencilla de crear un archivo de configuración es usando el comando interactivo init:

./vendor/bin/dload init

Esto hará lo siguiente:

Te guiará en la selección de paquetes de software
Mostrará software disponible con descripciones y repositorios
Generará un archivo dload.xml bien formateado con validación de esquema
Manejará archivos de configuración existentes de manera elegante

Configuración Manual

Crea dload.xml en la raíz de tu proyecto:

<?xml version="1.0"?>
<dload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/php-internal/dload/refs/heads/1.x/dload.xsd"
       temp-dir="./runtime">
    <actions>
        <download software="rr" version="^2025.1" />
        <download software="temporal" />
        <download software="frontend" extract-path="frontend" />
    </actions>
</dload>

Tipos de Descarga

DLoad soporta tres tipos de descarga que determinan cómo se procesan los assets:

Atributo Type

<!-- Especificación explícita de tipo -->
<download software="psalm" type="phar" />        <!-- Descargar .phar sin extraer -->
<download software="frontend" type="archive" />  <!-- Forzar extracción de archivo -->
<download software="rr" type="binary" />         <!-- Procesamiento específico para binarios -->

<!-- Manejo automático de tipo (recomendado) -->
<download software="rr" />           <!-- Usa todos los manejadores disponibles -->
<download software="frontend" />     <!-- Procesamiento inteligente basado en la config del software -->

Comportamiento por Defecto (Sin Especificar Type)

Cuando no se especifica type, DLoad automáticamente usa todos los manejadores disponibles:

Procesamiento de binarios: Si el software tiene una sección <binary>, verifica la presencia y versión del binario
Procesamiento de archivos: Si el software tiene una sección <file> y el asset se descarga, procesa los archivos durante la extracción
Descarga simple: Si no hay secciones, descarga el asset sin extraer

<!-- lista del registro -->
<software name="complex-tool">
    <binary name="tool" pattern="/^tool-.*/" />
    <file pattern="/^config\..*/" extract-path="config" />
</software>

<!-- lista de acciones -->
<!-- Usa tanto procesamiento de binarios como de archivos -->
<download software="complex-tool" />

Comportamientos de Tipos Explícitos

Tipo	Comportamiento	Caso de Uso
`binary`	Verificación de binarios, validación de versión, permisos de ejecución	Herramientas CLI, ejecutables
`phar`	Descarga archivos `.phar` como ejecutables sin extraer	Herramientas PHP como Psalm, PHPStan
`archive`	Fuerza la extracción incluso para archivos .phar	Cuando necesitas el contenido del archivo

Note

Usa type="phar" para herramientas PHP que deben mantenerse como archivos .phar. Usar type="archive" extraerá incluso archivos .phar.

Restricciones de Versión

Usa restricciones de versión estilo Composer:

<actions>
    <!-- Versión exacta -->
    <download software="rr" version="2.12.3" />
    
    <!-- Restricciones de rango -->
    <download software="temporal" version="^1.20.0" />
    <download software="dolt" version="~0.50.0" />
    
    <!-- Restricciones de estabilidad -->
    <download software="tool" version="^1.0.0@beta" />
    
    <!-- Releases experimentales (automáticamente establece estabilidad preview) -->
    <download software="experimental" version="^1.0.0-experimental" />
</actions>

Opciones de Configuración Avanzadas

<dload temp-dir="./runtime">
    <actions>
        <!-- Diferentes rutas de extracción -->
        <download software="frontend" extract-path="public/assets" />
        <download software="config" extract-path="config" />
        
        <!-- Apuntar a diferentes entornos -->
        <download software="prod-tool" version="^2.0.0@stable" />
        <download software="dev-tool" version="^2.0.0@beta" />
    </actions>
</dload>

Construir RoadRunner Personalizado

DLoad soporta la construcción de binarios personalizados de RoadRunner usando la herramienta Velox. Esto es útil cuando necesitas RoadRunner con combinaciones específicas de plugins que no están disponibles en las versiones pre-construidas.

Configuración de Acción de Construcción

<actions>
    <!-- Configuración básica usando velox.toml local -->
    <velox config-file="./velox.toml" />
    
    <!-- Con versiones específicas -->
    <velox config-file="./velox.toml"
          velox-version="2025.1.1"
          golang-version="^1.22"
          roadrunner-ref="2024.1.5"
          binary-path="./bin/rr"
          debug="true" />
</actions>

Atributos de Acción Velox

Atributo	Descripción
`velox-version`	Restricción de versión para la herramienta de construcción Velox a utilizar
`golang-version`	Restricción de versión de Go requerida para construir RoadRunner
`roadrunner-ref`	Referencia Git de RoadRunner (tag, commit o rama) a usar como base para la construcción
`config-file`	Ruta al archivo de configuración base que puede fusionarse con respuestas de API remotas u otras fuentes
`binary-path`	Ruta de salida para el binario RoadRunner construido. La extensión del archivo se agrega automáticamente según el SO (`.exe` para Windows). Por defecto usa el directorio de trabajo actual
`debug`	Construir RoadRunner con símbolos de depuración para perfilarlo con pprof (booleano, por defecto `false`)

Proceso de Construcción

DLoad maneja automáticamente todo el proceso de construcción:

Verificación de Golang: Verifica que Go esté instalado globalmente (dependencia requerida)
Preparación de Velox: Usa Velox desde instalación global, descarga local, o lo descarga automáticamente si es necesario
Configuración: Copia tu archivo velox.toml local al directorio de construcción
Construcción: Ejecuta el comando vx build con la configuración especificada
Instalación: Mueve el binario construido a la ubicación de destino y establece permisos de ejecución
Limpieza: Elimina archivos temporales de construcción

Note

DLoad requiere que Go (Golang) esté instalado globalmente en tu sistema. No descarga ni gestiona instalaciones de Go.

Generación de Archivo de Configuración

Puedes generar un archivo de configuración velox.toml usando el constructor online en https://build.roadrunner.dev/

Para documentación detallada sobre opciones de configuración de Velox y ejemplos, visita https://docs.roadrunner.dev/docs/customization/build

Esta interfaz web te ayuda a seleccionar plugins y genera la configuración apropiada para tu build personalizado de RoadRunner.

Usar Velox Descargado

Puedes descargar Velox como parte de tu proceso de construcción en lugar de depender de una versión instalada globalmente:

<actions>
    <download software="velox" extract-path="bin" version="2025.1.1" />
    <velox config-file="velox.toml"
          golang-version="^1.22"
          roadrunner-ref="2024.1.5" />
</actions>

Esto asegura versiones consistentes de Velox entre diferentes entornos y miembros del equipo.

Configuración DLoad

<?xml version="1.0"?>
<dload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/php-internal/dload/refs/heads/1.x/dload.xsd">
    <actions>
        <velox config-file="./velox.toml" 
              velox-version="^1.4.0"
              golang-version="^1.22"
              roadrunner-ref="2024.1.5"
              binary-path="./bin/rr" />
    </actions>
</dload>

Construir RoadRunner

# Construir RoadRunner usando la configuración velox.toml
./vendor/bin/dload build

# Construir con un archivo de configuración específico
./vendor/bin/dload build --config=custom-rr.xml

El binario de RoadRunner construido incluirá solo los plugins especificados en tu archivo velox.toml, reduciendo el tamaño del binario y mejorando el rendimiento para tu caso de uso específico.

Registro de Software Personalizado

Definir Software

<dload>
    <registry overwrite="false">
        <!-- Ejecutable binario -->
        <software name="RoadRunner" alias="rr" 
                  homepage="https://roadrunner.dev"
                  description="Servidor de aplicaciones de alto rendimiento">
            <repository type="github" uri="roadrunner-server/roadrunner" asset-pattern="/^roadrunner-.*/" />
            <binary name="rr" pattern="/^roadrunner-.*/" />
        </software>

        <!-- Archive con archivos -->
        <software name="frontend" description="Assets de frontend">
            <repository type="github" uri="my-org/frontend" asset-pattern="/^artifacts.*/" />
            <file pattern="/^.*\.js$/" />
            <file pattern="/^.*\.css$/" />
        </software>

        <!-- Mixto: binarios + archivos -->
        <software name="development-suite" description="Suite completa de herramientas de desarrollo">
            <repository type="github" uri="my-org/dev-tools" />
            <binary name="cli-tool" pattern="/^cli-tool.*/" />
            <file pattern="/^config\.yml$/" extract-path="config" />
            <file pattern="/^templates\/.*/" extract-path="templates" />
        </software>

        <!-- Herramientas PHAR -->
        <software name="psalm" description="Herramienta de análisis estático">
            <repository type="github" uri="vimeo/psalm" />
            <binary name="psalm.phar" pattern="/^psalm\.phar$/" />
        </software>

        <!-- Repositorio GitLab -->
        <software name="My cool project" alias="cool-project"
              homepage="https://gitlab.com/path/to/my/repository"
              description="">
            <repository type="gitlab" uri="path/to/my/repository" asset-pattern="/^cool-.*/" />
            <binary name="cool" pattern="/^cool-.*/" />
        </software>
    </registry>
</dload>

Elementos de Software

Configuración de Repository

type: Actualmente soporta "github"
uri: Ruta del repositorio (ej., "username/repo")
asset-pattern: Patrón regex para hacer match con assets de release

Elementos Binary

name: Nombre del binario para referencia
pattern: Patrón regex para hacer match con el binario en los assets
Maneja automáticamente el filtrado por SO/arquitectura

Elementos File

pattern: Patrón regex para hacer match con archivos
extract-path: Directorio de extracción opcional
Funciona en cualquier sistema (sin filtrado por SO/arquitectura)

Casos de Uso

Configurar Entorno de Desarrollo

# Configuración única para nuevos desarrolladores
composer install
./vendor/bin/dload init  # Solo la primera vez
./vendor/bin/dload get

Configurar Nuevo Proyecto

# Empezar un nuevo proyecto con DLoad
composer init
composer require internal/dload -W
./vendor/bin/dload init
./vendor/bin/dload get

Integración CI/CD

# GitHub Actions
- name: Download tools
  run: GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} ./vendor/bin/dload get

Equipos Multiplataforma

Cada desarrollador obtiene los binarios correctos para su sistema:

<actions>
    <download software="rr" />        <!-- Binario Linux para Linux, .exe de Windows para Windows -->
    <download software="temporal" />   <!-- Binario macOS para macOS, etc. -->
</actions>

Gestión de Herramientas PHAR

<actions>
    <!-- Descargar como archivos .phar ejecutables -->
    <download software="psalm" type="phar" />
    <download software="phpstan" type="phar" />
    
    <!-- Extraer contenido en su lugar -->
    <download software="psalm" type="archive" />  <!-- Extrae psalm.phar -->
</actions>

Distribución de Assets Frontend

<software name="ui-kit">
    <repository type="github" uri="company/ui-components" />
    <file pattern="/^dist\/.*/" extract-path="public/components" />
</software>

<actions>
    <download software="ui-kit" type="archive" />
</actions>

Límites de Rate de la API

Usa un token de acceso personal para evitar límites de rate:

GITHUB_TOKEN=your_token_here ./vendor/bin/dload get
GITLAB_TOKEN=your_token_here ./vendor/bin/dload get

Agrégalo a las variables de entorno CI/CD para descargas automatizadas.

Configuración de Gitlab CI

Al crear un release en Gitlab, asegúrate de subir tus assets a la página del release a través del gestor de paquetes. Esto se puede hacer fácilmente mediante Gitlab CLI y el comando glab release upload --use-package-registry.

# .gitlab-ci.yml

Build artifacts:
  stage: push
  script:
    - mkdir bin
    - echo "Mock binary for darwin arm" > bin/cool-darwin-arm64
    - echo "Mock binary for darwin amd" > bin/cool-darwin-amd64
    - echo "Mock binary for linux arm" > bin/cool-linux-arm64
    - echo "Mock binary for linux amd" > bin/cool-linux-amd64
  artifacts:
    expire_in: 2 hours
    paths:
      - $CI_PROJECT_DIR/bin/cool-*
  rules:
    - if: $CI_COMMIT_TAG

Release artifacts:
    stage: deploy
    image: gitlab/glab:latest
    needs: [ "Build artifacts" ]
    script:
        - glab auth login --job-token $CI_JOB_TOKEN --hostname $CI_SERVER_HOST
        - glab release upload --use-package-registry "$CI_COMMIT_TAG" ./bin/*
    rules:
        - if: $CI_COMMIT_TAG

Contribuir

¡Las contribuciones son bienvenidas! Envía Pull Requests para:

Agregar nuevo software al registro predefinido
Mejorar la funcionalidad de DLoad
Mejorar la documentación y traducirla a otros idiomas