gutenberg / lib / README.md

README.md in Gutenberg 23.6.2, at lib/README.md

204 lines 10.0 KB

Raw Download Zip

1	# Gutenberg PHP
2
3	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.
4
5	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.
6
7	During a WordPress release, new features, bugfixes and other changes are "synced" between the Gutenberg plugin and WordPress Core. Consistent naming and directory structures make this process easier by preventing naming conflicts and compartmentalizing release-specific code.
8
9	The following documentation is intended to act as a guide only. If you're unsure about naming or where to place new PHP files, please don't hesitate to ping other contributors on GitHub or ask in the #core-editor channel on [](https://make.wordpress.org/chat/WordPress Slack](https://make.wordpress.org/chat/](https://make.wordpress.org/chat/).
10
11	## File structure
12
13	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:
14
15	- `lib/experimental` - Experimental features that exist only in the plugin. They should not be merged into Core.
16	- `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.
17	- `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.
18
19	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.
20
21	## Best practices
22
23	There are a few best practices that should be observed when adding new files to the Gutenberg plugin.
24
25	### Using `gutenberg` suffixes/prefixes vs. `wp` prefixes
26
27	To avoid naming conflicts with WordPress Core and other plugins, the Gutenberg plugin uses the `gutenberg` identifier in many of its PHP classes and function names, e.g., `WP_Theme_JSON_Gutenberg` and `gutenberg_get_block_editor_settings`.
28
29	This is especially so for classes and functions whose functionality is ubiquitous and constantly being updated — so-called "evergreen" code. Anything related to `WP_Theme_JSON_Gutenberg` is a good example of this: this class controls the way Gutenberg processes and outputs global styles and much more, and its methods are called in many places. In every aspect of plugin functionality, we want plugin users to have access to the latest versions of these files, even if they are running an older version of WordPress.
30
31	```php
32	/**
33	* Returns something useful.
34	*
35	* @since 6.2.0 Updates to something even more useful.
36	* @since 6.3.0 Now more useful than ever.
37	*
38	* @return string Something useful.
39	*/
40	function gutenberg_get_something_useful() {
41	// ...
42	}
43	```
44
45	When porting new functions into Core, the function must be renamed to use the `wp_` prefix for functions or a `WP_` prefix for classes.
46
47	```php
48	/**
49	* Returns something useful.
50	*
51	* @since 6.2.0 Updates to something even more useful.
52	* @since 6.3.0 Now more useful than ever.
53	*
54	* @return string Something useful.
55	*/
56	function wp_get_something_useful() {
57	// ...
58	}
59	```
60
61	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.
62
63	#### Avoiding duplicate declarations
64
65	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.
66
67	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.
68
69	```php
70	if ( ! function_exists( 'wp_a_new_and_stable_feature' ) ) {
71	/**
72	* A very new and stable feature.
73	*
74	* @return string Something useful.
75	*/
76	function wp_a_new_and_stable_feature() {
77	// ...
78	}
79	}
80	```
81
82	Or for classes:
83
84	```php
85	/**
86	* WP_A_Stable_Class class
87	*
88	* @package WordPress
89	* @since 6.3.0
90	*/
91	if ( ! class_exists( 'WP_A_Stable_Class' ) ) {
92	// Do not invert this pattern with an early `return`.
93	// See below for details...
94	class WP_A_Stable_Class { ... }
95	}
96	```
97
98	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.
99
100	The `return` operator is considered an anti-pattern in the context provided below because it [](https://www.php.net/manual/en/function.return.php#112515does not halt](https://www.php.net/manual/en/function.return.php#112515](https://www.php.net/manual/en/function.return.php#112515) the parsing of the PHP script and can cause [](https://github.com/WordPress/gutenberg/pull/58429#issuecomment-1916670097unexpected side effects](https://github.com/WordPress/gutenberg/pull/58429#issuecomment-1916670097](https://github.com/WordPress/gutenberg/pull/58429#issuecomment-1916670097):
101	```php
102	/**
103	* ANTI-PATTERN
104	* DO NOT COPY!
105	*
106	*/
107	if ( class_exists( 'WP_A_Stable_Class' ) ) {
108	return; // do not do this.
109	}
110	```
111
112	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.
113
114	#### When not to use plugin-specific prefixes/suffixes
115
116	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.
117
118	`Gutenberg` prefixes/suffixes _should not_ be used in Core PHP code. When syncing `/lib` files to Core, plugin-specific prefixes/suffixes are generally replaced with their `WP_` or `wp_` equivalents manually.
119
120	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 [](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release/README.md#packages-releases-to-npm-and-wordpress-core-updatespublished as NPM packages](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release/README.md#packages-releases-to-npm-and-wordpress-core-updates](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release/README.md#packages-releases-to-npm-and-wordpress-core-updates), which Core consumes as NPM dependencies.
121
122	See [](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functionsblock naming conventions](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functions](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functions) for more information on block naming conventions.
123
124	As always, get in touch with your fellow contributors if you're unsure.
125
126	### Documentation and annotations
127
128	For every class, method and function in the plugin, refer to the [](https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/WordPress PHP documentation standards](https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/](https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/) when documenting your code.
129
130	It's particularly important to observe annotation standards, and `@since` descriptions that specify the target WordPress version, so that all contributors can easily identify what needs to be (or what already has been) merged to Core and when.
131
132	Developers should also write a brief note about _how_ their feature should be merged to Core, for example, which Core file or function should be patched.
133
134	Notes can be included in the doc comment.
135
136	This helps future developers know what to do when merging Gutenberg features into Core.
137
138	```php
139	/**
140	* Returns a navigation object for the given slug.
141	*
142	* Should live in `wp-includes/navigation.php` when merged to Core.
143	*
144	* @since 6.3.0
145	*
146	* @param string $slug
147	* @return WP_Navigation
148	*/
149	function wp_get_navigation( $slug ) { ... }
150	```
151
152	### Group PHP code by _feature_
153
154	Developers should organize PHP into files or folders by _feature_, not by _component_.
155
156	When defining a function that will be hooked, developers should call `add_action` and `add_filter` immediately after the function declaration.
157
158	These two practices make it easier for PHP code to start in one folder (e.g., `lib/experimental`) and eventually move to another using a simple `git mv`.
159
160	#### Good
161
162	```php
163	// lib/experimental/navigation.php
164
165	function wp_get_navigation( $slug ) { ... }
166
167	function wp_register_navigation_cpt() { ... }
168
169	add_action( 'init', 'wp_register_navigation_cpt' );
170	```
171
172	#### Not so good
173
174	```php
175	// lib/experimental/functions.php
176
177	function wp_get_navigation( $slug ) { ... }
178
179	// lib/experimental/post-types.php
180
181	function wp_register_navigation_cpt() { ... }
182
183	// lib/experimental/init.php
184	add_action( 'init', 'wp_register_navigation_cpt' );
185	```
186
187	### Requiring files in lib/load.php
188
189	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.
190
191	Existing comments in `lib/load.php` should act as a guide.
192
193	## When to sync changes to Gutenberg PHP with Core and vice versa
194
195	On open Gutenberg PRs, changes to certain files are flagged as requiring syncing (also called "backporting") to WordPress Core, for example, PHP files in `/lib` and PHP unit tests.
196
197	The CI checks will indicate whether you need to create a Core PR. If you do, you'll need to create a corresponding markdown file and place it within the appropriate release subdirectory in the [](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/Core backport changelog](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/).
198
199	For more information, please refer to the [](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/readme.mdCore backport changelog documentation](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/readme.md](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/readme.md).
200
201	So too, if you've made changes in WordPress Core to code that also lives in the Gutenberg plugin, these changes will need to be synced to Gutenberg. The relevant Gutenberg GitHub pull request should be labeled with the `Backport from WordPress Core` label.
202
203	If you're unsure, you can always ask for help in the #core-editor channel in [](https://make.wordpress.org/chat/WordPress Slack](https://make.wordpress.org/chat/](https://make.wordpress.org/chat/).
204