WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 4 years ago

Last modified 3 years ago

#33413 closed task (blessed) (fixed)

most PHP classes should be in their own file

Reported by: wonderboymusic Owned by: nacin
Milestone: 4.4 Priority: normal
Severity: normal Version: 4.4
Component: General Keywords:
Focuses: Cc:
PR Number:

Description

WordPress has a weird way of bundling things in files: symbols, functions, classes, top-level code, the works. This can get increasingly bad over time. If we were to start WP anew today, there is no way we would organize our code in this fashion. This begs the question: are we open to cleaning some of these things up, or do we need these files to continue to arbitrarily include the works?

PSR-1, if anyone cares, suggests:

Files SHOULD either declare symbols (classes, functions, constants, etc.) 
or cause side-effects (e.g. generate output, change .ini settings, etc.) 
but SHOULD NOT do both.

I am not suggesting that we adopt PSR-1, but ...

In #30947 and #32529, I was able to remove top-level code from several WP files. This allows the remaining files to only declare functions. default-filters, admin-filters.php, and ms-admin-filters.php contain only function calls (top-level code). One remaining irksome piece: there are some multi-thousand line files in the codebase that declare a swath of functions, and then, seemingly out of nowhere: they declare a class.

There are several files in wp-includes that declare classes properly: 1) in their own file and 2) using a consistent naming convention: class-{DASHED LOWERCASED CLASS}.php. All classes should use this convention.

Forgetting that some of our classes are way too big and do way too much, some of these files contain hundreds/thousands of lines of function declarations and then still also declare a class of 100s/1000s of lines long.

I think we can see where this is heading, I would like to propose the creation of class files for:

WP_Comment_Query
WP_Http_Cookie
WP_Http_Curl
WP_Http_Encoding
WP_HTTP_Proxy
WP_Http_Streams
WP_Http
WP_Meta_Query
WP_Post
WP_Query
WP_Rewrite
WP_Role
WP_Roles
WP_Tax_Query
WP_User_Query
WP_User
WP_Widget_Factory
WP_Widget

We had a similar problem with Media JS, which was alleviated by me in [31373]. It is WAY easier to absorb complex code when these units are broken up.

I have a patch, and I welcome feedback.

Attachments (8)

classes.diff (1.5 MB) - added by wonderboymusic 4 years ago.
33413.diff (762.0 KB) - added by wonderboymusic 4 years ago.
33413.2.diff (24.6 KB) - added by dimadin 4 years ago.
33413.3.diff (1.6 MB) - added by wonderboymusic 4 years ago.
new-files.png (51.5 KB) - added by wonderboymusic 4 years ago.
33413.4.diff (27.5 KB) - added by wonderboymusic 4 years ago.
33413.5.diff (629 bytes) - added by dimadin 4 years ago.
33413.6.diff (1.2 KB) - added by helen 4 years ago.

Change History (149)

#1 follow-up: @pento
4 years ago

I'd probably add a block to include the classes in their original location if they're undefined, in case people are manually including individual files.

ie, in query.php:

if ( ! class_exists( 'WP_Query' ) ) {
    require( ABSPATH . WPINC . '/class-wp-query.php' );
}

The massive churn is not my favourite thing in the world, especially for some of the more complex classes that regularly need SVN log archeology to find out why a part works like it does.

#2 @wonderboymusic
4 years ago

the patch uses svn cp to create the files - does that persist history well enough, or is there another way?

#3 @pento
4 years ago

Ah, I see. Yeah, svn cp should do the job.

Minor side note, classes.diff isn't applying, it seems to be having trouble with creating the new files, I think because svn diff doesn't show copied files as files that need to be created.

#4 in reply to: ↑ 1 @jmichaelward
4 years ago

Replying to pento:

I'd probably add a block to include the classes in their original location if they're undefined, in case people are manually including individual files.

ie, in query.php:

if ( ! class_exists( 'WP_Query' ) ) {
    require( ABSPATH . WPINC . '/class-wp-query.php' );
}

I strongly agree with the premise of this ticket, and I also concur with @pento's concern above, with regard to making sure classes that are moved out of their original files can still be referenced by existing codebases.

With regard to coding standards, whether or not WordPress as an open-source project wants to adopt the PSR-1 standards, I have noticed from digging through the codebase a bit recently that there is quite a bit of code that fails to adhere to WordPress's own standards. I think it's worthy of discussion whether that's something to address for 4.4 (and future releases), as there are some code quality issues throughout core that could benefit from cleanup/simplification (such as ensuring braces always surround conditional blocks, not doing an if { return $this; } else { return $that; } etc. I'll dig around and see if there's already a ticket about this, and if not, I'll open one.

#5 @DrewAPicture
4 years ago

Yes! This has been an issue that has plagued our code base for years. I'd say say any ground we can gain on subdividing some of these multi-thousand line files would be a win.

#6 @welcher
4 years ago

I love this idea! I'd like to extend to default-widgets.php as well. We are already hoping to refresh that file for 4.4 ( #23012 ) and the next logical step would be to split those files out into separate classes.

#7 @nicholas_io
4 years ago

Totally agree with this idea. WordPress is growing fast and we need to keep things organized.

But we need to take care of some files that plugins developers usually include by their own, or at least be aware of this. (Although, looking at the patch, I didn't see any file change that can break backward compatibility)

#8 @DrewAPicture
4 years ago

If you'd like to preview the diff in the browser, it can be viewed here: https://cloudup.com/caVNEnpSGxI

#9 @wonderboymusic
4 years ago

  • Owner set to wonderboymusic
  • Status changed from new to assigned

#10 @wonderboymusic
4 years ago

In 33746:

Widgets: move classes into their own files, widgets.php loads the new files, so this is 100% BC if someone is loading widgets.php directly. New files created using svn cp.

Creates:
class-wp-widget.php
class-wp-widget-factory.php
widget-functions.php

widgets.php contains only top-level code. Class files only contain classes. Functions file only contains functions.

See #33413.

#11 @wonderboymusic
4 years ago

In 33748:

HTTP: move classes into their own files, http.php loads the new files, so this is 100% BC if someone is loading http.php directly. New files created using svn cp.

class-http.php requires functions from http.php, so loading it by itself wouldn't have worked.

Creates:
class-wp-http-cookie.php
class-wp-http-curl.php
class-wp-http-encoding.php
class-wp-http-proxy.php
class-wp-http-streams.php
http-functions.php

WP_Http remains in class-http.php.

http.php contains only top-level code. Class files only contain classes. Functions file only contains functions.

See #33413.

#12 @wonderboymusic
4 years ago

In 33749:

Users: move WP_User_Query into its own file. user.php loads the new files, so this is 100% BC if someone is loading user.php directly (a lot of plugins do). New files created using svn cp.

Creates:
class-wp-user-query.php
user-functions.php

user.php contains only top-level code. Class file only contains the class. Functions file only contains functions.

See #33413.

#13 @wonderboymusic
4 years ago

In 33750:

Comments: move WP_Comment_Query into its own file. comment.php loads the new files, so this is 100% BC if someone is loading comment.php directly. New files created using svn cp.

Creates:
class-wp-comment-query.php
comment-functions.php

comment.php contains only top-level code. Class file only contains the class. Functions file only contains functions.

See #33413.

#14 @wonderboymusic
4 years ago

In 33751:

Rewrite: move WP_Rewrite into its own file. rewrite.php loads the new files, so this is 100% BC if someone is loading rewrite.php directly. New files created using svn cp.

The rewrite functions have all kinds of cross-dependencies (like WP_Query), so loading the file by itself would have been bizarre (and still is).

Creates:
rewrite-constants.php
rewrite-functions.php
class-wp-rewrite.php

rewrite.php contains only top-level code. Class file only contains the class. Functions file only contains functions.

See #33413.

#15 @wonderboymusic
4 years ago

In 33752:

Roles: move classes into their own file. capbilities.php loads the new files, so this is 100% BC if someone is loading capbilities.php directly. New files created using svn cp.

Creates:
class-wp-roles.php
class-wp-role.php
class-wp-user.php
capbilities-functions.php

capbilities.php contains only top-level code. Class files only contains classes. Functions file only contains functions.

See #33413.

#16 @DrewAPicture
4 years ago

In 33755:

Docs: Add a file header to wp-includes/class-wp-widget.php, created when the WP_Widget class was moved to its own file in [33746].

It's important for every file in WordPress, regardless of makeup or architecture, to have its own file header, even if the file contains nothing but a class. When parsed, files and classes are mutually exclusive and should be documented with this in mind.

See [33746]. See #33413.

#17 @DrewAPicture
4 years ago

In 33756:

Docs: Add a file header to wp-includes/class-wp-widget-factory.php, created when the WP_Widget_Factory class was moved to its own file in [33746].

It's important for every file in WordPress, regardless of makeup or architecture, to have its own file header, even if the file contains nothing but a class. When parsed, files and classes are mutually exclusive and should be documented with this in mind.

See [33746]. See #33413.

#18 @DrewAPicture
4 years ago

In 33757:

Docs: Add a file header description and @since version to wp-includes/widget-functions.php, introduced in [33746].

Also adds sub-section headers per the inline documentation standards for syntax.

See [33746]. See #33413.

#19 @DrewAPicture
4 years ago

In 33758:

Docs: Add inline-docblocks for the require_once() calls that now bring in the WP_Widget and WP_Widget_Factory classes, as well as general core widgets functionality, as of [33746].

See [33746]. See #33413.

#20 follow-up: @kovshenin
4 years ago

It looks like r33748 broke WP-CLI:

PHP Fatal error:  Cannot declare class WP_Http, because the name is already in use in /home/kovshenin/htdocs/develop.lo/src/wp-includes/class-http.php on line 15

It's happening because class-http.php is being included twice, once in http.php and the second time in WP-CLI's version of wp-settings.php just a moment later. I guess this may break other "forks" of wp-settings.php and possibly some plugins that include/require the files directly, though a quick search through the .org directory shows mostly include_once and require_once.

This ticket was mentioned in Slack in #docs by garyj. View the logs.


4 years ago

#23 @wonderboymusic
4 years ago

In 33759:

Posts: move WP_Post into its own file. post.php loads the new files, so this is 100% BC if someone is loading post.php directly. New files created using svn cp.

Creates:
class-wp-post.php
post-functions.php

post.php contains only top-level code. Class file only contains the class. Functions file only contains functions.

See #33413.

#24 in reply to: ↑ 20 @pento
4 years ago

Replying to kovshenin:

PHP Fatal error:  Cannot declare class WP_Http, because the name is already in use in /home/kovshenin/htdocs/develop.lo/src/wp-includes/class-http.php on line 15

Good news! The vast majority of plugins that include class-http.php as well as http.php are either using include_once(), or wrapping it in a class_exists( 'WP_Http' ) check.

These were the only two plugins I found that would likely run into the same bug.

clicksold-wordpress-plugin
rrze-access

#25 @wonderboymusic
4 years ago

In 33760:

Taxonomy: move WP_Tax_Query into its own file. taxonomy.php loads the new files, so this is 100% BC if someone is loading taxonomy.php directly. New files created using svn cp.

Creates:
class-wp-tax-query.php
taxonomy-functions.php

taxonomy.php contains only top-level code. Class file only contains the class. Functions file only contains functions.

See #33413.

#26 @wonderboymusic
4 years ago

In 33761:

Meta: move WP_Meta_Query into its own file. meta.php loads the new files, so this is 100% BC if someone is loading meta.php directly. New files created using svn cp.

Creates:
class-wp-meta-query.php
meta-functions.php

meta.php contains only top-level code. Class file only contains the class. Functions file only contains functions.

See #33413.

This ticket was mentioned in Slack in #core by wonderboymusic. View the logs.


4 years ago

#29 @wonderboymusic
4 years ago

I just contacted ClickSold

#30 @wonderboymusic
4 years ago

rrze-access hasn't been touched in 3 years and forks wp-settings in a way that I think voids his warranty

#31 @kovshenin
4 years ago

Would it make sense to wrap the moved classes into class_exists and not break anything at all?

#32 @wonderboymusic
4 years ago

WP_Http is the only class loading that was "moved". Everything else loads from the exact same place. The internals of classes in the class-http.php pre-4.4 require some functions from http.php, like wp_http_validate_url() - so loading just the class in a strange environment where someone thought these files are sandboxed modules would have broken in the right scenario anyway, once it reached one of those functions that wasn't loaded.

#33 @DrewAPicture
4 years ago

In 33816:

Docs: Bring the file header and class DocBlock summaries for class-wp-widget.php in-line with the intention of the docs standard:

  • File headers: _What_ the file is
  • Class DocBlocks: What purpose the class serves. Mentioning the class name in the class DocBlock is redundant

See #33413

@wonderboymusic
4 years ago

#34 @wonderboymusic
4 years ago

In 33843:

Move widget classes to their own files in wp-includes/widgets:

  • default-widgets.php now requires all of the individual classes
  • Move the functions scattered about this file to widget-functions.php, which loads before default-widgets.php, which only conditionally loads anyway in wp_maybe_load_widgets(), which is hooked on plugins_loaded

See #33413, #23012.

#35 @DrewAPicture
4 years ago

In 33869:

Docs: Improve the file header for class-wp-widget.php to describe what the file contains.

Also rewrites the class DocBlock summary for WP_Widget to better describe the purpose of the class.

See #33413. See #33701.

#36 @DrewAPicture
4 years ago

In 33870:

Docs: Clarify the file header summary for class-wp-widget-factory.php, introduced in [33746].

See #33413. See #33701.

#37 @DrewAPicture
4 years ago

In 33871:

Docs: Clarify the file header summary for widget-functions.php, introduced in [33746].

See #33413. See #33701.

#38 @DrewAPicture
4 years ago

In 33872:

Docs: Clarify the file header summary for wp-includes/widgets.php, the top-level file for the core Widgets API.

Also fixes some minor grammar issues in the file description.

See #33413. See #33701.

#39 @DrewAPicture
4 years ago

In 33873:

Docs: Add a missing file header to wp-includes/class-wp-http-cookie.php, introduced in [33748].

Also clarifies the summary in the class DocBlock for WP_Http_Cookie.

See #33413. See #33701.

#40 @DrewAPicture
4 years ago

In 33874:

Docs: Add a missing file header for wp-includes/class-wp-http-curl.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_Http_Curl to better describe its purpose.

See #33413. See #33701.

#41 @DrewAPicture
4 years ago

In 33875:

Docs: Add a missing file header for wp-includes/class-wp-http-encoding.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_Http_Encoding.

See #33413. See #33701.

#42 @DrewAPicture
4 years ago

In 33876:

Docs: Add a missing file header to wp-includes/class-wp-http-proxy.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_HTTP_Proxy to better describe its purpose.

See #33413. See #33701.

#43 @DrewAPicture
4 years ago

In 33878:

Docs: Add a missing file header to wp-includes/class-wp-http-streams.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_Http_Streams to better describe its purpose.

See #33413. See #33701.

#44 @DrewAPicture
4 years ago

In 33879:

Docs: Clarify the file header summary for wp-includes/http-functions.php, introduced in [33748].

Also removes now-moot extra information from the file header description.

See #33413. See #33701.

#45 @DrewAPicture
4 years ago

In 33880:

Docs: Add a missing file header for wp-includes/class-http.php.

Also clarifies the class DocBlock summary for WP_Http to more clearly describe its purpose.

See #33413. See #33701.

#46 @DrewAPicture
4 years ago

In 33881:

Docs: Clarify the file header summary for wp-includes/http.php, the top-level file for the HTTP Request API.

See #33413. See #33701.

#47 @DrewAPicture
4 years ago

In 33882:

Docs: Add inline DocBlocks for the require_once() calls that now bring in top-level HTTP API functionality and HTTP API classes.

Classes brought in from separate files now include:

  • WP_Http
  • WP_Http_Streams
  • WP_Http_Curl
  • WP_HTTP_Proxy
  • WP_Http_Cookie
  • WP_Http_Encoding

See #33413. See #32246.

#48 @DrewAPicture
4 years ago

In 33895:

Docs: Add a missing file header for wp-includes/class-wp-user-query.php, introduced in [33749].

Also clarifies the class DocBlock summary for WP_User_Query to better describe its purpose.

See #33413. See #33701.

#49 @DrewAPicture
4 years ago

In 33896:

Docs: Clarify the file header summary for wp-includes/user-functions.php, introduced in [33749].

See #33413. See #33701.

#50 @DrewAPicture
4 years ago

In 33897:

Docs: Clarify the file header summary for wp-includes/user.php, the top-level file for the core Users API.

Also adds inline DocBlocks for the require_once() calls that now bring in core users functionality and the WP_User_Query class, as of [33749].

See #33413. See #33701.

#51 @DrewAPicture
4 years ago

In 33898:

Docs: Add a missing file header for wp-includes/class-wp-comment-query.php, introduced in [33750].

Also clarifies the class DocBlock summary and tags for WP_Comment_Query.

See #33413. See #33701.

#52 @DrewAPicture
4 years ago

In 33899:

Docs: Clarify the file header summary for wp-includes/comment-functions.php, introduced in [33750].

See #33413. See #33701.

#53 @DrewAPicture
4 years ago

In 33900:

Docs: Clarify the file header summary for wp-includes/comment.php, the top-level file for the core Comments API.

Also adds inline DocBlock for the require_once() calls that now bring in the WP_Comment and WP_Comment_Query classes, as well as core comments functionality.

See #33413. See #33701.

#54 @DrewAPicture
4 years ago

In 33901:

Docs: Clarify the file header summary for wp-includes/rewrite-constants.php, introduced in [33751].

See #33413. See #33701.

#55 @dimadin
4 years ago

Some documentation should be updated to point to new files. In attached patch I tried to catch everything.

@dimadin
4 years ago

#56 @wonderboymusic
4 years ago

In 33954:

After [33843], update the location of some files in This filter is documented in docs

Props dimadin.
See #33413.

#57 follow-up: @wonderboymusic
4 years ago

33413.3.diff handles the Customizer, and I promised @westonruter that I would do a breakdown before moving forward. Follows the same tenets/principles as above. Makes the code a LOT easier to understand. Existing files are way too huge.

Highlights:


Screenshot above shows new files.

#58 @wonderboymusic
4 years ago

In 33962:

Walker_Comment should be in its own file. Loaded now via wp-includes/comment.php, which makes it 100% BC.

See #33413.

#59 in reply to: ↑ 57 ; follow-up: @westonruter
4 years ago

Replying to wonderboymusic:

33413.3.diff handles the Customizer, […] _wp_customize_include() now loads wp-includes/customize-functions.php and wp-includes/customize/class-wp-customize-manager.php - I found no use cases of these files being loaded by plugins: https://github.com/search?utf8=%E2%9C%93&q=user%3Awp-plugins+class-wp-customize&type=Code&ref=searchresults .... compared to: https://github.com/search?utf8=%E2%9C%93&q=user%3Awp-plugins+class-http&type=Code&ref=searchresults

I've actually required it directly in my plugins, however, this was done specifically in PHPUnit tests: https://github.com/xwp/wp-customize-widgets-plus/search?utf8=%E2%9C%93&q=class-wp-customize-manager.php&type=Code

If you search GitHub across all repos, you'll see many examples of this (though many are just clones of Core): https://github.com/search?l=php&q=class-wp-customize-manager.php&type=Code

I suppose it is acceptable to break plugin unit tests with this re-organization if this is all that breaks… but, loading other class files is not limited to unit tests. I see examples of directly loading the control class file require_once( ABSPATH . WPINC . '/class-wp-customize-control.php' ):

These plugins would all break.

#60 in reply to: ↑ 59 @DrewAPicture
4 years ago

Replying to westonruter:

If you search GitHub across all repos, you'll see many examples of this (though many are just clones of Core): https://github.com/search?l=php&q=class-wp-customize-manager.php&type=Code

I suppose it is acceptable to break plugin unit tests with this re-organization if this is all that breaks… but, loading other class files is not limited to unit tests. I see examples of directly loading the control class file require_once( ABSPATH . WPINC . '/class-wp-customize-control.php' ):

These plugins would all break.

What if we introduced the new file and loaded it from the old one for back-compat, meanwhile tossing a _deprecated_file() notice, then delete the old file a few releases down the road, giving time for devs to update?

#61 @wonderboymusic
4 years ago

@westonruter @DrewAPicture I think I can do a Take 2 on this that doesn't churn so much

This ticket was mentioned in Slack in #core by sergey. View the logs.


4 years ago

#63 @wonderboymusic
4 years ago

In 34109:

Move Walker_Page and Walker_PageDropdown into their own files via svn cp. Remove them from post-template.php. Load them in post.php.

post-template.php loads after post.php in wp-settings.php. It could probably also be loaded in post.php, but avoiding that for the moment.

See #33413.

#64 @wonderboymusic
4 years ago

In 34110:

Move Walker_Category and Walker_CategoryDropdown into their own files via svn cp. Remove them from category-template.php. Load them in category.php. svn cp category.php over to category-functions.php, which also loads now in category.php.

See #33413.

#65 @wonderboymusic
4 years ago

In 34123:

Fix the case-sensitivity of some HTTP class usage.

See #33413.

#66 @wonderboymusic
4 years ago

In 34168:

Move the admin Nav Menu Walker subclasses into their own files. Load in nav-menu.php to remain BC.

See #33413.

#67 @wonderboymusic
4 years ago

In 34169:

Move WP_Screen to its own file.

See #33413.

#68 @johnbillion
4 years ago

In 34174:

Place the filter docblock for http_api_transports immediately above the filter.

See #33413
Props dd32

#69 @wonderboymusic
4 years ago

In 34223:

Move WP_Post_Comments_List_Table to its own file.

See #33413.

#70 @SergeyBiryukov
4 years ago

In 34231:

Comments: Fix a fatal error in Comments meta box after [34223].

Props tyxla.
Fixes #33893. See #33413.

#71 follow-up: @wonderboymusic
4 years ago

In 34241:

wp-admin/includes/template.php is now a loader for 3 files made via svn cp:

  • Walker_Category_Checklist class
  • WP_Internal_Pointers class
  • template-functions.php

This is BC for plugins that are loading wp-admin/includes/template.php for fun.

See #33413.

#72 in reply to: ↑ 71 @dimadin
4 years ago

Replying to wonderboymusic:

After this, one "This action is documented in" should be updated.

@dimadin
4 years ago

#73 @DrewAPicture
4 years ago

In 34385:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-categories.php.

See #33413.

#74 @DrewAPicture
4 years ago

In 34387:

Docs: Add a file header to wp-includes/class-wp-user.php, created in [33752].

See #33413.

#75 @DrewAPicture
4 years ago

In 34391:

Docs: Update the file path in the duplicate hook comment for the admin_xml_ns hook in wp-admin/includes/template-functions.php.

The hook was "moved" to the newly-created template-functions.php file via svn cp in [34241].

Props dimadin.
See #33413.

#76 @DrewAPicture
4 years ago

In 34394:

Docs: Add a file header to wp-includes/class-wp-roles.php, introduced in [33752].

Also adjusts the class DocBlock for WP_Roles.

See #33413. See #33701.

#77 @DrewAPicture
4 years ago

In 34395:

Docs: Add a file header to wp-includes/class-wp-role.php, introduced in [33752].

Also adjusts the class DocBlock for WP_Role.

See #33413. See #33701.

#78 @DrewAPicture
4 years ago

In 34396:

Docs: Clarify the file header summary for wp-includes/capabilities-functions.php, introduced in [33752].

See #33413. See #33701.

#79 @DrewAPicture
4 years ago

In 34398:

Docs: Clarify the file header summary for wp-includes/capabilities.php, which was broken up into multiple files in [33752].

Also adds inline DocBlocks for files now brought in via require_once() from this file.

See #33413. See #33701.

#80 @DrewAPicture
4 years ago

In 34399:

Docs: Add a file header to wp-includes/class-wp-post.php, introduced in [33759].

Also clarifies the class DocBlock for WP_Post.

See #33413. See #33701.

#81 @DrewAPicture
4 years ago

In 34400:

Docs: Clarify the file header summary for wp-includes/post-functions.php, introduced in [33759].

See #33413. See #33701.

#82 @DrewAPicture
4 years ago

In 34401:

Docs: Clarify the file header summary for wp-includes/post.php, the top-level file for the Post API.

See #33413. See #33701.

#83 @DrewAPicture
4 years ago

In 34402:

Docs: Add a file header to wp-includes/class-wp-tax-query.php, introduced in [33760].

Also clarifies the class DocBlock summary and description for WP_Tax_Query.

See #33413. See #33701.

#84 @DrewAPicture
4 years ago

In 34403:

Docs: Clarify the file header summary for wp-includes/taxonomy-functions.php, introduced in [33760].

See #33413. See #33701.

#85 @DrewAPicture
4 years ago

In 34404:

Docs: Clarify the file header summary for wp-includes/taxonomy.php, the top-level file for the core Taxonomy API.

See #33413. See #33701.

#86 @DrewAPicture
4 years ago

In 34405:

Docs: Add a file header to wp-includes/class-wp-meta-query.php, introduced in [33761].

Also clarifies the class DocBlock summary for WP_Meta_Query.

See #33413. See #33701.

#87 @DrewAPicture
4 years ago

In 34406:

Docs: Clarify the file header summary for wp-includes/meta-functions.php, introduced in [33761].

See #33413. See #33701.

#88 @DrewAPicture
4 years ago

In 34407:

Docs: Clarify the file header summary for wp-includes/meta.php, the top-level file for the core Meta API.

Also adds inline DocBlocks for files broken out in #33413 and now brought in via require_once().

See #33413. See #33701.

#89 @DrewAPicture
4 years ago

In 34408:

Docs: Clarify the file header summary for wp-includes/default-widgets.php, the top-level file for bringing in the core widget classes.

Also adds inline DocBlocks for the widget classes now brought in via require_once() as of [33843].

See #33413. See #33701.

#90 @DrewAPicture
4 years ago

In 34414:

Docs: Clarify the file header summary for wp-includes/class-walker-page.php, introduced in [34109].

Also clarifies the class DocBlock summary for Walker_Page.

See #33413. See #33701.

#91 @DrewAPicture
4 years ago

In 34415:

Docs: Clarify the file header subpackage for wp-includes/class-walker-page-dropdown.php, introduced in [34109].

Also clarifies the class DocBlock summary and tags for Walker_PageDropdown.

See #33413. See #33701.

#92 @DrewAPicture
4 years ago

In 34416:

Docs: Clarify the file header summary for wp-includes/class-walker-category.php, introduced in [34110].

Also clarifies the class DocBlock and tags for Walker_Category.

See #33413. See #33701.

#93 @DrewAPicture
4 years ago

In 34417:

Docs: Clarify the file header for wp-includes/class-walker-category-dropdown.php, introduced in [34110].

Also clarifies the class DocBlock and tags for Walker_CategoryDropdown.

See #33413. See #33701.

#94 @DrewAPicture
4 years ago

In 34418:

Docs: Clarify the file header for wp-includes/category.php.

See #33413. See #33701.

#95 @DrewAPicture
4 years ago

In 34419:

Docs: Clarify the file header summary and subpackage for wp-includes/category-functions.php, introduced in [34110].

See #33413. See #33701.

#96 @DrewAPicture
4 years ago

In 34420:

Docs: Clarify the file header summary and version for wp-includes/category-template.php.

See #33413. See #33701.

#97 @DrewAPicture
4 years ago

In 34423:

Docs: Clarify the file header summary for wp-admin/includes/class-wp-post-comments-list-table.php, introduced in [34223].

Also clarifies the class DocBlock summary and tags for WP_Post_Comments_List_Table.

See #33413. See #33701.

#98 @DrewAPicture
4 years ago

In 34425:

Docs: Clarify the file header summary for wp-admin/includes/class-walker-category-checklist.php, introduced in [34241].

Also clarifies the class DocBlock summary for Walker_Category_Checklist.

See #33413. See #33701.

#99 @DrewAPicture
4 years ago

In 34426:

Docs: Clarify the file header summary for wp-admin/includes/class-wp-internal-pointers.php, introduced in [34241].

Also adds a missing class DocBlock to WP_Internal_Pointers. See [19388].

See #33413. See #33701.

#100 @DrewAPicture
4 years ago

In 34427:

Docs: Clarify the file header summary for wp-admin/includes/template-functions.php, introduced in [34241].

See #33413. See #33701.

#101 @DrewAPicture
4 years ago

In 34428:

Docs: Clarify the file header summary for wp-includes/widgets/class-wp-nav-menu-widget.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Nav_Menu_Widget.

See #33413. See #33701.

#102 @DrewAPicture
4 years ago

In 34429:

Docs: Add a missing file header to wp-includes/widgets/class-wp-widget-archives.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Archives.

See #33413. See #33701.

#103 @DrewAPicture
4 years ago

In 34430:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-calendar.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Calendar.

See #33413. See #33701.

#104 @DrewAPicture
4 years ago

In 34432:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-links.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Links.

See #33413. See #33701.

#105 @DrewAPicture
4 years ago

In 34433:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-meta.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Meta.

See #33413. See #33701.

#106 @DrewAPicture
4 years ago

In 34434:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-pages.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Pages.

See #33413. See #33701.

#107 @DrewAPicture
4 years ago

In 34435:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-recent-comments.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Recent_Comments.

See #33413. See #33701.

#108 @DrewAPicture
4 years ago

In 34436:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-recent-posts.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Recent_Posts.

See #33413. See #33701.

#109 @DrewAPicture
4 years ago

In 34437:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-rss.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_RSS.

See #33413. See #33701.

#110 @DrewAPicture
4 years ago

In 34438:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-search.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Search.

See #33413. See #33701.

#111 @DrewAPicture
4 years ago

In 34439:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-tag-cloud.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Tag_Cloud.

See #33413. See #33701.

#112 @DrewAPicture
4 years ago

In 34440:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-text.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Text.

See #33413. See #33701.

#113 @DrewAPicture
4 years ago

@wonderboymusic: I'm caught up with your reorganization changes in terms of file header changes as of [34440] :-)

This ticket was mentioned in Slack in #core by drew. View the logs.


4 years ago

This ticket was mentioned in Slack in #core by sergey. View the logs.


4 years ago

#116 @DrewAPicture
4 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

Let's call this fixed and do new tickets for moving any remaining classes, including the Customizer split outlined in comment:57.

#117 @nacin
4 years ago

A few months ago I told @wonderboymusic that I liked the direction here, but that I questioned the need to have such a complicated include path, and that I was probably going to go

So rather than:

wp-settings.php
    -> post.php
        -> post-functions.php
        -> class-wp-post.php

I think we should have:

wp-settings.php
    -> post.php
    -> class-wp-post.php

Performance-wise: If we're going to have all of these files, we should at least try to go with as flat of an include graph as possible.

Back compat-wise: Every file affected by this change is always included in wp-settings.php. Thus, the simplified include graph is only going to break a situation when someone is short-circuiting or forking wp-settings.php. We cannot support this. It puts our feet in too much cement to support this. We have never supported it before. We have split files many times before, including post-3.0 when multisite (and SHORTINIT) came in and made us a bit more cautious. And we have never done any BC work for files that are always included, beyond just putting it in wp-settings.php. If we support this now, then we must always support this, and WordPress will get even harder to maintain. Does this mean we also can't move functions between files? There are many things that we should be accounting for, but certain things we have to agree void the warranty and should not restrict us.

This also avoids the problem noted with class-http.php, though I agree with the sentiment that it won't break much or at all.

So, I'm going to commit a change that moves all (.*)-functions.php files back to \1.php and moves the includes up to wp-settings.php. It's not ideal in that wp-settings.php is now quite a bit more loaded up with includes. (I also load up the customize manager with includes -- it could break things, but it's a low risk.) I also move the constants back to rewrite.php. And, I always load the functions before the classes.

#118 follow-up: @nacin
4 years ago

In 35718:

Simplify the include graph after work to split out classes.

see #33413. More details there.

#119 @danielbachhuber
4 years ago

Why does r35718 need to happen hours before RC, and not earlier in the cycle when developers can appropriately address fallout?

#120 @ocean90
4 years ago

In 35720:

Build: Update source for includes:embed after [35718].

See #33413.

#121 in reply to: ↑ 118 @jdgrimes
4 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Replying to nacin:

In 35718:

Simplify the include graph after work to split out classes.

see #33413. More details there.

After this the hook docs need to be updated again, from

	/** This filter is documented in wp-includes/comment-functions.php */

to

	/** This filter is documented in wp-includes/comment.php */

etc.

#122 @dd32
4 years ago

Why does r35718 need to happen hours before RC, and not earlier in the cycle when developers can appropriately address fallout?

For the record, this shouldn't have caused a problem for any developers; WP-CLI is a special child which does things it shouldn't :) Open a ticket to make it not have to do special things and we'll find a way.

#123 follow-up: @SergeyBiryukov
4 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

In 35725:

After [35718], update the location of some files in This filter is documented in docs.

Partially reverts [33954].

Fixes #33413.

#124 in reply to: ↑ 123 @jdgrimes
4 years ago

Replying to SergeyBiryukov:

In 35725:

After [35718], update the location of some files in This filter is documented in docs.

Partially reverts [33954].

Fixes #33413.

I guess we should really have a build tool that automatically regenerates these doc comments. :0)

#125 @nerrad
4 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

r35718 causes a fatal for our use case. We extend Walker_Category_Checklist to create a Walker_Radio_Checklist class and before extending we had this require:

require_once ABSPATH . 'wp-admin/includes/template.php';

prior to r35718 the backward compat added by @wonderboymusic took care of the require. But r35718 not only breaks but causes fatals. Easy fix, but it does seem to be the kind of thing that other developers might run into.

I agree with @danielbachhuber that making this kind of adjustment so close to RC is kind of hairy.

#126 @builtbynorthby
4 years ago

iiuc, if the user updates to WP 4.4 before updating their plugins, and if they have an active plugin, or theme, or custom code that extends Walker_Category_Checklist, where it previously just worked to require template.php [like in this example](http://wordpress.stackexchange.com/a/129295), then they will get a fatal error when they try to load up the WP admin.

@nerrad if you push your simple fix and release an update to your plugin right now, a percentage of users will not update the plugin before they update WP to 4.4. Won't that put some users in a tough spot when they get a fatal error right after they update to 4.4?

Last edited 4 years ago by builtbynorthby (previous) (diff)

#127 @nerrad
4 years ago

Yes they'll be in a tough spot. Thing is, the Walker classes aren't explicitly loaded via wp-settings.php... I'm not sure what the "correct" way is we should be requiring a file containing a Walker class we want to extend?

#128 @dd32
4 years ago

It sounds like in this case, the plugin is _doing_it_wrong(). No plugin should need to require a core file manually, either it's for use within the admin and should include the plugins file on admin_init, or it's for use on the front end, and should either a) file a ticket to move it to wp-includes and always load, or b) copy the core functionality needed to their own file.

In this case, Walker_Category_Checklist is a very minimal class, I'd suggest the proper way would be to just copy the minimal required functionality into your own Walker class.

#129 @nerrad
4 years ago

The definition of _doing_it_wrong() in this case can definitely be argued. However my concern is that this is such a severe breaking change that regardless of whether the code I have is wrong, we're putting WordPress users in the middle of this. They'll update to WordPress 4.4 and will immediately get a broken admin. I hope I'm the only one doing things wrong in a plugin, but it could be a nightmare if there are others out there doing something similar.

At the very least, please DON'T release this so late in this dev cycle. It would be a totally different story if this breaking change had been added in the beginning of the cycle, with the arguments given for why its needed, and then we (and possibly others) would have time to fix our wrong code and get releases out to users.

For what its worth, I *love* the changes made in this ticket to separate out classes and bring some order to the chaos :) Its just unfortunate that the last commit introduces potential pain for a number of WordPress users

Last edited 4 years ago by nerrad (previous) (diff)

This ticket was mentioned in Slack in #core by helen. View the logs.


4 years ago

#131 in reply to: ↑ 130 @helen
4 years ago

  • Keywords dev-feedback removed
  • Owner changed from wonderboymusic to nacin
  • Status changed from reopened to assigned
  • Type changed from enhancement to task (blessed)

Replying to slackbot:

This ticket was mentioned in Slack in #core by helen. View the logs.

​[4:12 PM] nacin: So yeah, I can handle the fix for template.php in the admin.

All yours.

This ticket was mentioned in Slack in #core by wonderboymusic. View the logs.


4 years ago

@helen
4 years ago

#133 @helen
4 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 35740:

Avoid potential fatal errors after [35718].

While these classes are intended for admin use, there are developers out there who include wp-admin/includes/template.php to access them in other contexts. There is no intention to continue to support this indefinitely, but a breaking change like that would need to happen very early in a cycle and communicated loudly.

In the meantime, if you're reading this commit message and you do the above, please update your code to not do that. Thank you :)

fixes #33413.

#134 follow-up: @nerrad
4 years ago

Thanks @helen for getting this resolved. However for clarification you made this comment:

While these classes are intended for admin use, ...

wp_dropdown_categories uses Walker_CategoryDropdown, is it therefore only a function that should be used in the admin? Since it's parent file, category-template.php is found in wp-includes and not wp-admin it seems reasonable to me that developers would assume Walker classes would be exposed for use in places other than the admin ;)

Last edited 4 years ago by nerrad (previous) (diff)

#135 in reply to: ↑ 134 @helen
4 years ago

Replying to nerrad:

wp_dropdown_categories uses Walker_CategoryDropdown

I'm not really following - the two classes referenced here are Walker_Category_Checklist and WP_Internal_Pointers.

#136 @nerrad
4 years ago

Duh, yeah sorry... you weren't making a generalized statement about walker classes in general, just those classes you moved in your commit.

This ticket was mentioned in Slack in #core by sergey. View the logs.


4 years ago

#138 @westonruter
3 years ago

In 37283:

Customize/Formatting: Move sanitize_hex_color(), sanitize_hex_color_no_hash(), and maybe_hash_hex_color() from class-wp-customize-manager.php into formatting.php.

Adds missing braces.

See #33413.
Props downstairsdev, tollmanz.
Fixes #27583.

This ticket was mentioned in Slack in #core-multisite by ryanduff. View the logs.


3 years ago

#140 @DrewAPicture
3 years ago

In 37640:

Nav Menus: Move the Walker_Nav_Menu class to its own file.

The new class-walker-nav-menu.php file is loaded in nav-menu-template.php for backward compatibility purposes.

Fixes #37035. See #33413.

This ticket was mentioned in Slack in #core-customize by westonruter. View the logs.


3 years ago

Note: See TracTickets for help on using tickets.