From 2c545b4f1d17f64071a5bbe63ed604618a6d0c44 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 19 Dec 2024 14:18:00 +0100
Subject: [PATCH 1/9] .phpdoc/template/components/tags.html.twig: Handle
 @used-by

https://docs.phpdoc.org/guide/references/phpdoc/tags/uses.html#uses-used-by is a tag added automatically when a @uses tag is met to create a mirror link back.
---
 tools/php_api_ref/.phpdoc/template/components/tags.html.twig | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/php_api_ref/.phpdoc/template/components/tags.html.twig b/tools/php_api_ref/.phpdoc/template/components/tags.html.twig
index d883f7ad27..68212eb431 100644
--- 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 %}

From 3718039a2444d82c984b44a4ee7a3e67c7b1c660 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 19 Dec 2024 14:33:12 +0100
Subject: [PATCH 2/9] .phpdoc/template/components/properties.html.twig: Get
 duplicates closer to each others.

---
 .../.phpdoc/template/components/properties.html.twig  | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/tools/php_api_ref/.phpdoc/template/components/properties.html.twig b/tools/php_api_ref/.phpdoc/template/components/properties.html.twig
index 220a5f5fe4..62a6406373 100644
--- 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 %}

From 9ca44d1e6a9e94f4059e6b2f9f45ce329e371e2f Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 19 Dec 2024 14:37:38 +0100
Subject: [PATCH 3/9] .phpdoc/template/class.html.twig: Deduplicates properties

---
 tools/php_api_ref/.phpdoc/template/class.html.twig | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/tools/php_api_ref/.phpdoc/template/class.html.twig b/tools/php_api_ref/.phpdoc/template/class.html.twig
index c5ddbb9b42..f86958a04a 100644
--- a/tools/php_api_ref/.phpdoc/template/class.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/class.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>

From adf81818950a5bd859aa82b5ca2b05da17bea6d0 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Wed, 11 Dec 2024 11:20:27 +0100
Subject: [PATCH 4/9] .phpdoc/template: Indicate interface or abstract

---
 .../.phpdoc/template/components/class-title.html.twig        | 5 +++++
 .../.phpdoc/template/components/interface-title.html.twig    | 2 ++
 2 files changed, 7 insertions(+)

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
index 1fe63de568..88b81a1850 100644
--- 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,6 +8,10 @@
     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\\' %}
@@ -39,4 +43,5 @@
             </div>
         {% endif %}
     {% endblock %}
+
 {% endembed %}
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
index 457bcad8fa..2ad8a9ad73 100644
--- 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

From cb1243edbf6efd01e8bdebc92caab3fd72212046 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Thu, 19 Dec 2024 17:04:54 +0100
Subject: [PATCH 5/9] .phpdoc/template/trait.html.twig: Add missing template

---
 .../template/components/trait-title.html.twig | 23 +++++
 .../.phpdoc/template/trait.html.twig          | 89 +++++++++++++++++++
 2 files changed, 112 insertions(+)
 create mode 100644 tools/php_api_ref/.phpdoc/template/components/trait-title.html.twig
 create mode 100644 tools/php_api_ref/.phpdoc/template/trait.html.twig

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
new file mode 100644
index 0000000000..e5a93cdc37
--- /dev/null
+++ b/tools/php_api_ref/.phpdoc/template/components/trait-title.html.twig
@@ -0,0 +1,23 @@
+{% 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/trait.html.twig b/tools/php_api_ref/.phpdoc/template/trait.html.twig
new file mode 100644
index 0000000000..bb1402a462
--- /dev/null
+++ 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' with { symfony_version: symfony_version } %}
+    {% 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 %}

From 0bf3893d3cc814655bde1af8e4e93e9796dd3b28 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 20 Dec 2024 03:26:01 +0100
Subject: [PATCH 6/9] .phpdoc/template/: Redo external links to GitHub using JS

---
 tools/php_api_ref/.phpdoc/template/base.html.twig      |  1 +
 tools/php_api_ref/.phpdoc/template/class.html.twig     |  2 +-
 .../.phpdoc/template/components/class-title.html.twig  |  9 +--------
 .../php_api_ref/.phpdoc/template/js/external-links.js  | 10 ++++++++++
 tools/php_api_ref/.phpdoc/template/layout.html.twig    |  1 +
 tools/php_api_ref/.phpdoc/template/trait.html.twig     |  2 +-
 6 files changed, 15 insertions(+), 10 deletions(-)
 create mode 100644 tools/php_api_ref/.phpdoc/template/js/external-links.js

diff --git a/tools/php_api_ref/.phpdoc/template/base.html.twig b/tools/php_api_ref/.phpdoc/template/base.html.twig
index fb60a137df..01c1e19dc0 100644
--- 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 = '5.4';
         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
index f86958a04a..aabd5f2677 100644
--- a/tools/php_api_ref/.phpdoc/template/class.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/class.html.twig
@@ -8,7 +8,7 @@
 
 {% block content %}
     {% include 'components/breadcrumbs.html.twig' %}
-    {% include 'components/class-title.html.twig' with { symfony_version: symfony_version } %}
+    {% include 'components/class-title.html.twig' %}
     {% include('components/element-header.html.twig') %}
     {% include 'components/constants.html.twig' %}
     {% include 'components/properties.html.twig' %}
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
index 88b81a1850..9372036ecf 100644
--- a/tools/php_api_ref/.phpdoc/template/components/class-title.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/components/class-title.html.twig
@@ -14,14 +14,7 @@
 
         {% 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/js/external-links.js b/tools/php_api_ref/.phpdoc/template/js/external-links.js
new file mode 100644
index 0000000000..5eabe159a6
--- /dev/null
+++ 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
index 785676190f..73d1dd0abb 100644
--- 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
index bb1402a462..74cf8a128b 100644
--- a/tools/php_api_ref/.phpdoc/template/trait.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/trait.html.twig
@@ -8,7 +8,7 @@
 
 {% block content %}
     {% include 'components/breadcrumbs.html.twig' %}
-    {% include 'components/trait-title.html.twig' with { symfony_version: symfony_version } %}
+    {% include 'components/trait-title.html.twig' %}
     {% include('components/element-header.html.twig') %}
     {% include 'components/constants.html.twig' %}
     {% include 'components/properties.html.twig' %}

From dfc05ab8151baa6d487eaeb3e1af2caf54ad8c2c Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 20 Dec 2024 11:11:34 +0100
Subject: [PATCH 7/9] .phpdoc/template/: Unify {% include %} VS {{ include() }}
 usage

---
 tools/php_api_ref/.phpdoc/template/class.html.twig     | 2 +-
 tools/php_api_ref/.phpdoc/template/interface.html.twig | 2 +-
 tools/php_api_ref/.phpdoc/template/trait.html.twig     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tools/php_api_ref/.phpdoc/template/class.html.twig b/tools/php_api_ref/.phpdoc/template/class.html.twig
index aabd5f2677..61c975d4c8 100644
--- a/tools/php_api_ref/.phpdoc/template/class.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/class.html.twig
@@ -9,7 +9,7 @@
 {% block content %}
     {% include 'components/breadcrumbs.html.twig' %}
     {% include 'components/class-title.html.twig' %}
-    {% include('components/element-header.html.twig') %}
+    {% include 'components/element-header.html.twig' %}
     {% include 'components/constants.html.twig' %}
     {% include 'components/properties.html.twig' %}
     {% include 'components/methods.html.twig' %}
diff --git a/tools/php_api_ref/.phpdoc/template/interface.html.twig b/tools/php_api_ref/.phpdoc/template/interface.html.twig
index 3917e39a8e..15977effdb 100644
--- 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/trait.html.twig b/tools/php_api_ref/.phpdoc/template/trait.html.twig
index 74cf8a128b..010096aa2e 100644
--- a/tools/php_api_ref/.phpdoc/template/trait.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/trait.html.twig
@@ -9,7 +9,7 @@
 {% block content %}
     {% include 'components/breadcrumbs.html.twig' %}
     {% include 'components/trait-title.html.twig' %}
-    {% include('components/element-header.html.twig') %}
+    {% include 'components/element-header.html.twig' %}
     {% include 'components/constants.html.twig' %}
     {% include 'components/properties.html.twig' %}
     {% include 'components/methods.html.twig' %}

From 16d6b594f7c7744f7fbaf9e1184ce81f5ecd0f28 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 20 Dec 2024 11:21:21 +0100
Subject: [PATCH 8/9] .phpdoc/template/base.html.twig: Declare Symfony version
 only once

---
 tools/php_api_ref/.phpdoc/template/base.html.twig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/php_api_ref/.phpdoc/template/base.html.twig b/tools/php_api_ref/.phpdoc/template/base.html.twig
index 01c1e19dc0..a53b7096d4 100644
--- a/tools/php_api_ref/.phpdoc/template/base.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/base.html.twig
@@ -6,7 +6,7 @@
     {{ parent() }}
 
     <script>
-        window.symfonyVersion = '5.4';
+        window.symfonyVersion = '{{ symfony_version }}';
         window.addEventListener('keyup', (event) => {
             if (event.key === '/') {
                 event.stopImmediatePropagation();

From 559140fe13eb5c090b92a255c4b30e316d20bfa3 Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 20 Dec 2024 13:02:50 +0100
Subject: [PATCH 9/9] .phpdoc/template/: Minor formatting

---
 .../.phpdoc/template/components/class-title.html.twig            | 1 -
 .../.phpdoc/template/components/trait-title.html.twig            | 1 -
 2 files changed, 2 deletions(-)

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
index 9372036ecf..c1c7ee4240 100644
--- a/tools/php_api_ref/.phpdoc/template/components/class-title.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/components/class-title.html.twig
@@ -36,5 +36,4 @@
             </div>
         {% endif %}
     {% endblock %}
-
 {% endembed %}
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
index e5a93cdc37..9a54c0f1ba 100644
--- a/tools/php_api_ref/.phpdoc/template/components/trait-title.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/components/trait-title.html.twig
@@ -19,5 +19,4 @@
             </div>
         {% endif %}
     {% endblock %}
-
 {% endembed %}