WordPress File Headers Have Overstayed Their Welcome

ben · March 5, 2026, 8:12pm

WordPress already parses theme.json for settings and styles. Why is theme metadata still in CSS comments? We think it’s time to move metadata into theme.json and introduce plugin.json.

ben · March 8, 2026, 2:38pm

PR submitted:

github.com/WordPress/wordpress-develop

Add JSON as an alternative to PHP/CSS file headers for plugin and theme metadata (#11200)

trunk ← retlehs:trac-24152-json-metadata-for-themes-and-plugins

opened 07:10AM - 08 Mar 26 UTC

retlehs

+1048 -25

Trac ticket: https://core.trac.wordpress.org/ticket/24152 This adds support f…or declaring plugin and theme metadata in JSON files as an alternative to PHP/CSS comment-based file headers. - **Plugins** can now use a `plugin.json` file alongside the main PHP file - **Themes** can now declare metadata in the `metadata` property of `theme.json` - JSON metadata takes priority when present; existing file headers work as a fallback - Backwards compatible fallback behavior remains: if JSON metadata is missing or invalid, existing file headers are still used ### Motivation PHP/CSS file headers are parsed via regex on the first 8KB of a file. JSON provides a structured, machine-readable, language-agnostic alternative that: - Eliminates regex parsing fragility - Aligns with modern conventions - Allows themes to work without `style.css` (block themes already don't need one for styling) See: [WordPress File Headers Have Overstayed Their Welcome](https://roots.io/wordpress-file-headers-have-overstayed-their-welcome/) ## Examples ### `plugin.json` ```json { "name": "My Plugin", "uri": "https://example.com/my-plugin", "description": "A short description of the plugin.", "author": "Plugin Author", "authorUri": "https://example.com", "version": "1.0.0", "textDomain": "my-plugin", "requires": { "wordpress": "7.0", "php": "8.0", "plugins": ["woocommerce", "jetpack"] }, "network": true, "mainFile": "bootstrap.php" } ``` ### `theme.json` (metadata property) ```json { "version": 3, "metadata": { "name": "My Theme", "uri": "https://example.com/my-theme", "description": "A short description of the theme.", "author": "Theme Author", "authorUri": "https://example.com", "version": "1.0.0", "tags": ["blog", "one-column"], "textDomain": "my-theme", "template": "parent-theme" }, "settings": { ... }, "styles": { ... } } ``` Other examples from my demo repo: https://github.com/retlehs/json-metadata-theme-and-plugin ## Changes ### Plugin metadata (`plugin.json`) - New `_get_plugin_json_data()` function reads `plugin.json` from a plugin's directory - `get_plugin_data()` checks for JSON metadata first, then falls back to PHP file headers - Only applies to direct children of `WP_PLUGIN_DIR` (not mu-plugins or drop-ins) - Supports a `mainFile` property to designate the main entry point (defaults to `{dir-name}/{dir-name}.php`) - `requires.plugins` array maps to comma-separated `RequiresPlugins` header format - `network` field uses strict boolean checking (`true` only) - Uses silent JSON decoding (not `wp_json_file_decode()`) to avoid errors during enumeration - Files outside direct child plugin directories (including mu-plugin subdirectories and drop-ins) are ignored - JSON parsing honors headers registered via the existing `extra_plugin_headers filter` ### Theme metadata (`theme.json` → `metadata`) - New `read_json_metadata()` private method on `WP_Theme` reads `metadata` from `theme.json` - Constructor tries JSON metadata before `style.css` headers - Themes with `theme.json` metadata can now work without a `style.css` file - Updated `validate_current_theme()` to allow active themes (including child themes) without `style.css` when `theme.json` contains valid `metadata.name` - Uses silent JSON decoding to avoid errors when enumerating themes with malformed `theme.json` - JSON metadata parsing honors headers registered via the existing `extra_theme_headers` filter ## Schema notes The `theme.json` schema (maintained in the Gutenberg repo) will need a companion PR to add the `metadata` property definition. Schema publication/documentation for `plugin.json` will need to be done. ## Testing ```bash npm run test:php -- --filter "Tests_Admin_IncludesPluginJsonMetadata|Tests_Admin_WPPluginDependencies_Initialize|Tests_Theme_ThemeDir|Tests_Theme_wpThemeJsonMetadata" ``` All filtered tests passed locally in Docker ## Demo See https://github.com/retlehs/json-metadata-theme-and-plugin for an example plugin and theme, along with instructions on how to setup your local environment with this PR | Plugin Metadata | Theme Metadata | Theme Front End | | --- | --- | --- | | ![JSON metadata plugin](https://cdn.roots.io/app/uploads/json-metadata-plugin.png) | ![JSON metadata theme](https://cdn.roots.io/app/uploads/json-metadata-theme.png) | ![JSON metadata theme front end](https://cdn.roots.io/app/uploads/json-metadata-theme-front-end.png) | ## Use of AI Tools This PR was authored with Claude Code and Codex. Both were used for implementation, test writing, and code review. I reviewed and validated all changes, and ran tests locally in Docker.