[wp-trac] [WordPress Trac] #24152: Use JSON as alternative to headers

[WordPress Trac]

#24152: Use JSON as alternative to headers
-----------------------------+-----------------------
 Reporter:  ryanve           |       Owner:
     Type:  feature request  |      Status:  reopened
 Priority:  normal           |   Milestone:
Component:  Themes           |     Version:
 Severity:  normal           |  Resolution:
 Keywords:  close            |     Focuses:
-----------------------------+-----------------------
Changes (by swalkinshaw):

 * status:  closed => reopened
 * resolution:  wontfix =>


Comment:

 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. But first, here are some benefits:

 == Summary ==

 There should be a single consistent file where metadata for plugins and
 themes are 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.

 * '''Bugs''': The current parsing method is error prone due to using
 regular expressions. See ticket:19854 and ticket:15193.

 * '''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.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/24152#comment:17>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform