register_block_type_from_metadata does not allow full path to file as docs say it does

[coreyw]

From the source code comment:

Path to the JSON file with metadata definition for the block or path to the folder where the block.json file is located.

From ​docs:

$block_type (string) – path to the folder where the block.json file is located or full path to the metadata file if named differently.

Both of these sound like you could do register_block_type_from_metadata(__DIR__.'/custom-block.json', []). But this actually just ends up trying to test if DIR/custom-block.json/block.json exists.

[coreyw]

Sorry, just realized it does work as long as the filename ends in block.json. I had previously just tried block-name.json which did not work. But something like whatever-name-block.json will work. Maybe the docs and comment could be updated to include that requirement if that is the intention.

Providing register_block_type_from_metadata with the path to a custom named metadata file would search for path/to/metadata_file.json/block.json instead of correctly searching for path/to/metadata_file.json.

The following checks are now carried out:

• If the $file_or_folder path provided is a directory, or doesn't end in .json, search for $file_or_folder/block.json.
• Otherwise, search for the $file_or_folder path exactly as provided.

Trac ticket: https://core.trac.wordpress.org/ticket/53806

[costdev]

Local PHPUnit tests

[costdev]

As @coreyw mentioned, if the provided filename has block.json at the end, then it works.

However, the ​Docs specify or full path to the metadata file if named differently. This would suggest that any filename with .json should work, such as custom_metadata.json.

I've submitted a PR that is successful with the following local PHPUnit tests:

[costdev]

I've updated the PR to remove an irrelevant check for .json ending. All of the local PHPUnit tests still pass.

The following checks are now carried out:

• If the $file_or_folder path provided is a directory, or doesn't end in .json, search for $file_or_folder/block.json.
• Otherwise, search for the $file_or_folder path exactly as provided.

@costdev, thank you for looking at this issue. It was brought to my attention by @cr0ybot in the comment ​https://github.com/WordPress/gutenberg/issues/25188#issuecomment-916109577. I'm trying to confirm whether the documentation is incorrect or the implementation. The comment from @coreyworrell in the Trac ticket might be valid:

Sorry, just realized it does work as long as the filename ends in block.json. I had previously just tried block-name.json which did not work. But something like whatever-name-block.json will work. Maybe the docs and comment could be updated to include that requirement if that is the intention.

Great @gziolo! If a discussion about the documentation follows, I'd suggest that we maybe shouldn't force third party block developers to use a file ending in ...block.json? We could just assume that ending if an alternative isn't explicitly provided - unless of course there's other code that currently relies on that ending in all cases.

I located the PR in Gutenberg that added the handling which allows passing a full path (ending with block.json): ​https://github.com/WordPress/gutenberg/pull/22491. There is no discussion around that, it was driven by the convenience of providing a path to the file which was already computed in the code for core blocks 😄

Let me share some concerns I shared in another place regarding the name:

One thing that comes to my mind is integrations with the Plugin Directory or WP-CLI. A good example is the WP-CLI command to extract translations, it restricts processing to files that have block.json name:

​https://github.com/wp-cli/i18n-command/blob/49fb6d98ebd5cbe85c87a5efc3c0877be9e358d2/src/MakePotCommand.php#L641-L642

I don't remember how the Plugin Directory detects if the plugin contains blocks, but for sure it would be simpler if the presence of the block.json file in the source code would be the way to do it.

Regarding Plugins Directory, I'm talking about the automated section that lists blocks shipped with the plugin:

<img width="686" alt="Screen Shot 2021-09-10 at 09 50 53" src="​https://user-images.githubusercontent.com/699132/132819669-191450e5-0ab6-42e0-8c3c-91f716dbdbe2.png">

<img width="712" alt="Screen Shot 2021-09-10 at 09 52 06" src="​https://user-images.githubusercontent.com/699132/132819763-480a7539-500e-4f31-8c6f-46021ac75df1.png">
<img width="597" alt="Screen Shot 2021-09-10 at 09 52 27" src="​https://user-images.githubusercontent.com/699132/132819765-bf9a5466-f9e6-4459-8220-187b9eb29a9c.png">

@swissspidy, does the i18n command in WP-CLI detects only files named exactly block.json, or ending with block.json? What if we were to allow any name for block metadata files, could we teach WP-CLI command to discover them?

@tellyworth, a similar question related to Plugin Directory and Block Directory. How much does the name of the block metadata file impact how all accompanying tools work today? I'm mostly curious if the name block.json is mandatory or we can works with a wider set of options.

@swissspidy, does the i18n command in WP-CLI detects only files named exactly block.json, or ending with block.json? What if we were to allow any name for block metadata files, could we teach WP-CLI command to discover them?

Right now it strictly looks for block.json, nothing else:

​https://github.com/wp-cli/i18n-command/blob/01d6bd9c7933d67b87cc041620a4a5918914c633/src/MakePotCommand.php#L641-L642

You mentioned that line in ​your above comment yourself though 😄

We could change the WP-CLI command to scan _any_ JSON file though and then check every file whether it's a block file. That might slow down things a bit if you have tons of other JSON files, but would be the most convenient option.

We need to make decision before WP 5.9 beta 1 release. It looks like updating the documentation makes the most sense here. We can always relax the requirement as proposed in the PR later.

[costdev]

Alternative: Modify the DocBlock

[costdev]

53806.docs.diff modifies the DocBlock until a decision can be made about relaxing the requirements on filenames.

Relaxing the requirements may require changes in WP-CLI and possibly in the Plugin and Block directories.

[gziolo]

In 52012:

Docs: Clarify the path usage register_block_type_from_metadata

The filename passed with the first param must end with block.json.

Fixes #53806.
Props coreyw, costdev.

[gziolo]

Thank you @costdev. I landed your patch for the documentation of the function.