From 7923bcacc558946bd9931f6f3214bee81aee27c5 Mon Sep 17 00:00:00 2001 From: Dave Smith Date: Tue, 30 Jan 2024 14:55:13 +0000 Subject: [PATCH 1/3] Update docs to avoid recommending anti-pattern --- lib/README.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/lib/README.md b/lib/README.md index 2c8e6cb2385d62..505dfab418e455 100644 --- a/lib/README.md +++ b/lib/README.md @@ -12,9 +12,9 @@ The following documentation is intended to act as a guide only. If you're unsure To make it easier for contributors to identify features that should be merged into Core and those that can be deleted, Gutenberg uses the following file structure for its PHP code: -- `lib/experimental` - Experimental features that exist only in the plugin. They should not be merged into Core. -- `lib/compat/wordpress-X.Y` - Stable features that are intended to be merged into Core in a future `X.Y` release, or that were previously merged to Core in the `X.Y` release and remain in the plugin for backwards compatibility when running the plugin on older versions of WordPress. -- `lib/compat/plugin` - Features for backwards compatibility for the plugin consumers. These files don't need to be merged into Core and should have a timeline for when they should be removed from the plugin. +- `lib/experimental` - Experimental features that exist only in the plugin. They should not be merged into Core. +- `lib/compat/wordpress-X.Y` - Stable features that are intended to be merged into Core in a future `X.Y` release, or that were previously merged to Core in the `X.Y` release and remain in the plugin for backwards compatibility when running the plugin on older versions of WordPress. +- `lib/compat/plugin` - Features for backwards compatibility for the plugin consumers. These files don't need to be merged into Core and should have a timeline for when they should be removed from the plugin. Files at the root of `/lib` are generally considered to contain "evergreen" code. Such code is both fundamental to the proper functioning of the plugin, and also so often updated that versioning it between WordPress releases is not practical. Changes to these files are merged into Core as required. @@ -60,6 +60,8 @@ function wp_get_something_useful() { Plugin code that is stable and expected to be merged "as-is" into Core in the near future can use the `wp_` prefix for functions or a `WP_` prefix for classes. +#### Avoiding duplicate declarations + When doing so, care must be taken to ensure that no duplicate declarations to create functions or classes exist between Gutenberg and WordPress core code. A quick codebase search will also help you know if your new names are unique. Wrapping such code in `class_exists()` and `function_exists()` checks should be used to ensure it executes in the plugin up until it is merged to Core, or when running the plugin on older versions of WordPress. @@ -87,18 +89,27 @@ Or for classes: * @since 6.3.0 */ if ( ! class_exists( 'WP_A_Stable_Class' ) ) { - /** - * A very stable class that does something. - * - * @since 6.3.0 - */ + // Do not invert this pattern with an early `return`. + // See below for details... class WP_A_Stable_Class { ... } } - ``` Wrapping code in `class_exists()` and `function_exists()` is usually inappropriate for evergreen code, or any plugin code that we expect to undergo constant change between WordPress releases, because it would prevent the latest versions of the code from being used. For example, the statement `class_exists( 'WP_Theme_JSON' )` would return `true` because the class already exists in Core. +The early return pattern shown below is considered an **anti-pattern** because it is not supported by older versions of PHP and can cause [unexpected side effects](https://github.com/WordPress/gutenberg/pull/58429#issuecomment-1916670097): + +```php +/** + * ANTI-PATTERN + * DO NOT COPY! + * + */ +if ( class_exists( 'WP_A_Stable_Class' ) ) { + return; // do not do this. +} +``` + 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 @@ -175,6 +186,7 @@ add_action( 'init', 'wp_register_navigation_cpt' ); ``` ### Requiring files in lib/load.php + Should the load order allow it, try to group imports according to WordPress release, then feature. It'll help everyone to quickly recognise the files that belong to specific WordPress releases. Existing comments in `lib/load.php` should act as a guide. From 7cb237519a914dc4199f0ae57479e2050c1ac08d Mon Sep 17 00:00:00 2001 From: Dave Smith Date: Tue, 6 Feb 2024 18:45:55 +0000 Subject: [PATCH 2/3] Update lib/README.md Co-authored-by: Anton Vlasenko <43744263+anton-vlasenko@users.noreply.github.com> --- lib/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/README.md b/lib/README.md index 505dfab418e455..3d21cb27ba0883 100644 --- a/lib/README.md +++ b/lib/README.md @@ -12,9 +12,9 @@ The following documentation is intended to act as a guide only. If you're unsure To make it easier for contributors to identify features that should be merged into Core and those that can be deleted, Gutenberg uses the following file structure for its PHP code: -- `lib/experimental` - Experimental features that exist only in the plugin. They should not be merged into Core. -- `lib/compat/wordpress-X.Y` - Stable features that are intended to be merged into Core in a future `X.Y` release, or that were previously merged to Core in the `X.Y` release and remain in the plugin for backwards compatibility when running the plugin on older versions of WordPress. -- `lib/compat/plugin` - Features for backwards compatibility for the plugin consumers. These files don't need to be merged into Core and should have a timeline for when they should be removed from the plugin. +- `lib/experimental` - Experimental features that exist only in the plugin. They should not be merged into Core. +- `lib/compat/wordpress-X.Y` - Stable features that are intended to be merged into Core in a future `X.Y` release, or that were previously merged to Core in the `X.Y` release and remain in the plugin for backwards compatibility when running the plugin on older versions of WordPress. +- `lib/compat/plugin` - Features for backwards compatibility for the plugin consumers. These files don't need to be merged into Core and should have a timeline for when they should be removed from the plugin. Files at the root of `/lib` are generally considered to contain "evergreen" code. Such code is both fundamental to the proper functioning of the plugin, and also so often updated that versioning it between WordPress releases is not practical. Changes to these files are merged into Core as required. From 3d2747690fdc6c53b9cd882ba9950c0807b2bdf5 Mon Sep 17 00:00:00 2001 From: Dave Smith Date: Wed, 7 Feb 2024 10:37:11 +0000 Subject: [PATCH 3/3] Update lib/README.md Co-authored-by: Anton Vlasenko <43744263+anton-vlasenko@users.noreply.github.com> --- lib/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/README.md b/lib/README.md index 3d21cb27ba0883..cbc86d67a18f7e 100644 --- a/lib/README.md +++ b/lib/README.md @@ -97,8 +97,7 @@ if ( ! class_exists( 'WP_A_Stable_Class' ) ) { Wrapping code in `class_exists()` and `function_exists()` is usually inappropriate for evergreen code, or any plugin code that we expect to undergo constant change between WordPress releases, because it would prevent the latest versions of the code from being used. For example, the statement `class_exists( 'WP_Theme_JSON' )` would return `true` because the class already exists in Core. -The early return pattern shown below is considered an **anti-pattern** because it is not supported by older versions of PHP and can cause [unexpected side effects](https://github.com/WordPress/gutenberg/pull/58429#issuecomment-1916670097): - +The `return` operator is considered an anti-pattern in the context provided below because it [does not halt](https://www.php.net/manual/en/function.return.php#112515) the parsing of the PHP script and can cause [unexpected side effects](https://github.com/WordPress/gutenberg/pull/58429#issuecomment-1916670097): ```php /** * ANTI-PATTERN