https://github.com/php-internal/dload
Helps to download binaries from release assets
https://github.com/php-internal/dload
hacktoberfest
Last synced: 5 months ago
JSON representation
Helps to download binaries from release assets
- Host: GitHub
- URL: https://github.com/php-internal/dload
- Owner: php-internal
- License: bsd-3-clause
- Created: 2024-07-17T15:26:38.000Z (almost 2 years ago)
- Default Branch: 1.x
- Last Pushed: 2025-12-17T06:29:55.000Z (7 months ago)
- Last Synced: 2025-12-17T06:35:37.469Z (7 months ago)
- Topics: hacktoberfest
- Language: PHP
- Homepage:
- Size: 1.12 MB
- Stars: 96
- Watchers: 3
- Forks: 3
- Open Issues: 14
-
Metadata Files:
- Readme: README-es.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
Descarga artefactos fácilmente
[](https://boosty.to/roxblnfk)
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.
[](README.md)
[](README-zh.md)
[](README-ru.md)
[](README-es.md)
## ¿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](#instalación)
- [Inicio Rápido](#inicio-rápido)
- [Uso desde Línea de Comandos](#uso-desde-línea-de-comandos)
- [Inicializar Configuración](#inicializar-configuración)
- [Descargar Software](#descargar-software)
- [Ver Software](#ver-software)
- [Construir Software Personalizado](#construir-software-personalizado)
- [Guía de Configuración](#guía-de-configuración)
- [Configuración Interactiva](#configuración-interactiva)
- [Configuración Manual](#configuración-manual)
- [Tipos de Descarga](#tipos-de-descarga)
- [Restricciones de Versión](#restricciones-de-versión)
- [Opciones de Configuración Avanzadas](#opciones-de-configuración-avanzadas)
- [Construir RoadRunner Personalizado](#construir-roadrunner-personalizado)
- [Configuración de Acción de Construcción](#configuración-de-acción-de-construcción)
- [Atributos de Acción Velox](#atributos-de-acción-velox)
- [Proceso de Construcción](#proceso-de-construcción)
- [Generación de Archivo de Configuración](#generación-de-archivo-de-configuración)
- [Usar Velox Descargado](#usar-velox-descargado)
- [Configuración DLoad](#configuración-dload)
- [Construir RoadRunner](#construir-roadrunner)
- [Registro de Software Personalizado](#registro-de-software-personalizado)
- [Definir Software](#definir-software)
- [Elementos de Software](#elementos-de-software)
- [Casos de Uso](#casos-de-uso)
- [Configurar Entorno de Desarrollo](#configurar-entorno-de-desarrollo)
- [Configurar Nuevo Proyecto](#configurar-nuevo-proyecto)
- [Integración CI/CD](#integración-cicd)
- [Equipos Multiplataforma](#equipos-multiplataforma)
- [Gestión de Herramientas PHAR](#gestión-de-herramientas-phar)
- [Distribución de Assets Frontend](#distribución-de-assets-frontend)
- [Límites de Rate de la API](#límites-de-rate-de-la-api)
- [Configuración de Gitlab CI](#configuración-de-gitlab-ci)
- [Contribuir](#contribuir)
## Instalación
```bash
composer require internal/dload -W
```
[](https://packagist.org/packages/internal/dload)
[](https://packagist.org/packages/internal/dload)
[](LICENSE.md)
[](https://packagist.org/packages/internal/dload/stats)
## Inicio Rápido
1. **Instala DLoad usando Composer**:
```bash
composer require internal/dload -W
```
También puedes descargar la versión más reciente desde [GitHub releases](https://github.com/php-internal/dload/releases).
2. **Crea tu archivo de configuración de forma interactiva**:
```bash
./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
```
3. **Descarga el software configurado**:
```bash
./vendor/bin/dload get
```
4. **Integra con Composer** (opcional):
```json
{
"scripts": {
"post-update-cmd": "dload get --no-interaction -v || \"echo can't dload binaries\""
}
}
```
## Uso desde Línea de Comandos
### Inicializar Configuración
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](#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`:
```bash
./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
```
### Tipos de Descarga
DLoad soporta tres tipos de descarga que determinan cómo se procesan los assets:
#### Atributo Type
```xml
```
#### 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 ``, verifica la presencia y versión del binario
- **Procesamiento de archivos**: Si el software tiene una sección `` y el asset se descarga, procesa los archivos durante la extracción
- **Descarga simple**: Si no hay secciones, descarga el asset sin extraer
```xml
```
#### 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:
```xml
```
### Opciones de Configuración Avanzadas
```xml
```
## 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
```xml
```
### 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:
1. **Verificación de Golang**: Verifica que Go esté instalado globalmente (dependencia requerida)
2. **Preparación de Velox**: Usa Velox desde instalación global, descarga local, o lo descarga automáticamente si es necesario
3. **Configuración**: Copia tu archivo velox.toml local al directorio de construcción
4. **Construcción**: Ejecuta el comando `vx build` con la configuración especificada
5. **Instalación**: Mueve el binario construido a la ubicación de destino y establece permisos de ejecución
6. **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:
```xml
```
Esto asegura versiones consistentes de Velox entre diferentes entornos y miembros del equipo.
### Configuración DLoad
```xml
```
### Construir RoadRunner
```bash
# 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
```xml
```
### 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
```bash
# Configuración única para nuevos desarrolladores
composer install
./vendor/bin/dload init # Solo la primera vez
./vendor/bin/dload get
```
### Configurar Nuevo Proyecto
```bash
# 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
```yaml
# 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:
```xml
```
### Gestión de Herramientas PHAR
```xml
```
### Distribución de Assets Frontend
```xml
```
## Límites de Rate de la API
Usa un token de acceso personal para evitar límites de rate:
```bash
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`.
```yaml
# .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](docs/guidelines/how-to-translate-readme-docs.md)