Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs to avoid recommending early return PHP "anti-pattern" #58454

Merged
merged 3 commits into from
Feb 8, 2024
Merged

Update docs to avoid recommending early return PHP "anti-pattern" #58454

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7923bca
Update docs to avoid recommending anti-pattern
getdave Jan 30, 2024
7cb2375
Update lib/README.md
getdave Feb 6, 2024
3d27476
Update lib/README.md
getdave Feb 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions lib/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -87,18 +89,26 @@ 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 `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
* 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
Expand Down Expand Up @@ -175,6 +185,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.
Expand Down
Loading