README

Download artifacts easily

DLoad simplifies downloading and managing binary artifacts for your projects. Perfect for development environments that require specific tools like RoadRunner, Temporal, or custom binaries.

Why DLoad?

DLoad solves a common problem in PHP projects: how to distribute and install necessary binary tools and assets alongside your PHP code. With DLoad, you can:

Automatically download required tools during project initialization
Ensure all team members use the same versions of tools
Simplify onboarding by automating environment setup
Manage cross-platform compatibility without manual configuration
Keep binaries and assets separate from your version control

Installation
Quick Start
Command Line Usage
Configuration Guide
Building Custom RoadRunner
Custom Software Registry
- Defining Software
- Software Elements
Use Cases
GitHub API Rate Limits
Contributing

Installation

composer require internal/dload -W

Quick Start

Install DLoad via Composer:
```
composer require internal/dload -W
```

Alternatively, you can download the latest release from GitHub releases.

Create your configuration file interactively:

./vendor/bin/dload init

This command will guide you through selecting software packages and create a dload.xml configuration file. You can also create it manually:

<?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>

Download configured software:
```
./vendor/bin/dload get
```

Integrate with Composer (optional):

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

Command Line Usage

Initialize Configuration

# Create configuration file interactively
./vendor/bin/dload init

# Create configuration in specific location
./vendor/bin/dload init --config=./custom-dload.xml

# Create minimal configuration without prompts
./vendor/bin/dload init --no-interaction

# Overwrite existing configuration without confirmation
./vendor/bin/dload init --overwrite

Download Software

# Download from configuration file
./vendor/bin/dload get

# Download specific packages
./vendor/bin/dload get rr temporal

# Download with options
./vendor/bin/dload get rr --stability=beta --force

Download Options

Option	Description	Default
`--path`	Directory to store binaries	Current directory
`--arch`	Target architecture (amd64, arm64)	System architecture
`--os`	Target OS (linux, darwin, windows)	Current OS
`--stability`	Release stability (stable, beta)	stable
`--config`	Path to configuration file	./dload.xml
`--force`, `-f`	Force download even if binary exists	false

View Software

# List available software packages
./vendor/bin/dload software

# Show downloaded software
./vendor/bin/dload show

# Show specific software details
./vendor/bin/dload show rr

# Show all software (downloaded and available)
./vendor/bin/dload show --all

Build Custom Software

# Build custom software using configuration file
./vendor/bin/dload build

# Build with specific configuration file
./vendor/bin/dload build --config=./custom-dload.xml

Build Options

Option	Description	Default
`--config`	Path to configuration file	./dload.xml

The build command executes build actions defined in your configuration file, such as creating custom RoadRunner binaries with specific plugins. For detailed information about building custom RoadRunner, see the Building Custom RoadRunner section.

Configuration Guide

Interactive Configuration

The easiest way to create a configuration file is using the interactive init command:

./vendor/bin/dload init

This will:

Guide you through selecting software packages
Show available software with descriptions and repositories
Generate a properly formatted dload.xml file with schema validation
Handle existing configuration files gracefully

Manual Configuration

Create dload.xml in your project root:

<?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>

Download Types

DLoad supports three download types that determine how assets are processed:

Type Attribute

<!-- Explicit type specification -->
<download software="psalm" type="phar" />        <!-- Download .phar without unpacking -->
<download software="frontend" type="archive" />  <!-- Force archive extraction -->
<download software="rr" type="binary" />         <!-- Binary-specific processing -->

<!-- Automatic type handling (recommended) -->
<download software="rr" />           <!-- Uses all available handlers -->
<download software="frontend" />     <!-- Smart processing based on software config -->

Default Behavior (No Type Specified)

When type is not specified, DLoad automatically uses all available handlers:

Binary processing: If software has <binary> section, performs binary presence and version checking
Files processing: If software has <file> section and asset is downloaded, processes files during unpacking
Simple download: If no sections exist, downloads asset without unpacking

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

<!-- actions list -->
<!-- Uses both binary and files processing -->
<download software="complex-tool" />

Explicit Type Behaviors

Type	Behavior	Use Case
`binary`	Binary checking, version validation, executable permissions	CLI tools, executables
`phar`	Downloads `.phar` files as executables without unpacking	PHP tools like Psalm, PHPStan
`archive`	Forces unpacking even for .phar files	When you need archive contents

Note

Use type="phar" for PHP tools that should remain as .phar files. Using type="archive" will unpack even .phar archives.

Version Constraints

Use Composer-style version constraints:

<actions>
    <!-- Exact version -->
    <download software="rr" version="2.12.3" />
    
    <!-- Range constraints -->
    <download software="temporal" version="^1.20.0" />
    <download software="dolt" version="~0.50.0" />
    
    <!-- Stability constraints -->
    <download software="tool" version="^1.0.0@beta" />
    
    <!-- Feature releases (automatically sets preview stability) -->
    <download software="experimental" version="^1.0.0-experimental" />
</actions>

Advanced Configuration Options

<dload temp-dir="./runtime">
    <actions>
        <!-- Different extraction paths -->
        <download software="frontend" extract-path="public/assets" />
        <download software="config" extract-path="config" />
        
        <!-- Target different environments -->
        <download software="prod-tool" version="^2.0.0@stable" />
        <download software="dev-tool" version="^2.0.0@beta" />
    </actions>
</dload>

Building Custom RoadRunner

DLoad supports building custom RoadRunner binaries using the Velox build tool. This is useful when you need RoadRunner with custom plugin combinations that aren't available in pre-built releases.

Build Action Configuration

<actions>
    <!-- Basic configuration using local velox.toml -->
    <velox config-file="./velox.toml" />

    <!-- With specific versions -->
    <velox config-file="./velox.toml"
           velox-version="2025.1.1"
           golang-version="^1.22"
           roadrunner-ref="v2025.1.2"
           binary-path="./bin/rr"
           debug="true" />

    <!-- Custom plugins -->
    <velox>
        <plugin name="temporal" />
        <plugin name="kv" />
    </velox>
</actions>

Velox Action Attributes

Attribute	Description
`velox-version`	Version constraint for the Velox build tool to use
`golang-version`	Go version constraint required for building RoadRunner
`roadrunner-ref`	RoadRunner Git reference (tag, commit, or branch) to use as the base for building
`config-file`	Path to base configuration file that may be merged with remote API responses or other sources
`binary-path`	Output path for the built RoadRunner binary. File extension is automatically added based on OS (`.exe` for Windows). Defaults to current working directory
`debug`	Build RoadRunner with debug symbols to profile it with pprof (boolean, defaults to `false`)

Build Process

DLoad automatically handles the build process:

Golang Check: Verifies Go is installed globally (required dependency)
Velox Preparation: Uses Velox from global installation, local download, or downloads automatically if needed
Configuration: Copies your local velox.toml to build directory
Building: Executes vx build command with specified configuration
Installation: Moves built binary to target location and sets executable permissions
Cleanup: Removes temporary build files

Note

DLoad requires Go (Golang) to be installed globally on your system. It does not download or manage Go installations.

Configuration File Generation

You can generate a velox.toml configuration file using the online builder at https://build.roadrunner.dev/

For detailed documentation on Velox configuration options and examples, visit https://docs.roadrunner.dev/docs/customization/build

This web interface helps you select plugins and generates the appropriate configuration for your custom RoadRunner build.

Using Downloaded Velox

You can download Velox as part of your build process instead of relying on a globally installed version:

<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>

This ensures consistent Velox versions across different environments and team members.

DLoad Configuration

<?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>

Building RoadRunner

# Build RoadRunner using velox.toml configuration
./vendor/bin/dload build

# Build with specific configuration file
./vendor/bin/dload build --config=custom-rr.xml

Custom Software Registry

Defining Software

<dload>
    <registry overwrite="false">
        <!-- Binary executable -->
        <software name="RoadRunner" alias="rr" 
                  homepage="https://roadrunner.dev"
                  description="High performance Application server">
            <repository type="github" uri="roadrunner-server/roadrunner" asset-pattern="/^roadrunner-.*/" />
            <binary name="rr" pattern="/^roadrunner-.*/" />
        </software>

        <!-- Archive with files -->
        <software name="frontend" description="Frontend assets">
            <repository type="github" uri="my-org/frontend" asset-pattern="/^artifacts.*/" />
            <file pattern="/^.*\.js$/" />
            <file pattern="/^.*\.css$/" />
        </software>

        <!-- Mixed: binaries + files -->
        <software name="development-suite" description="Complete development tools">
            <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>

        <!-- PHAR tools -->
        <software name="psalm" description="Static analysis tool">
            <repository type="github" uri="vimeo/psalm" />
            <binary name="psalm.phar" pattern="/^psalm\.phar$/" />
        </software>
    </registry>
</dload>

Software Elements

Repository Configuration

type: Currently supports "github"
uri: Repository path (e.g., "username/repo")
asset-pattern: Regex pattern to match release assets

Binary Elements

name: Binary name for reference
pattern: Regex pattern to match binary in assets
Automatically handles OS/architecture filtering

File Elements

pattern: Regex pattern to match files
extract-path: Optional extraction directory
Works on any system (no OS/architecture filtering)

Use Cases

Development Environment Setup

# One-time setup for new developers
composer install
./vendor/bin/dload init  # First time only
./vendor/bin/dload get

New Project Setup

# Start a new project with DLoad
composer init
composer require internal/dload -W
./vendor/bin/dload init
./vendor/bin/dload get

CI/CD Integration

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

Cross-Platform Teams

Each developer gets the correct binaries for their system:

<actions>
    <download software="rr" />        <!-- Linux binary for Linux, Windows .exe for Windows -->
    <download software="temporal" />   <!-- macOS binary for macOS, etc. -->
</actions>

PHAR Tools Management

<actions>
    <!-- Download as executable .phar files -->
    <download software="psalm" type="phar" />
    <download software="phpstan" type="phar" />
    
    <!-- Extract contents instead -->
    <download software="psalm" type="archive" />  <!-- Unpacks psalm.phar -->
</actions>

Frontend Asset Distribution

<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>

GitHub API Rate Limits

Use a personal access token to avoid rate limits:

GITHUB_TOKEN=your_token_here ./vendor/bin/dload get

Add to CI/CD environment variables for automated downloads.

Contributing

Contributions welcome! Submit Pull Requests to:

Add new software to the predefined registry
Improve DLoad functionality
Enhance documentation and translate this on other languages

internal / dload

Maintainers

Details