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

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.

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.

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.

5. Dynamic Versioning

<download software="temporal"
           version-path="composer.json@require.temporal/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.

Gotchas and Tips

1. Common Pitfalls

2. Debugging Workflow

1. Inspect available tools:

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

C. Rate Limits

• GitHub API: 60 requests/hour (unauthenticated).
• Workaround: Use --cache to reuse downloaded assets.

D. Extending DLoad

1. Add a new tool to the registry: Edit vendor/internal/dload/src/Registry/SoftwareRegistry.php (not recommended for production). Better: Use inline <registry> in dload.xml.

2. Custom download handlers: Implement Dload\Contracts\DownloadHandler and bind it in a service provider.