Framework Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel-zero/framework
   

   For a new project, use the installer:

   composer create-project laravel-zero/laravel-zero my-cli-app
   

2. First Command: Create a command in app/Console/Commands/ (e.g., HelloCommand.php):

   <?php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   
   class HelloCommand extends Command
   {
       protected $signature = 'hello {name?}';
       protected $description = 'Say hello to someone';
   
       public function handle()
       {
           $name = $this->argument('name') ?: 'World';
           $this->info("Hello, {$name}!");
       }
   }
   

   Run it:

   php artisan hello John
   

3. Key Files to Explore:

   • app/Console/Kernel.php: Command registration.
   • config/console.php: CLI-specific configuration.
   • artisan: The CLI entry point (customizable via app/Console/Kernel.php).

Implementation Patterns

Core Workflows

1. Command Development:

   • Signature & Description: Define CLI arguments/options and help text.

     protected $signature = 'task:run {--force} {--queue=}';
     protected $description = 'Run a scheduled task';
     

   • Argument Handling: Access inputs via $this->argument() or $this->option().
   • Output: Use $this->info(), $this->error(), or $this->table() for structured output.

2. Interactive Menus: Use laravel-zero/menu for CLI menus:

   use LaravelZero\Framework\Menu;
   
   $menu = Menu::new()
       ->title('Main Menu')
       ->option('Backup', fn() => $this->call('backup:run'))
       ->option('Cleanup', fn() => $this->call('cleanup:temp'))
       ->action();
   

3. Task Scheduling: Define tasks in app/Console/Kernel.php:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('backup:run')->daily();
   }
   

   Run with:

   php artisan schedule:run
   

4. PHAR Compilation: Build a standalone binary:

   php artisan build
   

   Customize via php artisan build --help.

5. Configuration: Share settings across commands via config/console.php or environment variables.

Integration Tips

• Laravel Ecosystem: Use Eloquent, Logging, or HTTP clients seamlessly.
• Prompts: Leverage laravel/prompts for user input:

  use Laravel\Prompts\Prompt;
  
  $name = Prompt::anticipate('What is your name?', ['John', 'Jane']);
  

• Error Handling: Integrate nunomaduro/collision for rich error reporting:

  use Collision\Collision;
  
  Collision::handle(function () {
      throw new \RuntimeException('Something went wrong!');
  });
  

Gotchas and Tips

Pitfalls

1. PHAR Limitations:

   • Avoid dynamic class loading (e.g., class_alias) or eval() in PHARs.
   • Ensure all dependencies are autoloaded; PHARs don’t support composer dump-autoload --optimize.

2. Command Registration:

   • Commands in app/Console/Commands/ must extend Illuminate\Console\Command (or LaravelZero\Framework\Commands\Command).
   • Forgetting to register commands in Kernel.php makes them invisible to artisan.

3. Configuration Conflicts:

   • Override config/console.php carefully; some keys (e.g., name) are critical for PHAR builds.
   • Use config_path() to dynamically load configs if needed.

4. Scheduler Quirks:

   • The scheduler runs via artisan schedule:run. For cron jobs, use:

     * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1
     

   • Avoid blocking operations in scheduled tasks (use queues if needed).

5. PHAR Debugging:

   • Test PHARs locally with:

     php artisan build --debug
     

   • Check the bootstrap/app.php for PHAR-specific overrides.

Debugging Tips

• Enable Debug Mode:

  php artisan --env=local
  

  Or set APP_DEBUG=true in .env.

• Log Output: Use ->debug() or ->line() for verbose logging. Check storage/logs/laravel.log.

• Collision Errors: Ensure nunomaduro/collision is installed and configured in config/collision.php.

• PHAR Issues:

  • Verify the stub in bootstrap/app.php matches your needs.
  • Use php artisan build --verbose to see compilation steps.

Extension Points

1. Custom Artisan Commands: Extend LaravelZero\Framework\Commands\Command for shared CLI logic (e.g., auth, logging).

2. Menu Customization: Override LaravelZero\Framework\Menu to add themes or dynamic options.

3. PHAR Hooks: Use BootstrapServiceProvider in config/app.php to modify PHAR behavior:

   'providers' => [
       // ...
       App\Providers\BootstrapServiceProvider::class,
   ],
   

4. Prompts Integration: Bind custom prompts to commands:

   $this->call('prompt:custom', [
       '--question' => 'Confirm action?',
       '--default' => 'yes',
   ]);
   

5. Scheduler Extensions: Add custom schedule events by extending Illuminate\Console\Scheduling\Schedule.