Dload Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require internal/dload -W
   

   Add to composer.json scripts for automatic execution:

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

2. First Use Case: Initialize a basic configuration:

   ./vendor/bin/dload init --no-interaction
   

   This creates dload.xml with default RoadRunner and Temporal packages.

3. Immediate Execution: Download dependencies:

   ./vendor/bin/dload get
   

   Binaries will be placed in ./bin/ by default.

Where to Look First

• Configuration File: dload.xml (auto-generated in project root)
• CLI Reference: Run ./vendor/bin/dload for command help
• Software Registry: List available packages with ./vendor/bin/dload software

Implementation Patterns

Core Workflows

1. Project Onboarding

# Initialize with interactive prompts
./vendor/bin/dload init

# Download all configured binaries
./vendor/bin/dload get

# Add to composer scripts for automatic execution
composer require internal/dload -W

2. Version-Specific Downloads

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

3. CI/CD Integration

# .github/workflows/ci.yml
- name: Install dependencies
  run: composer install -n --prefer-dist

- name: Download binaries
  run: ./vendor/bin/dload get --no-interaction --path=./bin

4. Custom Binary Building

<!-- dload.xml -->
<actions>
    <velox config-file="./velox.toml">
        <plugin name="temporal" />
        <plugin name="kv" />
    </velox>
</actions>

Laravel-Specific Patterns

1. Service Provider Integration

// app/Providers/DLoadServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Internal\DLoad\DLoad;

class DLoadServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $dload = new DLoad(config_path('dload.xml'));
        $dload->get(); // Execute during boot

        // Register binaries as Laravel commands
        $this->registerBinaries();
    }

    protected function registerBinaries()
    {
        if (file_exists($rr = base_path('bin/rr'))) {
            $this->app->singleton('roadrunner', function () {
                return new \RoadRunner\RoadRunner($rr);
            });
        }
    }
}

2. Artisan Command Wrapper

// app/Console/Commands/DownloadBinaries.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Internal\DLoad\DLoad;

class DownloadBinaries extends Command
{
    protected $signature = 'binaries:download {--config= : Path to config file}';
    protected $description = 'Download project binaries using DLoad';

    public function handle()
    {
        $config = $this->option('config') ?? config_path('dload.xml');
        $dload = new DLoad($config);

        $this->info("Downloading binaries from {$config}...");
        $dload->get();

        $this->info('Binaries downloaded successfully!');
    }
}

3. Environment Configuration

// config/dload.php
return [
    'path' => env('DLOAD_PATH', base_path('bin')),
    'temp_dir' => storage_path('dload_temp'),
    'default_software' => [
        'rr' => '^2025.1',
        'temporal' => '^1.3',
    ],
];

4. Dynamic Configuration

// In a service or controller
use Internal\DLoad\DLoad;

public function setupEnvironment()
{
    $config = [
        'actions' => [
            'download' => [
                ['software' => 'rr', 'version' => env('RR_VERSION', '^2025.1')],
                ['software' => 'frontend', 'extract-path' => public_path('assets')],
            ],
        ],
    ];

    $dload = new DLoad();
    $dload->setConfig($config);
    $dload->get();
}

Gotchas and Tips

Common Pitfalls

1. Binary Path Conflicts

   • Issue: Binaries may overwrite system paths if placed in /usr/local/bin
   • Fix: Always specify --path or configure temp-dir in XML:

     <dload temp-dir="./runtime">
     

2. Permission Denied

   • Issue: DLoad fails to set executable permissions on Windows
   • Fix: Use --force flag or manually set permissions after download

3. Version Constraint Mismatch

   • Issue: ^1.0.0 may pull unstable releases if no stable version exists
   • Fix: Use explicit versions or add @stable suffix:

     <download software="tool" version="^1.0.0@stable" />
     

4. Missing Go for Velox Builds

   • Issue: velox actions fail with "Go not found"
   • Fix: Install Go globally or use local Velox:

     <velox config-file="./velox.toml" velox-version="2025.1.1" />
     

5. PHAR vs Archive Confusion

   • Issue: Tools like Psalm fail when treated as archives
   • Fix: Explicitly set type="phar":

     <download software="psalm" type="phar" />
     

Debugging Tips

1. Verbose Output

   ./vendor/bin/dload get -vvv
   

2. Dry Run

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

3. Configuration Validation

   ./vendor/bin/dload init --validate
   

4. Manual Download Testing

   $dload = new DLoad();
   $dload->setConfig($config);
   $result = $dload->get(['--verbose' => true]);
   dd($result->getErrors());
   

Extension Points

1. Custom Software Registry Extend the registry by creating a service provider:

   // app/Providers/DLoadRegistryProvider.php
   use Internal\DLoad\Registry\SoftwareRegistry;
   
   class DLoadRegistryProvider extends ServiceProvider
   {
       public function boot()
       {
           $registry = app(SoftwareRegistry::class);
           $registry->addSoftware([
               'name' => 'custom-tool',
               'repository' => 'https://example.com/releases',
               'binary' => ['name' => 'tool', 'pattern' => '/^tool-.*/'],
           ]);
       }
   }
   

2. Pre/Post Download Hooks

   $dload = new DLoad();
   $dload->on('beforeDownload', function ($software) {
       // Add custom logic before download
   });
   
   $dload->on('afterDownload', function ($software, $path) {
       // Modify binary path or permissions
       chmod($path, 0755);
   });
   

3. Custom Download Handlers Implement Internal\DLoad\Handlers\HandlerInterface:

   class CustomHandler implements HandlerInterface
   {
       public function handle(DownloadAction $action, DLoad $dload)
       {
           // Custom download logic
           return new DownloadResult(true, 'Custom handler executed');
       }
   }
   

   Register the handler:

   $dload->addHandler(new CustomHandler(), 'custom');
   

4. Configuration Overrides Use environment variables to override XML settings:

   $dload = new DLoad();
   $dload->setConfigPath(env('DLOAD_CONFIG', config_path('dload.xml')));
   $dload->setTempDir(env('DLOAD_TEMP_DIR', storage_path('dload_temp')));
   

Configuration Quirks

1. XML Schema Validation

   • Always validate your dload.xml:

     ./vendor/bin/dload init --validate
     

   • Common errors:
     • Missing xsi:noNamespaceSchemaLocation
     • Invalid version constraints (e.g., 1.0 without ^ or ~)

2. Path Resolution

   • Relative paths in extract-path are resolved from the download directory
   • Absolute paths override relative resolution

3. Cross-Platform Issues

   • Windows paths use backslashes in XML (escape as \\)
   • Binary extensions (.exe) are auto-added on Windows

4. Rate Limiting