Robo Laravel Package

Getting Started

First Steps

1. Installation Add Robo to your project via Composer:

   composer require codegyre/robo --dev
   

   Initialize a basic RoboFile.php in your project root:

   vendor/bin/robo init
   

   This generates a skeleton file with common tasks.

2. First Task Define a simple task in RoboFile.php:

   <?php
   class RoboFile extends \Robo\Tasks
   {
       public function hello()
       {
           $this->yell('Hello, Robo!');
       }
   }
   

   Run it via CLI:

   vendor/bin/robo hello
   

3. Key Files to Explore

   • RoboFile.php: Your primary task definition file.
   • robo.phar: The standalone binary (if using the PHAR version).
   • Robo Documentation: Official docs for advanced usage.

Implementation Patterns

Common Workflows

1. Task Composition Break tasks into reusable subtasks:

   public function deploy()
   {
       $this->taskExec('git pull')
            ->run();
   
       $this->taskComposerInstall()
            ->run();
   
       $this->taskExec('php artisan migrate')
            ->run();
   }
   

2. Argument Handling Use @param annotations for CLI arguments:

   /**
    * @param string $name
    */
   public function backup($name = 'default')
   {
       $this->taskExec("mysqldump -u user -p db_name > backups/{$name}.sql")
            ->run();
   }
   

   Run with:

   vendor/bin/robo backup:custom
   

3. YAML/JSON Configuration Load external configs for flexibility:

   $config = $this->yaml()->load('config/tasks.yml');
   $this->taskExec($config['command'])->run();
   

4. Parallel Execution Run tasks concurrently for speed:

   $this->taskExec('php artisan queue:work')
        ->parallel()
        ->run();
   

5. Integration with Laravel Use Robo for Laravel-specific tasks (e.g., testing, deployments):

   public function test()
   {
       $this->taskExec('php artisan test')
            ->dir(base_path())
            ->run();
   }
   

Integration Tips

• Pre-commit Hooks: Use Robo to run tests/linting via composer.json scripts:

  "scripts": {
      "pre-commit": "robo lint"
  }
  

• CI/CD Pipelines: Trigger Robo tasks in GitHub Actions/GitLab CI:

  - run: vendor/bin/robo deploy:staging
  

• Custom Commands: Alias Robo tasks in composer.json:

  "extra": {
      "robo": {
          "commands": {
              "build": "build:prod"
          }
      }
  }
  

Gotchas and Tips

Pitfalls

1. Task Naming Conflicts Avoid naming tasks the same as existing Robo tasks (e.g., exec, composerInstall). Fix: Use unique names like customExec.

2. Working Directory Issues taskExec runs in the project root by default. Use ->dir() to change context:

   $this->taskExec('npm install')
        ->dir('resources/assets')
        ->run();
   

3. Error Handling Robo tasks fail silently if not wrapped in try/catch:

   try {
       $this->taskExec('failing-command')->run();
   } catch (\Robo\Exception\TaskException $e) {
       $this->yell('Task failed: ' . $e->getMessage());
   }
   

4. PHAR vs. Composer

   • PHAR: Use robo.phar for standalone scripts (e.g., in Docker).
   • Composer: Prefer vendor/bin/robo for project-specific tasks.

5. Dependency Loading Ensure RoboFile.php is autoloaded. Add to composer.json:

   "autoload": {
       "files": ["RoboFile.php"]
   }
   

6. Command Registration Changes (4.0.4+) In versions 4.0.4+, the command registration system has been refactored. If you were previously extending Robo\Runner to customize command registration, update your code to leverage the new Robo class methods:

   // Old approach (pre-4.0.4)
   class CustomRunner extends \Robo\Runner {
       public function registerCommands() { ... }
   }
   
   // New approach (4.0.4+)
   class RoboFile extends \Robo\Tasks {
       public function __construct() {
           parent::__construct();
           $this->registerCustomCommands();
       }
   
       protected function registerCustomCommands() {
           $this->addCommand('custom:task', function () { ... });
       }
   }
   

Debugging Tips

• Verbose Output: Enable debug mode:

  $this->logger()->debug('Debug message');
  

  Or run with:

  vendor/bin/robo --verbose task:name
  

• Dry Runs: Test tasks without execution:

  $this->taskExec('php artisan migrate')->dryRun()->run();
  

• Logging: Use $this->logger() to track task progress:

  $this->logger()->info('Starting deployment...');
  

Extension Points

1. Custom Tasks Extend \Robo\Tasks to add domain-specific tasks:

   class MyTasks extends \Robo\Tasks
   {
       public function myCustomTask() { ... }
   }
   

2. Plugins Use Robo’s plugin system for shared tasks:

   composer require codegyre/robo-plugin-example
   

3. Event Listeners Hook into Robo’s lifecycle (e.g., pre/post-task):

   $this->eventDispatcher()->addListener('robo.task.before', function ($event) { ... });
   

4. PSR-15 Middleware Intercept task execution with middleware:

   $this->taskExec('command')->middleware(MyMiddleware::class)->run();
   

5. PHP 8.2/8.1 Compatibility Leverage new PHP features like named arguments and union types in your tasks:

   public function deploy(string $env = 'production', bool $force = false) { ... }
   

PHP 8.2/8.1 Fixes (4.0.4)

• Named Arguments: Ensure your task methods support named arguments for better readability:

  $this->taskExec('command')->arg('value')->run();
  

• Union Types: Use union types for flexible parameter handling:

  public function backup(string|array $target) { ... }
  

• Attribute Support: Robo 4.0.4+ fully supports PHP 8.2 attributes for task metadata:

  #[Task]
  public function deploy() { ... }