Framework Laravel Package

Getting Started

Minimal Steps

1. Installation:

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

   Or add to an existing project:

   composer require laravel-zero/framework
   

2. Create a Command:

   php artisan make:command Greet
   

   Edit app/Commands/Greet.php:

   protected $signature = 'greet {name?}';
   protected $description = 'Greet someone';
   
   public function handle()
   {
       $name = $this->argument('name') ?: 'World';
       $this->info("Hello, {$name}!");
   }
   

3. Run the Command:

   php artisan greet John
   

First Use Case

Build a self-contained CLI tool (e.g., a deployment helper) with:

• Arguments/Options: Use $signature and $this->option().
• Interactive Prompts: Leverage laravel/prompts (built-in):

  $name = Prompt::text('What is your name?');
  

• Logging: Use Laravel’s logging:

  $this->info('Deploying...'); // Outputs to console
  \Log::info('Deployment started');
  

Implementation Patterns

Core Workflows

1. Command-Based Development:

   • Structure: Organize commands in app/Commands/ (e.g., DeployCommand, BackupCommand).
   • Dependencies: Inject services via constructor (Laravel’s DI container):

     public function __construct(private DatabaseService $db) {}
     

   • Testing: Use PHPUnit with artisan helper:

     $this->artisan('greet')->expectsOutput('Hello, World!');
     

2. Interactive Menus:

   • Use Menu facade (from spatie/laravel-menu or custom):

     use LaravelZero\Framework\Menus\Menu;
     
     Menu::new()
         ->title('Main Menu')
         ->addOption('Deploy', fn() => $this->call('deploy'))
         ->addOption('Backup', fn() => $this->call('backup'))
         ->display();
     

3. Scheduling:

   • Define tasks in app/Console/Kernel.php:

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

   • Run with:

     php artisan schedule:run
     

4. Standalone PHARs:

   • Compile to a single binary:

     php artisan build
     

   • Customize the build with php artisan build:config (e.g., PHP version, dependencies).

5. Database Integration:

   • Use Eloquent models (optional):

     use App\Models\User;
     
     $users = User::all();
     

   • Migrate with:

     php artisan migrate
     

Integration Tips

• Laravel Ecosystem: Reuse config files, service providers, and middleware from Laravel apps.
• Error Handling: Integrate nunomaduro/collision for rich error pages:

  $this->callSilently('deploy'); // Silently fail
  

• Environment Awareness: Use .env files for config (e.g., DB_CONNECTION=sqlite::memory for testing).
• Artisan Extensions: Extend Laravel’s Artisan class to add custom commands globally.

Gotchas and Tips

Pitfalls

1. PHAR Build Issues:

   • Problem: php artisan build fails with pcntl errors. Fix: Install pcntl or use --no-pcntl:

     php artisan build --no-pcntl
     

   • Problem: Missing migrations in PHAR. Fix: Ensure database/migrations is included in build.php:

     return [
         'mainClass' => 'App\Kernel',
         'includeFiles' => ['database/migrations'],
     ];
     

2. Dependency Conflicts:

   • Problem: Laravel Zero + Eloquent conflicts with other packages. Fix: Use replace in composer.json or alias classes:

     "extra": {
         "laravel": {
             "dont-discover": ["eloquent"]
         }
     }
     

3. Logging Quirks:

   • Problem: Logs don’t appear in storage/logs. Fix: Ensure APP_LOG is set in .env:

     APP_LOG=single
     APP_LOG_LEVEL=debug
     

4. Interactive Prompts in Non-TTY:

   • Problem: Prompt::text() fails in cron jobs. Fix: Check for TTY or use --ansi flag:

     if (! $this->output->isDecorated()) {
         $this->output->setDecorated(true);
     }
     

Debugging Tips

• Collision Errors: Enable detailed error pages:

  $this->call('collision:serve');
  

• Command Debugging: Use --verbose:

  php artisan greet --verbose
  

• PHAR Debugging: Extract the PHAR to inspect:

  php -d phar.readonly=0 vendor/bin/your-phar.phar
  

Extension Points

1. Custom Command Bus:

   • Override app/Providers/CommandServiceProvider.php to bind custom commands:

     public function register()
     {
         $this->commands([
             \App\Commands\CustomCommand::class,
         ]);
     }
     

2. Menu Extensions:

   • Create a MenuServiceProvider to register global menus:

     public function boot()
     {
         Menu::macro('admin', fn() => Menu::new()->title('Admin'));
     }
     

3. Scheduler Events:

   • Listen to scheduled events:

     $schedule->command('backup')->before(fn() => Log::info('Backup started'));
     

4. PHAR Customization:

   • Extend build.php to include assets or scripts:

     return [
         'mainClass' => 'App\Kernel',
         'includeFiles' => ['config/*', 'routes/*'],
         'postBuildCommands' => [
             'chmod +x storage/bin/hook.sh',
         ],
     ];
     

Pro Tips

• Reuse Laravel Config: Share config/app.php between web and CLI apps.
• Shared Services: Define services in app/Providers/AppServiceProvider for both web and CLI.
• Testing: Use artisan helper in tests:

  $this->artisan('command:name', ['option' => 'value'])
       ->expectsQuestion('Confirm?', 'yes')
       ->expectsOutput('Success!');
  

• Performance: Cache command results with Cache::remember:

  $data = Cache::remember('command:data', now()->addHours(1), fn() => $this->fetchData());