Add wp block convert and wp block conversion-support for server-side block conversion

.distignore

@@ -10,6 +10,7 @@ phpcs.xml.dist
 phpunit.xml.dist
 bin/
 features/
+phpstan/
 utils/
 *.zip
 *.tar.gz

README.md

@@ -38,6 +38,129 @@ wp block
 
 
 
+### wp block convert
+
+Converts HTML to block markup.
+
+~~~
+wp block convert [<html>] [--file=<file>]
+~~~
+
+Markup that no block claims is kept verbatim inside a Custom HTML block.
+Input that already contains block delimiters is parsed as blocks rather
+than converted again.
+
+The result is printed as-is and is not sanitized. Run it through the
+usual filters, for example by saving it with `wp post update`, before
+storing it as post content.
+
+Requires an active Gutenberg build from
+https://github.com/WordPress/gutenberg/pull/82013.
+
+**OPTIONS**
+
+	[<html>]
+		The HTML to convert. Reads from --file or STDIN when omitted.
+
+	[--file=<file>]
+		Read the HTML from a file instead of the argument.
+
+**EXAMPLES**
+
+    # Convert HTML passed as an argument
+    $ wp block convert '<h2>Title</h2><p>Text</p>'
+    <!-- wp:heading -->
+    <h2 class="wp-block-heading">Title</h2>
+    <!-- /wp:heading -->
+
+    <!-- wp:paragraph -->
+    <p>Text</p>
+    <!-- /wp:paragraph -->
+
+    # Convert the contents of a file
+    $ wp block convert --file=page.html
+
+    # Convert HTML from STDIN
+    $ cat page.html | wp block convert
+
+    # Convert a post's content in place
+    $ wp post get 123 --field=post_content | wp block convert | wp post update 123 -
+
+
+
+### wp block conversion-support
+
+Lists the blocks a server-side conversion can produce.
+
+~~~
+wp block conversion-support [--support=<support>] [--field=<field>] [--fields=<fields>] [--format=<format>]
+~~~
+
+Reports one row per block. The `support` column is one of:
+
+* converts: produced from any markup the block matches.
+* conditional: produced only from markup the block can save back.
+* declines: deliberately not produced by a server-side conversion.
+
+Requires an active Gutenberg build from
+https://github.com/WordPress/gutenberg/pull/82013.
+
+**OPTIONS**
+
+	[--support=<support>]
+		Only list blocks with this level of support.
+		---
+		options:
+		  - converts
+		  - conditional
+		  - declines
+		---
+
+	[--field=<field>]
+		Prints the value of a single field for each block.
+
+	[--fields=<fields>]
+		Limit the output to specific fields.
+
+	[--format=<format>]
+		Render output in a particular format.
+		---
+		default: table
+		options:
+		  - table
+		  - csv
+		  - json
+		  - count
+		  - yaml
+		---
+
+**AVAILABLE FIELDS**
+
+These fields will be displayed by default for each block:
+
+* name
+* support
+
+**EXAMPLES**
+
+    # List what a conversion can produce
+    $ wp block conversion-support
+    +----------------+-------------+
+    | name           | support     |
+    +----------------+-------------+
+    | core/heading   | converts    |
+    | core/paragraph | converts    |
+    | core/table     | declines    |
+    +----------------+-------------+
+
+    # List only the blocks that decline conversion
+    $ wp block conversion-support --support=declines --field=name
+
+    # Get the support map as JSON
+    $ wp block conversion-support --format=json
+
+
+
 ### wp block type
 
 Retrieves details on registered block types.

block-command.php

@@ -54,3 +54,8 @@
 WP_CLI::add_command( 'block binding', WP_CLI\Block\Block_Binding_Command::class, [ 'before_invoke' => $wpcli_block_before_invoke_6_5 ] );
 WP_CLI::add_command( 'block template', WP_CLI\Block\Block_Template_Command::class, [ 'before_invoke' => $wpcli_block_before_invoke_5_9 ] );
 WP_CLI::add_command( 'block synced-pattern', WP_CLI\Block\Block_Synced_Pattern_Command::class, [ 'before_invoke' => $wpcli_block_before_invoke_5_0 ] );
+
+// Server-side block conversion, provided by https://github.com/WordPress/gutenberg/pull/82013.
+// The commands check for the conversion functions themselves on top of the version gate.
+WP_CLI::add_command( 'block convert', [ WP_CLI\Block\Block_Conversion_Command::class, 'convert' ], [ 'before_invoke' => $wpcli_block_before_invoke_5_0 ] );
+WP_CLI::add_command( 'block conversion-support', [ WP_CLI\Block\Block_Conversion_Command::class, 'conversion_support' ], [ 'before_invoke' => $wpcli_block_before_invoke_5_0 ] );

composer.json

@@ -29,6 +29,8 @@
     "bundled": true,
     "commands": [
       "block",
+      "block convert",
+      "block conversion-support",
       "block type",
       "block type exists",
       "block type list",

features/block-convert.feature

@@ -0,0 +1,162 @@
+Feature: Server-side block conversion commands
+
+  # The conversion functions ship with the Gutenberg build from
+  # https://github.com/WordPress/gutenberg/pull/82013 and are not part of any
+  # released WordPress or Gutenberg version yet, so on a plain install every
+  # command fails with the same error.
+
+  @require-wp-5.0
+  Scenario: Convert fails without the server-side block conversion
+    Given a WP install
+
+    When I try `wp block convert '<p>Text</p>'`
+    Then STDERR should be:
+      """
+      Error: Server-side block conversion is not available. Activate the Gutenberg plugin from https://github.com/WordPress/gutenberg/pull/82013.
+      """
+    And STDOUT should be empty
+    And the return code should be 1
+
+  @require-wp-5.0
+  Scenario: Conversion support fails without the server-side block conversion
+    Given a WP install
+
+    When I try `wp block conversion-support`
+    Then STDERR should be:
+      """
+      Error: Server-side block conversion is not available. Activate the Gutenberg plugin from https://github.com/WordPress/gutenberg/pull/82013.
+      """
+    And STDOUT should be empty
+    And the return code should be 1
+
+  # The scenarios below need a Gutenberg build from that pull request, which
+  # CI cannot install, so they are tagged @broken and `composer behat` skips
+  # them. To run them locally:
+  #
+  # 1. Build the plugin zip from the `try/13163-php-block-conversion` branch
+  #    (`npm run build:plugin-zip` in a Gutenberg checkout).
+  # 2. Copy it to `gutenberg.zip` in the root of this package. Git ignores it.
+  # 3. Prepare the test database once with `composer prepare-tests`.
+  # 4. Run the scenarios by tag, bypassing the @broken exclusion:
+  #
+  #        vendor/bin/behat --tags=@broken features/block-convert.feature
+  #
+  # Each scenario installs the zip with `wp plugin install gutenberg.zip --activate`.
+
+  @broken
+  Scenario: Convert HTML passed as an argument
+    Given a WP install
+    And I run `wp plugin install {PROJECT_DIR}/gutenberg.zip --activate`
+
+    When I run `wp block convert '<h2>Title</h2><p>Text</p>'`
+    Then STDOUT should contain:
+      """
+      <!-- wp:heading -->
+      """
+    And STDOUT should contain:
+      """
+      <!-- wp:paragraph -->
+      """
+    And STDOUT should contain:
+      """
+      <p>Text</p>
+      """
+    And STDERR should be empty
+
+  @broken
+  Scenario: Convert HTML from STDIN and from a file
+    Given a WP install
+    And I run `wp plugin install {PROJECT_DIR}/gutenberg.zip --activate`
+    And a page.html file:
+      """
+      <h2>Title</h2>
+      <p>Text</p>
+      """
+
+    When I run `cat page.html | wp block convert`
+    Then STDOUT should contain:
+      """
+      <!-- wp:heading -->
+      """
+    And STDOUT should contain:
+      """
+      <!-- wp:paragraph -->
+      """
+
+    When I run `wp block convert --file=page.html`
+    Then STDOUT should contain:
+      """
+      <!-- wp:heading -->
+      """
+    And STDOUT should contain:
+      """
+      <!-- wp:paragraph -->
+      """
+
+    When I try `wp block convert --file=missing.html`
+    Then STDERR should contain:
+      """
+      Error: File 'missing.html' does not exist or is not readable.
+      """
+    And the return code should be 1
+
+    When I try `wp block convert '<p>Text</p>' --file=page.html`
+    Then STDERR should contain:
+      """
+      Error: Pass the HTML either as an argument or with --file, not both.
+      """
+    And the return code should be 1
+
+    When I try `wp block convert < /dev/null`
+    Then STDERR should contain:
+      """
+      Error: No HTML given. Pass it as an argument, with --file, or on STDIN.
+      """
+    And the return code should be 1
+
+  @broken
+  Scenario: Existing block markup is left alone and unknown markup becomes a Custom HTML block
+    Given a WP install
+    And I run `wp plugin install {PROJECT_DIR}/gutenberg.zip --activate`
+
+    When I run `wp block convert '<!-- wp:paragraph --><p>Text</p><!-- /wp:paragraph -->'`
+    Then STDOUT should be:
+      """
+      <!-- wp:paragraph --><p>Text</p><!-- /wp:paragraph -->
+      """
+
+    When I run `wp block convert '<marquee>Text</marquee>'`
+    Then STDOUT should contain:
+      """
+      <!-- wp:html -->
+      """
+
+  @broken
+  Scenario: List the blocks a conversion can produce
+    Given a WP install
+    And I run `wp plugin install {PROJECT_DIR}/gutenberg.zip --activate`
+
+    When I run `wp block conversion-support`
+    Then STDOUT should be a table containing rows:
+      | name           | support  |
+      | core/paragraph | converts |
+      | core/table     | declines |
+
+    When I run `wp block conversion-support --support=declines --field=name`
+    Then STDOUT should contain:
+      """
+      core/table
+      """
+    And STDOUT should not contain:
+      """
+      core/paragraph
+      """
+
+    When I run `wp block conversion-support --format=json`
+    Then STDOUT should contain:
+      """
+      {"name":"core\/paragraph","support":"converts"}
+      """
+
+    When I run `wp block conversion-support --format=count`
+    Then STDOUT should be a number

phpcs.xml.dist

@@ -4,6 +4,8 @@
 
 	<!-- What to scan. -->
 	<file>.</file>
+	<!-- PHPStan stubs for functions provided by other packages. -->
+	<exclude-pattern>*/phpstan/*</exclude-pattern>
 
 	<!-- Show progress. -->
 	<arg value="p"/>

phpstan.neon.dist

@@ -7,6 +7,7 @@ parameters:
     - vendor/wp-cli/wp-cli/php
   scanFiles:
     - vendor/php-stubs/wordpress-stubs/wordpress-stubs.php
+    - phpstan/gutenberg-block-conversion-stubs.php
   treatPhpDocTypesAsCertain: false
   ignoreErrors:
     # Standard WP-CLI ignores (same as entity-command)

phpstan/gutenberg-block-conversion-stubs.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * PHPStan stubs for the server-side block conversion from
+ * https://github.com/WordPress/gutenberg/pull/82013.
+ *
+ * The functions only exist while a Gutenberg build from that pull request is
+ * active, so `wp block convert` and `wp block conversion-support` check for
+ * them at runtime. This file gives PHPStan their signatures.
+ */
+
+/**
+ * Converts HTML into blocks.
+ *
+ * @param string $html HTML to convert.
+ * @return array<int, array<string, mixed>> Parsed block arrays, in the shape returned by `parse_blocks()`.
+ */
+function gutenberg_html_to_blocks( $html ) {}
+
+/**
+ * Converts HTML into serialized block markup.
+ *
+ * @param string $html HTML to convert.
+ * @return string Block markup.
+ */
+function gutenberg_html_to_block_markup( $html ) {}
+
+/**
+ * Reports which blocks a server-side conversion can produce.
+ *
+ * @return array{converts: string[], conditional: string[], declines: string[]}
+ */
+function gutenberg_get_block_conversion_support() {}