Plain Commands Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   "require": {
       "alexeyshockov/plain-commands-bundle": "^0.3"
   }
   

   Run composer require alexeyshockov/plain-commands-bundle.

2. Enable the Bundle Add to config/bundles.php:

   Alexeyshockov\PlainCommandsBundle\PlainCommandsBundle::class => ['all' => true],
   

3. Register Commands Tag your command classes in config/services.yaml:

   services:
       App\Console\Command\:
           resource: '../src/Console/Command'
           tags: ['plain_commands.set']
   

4. Annotate a Command Create a command class (e.g., src/Console/Command/ExampleCommand.php):

   use Alexeyshockov\PlainCommands\Annotation\Command;
   
   class ExampleCommand {
       /**
        * @Command(name="app:example", description="Runs an example command")
        */
       public function run() {
           echo "Command executed!";
       }
   }
   

5. Run the Command Execute via CLI:

   php bin/console app:example
   

Implementation Patterns

Workflow: Command Development

1. Define Commands Use @Command annotations to declare command metadata (name, description, arguments, options). Example:

   /**
    * @Command(
    *     name="app:user:create",
    *     description="Creates a new user",
    *     arguments={
    *         {"name", "name", "User name", "required"},
    *         {"email", "email", "User email", "required"}
    *     }
    * )
    */
   public function createUser(string $name, string $email) {
       // Logic here
   }
   

2. Argument/Option Handling Annotate parameters directly:

   /**
    * @Command(name="app:filter", arguments={{"limit", "limit", "Max items", "optional", 10}})
    */
   public function filter(int $limit = 10) {
       // Uses $limit from CLI input
   }
   

3. Dependency Injection Inject services into commands via constructor or annotations:

   use Alexeyshockov\PlainCommands\Annotation\Inject;
   
   class ExampleCommand {
       /**
        * @Inject
        */
       private $logger;
   
       /**
        * @Command(name="app:log")
        */
       public function log() {
           $this->logger->info("Command logged");
       }
   }
   

4. Grouping Commands Organize commands in namespaces (e.g., App\Console\Command\User) and tag the parent directory in services.yaml.

5. Integration with Symfony Console Commands are auto-registered with Symfony’s console component. Use bin/console as usual.

Integration Tips

• Leverage Symfony’s Console Features Combine with Symfony’s built-in console helpers (e.g., OutputInterface, InputInterface) by extending the base command class if needed.
• Validation Use Symfony’s validator component to validate annotated arguments/options.
• Testing Mock commands in tests by injecting dependencies or using the PlainCommandsTestCase (if provided by the underlying library).

Gotchas and Tips

Pitfalls

1. Annotation Parsing Issues

   • Ensure annotations are exactly formatted (e.g., @Command(name="...") with quotes).
   • Spaces or missing parentheses break parsing. Example of a bad annotation:

     // ❌ Fails
     @Command name="app:test"
     

   • Fix: Use proper syntax:

     // ✅ Works
     /**
      * @Command(name="app:test")
      */
     

2. Service Tagging

   • Forgetting to tag command classes with plain_commands.set in services.yaml silenty ignores them.
   • Fix: Verify tags with:

     php bin/console debug:container plain_commands.set
     

3. Dependency Injection Conflicts

   • Circular dependencies or missing services cause PlainCommandsBundle to skip commands.
   • Fix: Use debug:container to check service availability:

     php bin/console debug:container your_service
     

4. Symfony Version Mismatch

   • The bundle supports Symfony 3.3–5.0. Using an unsupported version may break annotation parsing.
   • Fix: Pin compatible versions in composer.json or upgrade/downgrade Symfony.

5. Archived Status

   • The package is archived (no active maintenance). Use at your own risk or fork it for critical projects.

Debugging Tips

1. Enable Debug Mode Set APP_DEBUG=1 in .env to see annotation parsing errors in logs.

2. Check Registered Commands List all registered commands to verify annotations:

   php bin/console list
   

3. Inspect Annotations Use a tool like phpDocumentor to validate annotation syntax.

4. Log Annotations Temporarily add logging to the bundle’s compiler pass (if you’re comfortable extending it):

   // In a custom compiler pass
   $this->container->set('logger', new NullLogger());
   

Extension Points

1. Custom Annotation Handlers Extend the bundle by creating a custom annotation reader or compiler pass to support additional annotations (e.g., @Command\Help).

2. Post-Processing Commands Use Symfony’s event system to modify commands after registration (e.g., add help text dynamically).

3. Fork and Maintain Since the package is archived, fork it to add features like:

   • Support for Symfony 6/7.
   • Integration with Laravel’s Artisan (via Symfony Bridge).
   • Custom argument/option validators.