Dload Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require internal/dload -W
   

   This adds the vendor/bin/dload CLI tool to your project.

2. Initialize configuration (interactive mode):

   ./vendor/bin/dload init
   

   This generates a dload.xml file in your project root with default tools (e.g., RoadRunner, Temporal).

3. First download:

   ./vendor/bin/dload get
   

   This fetches all configured binaries/PHARs to your project root (or specified extract-path).

First Use Case: Adding RoadRunner

<!-- dload.xml -->
<dload>
    <actions>
        <download software="rr" version="^2025.1.0" />
    </actions>
</dload>

Then run:

./vendor/bin/dload get

Verify with:

./rr --version

Where to Look First (1.19.x)

• Your dload.xml — actions are still the entry point for everything.
• ./vendor/bin/dload software — now also lists software definitions contributed by installed Composer packages (vendor/<pkg>#<id> style entries), so a package you already require may register its own binary without any XML at all.
• Archives (.tgz, .tar) are extractable as of 1.19.0, so "release ships a tarball" is no longer a blocker.

Implementation Patterns

1. Composer Integration (Recommended)

Add to composer.json to auto-download on composer install:

{
    "scripts": {
        "post-update-cmd": "dload get --no-interaction -v || echo 'Failed to download binaries'"
    }
}

Why? Ensures CI/CD and local devs always have consistent tooling.

1.19 tip: if the tool you need ships a dload software definition in its own Composer package, declaring the dependency is enough — dload get picks up registry entries from installed packages. Use <package>#<id> as the software attribute to disambiguate when the same id exists in multiple packages or in the built-in registry.

2. Project-Specific Tooling

Example: Custom PHAR Tool

<!-- dload.xml -->
<dload>
    <registry overwrite="false">
        <software name="MyPharTool" alias="myphar" description="Custom PHAR tool">
            <repository type="github" uri="myorg/myphar" asset-pattern="/^myphar\.phar$/" />
            <binary name="myphar" pattern="/^.*\.phar$/" version-command="--version" />
        </software>
    </registry>
    <actions>
        <download software="myphar" type="phar" extract-path="./tools" />
    </actions>
</dload>

Key Points:

• Use type="phar" to skip extraction (PHARs are self-contained).
• extract-path isolates tools from project files.

3. CI/CD Pipeline

# .github/workflows/download.yml
jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: ./vendor/bin/dload get --no-interaction
      - run: ./rr worker:start

Best Practices:

• Cache ./runtime (DLoad’s temp dir) to avoid re-downloading.
• Use --no-interaction to skip prompts.
• Rely on repository fallback (1.19.0): a repository with an invalid URI or unknown type no longer aborts the whole resolution — the next repository is tried. Log messages containing % are no longer swallowed, so failure output is trustworthy.
• Failed downloads now clean up their partial files, so a cached ./runtime won't poison subsequent runs with truncated binaries.

4. Cross-Platform Teams

<!-- dload.xml -->
<dload>
    <actions>
        <!-- Explicit OS/arch targeting -->
        <download software="rr" arch="arm64" os="darwin" />
        <download software="buf" arch="amd64" os="linux" />
    </actions>
</dload>

Use Case: Force specific binaries for M1 Macs or ARM CI runners.

1.19 improvements: universal macOS binaries and x86-64 microarchitecture levels (x86-64-v2, v3, …) are now ranked when picking an asset, so mixed Intel/M1 fleets usually pick the right build without pinning. Also note that OS packages are not selected when a binary is expected — and DLoad now names the skipped OS packages in the failure report, plus warns when it fell back to an older release.

5. Dynamic Versioning

<download software="temporal"
           version-path="[email protected]/sdk"
           version="^1.0.0" />

How It Works:

• Resolves version-path to a Composer constraint (e.g., "temporal/sdk": "^1.0.0").
• Merges with the explicit version constraint.

1.19 note: constraint parsing was rewritten. Hyphen ranges (1.2.3 - 2.0.0), != / <>, a leading v, constraints with five or more numeric parts, build metadata (+build.5), and numbered pre-releases are all supported now. See Gotchas — ordering is DLoad's own, not Composer's.

6. Archives and Self-Hosted Repositories (new in 1.19.0)

<download software="mycli" type="archive" extract-path="./tools" />

<software name="InternalTool" alias="itool">
    <repository type="gitlab" uri="https://git.internal.example.com/team/itool" />
    <binary name="itool" pattern="/^itool$/" />
</software>

• .tgz and .tar assets are unpacked automatically. If an archive can't be unpacked but a binary is expected, DLoad skips it instead of hard-failing the action.
• Repository URLs are no longer limited to GitHub/GitLab public hosts — self-hosted instances work via an explicit uri.
• Tokens are scoped to the server they belong to, and survive redirects — GitLab tokens are never sent to the GitHub host, so no leaked-credential risk when a project mixes both.

Gotchas and Tips

1. Common Pitfalls

2. Debugging Workflow

1. Inspect available tools (including package-provided ones, and any shadowing warnings):

   ./vendor/bin/dload software
   

2. Dry-run download:

   ./vendor/bin/dload get --dry-run
   

3. Check temp files:

   ls -la ./runtime/
   

4. Validate XML:

   xmllint --schema vendor/internal/dload/dload.xsd dload.xml
   

3. Advanced Tips

A. Custom Registry Merging

<registry overwrite="true">
    <!-- Overrides built-in tools -->
    <software name="rr" alias="rr" version="2025.1.0">
        <repository uri="spatie/roadrunner" asset-pattern="/^roadrunner-.*/" />
    </software>
</registry>

Use Case: Pin a specific fork of a tool.

B. Velox Builds (RoadRunner)

<actions>
    <velox config-file="./velox.toml"
           binary-path="./bin/custom-rr"
           debug="true" />
</actions>

Requirements:

• Go (Golang) installed globally.
• velox.toml generated from roadrunner.dev/build.
• 1.19 refactored Velox config generation onto the shared pipeline — output is unchanged, but custom config plumbing that relied on internal pipeline metadata will break.

C. Rate Limits

• GitHub API: 60 requests/hour (unauthenticated).
• Workaround: Use --cache to reuse downloaded assets. Repository fallback (invalid URI / unknown type) means a misconfigured mirror no longer burns a run.

D. Extending DLoad

1. Add a new tool to the registry: Prefer shipping a software definition inside your own Composer package (1.19.0) over editing vendor/internal/dload/src/Registry/SoftwareRegistry.php. Better: Use inline <registry> in dload.xml, or a Composer-provided definition referenced as <package>#<id>.

2. Custom download handlers: Implement Dload\Contracts\DownloadHandler and bind it in a service provider. The installer was refactored into a readonly step pipeline in 1.19 — handlers that assumed a specific install order or wrote the destination themselves should be revisited.

E. Upgrading from 1.13.x

• Version resolution semantics changed (ordering, pre-releases, build metadata, hyphen ranges). Re-run dload get --dry-run for every configured action after upgrading and pin exact versions if a range now selects a different release.
• Archives are now fetched and unpacked where previously they were skipped or errored — a software entry that "never matched" before may suddenly download something. Review asset-patterns.
• Token handling is stricter (GitLab token only to GitLab, API token only to its own server across redirects). Self-hosted setups that relied on a token leaking across hosts must configure per-repository credentials.