Method Tools

Maintenance tools for WordPress sites built on Method. Each tool gets a tab under Tools → Method Tools and, if it rewrites content, a WP-CLI command.

Included tools:

• Accordion Converter — converts core/accordion blocks to method/accordion blocks, or the reverse.

Requirements: WordPress 6.0+, PHP 7.4+, and the manage_options capability (you can change this with the method_tools_capability filter). Tested on WordPress 6.0.17 (MariaDB), 6.8.3 and 7.1.3, with Method 2.0.0-beta27.

Install

Upload the method-tools folder to wp-content/plugins/ and activate it. The plugin header includes GitHub Plugin URI: https://github.com/pixelwatt/method-tools, so Git Updater can deliver updates once that repository exists.

Accordion Converter

The converter works directly on the raw block markup, so it does not depend on either block being registered. That means it runs on WordPress versions older than 6.9, where core/accordion doesn't exist yet. For example, content staged on a 6.9 site and imported into a 6.8 site can be converted to Method accordions.

Workflow

1. Choose a Direction, the post types and statuses to include, and optionally an ID list to include or exclude.
   • The available post types are every type that uses the block editor, plus patterns, templates, template parts and navigation.
   • Templates and template parts are included only if they've been customized and saved to the database. Theme files are not changed.
2. Click Scan (dry run). Nothing is saved. You see each affected post, how many accordions and items it has, and any notes.
3. Click Convert N posts. Each post is saved through wp_update_post(), so a revision is created and save_post hooks run as usual. The previous content is backed up first.
4. Run history lets you restore an entire run. A restore only touches posts that still have exactly the content the run wrote. Posts edited since the run are skipped, and you can force them if needed.

WP-CLI equivalents:

wp method-tools list
wp method-tools run accordion-converter --direction=core-to-method --post_type=page --status=publish,draft --dry-run
wp method-tools run accordion-converter --direction=core-to-method --include=12,48
wp method-tools runs
wp method-tools restore <run-id> [--force]
wp method-tools discard <run-id>

How settings carry over

Output is the exact markup each block's save() produces:

• Method blocks: the markup Method beta27 saves.
• Core blocks: the markup WordPress 6.9 and 7.0 save. WordPress 7.1+ lists this markup as a deprecation and upgrades it silently the next time the post is saved.

Converted markup was validated with Gutenberg's own block validator for WordPress 6.9, 7.0 and trunk, and with Method's compiled block scripts (tests/gutenberg-harness.cjs).

Safety model

• Only accordions change. Posts are parsed with an offset-preserving copy of core's block grammar, and the converted accordions are spliced into the original string. Every other byte stays the same, including blocks with unusual attributes that a parse_blocks() → serialize_blocks() round trip would rewrite.

• Self-check before saving. The converted post must parse cleanly and keep exactly the same non-accordion blocks with the same attributes. If not, the post is refused.

• Unexpected markup is skipped, never guessed at. An accordion is left alone with a warning when:

  • text, images or iframes sit in its wrapper markup;
  • it contains unexpected blocks;
  • its JSON is invalid;
  • its heading markup isn't recognized.

  Posts with malformed block delimiters or invalid UTF-8 are refused outright.

• Saves:

  • kses is lifted only for the plugin's own write. Running kses on the whole post would strip unrelated markup, such as iframes added by a super admin, whenever the user running the tool lacks unfiltered_html.
  • Converted headings go through a wp_kses allow-list.
  • Restores only write backups whose HMAC signature, keyed with the site's auth salts, proves this plugin created them.

• Page templates. A stale _wp_page_template left over from a previous theme no longer blocks or half-completes a save. The stored template is left untouched.

Known Method behaviour to check after converting

• Duplicate panel IDs. Method numbers panel IDs collapse1, collapse2, … within each accordion, so two Method accordions on one page share IDs. The second accordion's toggles then open the first accordion's panels. The converter flags every post that ends up with more than one Method accordion.
• PHP notice from "type": "bool". method/accordion and method/accordion-item declare closed as "type": "bool". When closed is set, WordPress logs a rest_validate_value_from_schema notice on render with WP_DEBUG on. Core accordions default to all items closed, so converted accordions usually set closed. Changing the type to "boolean" in both block.json files fixes it, and doesn't affect saved markup.

Adding a tool

A content tool extends Method_Tools\Post_Tool. The base plugin provides the targeting form, dry run, batched apply, backups and restore, REST routes and WP-CLI command.

add_action( 'method_tools_register', function ( \Method_Tools\Plugin $plugin ) {
    $plugin->register( new My_Tool() );
} );

final class My_Tool extends \Method_Tools\Post_Tool {
    public function id() { return 'my-tool'; }
    public function label() { return 'My Tool'; }
    public function description() { return 'What it does.'; }
    public function option_fields() { return array(); }
    public function content_needles( array $options ) { return array( 'wp:method/thing' ); } // SQL LIKE prefilter
    public function transform( $content, array $options, $post ) {
        $result = new \Method_Tools\Transform_Result( $content );
        // …set $result->content / ->changed, ->bump( 'things' ), ->add( Transform_Result::WARNING, '…' )
        return $result;
    }
}

transform() must be pure, meaning it makes no writes. Building blocks:

• Method_Tools\Blocks\Block_Document — the offset-preserving parser.
• Block_Markup — editor-identical serialization helpers.

A tool that doesn't rewrite posts can extend Method_Tools\Tool and render its own panel.

Filters:

Data and uninstall

• Run history: the method_tools_runs option. It isn't autoloaded.
• Backups: the _method_tools_backup_{run} post meta, one row per converted post. You can delete a run's backups from Run history or with wp method-tools discard.

Deleting the plugin removes both on every site of a network. Revisions are not affected.

Tests

The tests live in tests/ and are excluded from release archives.

• edge-cases.php and convert-samples.php don't write anything: wp eval-file tests/edge-cases.php tests/fixtures/core-6.9-samples.json
• pipeline.php creates and deletes its own posts. Run it only on a disposable local site.
• gutenberg-harness.cjs validates converted markup with the real @wordpress/blocks and @wordpress/block-library for a pinned WordPress release, together with Method's compiled block scripts. Setup instructions are in its header.

The fixtures are core accordion markup produced by Gutenberg 6.9's own serializer.