[wp-trac] [WordPress Trac] #59444: Add language injection comments for embedded languages in PHP

[WordPress Trac]

#59444: Add language injection comments for embedded languages in PHP
-----------------------------------------------+---------------------------
 Reporter:  westonruter                        |      Owner:  (none)
     Type:  enhancement                        |     Status:  new
 Priority:  normal                             |  Milestone:  Awaiting
                                               |  Review
Component:  General                            |    Version:  trunk
 Severity:  normal                             |   Keywords:
  Focuses:  javascript, css, coding-standards  |
-----------------------------------------------+---------------------------
 As part of #4773 and #58775, many manually-constructed inline `<script>`
 and `<style>` tags were replaced with API calls to
 `wp_print_inline_script_tag()` and `wp_add_inline_style()`, respectively.
 While doing so comes with key runtime benefits, a downside is introduced
 in terms of the developer experience. In particular, when editing a PHP
 file that has an embedded `<style>` or `<script>` tag, IDEs will do syntax
 highlighting and other code intelligence features for the embedded
 language. These IDE features are particularly important since the JS/CSS
 code in question is not located in a `.js` or `.css` file, meaning it is
 not included in static analysis checks (e.g. JSHint). This means that the
 IDE is the first line of defense against developers accidentally making a
 typo or introducing a syntax error which, if it passes code review, would
 otherwise only get discovered at runtime in user testing. These IDE
 features are also important for developer productivity (e.g.
 autocompletion).

 I understand PhpStorm to be the most popular IDE for WordPress core
 development, and it has a [https://www.jetbrains.com/help/phpstorm/using-
 language-injections.html#use-lang-annotation language injection] feature.
 It involves using comments that precede the embedded language string, for
 example:

 {{{#!php
 wp_print_inline_script_tag( /** @lang JavaScript */
 "document.body.className = document.body.className.replace('no-js','js');"
 );
 }}}

 or

 {{{#!php
 wp_add_inline_style(
         'admin-bar',
         // language=CSS
         '@media print { #wpadminbar { display:none; } }'
 );
 }}}

 VSCode has an issue for [https://github.com/Microsoft/vscode/issues/1751
 Universal Language Injections], but it was
 [https://github.com/Microsoft/vscode/issues/1751#issuecomment-919998146
 closed] for being too difficult. Apparently the scope was to go to the
 extent of detecting embedded languages even without the language injection
 comments that Jetbrains IDEs support. The feature was apparently relegated
 to the [https://code.visualstudio.com/api/language-extensions/embedded-
 languages extension space] (cf. [https://code.visualstudio.com/api
 /language-extensions/syntax-highlight-guide#embedded-languages Syntax
 Highlight Guide]).

 That being said, it does appear that VSCode does support method that
 PhpStorm supports: [https://www.jetbrains.com/help/phpstorm/using-
 language-injections.html#inject-language-nowdoc-heredoc Inject a language
 inside a nowdoc/heredoc string]. (I can't seem to find any VSCode
 documentation about this, but it seems to work locally.) This allows you
 to do:

 {{{#!php
 wp_print_inline_script_tag(
 <<<JS
         "document.body.className = document.body.className.replace('no-
 js','js');"
 JS
 );
 }}}

 Nevertheless, there are also issues with the ergonomics of heredoc
 strings, especially
 [https://www.php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc:~:text=Prior%20to%20PHP%207.3.0%2C%20it,be%20followed%20by%20a%20newline.
 prior to PHP 7.3]: the closing delimiter must always start at the
 beginning of the line, and it cannot have any comma following it on the
 same line. So that means you cannot do the following in PHP<7.3:

 {{{#!php
 $scripts->add_inline_script(
         'media-widgets',
         <<<JS
                 wp.mediaWidgets.init();
         JS,
         'after'
 );
 }}}

 Since WordPress only now just bumped the minimum requirement to 7.0, this
 isn't yet an option.

 I suggest that PhpStorm's syntax for language injection comments be
 adopted in WordPress core as a convention. Since PhpStorm is apparently
 the most popular IDE for WordPress core development, it will be useful for
 core contributors. For VSCode, an extension could potentially be written
 that adds support for the same syntax. Otherwise, we wait until PHP 7.3 is
 the minimum requirement and switch all existing JS/CSS string literals to
 heredocs.

 Previous conversations:

 * https://wordpress.slack.com/archives/C5UNMSU4R/p1693591315595499
 * https://core.trac.wordpress.org/ticket/58664#comment:17
 * https://github.com/WordPress/wordpress-
 develop/pull/4773#discussion_r1330779429

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/59444>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform