Merge pull request #22 from kbond/new-features

Some new features

Author: kbond

.github/workflows/ci.yml

@@ -23,25 +23,10 @@ jobs:
 
   cs-check:
     uses: zenstruck/.github/.github/workflows/php-cs-fixer.yml@main
+    with:
+      php: 8
 
   sca:
-    name: Static Code Analysis
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v2
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: 8.1
-          coverage: none
-
-      - name: Install Dependencies
-        uses: ramsey/composer-install@v1
-
-      - name: Install PHPUnit
-        run: vendor/bin/simple-phpunit install
-
-      - name: Run PHPStan
-        run: vendor/bin/phpstan --error-format=github
+    uses: zenstruck/.github/.github/workflows/php-stan.yml@main
+    with:
+      php: 8.1

README.md

@@ -13,12 +13,15 @@ A modular set of features to reduce configuration boilerplate for your commands:
  */
 final class CreateUserCommand extends InvokableServiceCommand
 {
-    use ConfigureWithDocblocks;
+    use ConfigureWithDocblocks, RunsCommands, RunsProcesses;
 
     public function __invoke(IO $io, UserRepository $repo): void
     {
         $repo->createUser($io->argument('email'), $io->argument('password'), $io->option('role'));
 
+        $this->runCommand('another:command');
+        $this->runProcess('/some/script');
+
         $io->success('Created user.');
     }
 }
@@ -85,6 +88,9 @@ class MyCommand extends \Symfony\Component\Console\Command\Command
         $role = $io->option('role');
 
         $io->success('created.');
+
+        // even if you don't inject IO, it's available as a method:
+        $this->io(); // IO
     }
 }
 ```
@@ -145,6 +151,29 @@ class CreateUserCommand extends Command
 }
 ```
 
+### `ConfigureWithAttributes`
+
+Use this trait to use the `Argument` and `Option` attributes to configure your command's
+arguments and options (_PHP 8+ required_):
+
+```php
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Zenstruck\Console\Attribute\Argument;
+use Zenstruck\Console\Attribute\Option;
+use Zenstruck\Console\ConfigureWithAttributes;
+
+#[Argument('arg1', description: 'Argument 1 description', mode: InputArgument::REQUIRED)]
+#[Argument('arg2', description: 'Argument 1 description')]
+#[Option('option1', description: 'Option 1 description')]
+class MyCommand extends Command
+{
+    use ConfigureWithAttributes;
+}
+```
+
+**NOTE:** This trait is incompatible with [`ConfigureWithDocblocks`](#configurewithdocblocks).
+
 ### `ConfigureWithDocblocks`
 
 Use this trait to allow your command to be configured by your command class' docblock.
@@ -194,6 +223,7 @@ class MyCommand extends Command
 2. All the configuration can be disabled by using the traditional methods of configuring your command.
 3. Command's are still [lazy](https://symfony.com/blog/new-in-symfony-3-4-lazy-commands) using this method of
    configuration but there is overhead in parsing the docblocks so be aware of this.
+4. This trait is incompatible with [`ConfigureWithAttributes`](#configurewithattributes).
 
 #### `@command` Tag
 
@@ -215,6 +245,131 @@ class MyCommand extends Command
 
 **TIP**: It is recommended to only do this for very simple commands as it isn't as explicit as splitting the tags out.
 
+### `CommandRunner`
+
+A `CommandRunner` object is available to simplify running commands anywhere (ie controller):
+
+```php
+use Zenstruck\Console\CommandRunner;
+
+/** @var \Symfony\Component\Console\Command\Command $command */
+
+CommandRunner::for($command)->run(); // int (the status after running the command)
+
+// pass arguments
+CommandRunner::for($command, 'arg --opt')->run(); // int
+```
+
+If the application is available, you can use it to run commands:
+
+```php
+use Zenstruck\Console\CommandRunner;
+
+/** @var \Symfony\Component\Console\Application $application */
+
+CommandRunner::from($application, 'my:command')->run();
+
+// pass arguments/options
+CommandRunner::from($application, 'my:command arg --opt')->run(); // int
+```
+
+If your command is interactive, you can pass inputs:
+
+```php
+use Zenstruck\Console\CommandRunner;
+
+/** @var \Symfony\Component\Console\Application $application */
+
+CommandRunner::from($application, 'my:command')->run([
+    'foo', // input 1
+    '', // input 2 (<enter>)
+    'y', // input 3
+]);
+```
+
+By default, output is suppressed, you can optionally capture the output:
+
+```php
+use Zenstruck\Console\CommandRunner;
+
+/** @var \Symfony\Component\Console\Application $application */
+
+$output = new \Symfony\Component\Console\Output\BufferedOutput();
+
+CommandRunner::from($application, 'my:command')
+    ->withOutput($output) // any OutputInterface
+    ->run()
+;
+
+$output->fetch(); // string (the output)
+```
+
+#### `RunsCommands`
+
+You can give your [Invokable Commands](#invokable) the ability to run other commands (defined
+in the application) by using the `RunsCommands` trait. These _sub-commands_ will use the same
+_output_ as the parent command.
+
+```php
+use Symfony\Component\Console\Command;
+use Zenstruck\Console\Invokable;
+use Zenstruck\Console\RunsCommands;
+
+class MyCommand extends Command
+{
+    use Invokable, RunsCommands;
+
+    public function __invoke(): void
+    {
+        $this->runCommand('another:command'); // int (sub-command's run status)
+
+        // pass arguments/options
+        $this->runCommand('another:command arg --opt');
+
+        // pass inputs for interactive commands
+        $this->runCommand('another:command', [
+            'foo', // input 1
+            '', // input 2 (<enter>)
+            'y', // input 3
+        ])
+    }
+}
+```
+
+### `RunsProcesses`
+
+You can give your [Invokable Commands](#invokable) the ability to run other processes (`symfony/process` required)
+by using the `RunsProcesses` trait. Standard output from the process is hidden by default but can be shown by
+passing `-v` to the _parent command_. Error output is always shown. If the process fails, a `\RuntimeException`
+is thrown.
+
+```php
+use Symfony\Component\Console\Command;
+use Symfony\Component\Process\Process;
+use Zenstruck\Console\Invokable;
+use Zenstruck\Console\RunsProcesses;
+
+class MyCommand extends Command
+{
+    use Invokable, RunsProcesses;
+
+    public function __invoke(): void
+    {
+        $this->runProcess('/some/script');
+
+        // construct with array
+        $this->runProcess(['/some/script', 'arg1', 'arg1']);
+
+        // for full control, pass a Process itself
+        $this->runProcess(
+            Process::fromShellCommandline('/some/script')
+                ->setTimeout(900)
+                ->setWorkingDirectory('/')
+        );
+    }
+}
+```
+
 ### `CommandSummarySubscriber`
 
 Add this event subscriber to your `Application`'s event dispatcher to display a summary after every command is run.

composer.json

@@ -23,8 +23,9 @@
         "phpstan/phpstan": "^1.4",
         "symfony/framework-bundle": "^4.4|^5.0|^6.0",
         "symfony/phpunit-bridge": "^5.3",
+        "symfony/process": "^4.4|^5.0|^6.0",
         "symfony/var-dumper": "^4.4|^5.0|^6.0",
-        "zenstruck/console-test": "^1.2"
+        "zenstruck/console-test": "^1.3"
     },
     "suggest": {
         "phpdocumentor/reflection-docblock": "To configure your Command's via class docblock."

phpstan-baseline.neon

@@ -1,97 +1,32 @@
 parameters:
 	ignoreErrors:
 		-
-			message: "#^Method Zenstruck\\\\Console\\\\Tests\\\\Fixture\\\\Command\\\\DocblockCommand\\:\\:docblock\\(\\) should return Zenstruck\\\\Console\\\\Configuration\\\\DocblockConfiguration\\<static\\(Zenstruck\\\\Console\\\\Tests\\\\Fixture\\\\Command\\\\DocblockCommand\\)\\> but returns Zenstruck\\\\Console\\\\Configuration\\\\DocblockConfiguration\\<Symfony\\\\Component\\\\Console\\\\Command\\\\Command\\>\\.$#"
+			message: "#^Method Zenstruck\\\\Console\\\\Attribute\\\\Argument\\:\\:__construct\\(\\) has parameter \\$default with no value type specified in iterable type array\\.$#"
 			count: 1
-			path: tests/Fixture/Command/DocblockCommand.php
+			path: src/Attribute/Argument.php
 
 		-
-			message: "#^Parameter \\#1 \\$value of static method Zenstruck\\\\Callback\\:\\:createFor\\(\\) expects \\(callable\\(\\)\\: mixed\\)\\|ReflectionFunction, \\$this\\(Zenstruck\\\\Console\\\\Tests\\\\Fixture\\\\Command\\\\InvokableCommand\\) given\\.$#"
+			message: "#^Property Zenstruck\\\\Console\\\\Attribute\\\\Argument\\:\\:\\$default type has no value type specified in iterable type array\\.$#"
 			count: 1
-			path: tests/Fixture/Command/InvokableCommand.php
+			path: src/Attribute/Argument.php
 
 		-
-			message: "#^Method Zenstruck\\\\Console\\\\Tests\\\\Fixture\\\\Command\\\\ServiceCommand\\:\\:__invoke\\(\\) has parameter \\$none with no type specified\\.$#"
+			message: "#^Method Zenstruck\\\\Console\\\\Attribute\\\\Option\\:\\:__construct\\(\\) has parameter \\$default with no value type specified in iterable type array\\.$#"
 			count: 1
-			path: tests/Fixture/Command/ServiceCommand.php
+			path: src/Attribute/Option.php
 
 		-
-			message: "#^Method Zenstruck\\\\Console\\\\Tests\\\\Fixture\\\\CustomIO\\:\\:success\\(\\) has parameter \\$message with no type specified\\.$#"
+			message: "#^Method Zenstruck\\\\Console\\\\Attribute\\\\Option\\:\\:__construct\\(\\) has parameter \\$shortcut with no value type specified in iterable type array\\.$#"
 			count: 1
-			path: tests/Fixture/CustomIO.php
+			path: src/Attribute/Option.php
 
 		-
-			message: "#^Method Zenstruck\\\\Console\\\\Tests\\\\Fixture\\\\Kernel\\:\\:configureRoutes\\(\\) has parameter \\$routes with no type specified\\.$#"
+			message: "#^Property Zenstruck\\\\Console\\\\Attribute\\\\Option\\:\\:\\$default type has no value type specified in iterable type array\\.$#"
 			count: 1
-			path: tests/Fixture/Kernel.php
+			path: src/Attribute/Option.php
 
 		-
-			message: "#^Cannot call method addSubscriber\\(\\) on object\\|null\\.$#"
-			count: 2
-			path: tests/Integration/EventListener/CommandSummarySubscriberTest.php
-
-		-
-			message: "#^Parameter \\#1 \\$description of method Symfony\\\\Component\\\\Console\\\\Command\\\\Command\\:\\:setDescription\\(\\) expects string, string\\|null given\\.$#"
-			count: 1
-			path: tests/Unit/DocblockConfigureTest.php
-
-		-
-			message: "#^Parameter \\#2 \\$haystack of method PHPUnit\\\\Framework\\\\Assert\\:\\:assertStringContainsString\\(\\) expects string, string\\|null given\\.$#"
-			count: 1
-			path: tests/Unit/DocblockConfigureTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/IOTest\\.php\\:116\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/IOTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/IOTest\\.php\\:137\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/IOTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/IOTest\\.php\\:90\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/IOTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:110\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/InvokableTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:125\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/InvokableTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:143\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/InvokableTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:143\\:\\:__invoke\\(\\) has parameter \\$none with no type specified\\.$#"
-			count: 1
-			path: tests/Unit/InvokableTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:176\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/InvokableTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:198\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/InvokableTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:33\\:\\:__invoke\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: tests/Unit/InvokableTest.php
-
-		-
-			message: "#^Method class@anonymous/tests/Unit/InvokableTest\\.php\\:33\\:\\:__invoke\\(\\) has parameter \\$none with no type specified\\.$#"
+			message: "#^Property Zenstruck\\\\Console\\\\Attribute\\\\Option\\:\\:\\$shortcut type has no value type specified in iterable type array\\.$#"
 			count: 1
-			path: tests/Unit/InvokableTest.php
+			path: src/Attribute/Option.php
 

phpunit.xml.dist

@@ -13,6 +13,7 @@
         <env name="SYMFONY_DEPRECATIONS_HELPER" value="max[self]=0&amp;max[direct]=0"/>
         <env name="KERNEL_CLASS" value="Zenstruck\Console\Tests\Fixture\Kernel" />
         <env name="SHELL_VERBOSITY" value="-1"/>
+        <env name="COLUMNS" value="120" />
     </php>
 
     <testsuites>

src/Attribute/Argument.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Zenstruck\Console\Attribute;
+
+use Symfony\Component\Console\Input\InputArgument;
+
+/**
+ * @author Kevin Bond <kevinbond@gmail.com>
+ */
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
+final class Argument
+{
+    /**
+     * @see InputArgument::__construct()
+     */
+    public function __construct(
+        private string $name,
+        private ?int $mode = null,
+        private string $description = '',
+        private string|bool|int|float|array|null $default = null,
+    ) {
+    }
+
+    /**
+     * @internal
+     *
+     * @return mixed[]
+     */
+    public function values(): array
+    {
+        return [$this->name, $this->mode, $this->description, $this->default];
+    }
+}