Getting Started

Minimal Setup

Installation:
```
composer require laminas/laminas-cli
```
This adds the vendor/bin/laminas CLI runner to your project.
First Use Case: Run a built-in command (e.g., list to see available commands):
```
vendor/bin/laminas list
```
For Laminas MVC/Mezzio apps, this will display commands registered in your application’s configuration.
Where to Look First:
- Configuration: Check config/autoload/laminas-cli.global.php (or equivalent) for registered commands.
- Command Registration: For custom commands, reference the Symfony Console docs and the README’s registration examples.

Implementation Patterns

Core Workflows

Command Registration:

Laminas MVC:

// config/autoload/laminas-cli.global.php
return [
    'laminas-cli' => [
        'commands' => [
            'app:custom-command' => \App\Command\CustomCommand::class,
        ],
    ],
    'service_manager' => [
        'factories' => [
            \App\Command\CustomCommand::class => \App\Factory\CustomCommandFactory::class,
        ],
    ],
];

Mezzio:

// config/autoload/laminas-cli.global.php
return [
    'laminas-cli' => [
        'commands' => [
            'app:custom-command' => \App\Command\CustomCommand::class,
        ],
    ],
    'dependencies' => [
        'factories' => [
            \App\Command\CustomCommand::class => \App\Factory\CustomCommandFactory::class,
        ],
    ],
];

Command Execution:
```
vendor/bin/laminas app:custom-command [options]
```
Use --container=<path> to specify a custom container file (e.g., vendor/bin/laminas --container=config/container.php app:custom-command).

Dependency Injection:

For commands with dependencies, use a factory (e.g., CustomCommandFactory) to resolve them via the container.

Example factory:

namespace App\Factory;
use Psr\Container\ContainerInterface;
use App\Command\CustomCommand;

class CustomCommandFactory
{
    public function __invoke(ContainerInterface $container): CustomCommand
    {
        return new CustomCommand(
            $container->get(\App\Service\SomeService::class)
        );
    }
}

Symfony Console Attributes (v1.15.0+): Decorate commands with attributes for metadata (e.g., descriptions, arguments):

use Symfony\Component\Console\Attribute\AsCommand;

#[AsCommand(name: 'app:custom-command', description: 'Does something awesome')]
class CustomCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Command logic
    }
}

Integration with Artisan-like Workflows:
- Use vendor/bin/laminas as a drop-in replacement for php artisan in Laravel projects.
- Example: Create a bin/console symlink:
```
ln -s vendor/bin/laminas bin/console
```

Gotchas and Tips

Pitfalls

Missing --container Flag:
- If commands fail with InvalidArgumentException, ensure you’re either:
  - Running in a Laminas MVC/Mezzio app (where the container is auto-detected), or
  - Explicitly passing --container=<path> to point to a PSR-11 container file.
- Fix: Update to laminas-cli v1.1.1+ (includes a bugfix for this).
Command Not Found:
- If vendor/bin/laminas list shows no commands, verify:
  - The laminas-cli config key exists in your autoload configuration.
  - Commands are registered under the commands key (e.g., 'app:command-name' => \Namespace\Command::class).
- Fix: Check for typos in command names or missing factory mappings.
Symfony Console Version Mismatch:
- laminas-cli v1.15.0+ requires Symfony Console v6+. Older versions may break with newer Symfony releases.
- Fix: Update laminas-cli or pin Symfony Console to a compatible version in composer.json.
Circular Dependencies in Factories:
- If commands fail to instantiate due to circular dependencies, refactor factories to avoid tight coupling.
- Tip: Use allow_override: true in config/autoload/global.php for development:
```
return [
    'laminas-cli' => [
        'allow_override' => true, // Debugging only!
    ],
];
```

Debugging Tips

Verbose Output: Add -v or -vv to commands for debugging:
```
vendor/bin/laminas -vv app:custom-command
```

Container Inspection: Dump the container contents to verify service availability:

// In a command's execute() method:
$container = $this->getApplication()->getKernel()->getContainer();
var_dump($container->get(\App\Service\SomeService::class));

PSR-11 Container Validation: Ensure your custom container implements Psr\Container\ContainerInterface and handles NotFoundException for missing services.

Extension Points

Dynamic Command Loading: Register commands dynamically via a Laminas\Cli\Command\CommandProviderInterface:

$provider = new class implements CommandProviderInterface {
    public function getCommands(): array
    {
        return [
            'app:dynamic-command' => \DynamicCommand::class,
        ];
    }
};
// Register the provider in your container.

Custom Command Helpers: Extend Laminas\Cli\Command\Command for reusable logic:

abstract class BaseCommand extends Command
{
    protected function log(string $message): void
    {
        $this->getApplication()->getKernel()->getLogger()->info($message);
    }
}

Environment-Specific Commands: Use config/autoload/{environment}.global.php to conditionally register commands:

// config/autoload/local.global.php
return [
    'laminas-cli' => [
        'commands' => [
            'app:dev-only-command' => \DevCommand::class,
        ],
    ],
];

Integration with Laravel:

Override vendor/bin/laminas with a custom script to leverage Laravel’s service container:

# bin/laminas
#!/usr/bin/env php
<?php
require __DIR__.'/../vendor/autoload.php';
$container = require __DIR__.'/../bootstrap/app.php';
$cli = new \Laminas\Cli\Cli($container);
$cli->run();

public function register()
{
    $this->app->extend('laminas-cli.commands', function ($commands) {
        $commands['app:laravel-command'] = \App\Command\LaravelCommand::class;
        return $commands;
    });
}

Performance Tips

Avoid Overhead in Production: Disable debug mode in config/autoload/global.php:
```
return [
    'laminas-cli' => [
        'debug' => false,
    ],
];
```
Cache Command Metadata: For large applications, cache command metadata (e.g., descriptions) in a static file to avoid reflection overhead:
```
// In a command provider:
$metadata = require __DIR__.'/../data/command-metadata.php';
return $metadata['commands'];
```

Laminas Cli Laravel Package