Dload Fetch Tool

Download a GitHub binary or PHAR into a project with dload

The whole task — "I want tool X from GitHub available in this project's folder" — boils down to one decision: does dload already know this tool? If yes, you add one line to dload.xml. If no, you also describe the tool inline in the same file. The artefact can be a native binary or a PHP .phar — both are first-class, they differ only in a couple of fields.

This skill targets consumers of dload — projects that pulled it in via composer require internal/dload. Everything happens in the project's own dload.xml. You never edit anything inside vendor/.

Decision tree

Does `vendor/bin/dload software` list the tool?
├── Yes → add <download software="alias" /> to dload.xml.   (Stop.)
└── No  → describe it inline in dload.xml's <registry>,
         then add <download software="alias" /> referencing it.

If the download fails after that, jump to the Troubleshooting section — it walks the four-stage selection pipeline.

Step 1 — check what dload already knows

./vendor/bin/dload software

This prints every tool baked into dload's built-in registry with its alias and description. If your tool is there, skip to Step 3.

Step 2 — describe a missing tool inline in dload.xml

You teach dload about a new tool by adding a <software> block to the <registry> element of your project's dload.xml. The built-in registry stays untouched; overwrite="false" (the default) merges your entry with what dload already ships.

You need six facts before writing the block:

1. GitHub repo as owner/repo.
2. A real release tag to inspect — any recent one will do.
3. The asset filename matrix — fetch and inspect:

   curl -s https://api.github.com/repos/<owner>/<repo>/releases/tags/<tag> \
     | grep -oE '"name": "[^"]+"'
   

4. Sibling tools in the same release that must be excluded — e.g. bufbuild/buf ships buf-* AND protoc-gen-buf-breaking-* / protoc-gen-buf-lint-*; only buf-* is wanted.
5. The version command — usually --version; some tools use version (no dashes) or have none.
6. Artefact type — native binary (executable for a specific OS/arch) or PHAR (single .phar file, platform-independent).

Designing asset-pattern

This regex filters the release's asset list. dload then runs OS/arch detection on every matching filename to pick the right one for the host — so your regex does not need to encode the platform. It just needs to:

• Match all OS/arch variants of the desired tool.
• Exclude unrelated assets (sibling tools, checksums, signatures, source archives).

Tokens dload's OS/arch matchers recognise (case-insensitive, bounded by _ or word boundary):

Typical asset-pattern shapes:

Designing binary.pattern

This regex matches the executable on disk after the asset is downloaded/extracted. For native binaries, three cases:

When unsure, the broad form (/^<name>(-.*)?(\.exe)?$/) is safe. binary.pattern is optional — drop it when binary.name alone uniquely identifies the file (e.g. a tarball with exactly one tool file).

If the user-facing CLI name differs from the filename (RoadRunner ships as roadrunner, invoked as rr), set binary.name to the short alias and use the pattern to match both.

For PHAR, binary.pattern is usually /^.*\.phar$/ or omitted.

Inline <registry> — native binary

<registry overwrite="false">
    <software name="MyTool" alias="mytool" description="…"
              homepage="https://example.com/">
        <repository type="github" uri="owner/repo" asset-pattern="/^mytool-.*/" />
        <binary name="mytool" pattern="/^mytool(-.*)?(\.exe)?$/" version-command="--version" />
    </software>
</registry>

In XML attributes regex backslashes are literal — write \.exe, not \\.exe.

overwrite="false" (default) merges your entries with the built-in registry. overwrite="true" replaces it — use only when you want exactly that.

Inline <registry> — PHAR

A PHAR is one platform-independent .phar file — no extraction, no OS/arch matching. The shape is the same as a binary entry but simpler:

<software name="Trap" alias="trap" description="…" homepage="https://buggregator.dev/">
    <repository type="github" uri="buggregator/trap" asset-pattern="/^trap\.phar$/" />
    <binary name="trap" pattern="/^.*\.phar$/" version-command="--version" />
</software>

On the <download> side, always set type="phar" so dload skips archive-extraction logic (see Step 3).

Other non-binary assets

Frontend bundles, configs, anything that isn't executable — use the <file> element instead of <binary> in the inline definition, and type="archive" on <download>.

Step 3 — add the <download> action

Wire the tool into your dload.xml:

<?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/main/dload.xsd"
    temp-dir="./runtime"
>
    <actions>
        <download software="buf" />
        <download software="trap" type="phar" version="^1.1" />
    </actions>
    <registry overwrite="false">
        <!-- inline <software> blocks from Step 2, if any -->
    </registry>
</dload>

Useful <download> attributes:

Stability suffixes (@alpha, @beta, @RC, @stable) follow Composer's ordering, with stable as the default.

Step 4 — pick the destination folder

By default dload places the artefact at the project root. To target a specific folder use extract-path on <download>:

<actions>
    <download software="rr" extract-path="./bin" />
    <download software="trap" type="phar" extract-path="./tools" />
</actions>

Same rule for binary and PHAR — extract-path is the literal folder where the file lands. Create the folder ahead of time if your VCS doesn't track empty ones (a .gitkeep is the usual trick), and add the downloaded file itself to .gitignore — only dload.xml belongs in git.

Step 5 — run dload

./vendor/bin/dload get             # process all <download> entries in dload.xml
./vendor/bin/dload get <alias>     # one specific entry

Verify it runs (./bin/rr --version, php ./tools/trap.phar --version) before considering the task done.

Troubleshooting — when dload can't find an asset

Failures almost always belong to one of four stages. Walk them in order — fixing an earlier stage often makes later symptoms disappear.

Stage 1 — release selection

Confirm the tag you expect is actually visible and matches the constraint:

curl -s "https://api.github.com/repos/<owner>/<repo>/releases?per_page=20" \
  | grep -E '"(tag_name|prerelease|draft)"'

• Release is prerelease: true but version demands stable → lower the stability (@beta/@RC/@alpha).
• Release is draft: true → not visible to the API yet.
• version-path resolved an unexpected constraint → echo the resolved value and re-check.

Stage 2 — asset filtering

Fetch the assets for the target tag (command from Step 2) and mentally apply your asset-pattern.

• Pattern not slash-delimited (^... instead of /^.../) → silently fails.
• In XML attributes backslashes are literal — \.exe, not \\.exe.
• Broad pattern accidentally catches sibling tools / checksums / signatures → tighten.

Stage 3 — platform matching

After asset-pattern filters, dload uses these regexes to pick the host's variant:

• OS regex: /(?:\b|_)(windows|linux|darwin|macos|alpine|bsd|freebsd|win32|win64)(?:\b|_)/i
• Arch regex: /(?:\b|_)(amd64|arm64|aarch64|x86_64|x64|win64)(?:\b|_)/i

If neither matches a filtered candidate, it's discarded. Common offenders:

• Non-standard tokens: linux64 (no word boundary before 64), osx, darwin_universal — won't match.
• No arch separator: tool-linux64.tar.gz — OS matches via the trailing boundary but no arch token is extractable.

Stage 4 — binary extraction

After the chosen asset is unpacked into temp-dir, binary.pattern selects the executable.

• Pattern missing → falls back to exact match on binary.name. If the archive nests the binary, add a pattern.
• Pattern over-matches (picks README, LICENSE) → tighten.
• Pattern under-matches → inspect what's actually inside:

  tar -tzf path/to/asset.tar.gz       # or: unzip -l path/to/asset.zip
  

  Then update the pattern. Use /^<name>(-.*)?(\.exe)?$/ for mixed raw-vs-archive distributions.

Triage one-liner

OWNER=bufbuild; REPO=buf; TAG=v1.69.0
echo "=== Assets ==="
curl -s "https://api.github.com/repos/$OWNER/$REPO/releases/tags/$TAG" \
  | grep -oE '"name": "[^"]+"' | sort -u
echo "=== Host ==="
php -r "echo PHP_OS_FAMILY, ' / ', php_uname('m'), PHP_EOL;"

Compare the asset names with the patterns in your registry entry and the OS/arch tokens above.

Reference

• Authoritative XML schema: https://raw.githubusercontent.com/php-internal/dload/refs/heads/main/dload.xsd (also in your vendor/internal/dload/dload.xsd).
• Working example with comments: vendor/internal/dload/dload-example.xml.
• List of built-in tools and aliases: ./vendor/bin/dload software.

Source: php-internal/dload — distributed by TomeVault.