Robo Config Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require nuvoleweb/robo-config
   

2. Add Trait to RoboFile.php:

   use NuvoleWeb\Robo\Task\Config\loadTasks;
   

3. Create Configuration Files:

   • Default config: robo.yml.dist
   • Local overrides: robo.yml (optional)
   • Example robo.yml.dist:

     site:
       name: "Default Site"
       url: "http://localhost"
     

4. Access Config in Robo:

   $siteName = $this->config('site.name');
   

First Use Case

Run a command with CLI overrides:

./vendor/bin/robo my-task -o "site.url: http://example.com"

Verify config resolution:

// In RoboFile.php
public function myTask() {
    $url = $this->config('site.url'); // Resolves to "http://example.com"
    $this->say("Site URL: {$url}");
}

Implementation Patterns

Configuration Workflows

1. Hierarchical Overrides:

   • Defaults in robo.yml.dist → Local overrides in robo.yml → CLI overrides (-o flag).
   • Example:

     # robo.yml.dist
     database:
       host: "localhost"
     

     # robo.yml (local)
     database:
       host: "127.0.0.1"
     

     ./vendor/bin/robo db:backup -o "database.host: db.example.com"
     

2. Dynamic References: Use !property.path syntax to reference other config values:

   # robo.yml.dist
   app:
     name: "MyApp"
     version: "1.0"
   build:
     version: !app.version
   

3. Environment-Specific Configs:

   • Use robo.yml for local dev, robo.yml.prod for production (load via CLI or script).
   • Example CLI load:

     ./vendor/bin/robo deploy -c robo.yml.prod
     

Integration Tips

1. PHP Config Generation: Convert YAML snippets to PHP arrays for frameworks like Drupal/Silex:

   $this->taskWriteConfiguration('config.php', 'settings')
        ->setConfigKey('config')
        ->run();
   

2. Task Dependencies: Pass resolved config to other tasks:

   $this->taskComposerInstall()
        ->option('no-dev', $this->config('install.no_dev'))
        ->run();
   

3. Validation: Add custom validation in RoboFile.php:

   public function validateConfig() {
       if (empty($this->config('site.url'))) {
           throw new \RuntimeException("Site URL is required!");
       }
   }
   

4. Modular Configs: Split configs into multiple files (e.g., robo.db.yml, robo.api.yml) and merge them:

   $this->config->merge('robo.db.yml');
   

Gotchas and Tips

Pitfalls

1. File Priority:

   • robo.yml overrides robo.yml.dist only if it exists. Ensure robo.yml is committed to version control if shared configs are needed.
   • CLI overrides (-o) always take precedence.

2. Circular References: Avoid infinite loops with !property.path:

   # ❌ Invalid (circular)
   a: !b.value
   b:
     value: !a
   

3. PHP Config Conflicts:

   • Appending/prepending to existing PHP files may cause syntax errors if the file already contains PHP code. Use taskWriteConfiguration for new files or validate content first.

4. Case Sensitivity: Config keys are case-sensitive in YAML. Ensure consistency:

   # ❌ Fails
   site.Name: "Test"  # Won't resolve $this->config('site.name')
   

Debugging

1. Dump Config:

   $this->say("Full config:\n" . print_r($this->config->all(), true));
   

2. Validate YAML: Use robo.yml.dist as a template and validate with:

   ./vendor/bin/robo config:validate
   

3. CLI Override Debugging: Verify overrides with:

   ./vendor/bin/robo --help  # Shows supported -o flags
   

Tips

1. Environment Variables: Combine with vlucas/phpdotenv for env vars:

   $this->config->set('db.host', getenv('DB_HOST'));
   

2. Default Values: Use config('key', 'default'):

   $timeout = $this->config('http.timeout', 30);
   

3. Custom Tasks: Extend the config system for project-specific needs:

   use NuvoleWeb\Robo\Task\Config\ConfigAwareTrait;
   
   class MyTask extends \Robo\Tasks {
       use ConfigAwareTrait;
   
       public function run() {
           $this->say("Using config: " . $this->config('my.key'));
       }
   }
   

4. CI/CD Integration:

   • Use -o flags to tweak configs in pipelines (e.g., -o "deploy.env: production").
   • Example GitHub Actions:

     - run: ./vendor/bin/robo deploy -o "deploy.target: staging"
     

5. Performance: Cache resolved configs in long-running processes:

   $this->config->cache(true); // Disable auto-reload