Annotated Command Laravel Package

Getting Started

Start by requiring the package: composer require consolidation/annotated-command. (⚠️ Note: Typo in some docs—use annotated, not annoted.) Next, create a command class (e.g., src/Command/Deploy.php) with a method annotated like:

/**
 * @command deploy:release
 * @description Deploy the latest release to production
 * @option env The environment (e.g. dev, staging, prod)
 * @arg target The target server
 */
public function deploy($target, $options = ['env' => 'prod']): int
{
    // ...
    return 0;
}

Then bootstrap your Console application:

use Consolidation\AnnotatedCommand\AnnotatedCommandFactory;
use Symfony\Component\Console\Application;

$application = new Application();
$factory = new AnnotatedCommandFactory();
$factory->addCommandsFromDirectory(__DIR__ . '/src/Command');
$application->addCommands($factory->getCommands());
$application->run();

First use case: Replace verbose Command subclasses with lean, self-documenting annotated methods—ideal for internal devops tools or microservice CLIs.

Implementation Patterns

• Command discovery via directories: Use AnnotatedCommandFileLoader or addCommandsFromDirectory() to auto-register commands in src/Command/*—keep related logic grouped by module (e.g., src/Command/DB/, src/Command/Cache/).
• Shared base logic: Extend AnnotatedCommandBase (if available) or create traits for cross-cutting concerns (e.g., OutputsJsonTrait, HandlesCredentialsTrait).
• Validation layer: Pair with Symfony’s Validator component (@validate annotations not built-in); pre-validate inputs in the method body or via custom annotations (see Gotchas).
• Testing workflow: Write unit tests for business logic directly (e.g., DeployTest::testDeployCalculatesArtifactVersion()). For integration, mock InputInterface/OutputInterface and call the annotated method directly—no app kernel needed.
• Modular scaling: In monorepos, partition annotated commands by service (e.g., services/api/src/Command/, services/worker/src/Command/) and load each independently.

Gotchas and Tips

• License ambiguity: NOASSERTION means no license is asserted—legally risky for production use. Verify intent with maintainers; consider alternatives (e.g., Laravel Echo’s laravel-zero/framework with native Artisan patterns) if compliance matters.
• Silent registration failures: If commands vanish after dump-autoload, double-check PSR-4 mapping in composer.json matches your directory structure. Run composer dump-autoload -o and inspect registered commands via $application->all()['deploy:release'].
• No typed options/args by default: @option env won’t auto-cast to string/int—validate manually (e.g., if (!in_array($options['env'], ['dev', 'prod'])) { ... }) or add custom annotation processing.
• Debugging tip: Call $application->find('deploy:release') to see Symfony’s parsed definition (arguments/options resolved). Use var_dump($factory->getCommands()) to verify discovery.
• Documentation gap: Source code is primary—study AnnotatedCommandFactory.php, AnnotationData.php, and AnnotatedCommandBase.php for advanced behavior (e.g., custom annotation handlers, event hooks).
• Extensibility hack: Implement CommandEventSubscriberInterface (if present) or override AnnotatedCommand::create() to inject services (e.g., Doctrine EntityManager) via constructor injection into command classes.