feature #176 Add more modern PHP syntax highlighting (wouterj)

This PR was squashed before being merged into the main branch.

Discussion
----------

Add more modern PHP syntax highlighting

Because I had fun playing around with this, I've added more changes to the PHP syntax file, bringing it more or less up to date with Highlight.js' syntax file.

Noteworthy changes:
* Support arrow functions, enums, match statement, named arguments and more constants
* Updated the full list of supported PHP types
* Identify function class/class instantiations (this improves highlighting function arguments)

`@javiereguiluz` please test this out locally. This patch will generally add more color to the code blocks. You might want to tweak the CSS a bit depending on your favor (we seem to have relatively little coloring in our code examples).
E.g. function calls now get `hljs-title` as well (you can use `.invoke__` to differentiate them from other titles), and named arguments will be labelled as `hljs-attr` (which is currently colored similar to `hljs-meta` used for PHP attributes).

| Before | After
| --- | ---
| ![image](https://github.com/symfony-tools/docs-builder/assets/749025/f38b5b93-f7e7-4bde-9be7-4b8f07adf961) | ![image](https://github.com/symfony-tools/docs-builder/assets/749025/cc2b36d7-73d0-4bc9-a151-6b1aaf699d7c)
| ![image](https://github.com/symfony-tools/docs-builder/assets/749025/5d0054ed-f3cf-459f-b079-1ace730dadea) | ![image](https://github.com/symfony-tools/docs-builder/assets/749025/c57facf0-101c-414d-92cd-c2f3c514d2f8)
| ![image](https://github.com/symfony-tools/docs-builder/assets/749025/89fc8e5f-a513-4c37-8ae1-8015a2960e55) | ![image](https://github.com/symfony-tools/docs-builder/assets/749025/5c772837-027c-4ae8-929e-9aaab12fc05f)

Commits
-------

0642507 Add more modern PHP syntax highlighting

src/Renderers/CodeNodeRenderer.php

@@ -70,9 +70,6 @@ public function render(): string
 
             $highLighter = new Highlighter();
             $highlightedCode = $highLighter->highlight($languageMapping, $code)->value;
-
-            // this allows to highlight the $ in PHP variable names
-            $highlightedCode = str_replace('<span class="hljs-variable">$', '<span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>', $highlightedCode);
         }
 
         if ('terminal' === $language) {

src/Templates/highlight.php/php.json

@@ -8,7 +8,7 @@
         "php7"
     ],
     "case_insensitive": true,
-    "keywords": "and include_once list abstract global private echo interface as static endswitch array null if endwhile or const for endforeach self var while isset public protected exit foreach throw elseif include __FILE__ empty require_once do xor return parent clone use __CLASS__ __LINE__ else break print eval new catch __METHOD__ case exception default die require __FUNCTION__ enddeclare final try match switch continue endfor endif declare unset true false goto instanceof insteadof __DIR__ __NAMESPACE__ yield finally",
+    "keywords": "PHP_VERSION PHP_MAJOR_VERSION PHP_MINOR_VERSION PHP_RELEASE_VERSION PHP_VERSION_ID PHP_EXTRA_VERSION ZEND_THREAD_SAFE ZEND_DEBUG_BUILD PHP_ZTS PHP_DEBUG PHP_MAXPATHLEN PHP_OS PHP_OS_FAMILY PHP_SAPI PHP_EOL PHP_INT_MAX PHP_INT_MIN PHP_INT_SIZE PHP_FLOAT_DIG PHP_FLOAT_EPSILON PHP_FLOAT_MIN PHP_FLOAT_MAX DEFAULT_INCLUDE_PATH PEAR_INSTALL_DIR PEAR_EXTENSION_DIR PHP_EXTENSION_DIR PHP_PREFIX PHP_BINDIR PHP_BINARY PHP_MANDIR PHP_LIBDIR PHP_DATADIR PHP_SYSCONFDIR PHP_LOCALSTATEDIR PHP_CONFIG_FILE_PATH PHP_CONFIG_FILE_SCAN_DIR PHP_SHLIB_SUFFIX PHP_FD_SETSIZE E_ERROR E_WARNING E_PARSE E_NOTICE E_CORE_ERROR E_CORE_WARNING E_COMPILE_ERROR E_COMPILE_WARNING E_USER_ERROR E_USER_WARNING E_USER_NOTICE E_RECOVERABLE_ERROR E_DEPRECATED E_USER_DEPRECATED E_ALL E_STRICT __COMPILER_HALT_OFFSET__ PHP_WINDOWS_EVENT_CTRL_C PHP_WINDOWS_EVENT_CTRL_BREAK PHP_CLI_PROCESS_TITLE STDERR STDIN STDOUT __CLASS__ __DIR__ __FILE__ __FUNCTION__ __LINE__ __METHOD__ __NAMESPACE__ __TRAIT__ die echo exit include include_once print require require_once abstract and as binary break case catch class clone const continue declare default do double else elseif empty enddeclare endfor endforeach endif endswitch endwhile enum eval extends final finally for foreach from global goto if implements instanceof insteadof interface isset list match|0 new or parent private protected public readonly return switch throw trait try unset use var void while xor yield array bool boolean callable float int integer iterable mixed never numeric object real string resource self static false FALSE null NULL true TRUE",
     "contains": [
         {
             "className": "meta",
@@ -26,9 +26,10 @@
                 {
                     "begin": "\\(",
                     "end": "\\)",
-                    "keywords": "true false null new array",
+                    "keywords": "array bool boolean float int integer new real string false FALSE null NULL true TRUE PHP_VERSION PHP_MAJOR_VERSION PHP_MINOR_VERSION PHP_RELEASE_VERSION PHP_VERSION_ID PHP_EXTRA_VERSION ZEND_THREAD_SAFE ZEND_DEBUG_BUILD PHP_ZTS PHP_DEBUG PHP_MAXPATHLEN PHP_OS PHP_OS_FAMILY PHP_SAPI PHP_EOL PHP_INT_MAX PHP_INT_MIN PHP_INT_SIZE PHP_FLOAT_DIG PHP_FLOAT_EPSILON PHP_FLOAT_MIN PHP_FLOAT_MAX DEFAULT_INCLUDE_PATH PEAR_INSTALL_DIR PEAR_EXTENSION_DIR PHP_EXTENSION_DIR PHP_PREFIX PHP_BINDIR PHP_BINARY PHP_MANDIR PHP_LIBDIR PHP_DATADIR PHP_SYSCONFDIR PHP_LOCALSTATEDIR PHP_CONFIG_FILE_PATH PHP_CONFIG_FILE_SCAN_DIR PHP_SHLIB_SUFFIX PHP_FD_SETSIZE E_ERROR E_WARNING E_PARSE E_NOTICE E_CORE_ERROR E_CORE_WARNING E_COMPILE_ERROR E_COMPILE_WARNING E_USER_ERROR E_USER_WARNING E_USER_NOTICE E_RECOVERABLE_ERROR E_DEPRECATED E_USER_DEPRECATED E_ALL E_STRICT __COMPILER_HALT_OFFSET__ PHP_WINDOWS_EVENT_CTRL_C PHP_WINDOWS_EVENT_CTRL_BREAK PHP_CLI_PROCESS_TITLE STDERR STDIN STDOUT __CLASS__ __DIR__ __FILE__ __FUNCTION__ __LINE__ __METHOD__ __NAMESPACE__ __TRAIT__",
                     "contains": {
-                        "$ref": "#contains.11.contains.1.contains"
+                        "$ref": "#contains.10.contains.3.contains",
+                        "_": "params"
                     }
                 },
                 {
@@ -137,39 +138,124 @@
         },
         {
             "className": "variable",
-            "begin": "\\$this\\b"
-        },
-        {
-            "className": "variable",
-            "begin": "\\$+[a-zA-Z_-ÿ][a-zA-Z0-9_-ÿ]*"
+            "begin": "\\$+[a-zA-Z_-ÿ][a-zA-Z0-9_-ÿ]*",
+            "returnBegin": true,
+            "contains": [
+                {
+                    "className": "variable-other-marker",
+                    "begin": "\\$"
+                },
+                {
+                    "begin": "\\$*[a-zA-Z_-ÿ][a-zA-Z0-9_-ÿ]*"
+                }
+            ]
         },
         {
-            "className": "operator",
-            "begin": "(::|->)",
-            "end": "[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*",
-            "excludeEnd": true
+            "begin": "\\b(?!fn\\b|function\\b|__CLASS__\\b|__DIR__\\b|__FILE__\\b|__FUNCTION__\\b|__COMPILER_HALT_OFFSET__\\b|__LINE__\\b|__METHOD__\\b|__NAMESPACE__\\b|__TRAIT__\\b|die\\b|echo\\b|exit\\b|include\\b|include_once\\b|print\\b|require\\b|require_once\\b|array\\b|abstract\\b|and\\b|as\\b|binary\\b|bool\\b|boolean\\b|break\\b|callable\\b|case\\b|catch\\b|class\\b|clone\\b|const\\b|continue\\b|declare\\b|default\\b|do\\b|double\\b|else\\b|elseif\\b|empty\\b|enddeclare\\b|endfor\\b|endforeach\\b|endif\\b|endswitch\\b|endwhile\\b|enum\\b|eval\\b|extends\\b|final\\b|finally\\b|float\\b|for\\b|foreach\\b|from\\b|global\\b|goto\\b|if\\b|implements\\b|instanceof\\b|insteadof\\b|int\\b|integer\\b|interface\\b|isset\\b|iterable\\b|list\\b|match\\b|mixed\\b|new\\b|never\\b|object\\b|or\\b|private\\b|protected\\b|public\\b|readonly\\b|real\\b|return\\b|string\\b|switch\\b|throw\\b|trait\\b|try\\b|unset\\b|use\\b|var\\b|void\\b|while\\b|xor\\b|yield|Countable\\b|OuterIterator\\b|RecursiveIterator\\b|SeekableIterator\\b|ArrayAccess\\b|BackedEnum\\b|Generator\\b|Iterator\\b|IteratorAggregate\\b|Serializable\\b|Stringable\\b|Throwable\\b|Traversable\\b|UnitEnum\\b|__PHP_Incomplete_Class\\b|parent\\b|php_user_filter\\b|self\\b|static\\b)[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*(?![A-Za-z0-9])(?![$])[ \\t\\n]*(?=(?=\\())",
+            "end": "\\)",
+            "returnBegin": true,
+            "contains": [
+                {
+                    "className": "title invoke__",
+                    "begin": "[a-zA-Z0-9_\\x7f-\\xff]\\w*",
+                    "relevance": 0
+                },
+                {
+                    "begin": "\\(",
+                    "endsWithParent": true,
+                    "keywords": "array bool boolean float int integer new real string false FALSE null NULL true TRUE PHP_VERSION PHP_MAJOR_VERSION PHP_MINOR_VERSION PHP_RELEASE_VERSION PHP_VERSION_ID PHP_EXTRA_VERSION ZEND_THREAD_SAFE ZEND_DEBUG_BUILD PHP_ZTS PHP_DEBUG PHP_MAXPATHLEN PHP_OS PHP_OS_FAMILY PHP_SAPI PHP_EOL PHP_INT_MAX PHP_INT_MIN PHP_INT_SIZE PHP_FLOAT_DIG PHP_FLOAT_EPSILON PHP_FLOAT_MIN PHP_FLOAT_MAX DEFAULT_INCLUDE_PATH PEAR_INSTALL_DIR PEAR_EXTENSION_DIR PHP_EXTENSION_DIR PHP_PREFIX PHP_BINDIR PHP_BINARY PHP_MANDIR PHP_LIBDIR PHP_DATADIR PHP_SYSCONFDIR PHP_LOCALSTATEDIR PHP_CONFIG_FILE_PATH PHP_CONFIG_FILE_SCAN_DIR PHP_SHLIB_SUFFIX PHP_FD_SETSIZE E_ERROR E_WARNING E_PARSE E_NOTICE E_CORE_ERROR E_CORE_WARNING E_COMPILE_ERROR E_COMPILE_WARNING E_USER_ERROR E_USER_WARNING E_USER_NOTICE E_RECOVERABLE_ERROR E_DEPRECATED E_USER_DEPRECATED E_ALL E_STRICT __COMPILER_HALT_OFFSET__ PHP_WINDOWS_EVENT_CTRL_C PHP_WINDOWS_EVENT_CTRL_BREAK PHP_CLI_PROCESS_TITLE STDERR STDIN STDOUT __CLASS__ __DIR__ __FILE__ __FUNCTION__ __LINE__ __METHOD__ __NAMESPACE__ __TRAIT__",
+                    "contains": [
+                        {
+                            "className": "attr",
+                            "begin": "[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*(?![A-Za-z0-9])(?![$])(?=:)(?=(?!::))"
+                        },
+                        {
+                            "variants": [
+                                {
+                                    "begin": "::(?=(?!class\\b))[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*(?![A-Za-z0-9])(?![$])\\b(?!\\()",
+                                    "returnBegin": true,
+                                    "contains": [
+                                        {
+                                            "begin": "::"
+                                        },
+                                        {
+                                            "className": "variable constant_",
+                                            "begin": "[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*(?![A-Za-z0-9])(?![$])\\b(?!\\()"
+                                        }
+                                    ]
+                                },
+                                {
+                                    "begin": "::class",
+                                    "returnBegin": true,
+                                    "contains": [
+                                        {
+                                            "begin": "::"
+                                        },
+                                        {
+                                            "className": "variable language_",
+                                            "begin": "class"
+                                        }
+                                    ]
+                                }
+                            ]
+                        },
+                        {
+                            "$ref": "#contains.8",
+                            "_": "variable"
+                        },
+                        {
+                            "$ref": "#contains.10.contains.3.contains.2",
+                            "_": "comment"
+                        },
+                        {
+                            "$ref": "#contains.10.contains.3.contains.3",
+                            "_": "string"
+                        },
+                        {
+                            "$ref": "#contains.10.contains.3.contains.4",
+                            "_": "number"
+                        },
+                        {
+                            "$ref": "#contains.10",
+                            "_": "closure"
+                        },
+                        {
+                            "$ref": "#contains.9",
+                            "_": "invoke"
+                        }
+                    ]
+                }
+            ]
         },
         {
             "className": "function",
-            "beginKeywords": "function",
+            "beginKeywords": "fn function",
             "end": "[;{]",
             "excludeEnd": true,
             "illegal": "\\$|\\[|%",
             "contains": [
+                {
+                    "beginKeywords": "use"
+                },
                 {
                     "className": "title",
                     "begin": "[a-zA-Z_]\\w*",
                     "relevance": 0
                 },
+                {
+                    "begin": "=>",
+                    "endsParent": true
+                },
                 {
                     "className": "params",
                     "begin": "\\(",
                     "end": "\\)",
-                    "keywords": "true false null new array",
+                    "keywords": "array bool boolean callable float int integer iterable mixed never numeric object real string resource self static false FALSE null NULL true TRUE",
                     "contains": [
                         "self",
                         {
-                            "$ref": "#contains.9"
+                            "$ref": "#contains.8",
+                            "_": "variable"
                         },
                         {
                             "className": "comment",
@@ -254,27 +340,42 @@
                             ]
                         },
                         {
-                            "$ref": "#contains.0"
+                            "$ref": "#contains.0",
+                            "_": "simple-attribute"
                         },
                         {
-                            "$ref": "#contains.1"
+                            "$ref": "#contains.1",
+                            "_": "attribute"
                         }
                     ]
                 }
             ]
         },
+        {
+            "$ref": "#contains.9.contains.1.contains.1",
+            "_": "constant"
+        },
         {
             "className": "class",
-            "beginKeywords": "class interface trait enum",
-            "end": "{",
+            "variants": [
+                {
+                    "beginKeywords": "enum",
+                    "illegal": "[($\"]"
+                },
+                {
+                    "beginKeywords": "class interface trait",
+                    "illegal": "[:($\"]"
+                }
+            ],
+            "end": "\\{",
             "excludeEnd": true,
-            "illegal": "[:\\(\\$\"]",
             "contains": [
                 {
                     "beginKeywords": "extends implements"
                 },
                 {
-                    "$ref": "#contains.11.contains.0"
+                    "$ref": "#contains.10.contains.1",
+                    "_": "title"
                 }
             ]
         },
@@ -284,7 +385,8 @@
             "illegal": "[\\.']",
             "contains": [
                 {
-                    "$ref": "#contains.11.contains.0"
+                    "$ref": "#contains.10.contains.1",
+                    "_": "title"
                 }
             ]
         },
@@ -293,18 +395,21 @@
             "end": ";",
             "contains": [
                 {
-                    "$ref": "#contains.11.contains.0"
+                    "$ref": "#contains.10.contains.1",
+                    "_": "title"
                 }
             ]
         },
         {
             "begin": "=>"
         },
         {
-            "$ref": "#contains.11.contains.1.contains.3"
+            "$ref": "#contains.10.contains.3.contains.3",
+            "_": "string"
         },
         {
-            "$ref": "#contains.11.contains.1.contains.4"
+            "$ref": "#contains.10.contains.3.contains.4",
+            "_": "number"
         }
     ]
 }

tests/IntegrationTest.php

@@ -115,8 +115,8 @@ public function testParseUnitBlock(string $blockName)
         $expected = preg_replace('/<\!\-\- REMOVE(.)+\-\->/', '', $expected);
 
         $this->assertSame(
-            $indenter->indent($expected),
-            $indenter->indent(trim($actualCrawler->filter('body')->html()))
+            $this->normalize($indenter->indent($expected)),
+            $this->normalize($indenter->indent(trim($actualCrawler->filter('body')->html())))
         );
     }
 
@@ -351,6 +351,11 @@ public function testParseString()
         $this->assertSame($htmlString, (new DocBuilder())->buildString($rstString)->getStringResult());
     }
 
+    private function normalize(string $str): string
+    {
+        return preg_replace('/\s+$/m', '', $str);
+    }
+
     private function createIndenter(): Indenter
     {
         $indenter = new Indenter();

tests/Templates/fixtures/php.output.html

@@ -11,10 +11,10 @@
      *
      * <span class="hljs-doctag">@Route</span>("/blog/{slug}", name="blog_list")
      */</span>
-    <span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">list</span><span class="hljs-params">(UrlGeneratorInterface <span class="hljs-variable">$urlGenerator</span>, string <span class="hljs-variable">$slug</span>)</span>
+    <span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">list</span><span class="hljs-params">(UrlGeneratorInterface <span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>urlGenerator</span>, <span class="hljs-keyword">string</span> <span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>slug</span>)</span>
     </span>{
-        <span class="hljs-keyword">return</span> <span class="hljs-variable">$this</span><span class="hljs-operator">-&gt;</span>render(<span class="hljs-string">'foo/bar.html.twig'</span>, [
-            <span class="hljs-string">'key'</span> =&gt; <span class="hljs-variable">$value</span>
+        <span class="hljs-keyword">return</span> <span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>this</span>-&gt;<span class="hljs-title invoke__">render</span>(<span class="hljs-string">'foo/bar.html.twig'</span>, [
+            <span class="hljs-string">'key'</span> =&gt; <span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>value</span>
         ]
     }
 }

tests/fixtures/expected/blocks/code-blocks/php-attributes.html

@@ -148,7 +148,7 @@
                 ;
                 <span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">__construct</span><span class="hljs-params">(
                         <span class="hljs-meta">#[TaggedIterator</span>(<span class="hljs-string">'app.handlers'</span>)<span class="hljs-meta">]</span>
-                        iterable <span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>handlers</span>,
+                        <span class="hljs-keyword">iterable</span> <span class="hljs-variable"><span class="hljs-variable-other-marker">$</span>handlers</span>,
                 )</span></span>{
                 }