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

Table of Contents

• Installation
• Quick Start
• Command Line Usage
  • Initialize Configuration
  • Download Software
  • View Software
  • Build Custom Software
• Configuration Guide
  • Interactive Configuration
  • Manual Configuration
  • Download Types
  • Version Constraints
  • Advanced Configuration Options
  • Version Registry
• Building Custom RoadRunner
  • Build Action Configuration
  • Velox Action Attributes
  • Build Process
  • Configuration File Generation
  • Using Downloaded Velox
  • DLoad Configuration
  • Building RoadRunner
• Custom Software Registry
  • Defining Software
  • Software Elements
  • Self-Hosted Servers
  • Software from Composer Packages
• Use Cases
  • Development Environment Setup
  • New Project Setup
  • CI/CD Integration
  • Cross-Platform Teams
  • PHAR Tools Management
  • Frontend Asset Distribution
• API Rate Limits
• Failure Reporting
• Gitlab CI configuration
• Contributing

Installation

composer require internal/dload -W

Quick Start

1. Install DLoad via Composer:

   composer require internal/dload -W

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

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

3. Download configured software:

   ./vendor/bin/dload get

4. 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 specific versions and minimum stability
./vendor/bin/dload get rr:2025.* dolt:1.44.1 mago:1.*@alpha

# 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, alpine, darwin, windows, android)	Current OS
--stability	Release stability (stable, beta)	stable
--config	Path to configuration file	./dload.xml
--force, -f	Force download even if binary exists	false
--refresh, -r	Check repositories for new releases even if the version registry is still fresh	false
--quiet, -q	Suppress output; when there is nothing to download, exit with status 0 instead of an error	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	Extracts the matched executable/files, flattened into the destination	CLI tools, executables
phar	Downloads .phar files as executables without unpacking	PHP tools like Psalm, PHPStan
archive	Unpacks the whole asset, preserving its directory structure	Multi-file tools, frontend bundles, docs

Note

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

Note

When a <binary> is configured, with type="binary" or without a type, OS packages (.deb, .rpm, .apk, .snap, .flatpak, .msi, .msix, .msixbundle, .appx, .appxbundle, .nupkg, .dmg, .pkg) are never selected: DLoad cannot unpack them. Neither are archives of a format DLoad cannot unpack — known archive formats other than .zip, .tar.gz, .tgz, .tar, .gz and .phar, such as .tar.xz, .tar.bz2, .zst, .7z or .rar; a file without a known archive extension, like a plain binary or an .AppImage, is still selected. A release that offers only such assets for the host is skipped for an older one, among the 10 newest releases that satisfy the version constraint; pin version to go further back.

Archive Extraction (Preserving Structure)

type="archive" unpacks the entire asset into extract-path, keeping the archive's internal directory layout instead of flattening matched files into a single folder:

• A single top-level directory wrapping the whole archive is stripped, like tar --strip-components=1 (so pkg-1.2.3/bin/app lands as bin/app).
• <file> elements, when present, act as an include filter (matched by file name); omit them to extract everything.
• A <binary>, if configured, is used only to locate the executable inside the extracted tree (for the version check) and to set its executable bit — it is not moved out of its subdirectory.

This is required when files reference each other by relative path — for example a binary that resolves a shared library through an $ORIGIN/../lib rpath. Flattening would break that link; structure-preserving extraction keeps bin/ and lib/ in place relative to each other.

<!-- A self-contained tool: a binary plus its shared library, kept nested under ./runtime -->
<software name="Rapira" alias="rapira" description="PHP application server" homepage="https://rapira.rs/">
    <repository type="github" uri="rapira-rs/rapira" asset-pattern="/^rapira-v.*-linux-.*/" />
    <binary name="rapira" />
</software>

<download software="rapira" type="archive" extract-path="./runtime" />

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" />
    <!-- AND by a space or a comma, OR by ||, hyphen ranges, wildcards, exclusions -->
    <download software="buf" version="^1.28 || ^2.0" />
    <download software="protoc" version="25.0 - 26.1" />
    <download software="mago" version="1.0.*, !=1.0.1" />
    
    <!-- Stability constraints -->
    <download software="tool" version="^1.0.0@beta" />

    <!-- Exact pre-release: only this one, its stability is implied -->
    <download software="rr" version="2025.1.0-rc.2" />
    <!-- From a pre-release on: rc.1, rc.2, the final 2025.1.0 and later 2025.x of RC stability or higher -->
    <download software="rr" version="^2025.1.0-rc.1" />
    
    <!-- Feature releases (automatically sets preview stability) -->
    <download software="experimental" version="^1.0.0-experimental" />
</actions>

A pre-release in a constraint sets the minimum stability for any operator, even for <3.5.0-beta.2; lower it with @alpha or @dev. A keyword without a number is a bound too, as in Composer: >2.0-beta takes 2.0.0-RC1 and 2.0.0. An exact version with a pre-release or another suffix matches only that tag: 2.0-beta takes neither 2.0.0-beta.3 nor 2.0.0, and 2.12.0-hotfix not 2.12.0-hotfix.2. Case does not matter: 1.0.0-arm64 matches the tag 1.0.0-ARM64, and ^1.0-Linux takes 1.0.0-linux. A pre-release may follow the number right away, as in tags: ^2.0.0rc1.

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>

Version Registry

Resolving a version means asking GitHub or GitLab for the repository's release list. DLoad keeps what it learns in a local version registry: a small database of the releases and assets every known repository offers, one JSON file per repository. Versions never expire from it. What expires is the last check of a repository: while the check is younger than cache-ttl, dload get is answered from the registry without a single API request. When it is older, DLoad asks the API only for the releases published since the last check, which is usually one request.

Release pages are still loaded lazily. The first run fetches only as many pages as it takes to find a release that satisfies the requested version, and older releases are fetched later, on demand, when a run actually needs one of them.

The registry is on by default and lives in the per-user cache directory ($XDG_CACHE_HOME/dload, %LOCALAPPDATA%\dload\cache on Windows, ~/.cache/dload otherwise):

<dload temp-dir="./runtime" cache-dir="./runtime/dload-cache" cache-ttl="3600">
    <actions>
        <download software="rr" />
    </actions>
</dload>

Attribute	Environment variable	Default	Meaning
cache-dir	DLOAD_CACHE_DIR	user cache directory	Directory of the version registry.
cache-ttl	DLOAD_CACHE_TTL	600	Seconds the last check of a repository stays valid. 0 disables the registry.

The environment variable takes precedence over the attribute in dload.xml, and the command line option over both.

# Check the repositories for new releases even if the last check is still fresh
./vendor/bin/dload get rr --refresh

# Forget the repositories a software package is served from, or the whole registry
./vendor/bin/dload cache:clear rr
./vendor/bin/dload cache:clear --force

Note

The registry holds release metadata only: tags, names and asset download links. Downloads never go through it and credentials are never stored in it, so the directory can be shared or committed to a CI cache freely. When a check fails because of a network error or a rate limit, the stored releases are used instead, and a repository that was never seen before still fails loudly. A stored release whose assets have disappeared upstream is dropped from the registry as soon as its download fails, and the release list is fetched again before the run gives up. GitHub draft releases are never served; the registry keeps only their tags, as hidden placeholders that hold the position in the listing. A release that a provider inserts below the top of its listing, such as a GitLab release with a backdated released_at, is not noticed by a check; run cache:clear for that software to pick it up.

In GitHub Actions the directory can be carried between workflow runs, so a run spends the rate limit only on releases published since the previous one:

- name: Restore DLoad version registry
  uses: actions/cache@v4
  with:
    path: ./runtime/dload-cache
    key: dload-registry-${{ github.run_id }}
    restore-keys: dload-registry-

- run: ./vendor/bin/dload get
  env:
    DLOAD_CACHE_DIR: ./runtime/dload-cache

The github.run_id in the key makes every workflow run save its registry, while restore-keys lets the next run start from the most recent one. Jobs that run in parallel within one workflow do not see each other's cache, since actions/cache saves it when a job ends.

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:

1. Golang Check: Verifies Go is installed globally (required dependency)
2. Velox Preparation: Uses Velox from global installation, local download, or downloads automatically if needed
3. Configuration: Copies your local velox.toml to build directory
4. Building: Executes vx build command with specified configuration
5. Installation: Moves built binary to target location and sets executable permissions
6. 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>
        
        <!-- GitLab repository -->
        <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>

        <!-- Monorepo with release-please tags like `cli-v1.2.0` -->
        <software name="my-cli" description="CLI component of a monorepo">
            <repository type="github" uri="my-org/monorepo" tag-prefix="cli-" asset-pattern="/^cli-.*/" />
            <binary name="cli" pattern="/^cli-.*/" />
        </software>
    </registry>
</dload>

Software Elements

Repository Configuration

• type: "github" or "gitlab"
• uri: Repository path (e.g., "username/repo"), or its URL on a self-hosted server, see Self-Hosted Servers
• asset-pattern: Regex pattern to match release assets
• tag-prefix: Text before the version in release tags, e.g. bun- for bun-v1.4.2. Releases with other tags are ignored, so only the selected component of a monorepo with per-component tags (release-please) is used

Binary Elements

• name: Binary name for reference; a file name, not a path
• pattern: Regex pattern to match binary in assets
• version-command: Arguments that make the binary print its version, e.g. --version; without it the version is not checked. They are passed to the binary as they are, without a shell: quotes and pipes are not interpreted. In entries of Composer packages it is one option such as --version, or version
• Automatically handles OS/architecture filtering

File Elements

• pattern: Regex pattern to match files
• rename: Optional new name of the matched file, a file name, not a path. The extension of the matched file is appended unless the new name already ends with it
• extract-path: Optional extraction directory
• Works on any system (no OS/architecture filtering)

Self-Hosted Servers

A repository on GitHub Enterprise Server, a self-hosted GitLab or any other on-premise instance is given by its URL in uri, instead of a path on github.com / gitlab.com:

<registry>
    <software name="Tool" alias="tool">
        <repository type="github" uri="https://ghe.example.com/my-org/tool" />
    </software>
    <software name="Other" alias="other">
        <repository type="gitlab" uri="https://gitlab.example.com:8443/group/subgroup/other" />
    </software>
</registry>

• The scheme, host and port of the URL are the server, the path is the repository: owner/repo for GitHub, the full project path with subgroups for GitLab. A trailing / and a .git suffix are ignored, so a clone URL works too. A URL of a page inside the repository (/releases, /-/tags) is an error.
• The scheme is required: ghe.example.com/my-org/tool is not a URL, and dload never takes a server from it.
• A URL of the public host (https://github.com/owner/repo, https://gitlab.com/group/project) means the public host, as does a plain path.
• The API lives at {server}/api/v3 for GitHub Enterprise Server and at {server}/api/v4 for GitLab. A GitLab installed under a relative URL root (https://example.com/gitlab/...) is not supported.

A token is declared per server in an environment variable named after it: DLOAD_TOKEN_ followed by the host in upper case, where a dot becomes _ and a hyphen __; a port other than the default follows after ___. An IPv6 address starts with _ and lists all eight groups. Each server gets a name of its own, so ghe.example.com and ghe-example.com never share a token. The scheme is not a part of the name.

Server	Token variable
github.com	DLOAD_TOKEN_GITHUB_COM, then GITHUB_TOKEN
gitlab.com	DLOAD_TOKEN_GITLAB_COM, then GITLAB_TOKEN
ghe.example.com	DLOAD_TOKEN_GHE_EXAMPLE_COM
git-lab.example.com	DLOAD_TOKEN_GIT__LAB_EXAMPLE_COM
gitlab.example.com:8443	DLOAD_TOKEN_GITLAB_EXAMPLE_COM___8443
http://[::1]:8080	DLOAD_TOKEN__0_0_0_0_0_0_0_1___8080

DLOAD_TOKEN_GHE_EXAMPLE_COM=your_token_here ./vendor/bin/dload get

The configuration cannot choose which variable is read, so a dload.xml from a third party cannot send your tokens anywhere. GITHUB_TOKEN and GITLAB_TOKEN are never sent to a self-hosted server, and a server's token goes only to that exact scheme, host and port, and is dropped when the server redirects elsewhere.

Plain http is allowed, e.g. for a local fake API in tests (uri="http://127.0.0.1:8080/owner/repo"), but a token is sent over it only to localhost, 127.0.0.0/8 and [::1].

Software from Composer Packages

A framework or a CMS can ship the definitions of the binaries it needs, so the projects that use it do not copy them into their dload.xml. The package points to an XML file inside it in its composer.json:

{
    "extra": {
        "dload": {
            "registry": "resources/dload.xml"
        }
    }
}

The file has the dload.xml format, so the IDE completes and validates it; only its <registry> section is read. It can be a dedicated file or the package's own dload.xml. Keep it in the package dist: do not export-ignore it.

<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">
    <registry>
        <software name="GitHub CLI" alias="gh">
            <repository type="github" uri="cli/cli" asset-pattern="/^gh_.*/" />
            <binary name="gh" pattern="/^gh(\.exe)?$/" />
        </software>
    </registry>
</dload>

DLoad finds composer.json next to the loaded dload.xml (the working directory without one) and reads the installed packages from vendor/composer/installed.json (COMPOSER_VENDOR_DIR and config.vendor-dir are honoured, Composer 2 only). It works the same for the Composer package, the PHAR and the binary.

• Who can declare: the root package and its direct dependencies (require, require-dev). A transitive dependency cannot add software.
• Where the file can be: only inside the package. A path that leads out of it, through .., an absolute path or a symlink, is rejected. Remote files are not supported.
• Priority: dload.xml > the official registry > packages. A package never replaces an entry of the other two; when the official registry shadows a package entry that is being downloaded and points to other repositories, DLoad warns about it.
• Explicit choice: <package>#<id> picks the entry of a package, whatever shadows it (__root__#<id> for a root package without a name): dload get acme/framework#gh:^2.0 or <download software="acme/framework#gh" />.
• Several packages, one id: packages pointing to the same repositories agree, nothing to report. Otherwise the root package wins, then the packages in the order of require and require-dev, and a download of that id prints every <package>#<id> to choose from.
• Broken declarations are reported as warnings and skipped; they never stop DLoad. That covers a missing file, an invalid XML, a required attribute left empty, a path where a file name is expected, an invalid regex, a version-command other than one option such as --version, or version, and an id with #, : or spaces around it.
• Switching off: <registry from-packages="false"> drops the software of packages and keeps the official registry; <registry overwrite="true"> drops both.

dload software shows where each entry comes from: official, dload.xml or the package name. An entry that hides others lists them under Shadows:, package ones as <package>#<id>; dload show <id> prints the origin as Source:.

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>

API Rate Limits

Use a personal access token to avoid rate limits:

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

Add to CI/CD environment variables for automated downloads.

DLOAD_TOKEN_GITHUB_COM and DLOAD_TOKEN_GITLAB_COM take precedence over GITHUB_TOKEN and GITLAB_TOKEN, which helps when those names are already taken by another tool. Self-hosted servers have their own variables, see Self-Hosted Servers.

Note

In GitHub Actions, secrets.GITHUB_TOKEN is scoped to the current repository and shares a limit of 1,000 requests per hour across all jobs of the repository. With a large job matrix the limit may run out, and downloads from other repositories may be rejected. Use a personal access token if that happens.

Release lists are also kept in a local version registry, so repeated runs and runs that carry the registry between them spend the rate limit only on new releases: see Version Registry.

Failure Reporting

dload get exits with a non-zero code when at least one requested package was not installed, and prints the reason for every failed download: the API error (invalid token, exhausted rate limit, missing repository), the number of matched releases, the assets each checked release contains, and the filters that rejected them.

When a software entry lists several <repository> elements, a failed repository (API error, no suitable release or asset, invalid uri or unknown type) is reported and DLoad moves on to the next one.

 Failed to download `rr` 
Requested: version `any`, OS `linux`, architecture `amd64`, minimum stability `stable`, asset type `any`.
Tried 1 repository(ies):
  1) github `roadrunner-server/roadrunner`
    GitHub API rejected the credentials (HTTP 401: Bad credentials).
    The API token from the GITHUB_TOKEN environment variable is invalid, expired or revoked. Provide a valid
    token or unset the variable to use anonymous access.

1 of 1 download(s) failed.

Run with -vvv to also get stack traces and the full request log.

Gitlab CI configuration

When you make a release in Gitlab, make sure to upload your assets to the release page via package manager. This can easily be done via Gitlab CLI and the glab release upload --use-package-registry command.

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

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