Plugin: Document the project structure and conventions used in the `lib` folder for PHP code #39603

noisysocks · 2022-03-21T07:07:54Z

What?

Adds some documentation about our PHP file structure and some best practices when writing PHP.

Why?

How?

I wrote it and have not proofread it at all. Please feel free to push changes. It's based off of the discussion in #33810 and my own gut feelings having merged PHP code from Gutenberg to Core a few times.

Testing Instructions

Read the file.

ramonjd · 2022-03-21T09:10:15Z

lib/README.md

+  are not ready to be merged to Core.
+- `lib/stable` - Stable features that exist only in the plugin. They could one
+  day be merged to Core, but not yet.
+- `lib/compat/wordpress-X.Y` - Stable features that are intended to be merged to


Not suggesting we do it right away, but do you think it'd be helpful for folks if expanded the compat topic at some stage? For example rationale, preferred naming conventions when extending classes, things to test, and so on.

There are also plenty of lessons to draw from PRs such as #38883 and #38671

Or maybe it's just too fuzzy an area to pin down. 🌪️

Yes absolutely. This should be a living document, like all our docs. I think we're still figuring a lot of that out, so it's hard to pen down right now. If you have any suggestions on things we can add now then please go ahead!

gziolo · 2022-03-21T14:21:22Z

@adamziel and @priethor, the first section is important as it covers the recommendations for the plugin project structure. This is something that drives how backporting to WordPress Core new features added in the Gutenberg Plugin.

noisysocks · 2022-03-21T22:12:31Z

Thanks for editing @ramonjd!

andrewserong

Thanks so much for starting this @noisysocks! I've just added a couple questions and a few tiny grammar suggestions, but this looks like a great start for a living document. Nice work!

lib/README.md

andrewserong · 2022-03-21T23:56:51Z

lib/README.md

+// lib/experimental/navigation/class-wp-navigation.php
+
+if ( class_exists( 'WP_Navigation' ) ) {
+	return;


Nice, TIL you can call return at root level in a PHP file (i.e. not inside a function) to skip execution 👍

PHP is pretty lawless.

tellthemachines

Thanks for writing this up! It's clear and detailed and will make everyone's life easier 🎉

lib/README.md

tellthemachines · 2022-03-22T00:03:39Z

lib/README.md

+
+### Note how your feature should look when merged to Core
+
+Developers should write a brief note about how their feature should be merged to Core, for example, which Core file or function should be patched. 


This will help so much with backports to Core ⭐

lib/README.md

Co-authored-by: Daniel Richards <[email protected]>

noisysocks · 2022-03-22T03:24:08Z

Thanks for the proofreading and suggestions! I'll link to this in the #core-editor chat for awareness. Again, let's iterate on this document. The team is still figuring out a lot of it 😀

youknowriad

Really cool addition, thanks Robert.

youknowriad · 2022-03-22T07:55:08Z

lib/README.md

+function gutenberg_get_navigation( $slug ) { ... }
+```
+
+### Group PHP code by _feature_


I actually think the lib/compat folder should group its code by "core" php file. Meaning if the change needs to happen in edit-form-blocks.php in 5.9, I'd put it in lib/compat/5.9/edit-form-blocks.php and for new files, try to come up with the best file name that will suite core merge. In practice, this is also very close to "group by feature".

The main goal is to simplify the work for the person back porting.

The downside of that though is that you can't move features in and out of "experimental" status e.g. using git mv lib/experimental/cool-new-feature.php lib/compat/wordpress-6.0/cool-new-feature.php. Not sure if we do this in practice, mind you 😀

ajlende · 2022-03-22T18:16:04Z

lib/README.md

+### Prefer the `wp` prefix
+
+For features that may be merged to Core, it's best to use a `wp_` prefix for functions or a `WP_` prefix for classes. 
+
+This applies to both experimental and stable features.
+
+Using the `wp_` prefix avoids us having to rename functions and classes from `gutenberg_` to `wp_` if the feature is merged to Core.
+
+Functions that are intended solely for the plugin, e.g., plugin infrastructure, should use the `gutenberg_` prefix.
+


Any thoughts on naming conventions for when we're updating a function from core?

For example, this change from https://github.com/WordPress/gutenberg/pull/38681/files?w=1#diff-089523f9c993d53f6f02926d28f7a80394d93740e7d16e47e17244547b2b8f5e. The core action is removed and the plugin action is added to replace it.

My intention with that change was that the gutenberg_ version of the function in the plugin would replace the wp_ version when porting to core. If we're reserving that prefix for things that should never go into core, we need another convention.

I don't think we really have a good strategy for this kind of stuff. We have a similar nightmare with WP_Theme_JSON needing Gutenberg_Theme_JSON and WP_Theme_JSON_5_9 😅

Using gutenberg_ seems fine to me, though it will get tricky when the new gutenberg_ function makes it into WP 6.0 and we want to make more changes in 6.1 We won't be able to tell whether the wp_ function that exists is the 5.9 version or the 6.0 version.

…ib` folder for PHP code (WordPress#39603) * Add lib/README.md * Subediting * Formatting * Fix typo Co-authored-by: Daniel Richards <[email protected]> * Clarify why we want the wp_ prefix * Reword sentence about hooking * Fix typo * Clarify that gutenberg_ is acceptable for infrastrucutre Co-authored-by: Ramon <[email protected]> Co-authored-by: Daniel Richards <[email protected]>

priethor · 2022-03-23T11:36:56Z

Thanks indeed! These changes helped me better understand the methodology and nuances of the PHP merging process!

Add lib/README.md

476964f

noisysocks requested review from gziolo and tellthemachines March 21, 2022 07:07

noisysocks requested review from TimothyBJacobs and spacedmonkey as code owners March 21, 2022 07:07

noisysocks added [Type] Developer Documentation Documentation for developers Gutenberg Plugin Issues or PRs related to Gutenberg Plugin management related efforts Developer Experience Ideas about improving block and theme developer experience labels Mar 21, 2022

Subediting

abbfb8b

ramonjd reviewed Mar 21, 2022

View reviewed changes

Formatting

d43351b

gziolo requested review from adamziel and priethor March 21, 2022 14:17

gziolo changed the title ~~Add lib/README.md~~ Plugin: Document the project structure and conventions used in the lib folder for PHP code Mar 21, 2022

andrewserong mentioned this pull request Mar 21, 2022

Consider renaming lib/compat PHP files and directories for evergreen overrides of core WordPress #38900

Open

andrewserong reviewed Mar 22, 2022

View reviewed changes

tellthemachines approved these changes Mar 22, 2022

View reviewed changes

talldan reviewed Mar 22, 2022

View reviewed changes

lib/README.md Outdated Show resolved Hide resolved

noisysocks and others added 5 commits March 22, 2022 14:15

Fix typo

be12599

Co-authored-by: Daniel Richards <[email protected]>

Clarify why we want the wp_ prefix

a32abde

Reword sentence about hooking

b3fe3f6

Fix typo

dcb2d7e

Clarify that gutenberg_ is acceptable for infrastrucutre

b2cdd80

noisysocks merged commit cb63e4e into trunk Mar 22, 2022

noisysocks deleted the add/PHP-readme branch March 22, 2022 03:22

github-actions bot added this to the Gutenberg 12.9 milestone Mar 22, 2022

gziolo mentioned this pull request Mar 22, 2022

Plugin: Seek ways to improve the process of backporting PHP code to WP core #33810

Closed

youknowriad reviewed Mar 22, 2022

View reviewed changes

ajlende reviewed Mar 22, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Plugin: Document the project structure and conventions used in the `lib` folder for PHP code #39603

Plugin: Document the project structure and conventions used in the `lib` folder for PHP code #39603

noisysocks commented Mar 21, 2022

ramonjd Mar 21, 2022

noisysocks Mar 21, 2022 •

edited

Loading

gziolo commented Mar 21, 2022

noisysocks commented Mar 21, 2022

andrewserong left a comment

andrewserong Mar 21, 2022

noisysocks Mar 22, 2022

tellthemachines left a comment

tellthemachines Mar 22, 2022

noisysocks commented Mar 22, 2022

youknowriad left a comment

youknowriad Mar 22, 2022

noisysocks Mar 24, 2022

ajlende Mar 22, 2022 •

edited

Loading

noisysocks Mar 24, 2022

priethor commented Mar 23, 2022


		### Note how your feature should look when merged to Core

		Developers should write a brief note about how their feature should be merged to Core, for example, which Core file or function should be patched.

Plugin: Document the project structure and conventions used in the lib folder for PHP code #39603

Plugin: Document the project structure and conventions used in the lib folder for PHP code #39603

Conversation

noisysocks commented Mar 21, 2022

What?

Why?

How?

Testing Instructions

ramonjd Mar 21, 2022

Choose a reason for hiding this comment

noisysocks Mar 21, 2022 • edited Loading

Choose a reason for hiding this comment

gziolo commented Mar 21, 2022

noisysocks commented Mar 21, 2022

andrewserong left a comment

Choose a reason for hiding this comment

andrewserong Mar 21, 2022

Choose a reason for hiding this comment

noisysocks Mar 22, 2022

Choose a reason for hiding this comment

tellthemachines left a comment

Choose a reason for hiding this comment

tellthemachines Mar 22, 2022

Choose a reason for hiding this comment

noisysocks commented Mar 22, 2022

youknowriad left a comment

Choose a reason for hiding this comment

youknowriad Mar 22, 2022

Choose a reason for hiding this comment

noisysocks Mar 24, 2022

Choose a reason for hiding this comment

ajlende Mar 22, 2022 • edited Loading

Choose a reason for hiding this comment

noisysocks Mar 24, 2022

Choose a reason for hiding this comment

priethor commented Mar 23, 2022

Plugin: Document the project structure and conventions used in the `lib` folder for PHP code #39603

Plugin: Document the project structure and conventions used in the `lib` folder for PHP code #39603

noisysocks Mar 21, 2022 •

edited

Loading

ajlende Mar 22, 2022 •

edited

Loading