Laminas Cli Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laminas/laminas-cli
   

   Ensure you install it in a Laravel project (or any PHP project) where you need CLI tooling.

2. First Use Case: Run the CLI tool to list available commands:

   vendor/bin/laminas
   

   This will display all registered commands, including those from Laravel (e.g., migrate, make) and any custom commands you later add.

3. Run a Command: Execute a built-in Laravel command via laminas-cli:

   vendor/bin/laminas migrate
   

Implementation Patterns

Workflows

1. Leveraging Laravel Commands: Use laminas-cli as a unified entry point for all Laravel CLI commands. For example:

   vendor/bin/laminas make:controller UserController
   

   This avoids managing multiple CLI scripts (e.g., artisan, phpunit).

2. Custom Command Integration:

   • Create a Symfony Console command:

     namespace App\Console\Commands;
     
     use Illuminate\Console\Command;
     use Symfony\Component\Console\Input\InputOption;
     
     class CustomCommand extends Command
     {
         protected function configure()
         {
             $this->setName('app:custom')
                   ->addOption('param', null, InputOption::VALUE_REQUIRED, 'A custom parameter');
         }
     
         protected function execute($input, $output)
         {
             $output->writeln('Custom command executed with param: ' . $input->getOption('param'));
         }
     }
     

   • Register the command in Laravel’s AppServiceProvider:

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

   • Run it via laminas-cli:

     vendor/bin/laminas app:custom --param=value
     

3. Parameterized Commands: Use laminas-cli's input parameters for interactive prompts:

   // In your command class
   $this->addParameter('confirm', 'Do you want to proceed?', false, true);
   

   Run the command without arguments to trigger the prompt:

   vendor/bin/laminas app:interactive-command
   

4. Dependency Injection: Inject Laravel services (e.g., DB, Cache) into commands:

   use Illuminate\Support\Facades\DB;
   
   class DatabaseCommand extends Command
   {
       protected $db;
   
       public function __construct(DB $db)
       {
           parent::__construct();
           $this->db = $db;
       }
   }
   

   Register the factory in Laravel’s config/app.php under commands.

Gotchas and Tips

Pitfalls

1. Container Path: If Laravel’s container isn’t auto-detected (e.g., custom setup), specify it explicitly:

   vendor/bin/laminas --container=path/to/container.php
   

   Create a container.php file returning a PSR-11 container (e.g., using Laravel\Container).

2. Command Registration: Forgetting to register custom commands in Laravel’s AppServiceProvider or config/app.php will make them invisible to laminas-cli.

3. Input Parameters vs. Options:

   • Input parameters are interactive by default (prompts if omitted).
   • Options require explicit flags (e.g., --param=value). Misusing them can lead to unexpected behavior in non-interactive scripts.

4. Laravel-Specific Quirks:

   • Laravel’s artisan commands may not work directly with laminas-cli unless explicitly registered.
   • Use Laravel\Console\Command for Laravel-specific features (e.g., call() method).

Debugging

1. Command Not Found: Verify the command is registered in:

   • Laravel’s AppServiceProvider (for built-in commands).
   • config/app.php under commands (for custom commands).
   • laminas-cli configuration (if using external packages).

2. Dependency Injection Failures: Ensure factories for commands with dependencies are registered in Laravel’s config/app.php:

   'App\Console\Commands\CustomCommand' => App\Console\Commands\CustomCommandFactory::class,
   

3. Interactive Mode Issues: If prompts don’t appear, check:

   • The command is run in a terminal (not a cron job or non-interactive shell).
   • Input parameters are correctly marked as optional (false for isRequired).

Extension Points

1. Custom CLI Configuration: Extend laminas-cli behavior by modifying its configuration in config/autoload/laminas-cli.global.php:

   return [
       'commands' => [
           'app:custom' => App\Console\Commands\CustomCommand::class,
       ],
       'default_command' => 'app:custom', // Set a default command
   ];
   

2. Integration with Laravel Artisan: Alias laminas-cli to artisan for backward compatibility:

   alias artisan='vendor/bin/laminas'
   

   Add this to your .bashrc or .zshrc.

3. Non-Laravel Projects: For non-Laravel PHP projects, use laminas-cli with a custom container:

   // config/container.php
   return new Laravel\Container\Container();
   

   Then run:

   vendor/bin/laminas --container=config/container.php
   

4. Testing Commands: Use Laravel’s Artisan::call() for unit testing:

   $exitCode = Artisan::call('app:custom', ['param' => 'value']);
   $this->assertEquals(0, $exitCode);