WordPress.org

Make WordPress Core

Opened 2 years ago

Last modified 6 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 @ryanve2 years ago

  • Type changed from defect (bug) to feature request

comment:2 @toscho2 years ago

  • Cc info@… added

Oh, yes please!

comment:3 @TJNowell2 years ago

  • Cc tom@… added

comment:4 @johnbillion2 years ago

  • Cc johnbillion added

comment:5 @SergeyBiryukov2 years ago

  • Component changed from General to Themes

comment:6 @nacin2 years 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 @rmccue2 years 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 @markoheijnen2 years ago

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

comment:9 @nacin2 years ago

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

comment:10 @travisnorthcutt2 years 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 @TJNowell2 years 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 @zamoose2 years ago

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

comment:13 @ocean907 months ago

#29363 was marked as a duplicate.

comment:14 @Alaa Rihan7 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 @ocean903 months ago

#30974 was marked as a duplicate.

comment:16 @retlehs3 months 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 @swalkinshaw2 months 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 2 months ago by swalkinshaw (previous) (diff)

comment:18 follow-up: @TJNowell2 months 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 @swalkinshaw2 months 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 2 months ago by swalkinshaw (previous) (diff)

comment:20 @SergeyBiryukov2 months ago

  • Milestone set to Awaiting Review

comment:21 @slackbot6 weeks ago

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

Note: See TracTickets for help on using tickets.