WordPress.org

Make WordPress Core

Opened 23 months ago

Last modified 2 weeks ago

#24152 reopened feature request

Use JSON as alternative to headers

Reported by: ryanve Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: Themes Keywords: close
Focuses: Cc:

Description

Themes are required to include style.css for its header info. Plugins are required to contain header info in their main file. It makes more sense to store package info in JSON. A filename like theme.json or plugin.json (or an all-encompassing wordpress.json) seems viable. When present, the JSON file would be favored over the headers. This would make it possible to have a theme without a style.css file.

Change History (21)

comment:1 @ryanve23 months ago

  • Type changed from defect (bug) to feature request

comment:2 @toscho23 months ago

  • Cc info@… added

Oh, yes please!

comment:3 @TJNowell23 months ago

  • Cc tom@… added

comment:4 @johnbillion23 months ago

  • Cc johnbillion added

comment:5 @SergeyBiryukov23 months ago

  • Component changed from General to Themes

comment:6 @nacin23 months ago

  • Keywords close added

While this means you don't need a style.css file for a theme, you'll still need a .json file. Considering you don't actually need to use style.css for, well, CSS, this isn't much of a benefit. If anything, it means people will need to look in two places, not one. And given that all plugins do need a file, this will mean that plugins now need a minimum of two files. (Many plugins are very simple single-file plugins that can go into wp-content/plugins directly, and this is common for custom managed sites.)

While JSON files are both machine-readable and human-readable, they aren't necessarily human-editable. You need to understand syntax and such, and there are some gotchas like trailing commas and when to quote that can be confusing. I think this would be a nice thing to keep in our back pocket in case the world of dependencies, testing, and such force something more powerful than the existing headers. But the current headers are a very integral part of WordPress and are one of those things that make things so simple to so many.

Cool idea, but suggesting we close this as maybelater.

comment:7 @rmccue23 months ago

Oh please no. I love JSON as an interchange format between machines, but as configuration files, they're just insane. Agreed with nacin, +1 on close.

comment:8 @markoheijnen23 months ago

+1 for close it too. For dependencies it can be a JSON file but then use a file only for that.

comment:9 @nacin23 months ago

  • Milestone Awaiting Review deleted
  • Resolution set to wontfix
  • Status changed from new to closed

comment:10 @travisnorthcutt22 months ago

this will mean that plugins now need a minimum of two files.

Not to nitpick (ok, to nitpick), doesn't the proposed functionality (When present, the JSON file would be favored over the headers.) suggest that a json file isn't strictly required, and the existing method of using headers would still work just fine?

comment:11 @TJNowell22 months ago

Keeping in mind that themes already need 2 files as a minimum, index.php and style.css, and that the primary argument against this is a situation that we already have in plugins, namely that we have to define our plugin in the header, and readme.txt

comment:12 @zamoose22 months ago

@TJNowell:
Extra nitpicking: if it's a child theme, you don't even need an index.php.

comment:13 @ocean906 months ago

#29363 was marked as a duplicate.

comment:14 @Alaa Rihan6 months ago

in drupal they will use yaml to store themes and modules info in drupal -v8..

why we don't use php like "[Theme name].info.php" or xml like "[Theme name].xml"?

comment:15 @ocean908 weeks ago

#30974 was marked as a duplicate.

comment:16 @retlehs8 weeks ago

Time to revisit? The non-standard file headers specification is 17 different things, when it could be reduced to just "use valid JSON"

For backwards compat, the feature could work along the lines of: if less than 4.x, use get_file_data, if newer, use json_decode

comment:17 @swalkinshaw7 weeks ago

  • Resolution wontfix deleted
  • Status changed from closed to reopened

I'm re-opening this because I believe it should be open to discussion again and I'm going to address the reasons against this in the first place.

Summary

There should be a single consistent file where metadata for plugins and themes is contained. Theme metadata does not belong in the comments of a stylesheet. While it's slightly better being in a plugin's PHP file, creating a separate file would allow for uniformity and consistency. Replacing a custom non-standard specification that uses slow and error prone regular expressions with a well-known, performant, and mature standard like JSON is a big win. This metadata file would also allow more flexibility in the future.

Benefits

  • Performance: I haven't seen this mentioned before, but the current file headers parsing is quite slow due to regular expression usage. I made a very simple micro-benchmark to parse the exact same headers with the current WP method and also with json_decode and parse_ini_file. This benchmark just does 10000 iterations of the parsing.

Results:

  • get_file_data: 1.98s
  • json_decode: 218ms
  • parse_ini_file: 482ms

Obviously the usual disclaimers about benchmarks apply here. But that's almost 10x faster.

Note: I included parse_ini_file here in case the issue is really over JSON itself and not strictly a separate metadata file.

  • Dependencies: As mentioned above, a metadata file would allow for more flexibility for features like dependencies. Without it, a feature like that will probably never happen.
  • Uniformity: since JSON has a spec and built-in parsers in basically every language, it doesn't necessarily matter how you format whitespace for example. But with the current file headers, there's no uniformity and it can cause problems. Here's an example from the bug above:
 Original Theme Name
	Original Theme Name
        Theme Name
      Theme Name
    Theme Name
  Theme Name
 *   Theme Name
 * Theme Name
 *Theme Name
 Theme Name
/* Theme Name
/*	Theme Name
/*Theme Name
* Theme Name
/*Theme Name
		Theme Name
	Theme Name
Theme Name

Rebuttals

While this means you don't need a style.css file for a theme, you'll still need a .json file. Considering you don't actually need to use style.css for, well, CSS, this isn't much of a benefit. If anything, it means people will need to look in two places, not one.

Right now for a theme, you need to look in the style.css file to find the theme metadata. While this may be obvious to people familiar with WordPress, it doesn't actually make logic sense. Why would a theme's metadata be in comments in a stylesheet? It's an arbitrary choice. Why not a scripts.js file? Or the index.php file? A separate file for metadata is more common sense and logical since it's used across all software.

It would also make things consistent between plugins and themes. Right now you need to look in a stylesheet for one and a PHP for another. This is logical at all.

While JSON files are both machine-readable and human-readable, they aren't necessarily human-editable. You need to understand syntax and such, and there are some gotchas like trailing commas and when to quote that can be confusing.

The [File Header Specification](http://codex.wordpress.org/File_Header) is completely non-standard and is just a list of 17 things. There's no formal spec and frankly nothing really like it. While JSON may be harder to edit than the current headers (which is debatable), as it's a well known standard with a formal specification and tools to edit, validate, and parse it.

I also think JSON has gotten even more used since nacin's comment 21 months ago thanks to Composer in the PHP world and JavaScript.

Oh please no. I love JSON as an interchange format between machines, but as configuration files, they're just insane.

See above. Tons of popular tools use JSON as a configuration format including in the PHP world.

+1 for close it too. For dependencies it can be a JSON file but then use a file only for that.

Why would you have a separate file just for dependencies and not move the metadata to there as well? This goes completely against what many popular tools are doing now. See npm's package.json and Composer's composer.json.

Keeping in mind that themes already need 2 files as a minimum, index.php and style.css, and that the primary argument against this is a situation that we already have in plugins, namely that we have to define our plugin in the header, and readme.txt

This is a great point which a separate metadata file also solves. There should be a common file for plugins and themes which would replace file headers and deprecate the need for a readme.txt file.

Last edited 7 weeks ago by swalkinshaw (previous) (diff)

comment:18 follow-up: @TJNowell6 weeks ago

I would rather we allowed the use of package.json or composer.json rather than a new file and specification. composer.json already has precedents for defining a wordpress theme, and provisions for any additional data not already covered. It's a spec already in use by various projects and the PHP world at large, with a well tested toolchain.

If we added another json file, we could have the same information in 3 files if someone who uses Composer decided to also use grunt etc, which is an unnecessary level of redundancy to keep track of.

comment:19 in reply to: ↑ 18 @swalkinshaw6 weeks ago

Replying to TJNowell:

I would rather we allowed the use of package.json or composer.json rather than a new file and specification. composer.json already has precedents for defining a wordpress theme, and provisions for any additional data not already covered. It's a spec already in use by various projects and the PHP world at large, with a well tested toolchain.

If we added another json file, we could have the same information in 3 files if someone who uses Composer decided to also use grunt etc, which is an unnecessary level of redundancy to keep track of.

That's a good idea and fine with me. I'm not really arguing for a "new file" specifically. More so just to get rid of the file headers and move them into their own file (whatever that may be).

edit: if anything, composer.json makes sense over package.json for obvious reasons. I mostly didn't get into Composer in my reply because I don't want the discussion to get caught up into another debate over it. This is really just about a better file headers replacement.

Last edited 6 weeks ago by swalkinshaw (previous) (diff)

comment:20 @SergeyBiryukov5 weeks ago

  • Milestone set to Awaiting Review

comment:21 @slackbot2 weeks ago

This ticket was mentioned in Slack in #meta by obenland. View the logs.

Note: See TracTickets for help on using tickets.