From 454b1254e6dc9e19b95334612dcc97c68bdbcb52 Mon Sep 17 00:00:00 2001 From: ramon Date: Tue, 17 Oct 2023 12:33:19 +1100 Subject: [PATCH 1/4] Updating lib README.md to include information about prefixes in block php code (hint: don't do it) --- lib/README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/lib/README.md b/lib/README.md index 8239ae40fd8efa..2ea43c0c31d6d2 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,4 +1,6 @@ -# Gutenberg PHP + # Gutenberg PHP + +This documentation is intended for developers who are contributing to the PHP code in the Gutenberg plugin, and pertains to files in the `lib` directory. The Gutenberg plugin is continuously enhancing existing features and creating new ones. Some features, once considered stable and useful, are merged into Core (the WordPress source code) during a WordPress release. Others remain in the plugin forever or are eventually removed as the minimum supported WordPress version changes. @@ -100,6 +102,14 @@ Wrapping code in `class_exists()` and `function_exists()` is usually inappropria When to use which prefix is a judgement call, but the general rule is that if you're unsure, use the `gutenberg` prefix because it will less likely give rise to naming conflicts. +#### When not to use plugin-specific prefixes/suffixes + +The above recommendations in relation to plugin-specific prefixes/suffixes are relevant only to files in the `lib` directory and only in the Gutenberg plugin. + +`Gutenberg` prefixes/suffixes _should not_ be used in Core PHP code. When synching `/lib` files to Core, plugin-specific prefixes/suffixes are generally replaced with their `WP_` equivalents manually. + +Accordingly, you should avoid using plugin-specific prefixes/suffixes in any block PHP code. Core blocks in the plugin are [published as NPM packages](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release.md#packages-releases-to-npm-and-wordpress-core-updates), which Core consumes as NPM dependencies. See [block naming conventions](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functions) for more information. + As always, get in touch with your fellow contributors if you're unsure. ### Documentation and annotations From 89f59239ee32957bace08f6b1a606ed9b803e717 Mon Sep 17 00:00:00 2001 From: ramon Date: Tue, 17 Oct 2023 13:07:52 +1100 Subject: [PATCH 2/4] Fixed formatting and added some clarification on prefix examples --- lib/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/README.md b/lib/README.md index 2ea43c0c31d6d2..a601fd57958e36 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,4 +1,4 @@ - # Gutenberg PHP +# Gutenberg PHP This documentation is intended for developers who are contributing to the PHP code in the Gutenberg plugin, and pertains to files in the `lib` directory. @@ -106,7 +106,7 @@ When to use which prefix is a judgement call, but the general rule is that if yo The above recommendations in relation to plugin-specific prefixes/suffixes are relevant only to files in the `lib` directory and only in the Gutenberg plugin. -`Gutenberg` prefixes/suffixes _should not_ be used in Core PHP code. When synching `/lib` files to Core, plugin-specific prefixes/suffixes are generally replaced with their `WP_` equivalents manually. +`Gutenberg` prefixes/suffixes _should not_ be used in Core PHP code. When synching `/lib` files to Core, plugin-specific prefixes/suffixes are generally replaced with their `WP_` or `wp_` equivalents manually. Accordingly, you should avoid using plugin-specific prefixes/suffixes in any block PHP code. Core blocks in the plugin are [published as NPM packages](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release.md#packages-releases-to-npm-and-wordpress-core-updates), which Core consumes as NPM dependencies. See [block naming conventions](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functions) for more information. From 518332ecc60cb1192c602bef66cf65aad1d1fd4d Mon Sep 17 00:00:00 2001 From: ramon Date: Tue, 17 Oct 2023 14:09:04 +1100 Subject: [PATCH 3/4] Adding info about webpack prefix transformation --- lib/README.md | 4 +++- packages/block-library/README.md | 12 ++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/lib/README.md b/lib/README.md index a601fd57958e36..0650d82bb36b63 100644 --- a/lib/README.md +++ b/lib/README.md @@ -108,7 +108,9 @@ The above recommendations in relation to plugin-specific prefixes/suffixes are r `Gutenberg` prefixes/suffixes _should not_ be used in Core PHP code. When synching `/lib` files to Core, plugin-specific prefixes/suffixes are generally replaced with their `WP_` or `wp_` equivalents manually. -Accordingly, you should avoid using plugin-specific prefixes/suffixes in any block PHP code. Core blocks in the plugin are [published as NPM packages](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release.md#packages-releases-to-npm-and-wordpress-core-updates), which Core consumes as NPM dependencies. See [block naming conventions](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functions) for more information. +Accordingly, unless required to run plugin-only code, you should avoid using plugin-specific prefixes/suffixes in any block PHP code. Core blocks in the plugin are [published as NPM packages](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release.md#packages-releases-to-npm-and-wordpress-core-updates), which Core consumes as NPM dependencies. + +See [block naming conventions](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functions) for more information on block naming conventions. As always, get in touch with your fellow contributors if you're unsure. diff --git a/packages/block-library/README.md b/packages/block-library/README.md index 695e2c935ef603..a47e055a7b2567 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -138,4 +138,16 @@ For the PHP functions declared in the `packages/block-library/src/my-block/index - `render_block_core_my_block` - `register_block_core_my_block` +#### Using plugin-specific prefixes/suffixes + +Unlike in [PHP code in the /lib directory](https://github.com/WordPress/gutenberg/blob/trunk/lib/README.md), you should generally avoid applying plugin-specific prefixes/suffixes such as `gutenberg_` to functions and other code in block PHP files. + +There are times, however, when blocks may need to use Gutenberg functions even when a Core-equivalent exists, for example, where a Gutenberg function relies on code that is only available in the plugin. + +In such cases, you can use the corresponding Core `wp_` function in the block PHP code, and add its name to [a list of prefixed functions in the Webpack configuration file](https://github.com/WordPress/gutenberg/blob/trunk/tools/webpack/blocks.js#L30). + +At build time, Webpack will search for `wp_` functions in that list and replace them with their `gutenberg_` equivalents. This process ensures that the plugin calls the `gutenberg_` functions, but the block will still call the Core `wp_` function when updates are back ported. + +Webpack assumes that, prefixes aside, the functions' names are identical: `wp_get_something_useful()` will be replaced with `gutenberg_get_something_useful()`. +

Code is Poetry.

From 07b4aac7861b6769d029a59285e7157b290e5268 Mon Sep 17 00:00:00 2001 From: ramon Date: Tue, 17 Oct 2023 14:28:09 +1100 Subject: [PATCH 4/4] npm run docs:build --- packages/block-library/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/block-library/README.md b/packages/block-library/README.md index a47e055a7b2567..25c5f9b52c71a4 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -146,7 +146,7 @@ There are times, however, when blocks may need to use Gutenberg functions even w In such cases, you can use the corresponding Core `wp_` function in the block PHP code, and add its name to [a list of prefixed functions in the Webpack configuration file](https://github.com/WordPress/gutenberg/blob/trunk/tools/webpack/blocks.js#L30). -At build time, Webpack will search for `wp_` functions in that list and replace them with their `gutenberg_` equivalents. This process ensures that the plugin calls the `gutenberg_` functions, but the block will still call the Core `wp_` function when updates are back ported. +At build time, Webpack will search for `wp_` functions in that list and replace them with their `gutenberg_` equivalents. This process ensures that the plugin calls the `gutenberg_` functions, but the block will still call the Core `wp_` function when updates are back ported. Webpack assumes that, prefixes aside, the functions' names are identical: `wp_get_something_useful()` will be replaced with `gutenberg_get_something_useful()`.