most PHP classes should be in their own file

[wonderboymusic]

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.

[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' );
}

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.

[wonderboymusic]

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

[pento]

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.

[jmichaelward]

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.

[DrewAPicture]

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.

[welcher]

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.

[nicholas_io]

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)

[DrewAPicture]

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

[wonderboymusic]

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.

[wonderboymusic]

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.

[wonderboymusic]

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.

[wonderboymusic]

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.

[wonderboymusic]

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.

[wonderboymusic]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[kovshenin]

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.

[wonderboymusic]

@kovshenin: PR is here ​https://github.com/wp-cli/wp-cli/pull/2010

[wonderboymusic]

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.

[pento]

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

[wonderboymusic]

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.

[wonderboymusic]

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.

[wonderboymusic]

Fixed in wp-cli here: ​https://github.com/wp-cli/wp-cli/pull/2011

[wonderboymusic]

I just contacted ClickSold

[wonderboymusic]

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

[kovshenin]

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

[wonderboymusic]

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.

[DrewAPicture]

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]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 33870:

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

See #33413. See #33701.

[DrewAPicture]

In 33871:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 33896:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 33899:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

In 33901:

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

See #33413. See #33701.

[dimadin]

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

[wonderboymusic]

In 33954:

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

Props dimadin.
See #33413.

[wonderboymusic]

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:

• Moves classes to wp-includes/customize/
• _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
• WP_Customize_Manager::__construct() loads wp-includes/customize.php, which is a manifest that loads all of the files in wp-includes/customize/* - this could probably change to not have to do this. The file should just load in theme.php. In the past, it looked like the __construct() was just loading a few classes, but each of those files was loading in aggregate 3 dozen classes.

Screenshot above shows new files.

[wonderboymusic]

In 33962:

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

See #33413.

[westonruter]

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' ):

• ​https://github.com/nathancorbier/condemnationlaw/blob/631af9ba9a9cf9b2b09c58e3c9ead930081b55a4/wp-content/themes/stacy/includes/class-fonts-customizer.php#L2
• ​https://github.com/xwp/wp-settings-revisions/blob/231ba0ff2991d15980c9ec34c180f20b26dea489/php/meta-control.php#L3
• ​https://github.com/engrnvd/Wordpress-Sandbox/blob/ac31a58db97df411b3dc3b698ad80379907bb93b/wp-content/themes/dw-fixel/inc/class-customization.php#L2

These plugins would all break.

[DrewAPicture]

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' ):

• ​https://github.com/nathancorbier/condemnationlaw/blob/631af9ba9a9cf9b2b09c58e3c9ead930081b55a4/wp-content/themes/stacy/includes/class-fonts-customizer.php#L2
• ​https://github.com/xwp/wp-settings-revisions/blob/231ba0ff2991d15980c9ec34c180f20b26dea489/php/meta-control.php#L3
• ​https://github.com/engrnvd/Wordpress-Sandbox/blob/ac31a58db97df411b3dc3b698ad80379907bb93b/wp-content/themes/dw-fixel/inc/class-customization.php#L2

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?

[wonderboymusic]

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

[wonderboymusic]

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.

[wonderboymusic]

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.

[wonderboymusic]

In 34123:

Fix the case-sensitivity of some HTTP class usage.

See #33413.

[wonderboymusic]

In 34168:

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

See #33413.

[wonderboymusic]

In 34169:

Move WP_Screen to its own file.

See #33413.

[johnbillion]

In 34174:

Place the filter docblock for http_api_transports immediately above the filter.

See #33413
Props dd32

[wonderboymusic]

In 34223:

Move WP_Post_Comments_List_Table to its own file.

See #33413.

[SergeyBiryukov]

In 34231:

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

Props tyxla.
Fixes #33893. See #33413.

[wonderboymusic]

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.

[dimadin]

Replying to wonderboymusic:

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

[DrewAPicture]

In 34385:

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

See #33413.

[DrewAPicture]

In 34387:

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

See #33413.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34396:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34400:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34403:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34406:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34418:

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

See #33413. See #33701.

[DrewAPicture]

In 34419:

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

See #33413. See #33701.

[DrewAPicture]

In 34420:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34427:

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

See #33413. See #33701.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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

[DrewAPicture]

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

[nacin]

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.

[nacin]

In 35718:

Simplify the include graph after work to split out classes.

see #33413. More details there.

[danielbachhuber]

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

[ocean90]

In 35720:

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

See #33413.

[jdgrimes]

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.

[dd32]

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.

[SergeyBiryukov]

In 35725:

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

Partially reverts [33954].

Fixes #33413.

[jdgrimes]

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)

[nerrad]

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.

[builtbynorthby]

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?

[nerrad]

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?

[dd32]

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.

[nerrad]

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 our code is wrong, the fact that this is such a severe breaking issue means that we're putting WordPress users in the middle of this. They'll update to WordPress 4.4 and will immediately get a broken admin.

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

[helen]

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.

[helen]

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.

[nerrad]

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 ;)

[helen]

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.

[nerrad]

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

[westonruter]

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.

[DrewAPicture]

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.