Enhance PHP API Ref (#2584)

adriendupuis · web-flow · commit 53836ce2c03f · 2025-01-06T09:56:38.000+01:00
* .phpdoc/template/components/tags.html.twig: Handle @Used-By * .phpdoc/template/components/properties.html.twig: Get duplicates closer to each others. * .phpdoc/template/class.html.twig: Deduplicates properties * .phpdoc/template: Indicate interface or abstract * .phpdoc/template/trait.html.twig: Add missing template * .phpdoc/template/: Redo external links to GitHub using JS
diff --git a/tools/php_api_ref/.phpdoc/template/base.html.twig b/tools/php_api_ref/.phpdoc/template/base.html.twig
@@ -6,6 +6,7 @@
     {{ parent() }}
 
     <script>
+        window.symfonyVersion = '{{ symfony_version }}';
         window.addEventListener('keyup', (event) => {
             if (event.key === '/') {
                 event.stopImmediatePropagation();
diff --git a/tools/php_api_ref/.phpdoc/template/class.html.twig b/tools/php_api_ref/.phpdoc/template/class.html.twig
@@ -8,8 +8,8 @@
 
 {% block content %}
     {% include 'components/breadcrumbs.html.twig' %}
-    {% include 'components/class-title.html.twig' with { symfony_version: symfony_version } %}
-    {% include('components/element-header.html.twig') %}
+    {% include 'components/class-title.html.twig' %}
+    {% include 'components/element-header.html.twig' %}
     {% include 'components/constants.html.twig' %}
     {% include 'components/properties.html.twig' %}
     {% include 'components/methods.html.twig' %}
@@ -52,12 +52,16 @@
                 </a>
                 <nav class="md-nav">
                     <ul class="md-nav__list">
+                        {% set treated_properties = [] %}
                         {% for property in properties|sortByVisibility %}
-                            <li class="md-nav__item level-2">
-                                <a href="{{ link(property) }}" title="{{ property.name }}" class="md-nav__link">
-                                    {{ property.name }}
-                                </a>
-                            </li>
+                            {% if property.__toString() not in treated_properties %}
+                                <li class="md-nav__item level-2">
+                                    <a href="{{ link(property) }}" title="{{ property.name }}" class="md-nav__link">
+                                        {{ property.name }}
+                                    </a>
+                                </li>
+                                {% set treated_properties = treated_properties|merge([property.__toString()]) %}
+                            {% endif %}
                         {% endfor %}
                     </ul>
                 </nav>
diff --git a/tools/php_api_ref/.phpdoc/template/components/class-title.html.twig b/tools/php_api_ref/.phpdoc/template/components/class-title.html.twig
@@ -8,16 +8,13 @@
     add_edition: true,
 } %}
     {% block subheader %}
+        {% if node.isAbstract %}
+            <div class="content-header__subheader">Abstract</div>
+        {% endif %}
+
         {% if node.parent %}
             <div class="content-header__subheader">
-                {% if node.parent.__toString starts with '\\Symfony\\' %}
-                    Extends
-                    <a href="{{ 'https://github.com/symfony/symfony/blob/' ~ symfony_version ~ '/src' ~ node.parent|replace({'\\': '/'}) ~ '.php' }}" class="external">
-                        <abbr title="{{ node.parent }}">{{ node.parent.name }}</abbr>
-                    </a>
-                {% else %}
-                    Extends {{ node.parent|route('class:short') }}
-                {% endif %}
+                Extends {{ node.parent|route('class:short') }}
             </div>
         {% endif %}
 
diff --git a/tools/php_api_ref/.phpdoc/template/components/interface-title.html.twig b/tools/php_api_ref/.phpdoc/template/components/interface-title.html.twig
@@ -8,6 +8,8 @@
     add_edition: true,
 } %}
     {% block subheader %}
+        <div class="content-header__subheader">Interface</div>
+
         {% if node.parent is not empty %}
             <div class="content-header__subheader">
                 Extends
diff --git a/tools/php_api_ref/.phpdoc/template/components/properties.html.twig b/tools/php_api_ref/.phpdoc/template/components/properties.html.twig
@@ -1,4 +1,6 @@
 {% set properties = properties(node)|sortByVisibility %}
+{% set explorable_properties = properties(node)|sortByVisibility %}
+{% set treated_properties = [] %}
 
 {% if properties is not empty %}
         <h2 id="properties">
@@ -7,7 +9,14 @@
         </h2>
 
         {% for property in properties %}
-            {% include 'components/property.html.twig' %}
+            {% if property.__toString() not in treated_properties %}
+                {% for explored_property in explorable_properties %}
+                    {% if explored_property.__toString() == property.__toString() %}
+                        {% include 'components/property.html.twig' with {'property': explored_property} %}
+                    {% endif %}
+                {% endfor %}
+                {% set treated_properties = treated_properties|merge([property.__toString()]) %}
+            {% endif %}
         {% endfor %}
     </section>
 {% endif %}
diff --git a/tools/php_api_ref/.phpdoc/template/components/tags.html.twig b/tools/php_api_ref/.phpdoc/template/components/tags.html.twig
@@ -3,7 +3,7 @@
 {% set tags = node.tags|filter((v,k) => k not in excluded_tags and not (k starts with 'phpstan-')) %}
 {% set has_tags = false %}
 {% for name,seriesOfTag in tags %}
-    {% if name in ['see', 'uses'] %}
+    {% if name in ['see', 'uses', 'used-by'] %}
         {% set seriesOfTag = seriesOfTag|filter(tag => '<a ' in tag.reference|route('class:short')) %}
     {% endif %}
     {% if seriesOfTag|length > 0 %}
@@ -19,7 +19,7 @@
     </h5>
     <dl class="phpdocumentor-tag-list">
         {% for name,seriesOfTag in tags %}
-            {% if name in ['see', 'uses'] %}
+            {% if name in ['see', 'uses', 'used-by'] %}
                 {%  set seriesOfTag = seriesOfTag|filter(tag => '<a ' in tag.reference|route('class:short')) %}
             {% endif %}
             {% for tag in seriesOfTag %}
diff --git a/tools/php_api_ref/.phpdoc/template/components/trait-title.html.twig b/tools/php_api_ref/.phpdoc/template/components/trait-title.html.twig
@@ -0,0 +1,22 @@
+{% set breadcrumbs = usesNamespaces ? breadcrumbs(node) : packages(node) %}
+{% set fqcn = breadcrumbs|map(breadcrumb => breadcrumb.name)|join('\\') ~ '\\' ~ node.name %}
+
+{% embed 'components/content-header.html.twig' with { 
+    anchor: node.name,
+    anchor_link: '#' ~ node.name,
+    fqcn,
+    add_edition: true,
+} %}
+    {% block subheader %}
+        <div class="content-header__subheader">Trait</div>
+
+        {% if node.usedTraits is not empty %}
+            <div class="content-header__subheader">
+                Uses
+                {% for trait in node.usedTraits %}
+                    {{ trait|route('class:short') }}{% if not loop.last %}, {% endif %}
+                {% endfor %}
+            </div>
+        {% endif %}
+    {% endblock %}
+{% endembed %}
diff --git a/tools/php_api_ref/.phpdoc/template/interface.html.twig b/tools/php_api_ref/.phpdoc/template/interface.html.twig
@@ -9,7 +9,7 @@
 {% block content %}
     {% include 'components/breadcrumbs.html.twig' %}
     {% include 'components/interface-title.html.twig' %}
-    {% include('components/element-header.html.twig') %}
+    {% include 'components/element-header.html.twig' %}
     {% include 'components/constants.html.twig' %}
     {% include 'components/methods.html.twig' %}
 {% endblock %}
diff --git a/tools/php_api_ref/.phpdoc/template/js/external-links.js b/tools/php_api_ref/.phpdoc/template/js/external-links.js
@@ -0,0 +1,10 @@
+$(() => {
+    $('abbr').each((index, element) => {
+        let $this = $(element);
+        let fqcn = $this.attr('title');
+        if (fqcn.startsWith('\\Symfony\\') && 'a' != $this.parent().prop('tagName')) {
+            let href = 'https://github.com/symfony/symfony/blob/' + symfonyVersion + '/src' + fqcn.replaceAll('\\', '/') + '.php';
+            $this.wrap('<a href="' + href + '" class="external">');
+        }
+    });
+})
diff --git a/tools/php_api_ref/.phpdoc/template/layout.html.twig b/tools/php_api_ref/.phpdoc/template/layout.html.twig
@@ -68,5 +68,6 @@
     <script src="js/search_custom.js"></script>
     <script src="js/copy_to_clipboard.js"></script>
     <script src="js/version_switcher_custom.js"></script>
+    <script src="js/external-links.js"></script>
 </body>
 </html>
diff --git a/tools/php_api_ref/.phpdoc/template/trait.html.twig b/tools/php_api_ref/.phpdoc/template/trait.html.twig
@@ -0,0 +1,89 @@
+{% extends 'base.html.twig' %}
+
+{% block title %}{{ node.name }} | {{ parent() }}{% endblock %}
+{% block meta %}
+    <meta name="description" content="{{ node.summary|escape }}" />
+    {{ parent() }}
+{% endblock %}
+
+{% block content %}
+    {% include 'components/breadcrumbs.html.twig' %}
+    {% include 'components/trait-title.html.twig' %}
+    {% include 'components/element-header.html.twig' %}
+    {% include 'components/constants.html.twig' %}
+    {% include 'components/properties.html.twig' %}
+    {% include 'components/methods.html.twig' %}
+{% endblock %}
+
+{% block on_this_page %}
+    {% set constants = constants(node) %}
+    {% set properties = properties(node) %}
+    {% set methods = methods(node) %}
+
+    {% if constants is not empty or properties is not empty or methods is not empty %}
+        <label class="md-nav__title" for="__toc" title="{{ node.name }}">
+            {{ node.name }}
+        </label>
+    {% endif %}
+
+    <ul class="md-nav__list">
+        {% if constants is not empty %}
+            <li class="md-nav__item level-1 with-children">
+                <a href="{{ node|route("url")|raw }}#constants" title="Constants" class="md-nav__link">
+                    Constants
+                </a>
+                <nav class="md-nav">
+                    <ul class="md-nav__list">
+                        {% for constant in constants|sortByVisibility %}
+                            <li class="md-nav__item level-2">
+                                <a href="{{ link(constant) }}" title="{{ constant.name }}" class="md-nav__link">
+                                    {{ constant.name }}
+                                </a>
+                            </li>
+                        {% endfor %}
+                    </ul>
+                </nav>
+            </li>
+        {% endif %}
+        {% if properties is not empty %}
+            <li class="md-nav__item level-1 with-children">
+                <a href="{{ node|route("url")|raw }}#properties" title="Properties" class="md-nav__link">
+                    Properties
+                </a>
+                <nav class="md-nav">
+                    <ul class="md-nav__list">
+                        {% set treated_properties = [] %}
+                        {% for property in properties|sortByVisibility %}
+                            {% if property.__toString() not in treated_properties %}
+                                <li class="md-nav__item level-2">
+                                    <a href="{{ link(property) }}" title="{{ property.name }}" class="md-nav__link">
+                                        {{ property.name }}
+                                    </a>
+                                </li>
+                                {% set treated_properties = treated_properties|merge([property.__toString()]) %}
+                            {% endif %}
+                        {% endfor %}
+                    </ul>
+                </nav>
+            </li>
+        {% endif %}
+        {% if methods is not empty %}
+            <li class="md-nav__item level-1 with-children">
+                <a href="{{ node|route("url")|raw }}#methods" title="Methods" class="md-nav__link">
+                    Methods
+                </a>
+                <nav class="md-nav">
+                    <ul class="md-nav__list">
+                        {% for method in methods|sortByVisibility %}
+                            <li class="md-nav__item level-2">
+                                <a href="{{ link(method) }}" title="{{ method.name }}" class="md-nav__link">
+                                    {{ method.name }}()
+                                </a>
+                            </li>
+                        {% endfor %}
+                    </ul>
+                </nav>
+            </li>
+        {% endif %}
+    </ul>
+{% endblock %}
