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. 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 and bootstrapping.
   • config/: Framework configuration (logging, Prompts, etc.).
   • artisan: The CLI entry point (customizable via app/Console/Kernel.php).

Implementation Patterns

Core Workflows

1. Command Development:

   • Signature & Arguments:

     protected $signature = 'migrate:fresh {--database= : Database connection} {--force : Force the operation}';
     

   • Interactive Prompts (using laravel/prompts):

     use Laravel\Prompts\Prompt;
     
     $name = Prompt::text('What is your name?');
     $confirm = Prompt::confirm('Proceed?', default: false);
     

   • Output:

     $this->info('Success!');
     $this->error('Failed!');
     $this->table(['Name', 'Value'], [['Foo', 'Bar']]);
     

2. Configuration Management:

   • Access config via config() helper or $this->config in commands.
   • Publish config files:

     php artisan vendor:publish --tag=laravel-zero-config
     

   • Override defaults in .env or config/laravel-zero.php.

3. Task Scheduling:

   • Define in app/Console/Kernel.php:

     protected function schedule(Schedule $schedule)
     {
         $schedule->command('backup:run')->daily();
         $schedule->exec('php artisan optimize')->everyFiveMinutes();
     }
     

   • Run scheduler:

     php artisan schedule:run
     

4. Interactive Menus:

   • Use laravel-zero/menus (included) or spatie/laravel-menu:

     use LaravelZero\Framework\Menus\Menu;
     
     Menu::new()
         ->title('Main Menu')
         ->option('Option 1', fn () => $this->handleOption1())
         ->option('Exit', fn () => exit)
         ->display();
     

5. PHAR Compilation:

   • Build a standalone binary:

     php artisan build
     

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

6. Logging & Error Handling:

   • Log with Log::info(), Log::error(), etc.
   • Use Collision for rich error reporting (auto-integrated):

     $this->callSilently('deploy', ['--verbose']);
     

Integration Tips

• Shared Logic with Web Apps: Use Laravel’s service container to share classes between CLI and web:

  $this->app->bind('MyService', fn () => new MyService());
  

• Database Access: Enable Eloquent via composer require illuminate/database and configure .env. Use DB::table() or Eloquent models in commands.
• Testing: Use Laravel’s testing tools:

  use Tests\TestCase;
  
  class HelloCommandTest extends TestCase
  {
      public function test_hello_command()
      {
          $this->artisan('hello', ['name' => 'John'])
               ->expectsOutput('Hello, John!');
      }
  }
  

Gotchas and Tips

Pitfalls

1. PHAR Build Issues:

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

     php artisan build --no-pcntl
     

   • Problem: Missing dependencies in PHAR. Fix: Explicitly list dependencies in composer.json under require and use php artisan build:config to include them.

2. Configuration Overrides:

   • Problem: Config changes not reflected in PHAR. Fix: Rebuild the PHAR after config changes:

     php artisan build --force
     

3. Prompt Version Conflicts:

   • Problem: laravel/prompts version mismatch. Fix: Ensure compatibility (Laravel Zero v10+ supports 0.2–0.3):

     composer require laravel/prompts:^0.3
     

4. Scheduler Not Running:

   • Problem: Scheduled tasks not executing. Fix: Ensure schedule:run is called via cron or systemd:

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

5. Eloquent in PHAR:

   • Problem: Database connections fail in PHAR. Fix: Ensure .env is included in the PHAR or use --env flag:

     php artisan build --env=production
     

Debugging Tips

1. Enable Debug Mode:

   php artisan --env=local --debug
   

   Or set APP_DEBUG=true in .env.

2. Collision Error Reporting:

   • Use php artisan collision:install to enable rich error pages.
   • Access errors at http://localhost:8000/collision during development.

3. Logging:

   • Check logs in storage/logs/laravel.log.
   • Use php artisan log:clear to reset logs.

4. Command Debugging:

   • Dump variables:

     $this->dump($variable);
     

   • Pause execution:

     $this->pause('Press enter to continue...');
     

Extension Points

1. Custom Command Macros: Extend the Command class globally in app/Providers/AppServiceProvider.php:

   use Illuminate\Console\Command;
   
   Command::macro('successMessage', function ($message) {
       $this->info("[SUCCESS] {$message}");
   });
   

   Usage:

   $this->successMessage('Operation completed!');
   

2. Custom Artisan Commands: Override the artisan binary path in app/Console/Kernel.php:

   protected function configureArtisan()
   {
       $this->artisan->binaryPath('/custom/path/to/artisan');
   }
   

3. Custom PHAR Compiler: Extend the BuildCommand to add pre/post-build steps:

   use LaravelZero\Framework\Commands\BuildCommand;
   
   class CustomBuildCommand extends BuildCommand
   {
       protected function getExtraBoxOptions()
       {
           return ['--platform' => 'linux'];
       }
   }
   

4. Interactive Menu Extensions: Create custom menu items or themes by extending LaravelZero\Framework\Menus\Menu.

5. Event Listeners: Listen to command events (e.g., CommandStarting, CommandFinished):

   use Illuminate\Console\Events\CommandStarting;
   
   public function boot()
   {
       CommandStarting::listen(function (CommandStarting $event) {
           Log::debug("Command starting: {$event->commandName}");
       });
   }
   

Configuration Quirks

1. Environment Variables:

   • PHARs ignore .env by default. Use --env flag or include .env in the PHAR:

     php artisan build --env=production --include-env
     

2. Logging Channels:

   • Configure logging in config/laravel-zero.php to use custom channels (e.g., Slack, Syslog).

3. Prompt Defaults:

   • Set defaults for prompts in config/prompts.php:

     'defaults' => [
         'confirm' => ['default' => false],
         'text' => ['default' => ''],
     ],
     

4. Scheduler Timezones:

   • Set APP_TIMEZONE in .env to avoid timezone issues in scheduled tasks.

Performance Tips

1. PHAR Optimization:

   • Exclude unnecessary files:

     php artisan build --exclude=tests,node_modules
     

   • Use --optimize to minify included files.

2. Command Caching: