Add info about Yaml configuration and the config converter

cookbooks/creating_a_context_configuration_extension.rst

@@ -223,20 +223,31 @@ the ``HelloWorldExtension`` key and configure our ``text`` and ``enable`` value.
 
 Finally, we need to load the ``HelloWorld\Context\HelloWorldContext`` into our suite.
 
-Here's the ``behat.yaml``:
-
-.. code-block:: yaml
-
-  default:
-    suites:
-      default:
-        contexts:
-          - FeatureContext
-          - HelloWorld\Context\HelloWorldContext
-    extensions:
-      HelloWorld\ServiceContainer\HelloWorldExtension:
-        text: 'Hi there!'
-        enable: true
+Here's the ``behat.php``:
+
+.. code-block:: php
+
+    <?php
+
+    use Behat\Config\Config;
+    use Behat\Config\Extension;
+    use Behat\Config\Profile;
+    use Behat\Config\Suite;
+    use FeatureContext;
+    use HelloWorld\Context\HelloWorldContext;
+    use HelloWorld\ServiceContainer\HelloWorldExtension;
+
+    return new Config()
+        ->withProfile(new Profile('default')
+            ->withExtension(new Extension(HelloWorldExtension::class, [
+                'text' => 'Hi there!',
+                'enable' => true,
+            ]))
+            ->withSuite(new Suite('default')
+                ->withContexts(
+                    FeatureContext::class,
+                    HelloWorldContext::class
+                )));
 
 And now a scenario like this one:
 

cookbooks/custom_formatter.rst

@@ -415,22 +415,31 @@ file.
 Integration in your project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You need to add the extension in your Behat configuration file (default is ``behat.yml``)
+You need to add the extension in your Behat configuration file (default is ``behat.php``)
 and configure it to use the formatter:
 
-.. code:: yaml
-
-   default:
-     extensions:
-       HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension: ~
+.. code:: php
 
-     formatters:
-       pretty: true
-       reviewdog: # "reviewdog" here is the "name" given in our formatter
-         # output_path is optional and handled directly by Behat
-         output_path: 'build/logs/behat'
-         # file_name is optional and a custom parameter that we inject into the printer
-         file_name: 'reviewdog-behat.json'
+    <?php
+
+    use Behat\Config\Config;
+    use Behat\Config\Extension;
+    use Behat\Config\Formatter\Formatter;
+    use Behat\Config\Formatter\PrettyFormatter;
+    use Behat\Config\Profile;
+    use HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension;
+
+    return new Config()
+        ->withProfile(new Profile('default')
+            ->withExtension(new Extension(ReviewdogFormatterExtension::class)));
+            ->withFormatter(new PrettyFormatter())
+            // "reviewdog" here is the "name" given in our formatter
+            ->withFormatter(new Formatter('reviewdog', [
+                // 'file_name' is optional and a custom parameter that we inject into the printer
+                'file_name' => 'reviewdog-behat.json',
+            ])
+                // outputPath is optional and handled directly by Behat
+                ->withOutputPath('build/logs/behat'))
 
 .. note::
 
@@ -445,23 +454,29 @@ You can activate the extension only when you specify a profile in your command (
 For example if you want the pretty formatter by default, but both progress and reviewdog on your CI,
 you can configure it like this:
 
-.. code:: yaml
-
-   default:
-     extensions:
-       HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension: ~
-
-     formatters:
-       pretty: true
-
-   ci:
-     formatters:
-       pretty: false
-       progress: true
-       reviewdog:
-         output_path: 'build/logs/behat'
-         file_name: 'reviewdog-behat.json'
+.. code:: php
 
+    <?php
+
+    use Behat\Config\Config;
+    use Behat\Config\Extension;
+    use Behat\Config\Formatter\Formatter;
+    use Behat\Config\Formatter\PrettyFormatter;
+    use Behat\Config\Formatter\ProgressFormatter;
+    use Behat\Config\Profile;
+    use HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension;
+
+    return new Config()
+        ->withProfile(new Profile('default')
+            ->withExtension(new Extension(ReviewdogFormatterExtension::class)))
+            ->withFormatter(new PrettyFormatter())
+        ->withProfile(new Profile('ci')
+            ->disableFormatter('pretty')
+            ->withFormatter(new ProgressFormatter())
+            ->withFormatter(new Formatter('reviewdog', [
+                'file_name' => 'reviewdog-behat.json',
+            ])
+                ->withOutputPath('build/logs/behat')));
 
 Enjoy!
 -------

user_guide/command_line_tool.rst

@@ -107,6 +107,8 @@ This is a summary of the usage of Behat in the command line:
           addition to exceptions.
       -h, --help
           Display this help message.
+      --convert-config
+          Convert the configuration to the PHP format.
       --config-reference
           Display the configuration reference.
       --debug

user_guide/command_line_tool/informative_output.rst

@@ -93,12 +93,4 @@ This can also be set for each profile using the PHP configuration:
         )
     ;
 
-Or the yaml configuration:
-
-.. code-block:: yaml
-
-    default:
-        definitions:
-            print_unused_definitions: true
-
 

user_guide/configuration.rst

@@ -8,6 +8,7 @@ profiles.
    :maxdepth: 2
 
    configuration/suites.rst
+   configuration/yaml_configuration.rst
 
 ``behat.php``
 -------------

user_guide/configuration/yaml_configuration.rst

@@ -0,0 +1,66 @@
+Yaml configuration
+==================
+
+Currently the preferred way to define the configuration for your Behat project
+is by using one or more files with PHP configuration.
+
+But historically this configuration could also be expressed in files in the Yaml
+format. This possibility is still available for now, and you can use it instead
+of PHP configuration in your projects - however it will likely be deprecated and
+removed in the future.
+
+Here is an example of how some configuration could look using a Yaml file:
+
+.. code-block:: yaml
+
+    imports:
+        - imported.yaml
+
+    default:
+        formatters:
+            progress: ~
+            junit: false
+        suites:
+            my_suite:
+                contexts:
+                    - MyContext
+                paths:
+                    - "one.feature"
+                filters:
+                    tags: "@run"
+        extensions:
+            MyCustomExtension: ~
+
+Converting your configuration
+-----------------------------
+
+If your project uses the legacy Yaml format for your configuration, you can easily
+convert them to the PHP format by using the built in config converter.
+
+To use it, just run:
+
+.. code-block:: bash
+
+    vendor/bin/behat --convert-config
+
+This will load the default config file loaded by your project and convert it from the
+Yaml format to the PHP format. It will also convert any config files that are imported
+by this main file. It will then remove the old Yaml files.
+
+We recommend carefully reviewing the generated config, particularly if you are using extensions,
+custom formatters, or have complex configuration files.
+
+If you want to convert any other config file which is not your default config file (for
+example a config file used in the CI environment), just load it with the ``-c``
+(or ``--config``) option like this:
+
+.. code-block:: bash
+
+    vendor/bin/behat --convert-config -c ci-behat.yml
+
+This will load the ``ci-behat.yml`` config file and convert it to the PHP format.
+
+.. note::
+
+    Behat needs to be able to load this config file before converting it, so it must be
+    a valid Behat config file.