Upgrade docs

Author: veewee

README.md

@@ -72,7 +72,7 @@ You can specify a custom config filename and location in `composer.json` or in t
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     hooks_dir: ~
     hooks_preset: local
     git_hook_variables:
@@ -86,6 +86,12 @@ parameters:
     ascii:
         failed: grumphp-grumpy.txt
         succeeded: grumphp-happy.txt
+    parallel:
+        enabled: true
+        max_size: 32
+    fixer:
+        enabled: true
+        fix_by_default: false
     tasks: {}
     testsuites: []
     extensions: []
@@ -97,7 +103,7 @@ Details of the configuration are broken down into the following sections.
 - [Tasks](doc/tasks.md) – External tasks performing code validation and their respective configurations.
 - [TestSuites](doc/testsuites.md)
 - [Extensions](doc/extensions.md)
-- [Events](doc/events.md)
+- [Extending the TaskRunner](doc/runner.md)
 - [Conventions checker](doc/conventions.md)
 
 ## Commands

doc/conventions.md

@@ -45,6 +45,7 @@ Sample conventions grumphp file:
 # Convention grumphp.yml
 parameters:
   convention.git_commit_message_matchers: ['/.*/']
+grumphp:
   tasks:
     phpunit: ~
     git_commit_message:

doc/events.md

@@ -8,7 +8,7 @@ The configuration looks like this:
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     extensions:
         - My\Project\GrumPHPExtension
 ```

doc/extensions.md

@@ -3,7 +3,6 @@
 ## Table of content
 - [How can I bypass GrumPHP](#how-can-i-bypass-grumphp)
 - [Which parts of the code does GrumPHP scan?](#which-parts-of-the-code-does-grumphp-scan)
-- [Does GrumPHP support automatic fixing](#does-grumphp-support-automatic-fixing)
 - [Does GrumPHP support Windows](#does-grumphp-support-windows)
 - [How can I fix Composer require conflicts?](#how-can-i-fix-composer-require-conflicts)
 - [Why is the unstaged file state being used?](#why-is-the-unstaged-file-state-being-used)
@@ -34,14 +33,6 @@ that are able to check only the committed lines.
 [up](#table-of-content)
 
 
-## Does GrumPHP support automatic fixing
-
-No, he doesn't fix things for you. He wants you to have full
-control of the code you commit and not manipulate it in any way.
-
-[up](#table-of-content)
-
-
 ## Does GrumPHP support Windows
 
 Yes, he does. But there are some limitations.

doc/faq.md

@@ -2,7 +2,7 @@
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     hooks_dir: ~
     hooks_preset: local
     git_hook_variables:
@@ -17,6 +17,12 @@ parameters:
     ascii:
         failed: resource/grumphp-grumpy.txt
         succeeded: resource/grumphp-happy.txt
+    parallel:
+        enabled: true
+        max_size: 32
+    fixer:
+        enabled: true
+        fix_by_default: false
 ```
 
 **hooks_dir**
@@ -49,7 +55,7 @@ This parameter will allow you to customize git hooks templates. For now, those p
 Examples: 
 
 ```yaml
-parameters:
+grumphp:
     git_hook_variables:
         EXEC_GRUMPHP_COMMAND: '/usr/local/bin/php72'
         EXEC_GRUMPHP_COMMAND: 'lando php'
@@ -99,7 +105,7 @@ This parameter will display additional information at the end of a `success` *or
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
   additional_info: "\nTo get full documentation for the project!\nVisit https://docs.example.com\n"
 ```
 
@@ -126,7 +132,7 @@ from the list.
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     ascii:
         failed:
             - resource/grumphp-grumpy.txt
@@ -142,15 +148,70 @@ To disable all banners set ascii to `~`:
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     ascii: ~
 ```
 
 To disable a specific banner set ascii image path to `~`:
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     ascii:
         succeeded: ~
 ```
+
+
+**parallel**
+
+The parallel section can be used to configure how parallel execution works inside GrumPHP.
+You can specify following options:
+
+```
+grumphp:
+    parallel:
+        enabled: true
+        max_size: 32
+```
+
+**parallel.enabled**
+
+*Default: true*
+
+You can choose to enable or disable the parallel execution.
+If for some reason parallel tasks don't work for you, you can choose to run them in sequence.
+
+
+**parallel.max_size**
+
+*Default: 32*
+
+The maximum size of parallel threads.
+
+
+**fixer**
+
+GrumPHP provides a way of fixing your code. 
+However, we won't automatically commit the changes, so that you have the chance to review what has been fixed!
+You can configure how fixers work with following config:
+
+```
+grumphp:
+    fixer:
+        enabled: true
+        fix_by_default: false
+```
+
+**fixer.enabled**
+
+*Default: true*
+
+You can choose to enable or disable built-in fixers.
+
+
+**fixer.fix_by_default**
+
+*Default: false*
+
+In some contexts, like git commits, it is currently not possible to ask dynamic questions.
+Therefor, you can choose what the default answer will be.

doc/parameters.md

@@ -0,0 +1,112 @@
+# Extending the TaskRunner
+
+## Events
+
+It is possible to hook in to GrumPHP with events.
+Internally the Symfony event dispatcher is being used. 
+
+The following events are triggered during execution:
+
+| Event name              | Event class           | Triggered
+| ----------------------- | --------------------- | ----------
+| grumphp.task.run        | TaskEvent             | before a task is executed
+| grumphp.task.failed     | TaskFailedEvent       | when a task fails
+| grumphp.task.complete   | TaskEvent             | when a task succeeds
+| grumphp.runner.run      | RunnerEvent           | before the tasks are executed
+| grumphp.runner.failed   | RunnerFailedEvent     | when one task failed
+| grumphp.runner.complete | RunnerEvent           | when all tasks succeed
+| console.command         | ConsoleCommandEvent   | before a CLI command is ran
+| console.terminate       | ConsoleTerminateEvent | before a CLI command terminates
+| console.exception       | ConsoleExceptionEvent | when a CLI command throws an unhandled exception.
+
+Configure events just like you would in Symfony:
+
+```yml
+# grumphp.yml
+services:   
+    listener.some_listener:
+        class: MyNamespace\EventListener\MyListener
+        tags:
+            - { name: grumphp.event_listener, event: grumphp.runner.run }
+            - { name: grumphp.event_listener, event: grumphp.runner.run, method: customMethod, priority: 10 }
+    listener.some_subscriber:
+        class: MyNamespace\EventSubscriber\MySubscriber
+        tags:
+            - { name: grumphp.event_subscriber }
+```
+
+## Register a RunnerMiddleware
+
+A runner middleware can be used to adjust how a set of tasks is being executed.
+Examples are: resorting tasks, filtering tasks, logging, ....
+A runner middleware can be written by implementing the `RunnerMiddlewareInterface`.
+
+**Example:**
+
+```php
+use GrumPHP\Runner\Middleware\RunnerMiddlewareInterface;
+use GrumPHP\Collection\TaskResultCollection;
+use GrumPHP\Runner\TaskRunnerContext;
+
+class PassThroughMiddleware implements RunnerMiddlewareInterface
+{
+    /**
+     * @param callable(TaskRunnerContext $info): TaskResultCollection $next
+     */
+    public function handle(TaskRunnerContext $context, callable $next): TaskResultCollection
+    {
+        return $next($context);    
+    }
+}
+```
+
+Configuration:
+
+```yaml
+# grumphp.yaml
+
+services:
+    PassThroughMiddleware:
+        tags:
+            - { name: 'grumphp.runner_middleware', priority: 500 }
+```
+
+
+## Register a TaskHandlerMiddlewareInterface
+
+A task handler middleware can be used to adjust how to run one single task.
+Examples are: event dispatching, caching, logging, ...
+A runner middleware works Asynchronous in order to allow parallel execution and can be written by implementing the `TaskHandlerMiddlewareInterface`.
+You need to return an [amp](https://github.com/amphp/amp) promise object.
+
+**Example:**
+
+```php
+use GrumPHP\Runner\TaskHandler\Middleware\TaskHandlerMiddlewareInterface;
+use GrumPHP\Runner\TaskResultInterface;
+use GrumPHP\Runner\TaskRunnerContext;
+use GrumPHP\Task\TaskInterface;
+
+class PassThroughTaskHandlerMiddleware implements TaskHandlerMiddlewareInterface
+{
+    /**
+     * @param callable(TaskInterface, TaskRunnerContext): Promise<TaskResultInterface> $next
+     * @return Promise<TaskResultInterface>
+     */
+    public function handle(TaskInterface $task, TaskRunnerContext $runnercontext,callable $next): Promise
+    {
+        return $next($task, $runnercontext);    
+    }
+}
+```
+
+Configuration:
+
+```yaml
+# grumphp.yaml
+
+services:
+    PassThroughTaskHandlerMiddleware:
+        tags:
+            - { name: 'grumphp.task_handler', priority: 500 }
+```

doc/runner.md

@@ -5,7 +5,7 @@ To activate a task, it is sufficient to add an empty task configuration:
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     tasks:
         ant: ~
         atoum: ~
@@ -119,7 +119,7 @@ For example:
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     tasks:
         anytask:
             metadata:
@@ -185,7 +185,7 @@ interface TaskInterface
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     tasks:
         myConfigKey:
             config1: config-value
@@ -219,7 +219,7 @@ Configuration of the additional task will look like this:
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     tasks:
         phpcsfixer2:
             allow_risky: true

doc/tasks.md

@@ -5,7 +5,7 @@ It lives under the `ant` namespace and has following configurable parameters:
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     tasks:
         ant:
             build_file: ~

doc/tasks/ant.md

@@ -5,7 +5,7 @@ It lives under the `atoum` namespace and has the following configurable paramete
 
 ```yaml
 # grumphp.yml
-parameters:
+grumphp:
     tasks:
         atoum:
             config_file: .atoum.php