From f6f0894209ab38e9bfd491be7b81a54e2bbb942c Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Fri, 20 Dec 2024 16:03:56 +0100
Subject: [PATCH] Get #2584 enhancements

---
 .../.phpdoc/template/base.html.twig           |  1 +
 .../.phpdoc/template/class.html.twig          | 18 ++--
 .../template/components/class-title.html.twig | 13 ++-
 .../template/components/edition-tag.html.twig | 29 +++---
 .../components/interface-title.html.twig      |  2 +
 .../template/components/properties.html.twig  | 11 ++-
 .../template/components/tags.html.twig        |  4 +-
 .../template/components/trait-title.html.twig | 22 +++++
 .../.phpdoc/template/css/base.css.twig        |  5 ++
 .../.phpdoc/template/css/custom.css.twig      |  8 ++
 .../.phpdoc/template/interface.html.twig      |  2 +-
 .../.phpdoc/template/js/external-links.js     | 10 +++
 .../.phpdoc/template/layout.html.twig         |  1 +
 .../.phpdoc/template/trait.html.twig          | 89 +++++++++++++++++++
 tools/php_api_ref/phpdoc.sh                   |  7 ++
 15 files changed, 192 insertions(+), 30 deletions(-)
 create mode 100644 tools/php_api_ref/.phpdoc/template/components/trait-title.html.twig
 create mode 100644 tools/php_api_ref/.phpdoc/template/js/external-links.js
 create mode 100644 tools/php_api_ref/.phpdoc/template/trait.html.twig

diff --git a/tools/php_api_ref/.phpdoc/template/base.html.twig b/tools/php_api_ref/.phpdoc/template/base.html.twig
index fb60a137df..a53b7096d4 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 = '{{ 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
index c5ddbb9b42..61c975d4c8 100644
--- 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
index 1fe63de568..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
@@ -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/edition-tag.html.twig b/tools/php_api_ref/.phpdoc/template/components/edition-tag.html.twig
index dab46133b3..4857bd2caf 100644
--- a/tools/php_api_ref/.phpdoc/template/components/edition-tag.html.twig
+++ b/tools/php_api_ref/.phpdoc/template/components/edition-tag.html.twig
@@ -1,7 +1,8 @@
 {% extends "package-edition-map.twig" %}
 
 {% block content %}
-    {% set edition_list = [
+    {# List of displayable editions sorted in inclusion order, each edition includes the previous ones #}
+    {% set edition_pill_list = [
         'experience',
         'commerce',
     ] %}
@@ -17,15 +18,21 @@
         {% endfor %}
     {% endif %}
 
-    {% if package_edition_map[package] is defined and package_edition_map[package] in edition_list %}
-        {% set is_supporting = false %}
-        {% for edition in edition_list %}
-            {% if edition == package_edition_map[package] %}
-                {% set is_supporting = true %}
-            {% endif %}
-            {% if is_supporting %}
-                <div class="pill {{ edition }}-pill"></div>
-            {% endif %}
-        {% endfor %}
+    {% if package_edition_map[package] is defined %}
+        {% if package_edition_map[package] in edition_pill_list %}
+            {% set is_supporting = false %}
+            {# display edition pills since minimal edition supporting the package #}
+            {% for edition in edition_pill_list %}
+                {% if edition == package_edition_map[package] %}
+                    {% set is_supporting = true %}
+                {% endif %}
+                {% if is_supporting %}
+                    <div class="pill {{ edition }}-pill"></div>
+                {% endif %}
+            {% endfor %}
+        {% endif %}
+    {% else %}
+        {# if package is not in an edition #}
+        <div class="pill optional-pill" title="Included in the optional package {{ package }}"></div>
     {% endif %}
 {% endblock %}
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
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 %}
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 %}
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..9a54c0f1ba
--- /dev/null
+++ 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/css/base.css.twig b/tools/php_api_ref/.phpdoc/template/css/base.css.twig
index 8a334247c9..7fa4ff9992 100644
--- a/tools/php_api_ref/.phpdoc/template/css/base.css.twig
+++ b/tools/php_api_ref/.phpdoc/template/css/base.css.twig
@@ -256,6 +256,11 @@ ul.breadcrumbs li.breadcrumb-item-current span {
     border: 1px solid var(--ibexa-jazzberry);
 }
 
+.md-typeset .content-header .optional-pill {
+    color: var(--sherpa-blue);
+    border: 1px solid var(--sherpa-blue);
+}
+
 .md-typeset .content-header img {
     display: inline-block;
     margin-bottom: -2px;
diff --git a/tools/php_api_ref/.phpdoc/template/css/custom.css.twig b/tools/php_api_ref/.phpdoc/template/css/custom.css.twig
index d41a692e4e..4f110a93c4 100644
--- a/tools/php_api_ref/.phpdoc/template/css/custom.css.twig
+++ b/tools/php_api_ref/.phpdoc/template/css/custom.css.twig
@@ -540,6 +540,14 @@ div.pills {
     background-color: var(--ibexa-jazzberry);
 }
 
+.optional-pill::after {
+    content: "Optional";
+}
+
+.optional-pill {
+    background-color: var(--sherpa-blue);
+}
+
 .md-clipboard:focus, .md-clipboard:hover {
   color: var(--ibexa-jazzberry);
 }
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/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
new file mode 100644
index 0000000000..010096aa2e
--- /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' %}
+    {% 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 %}
diff --git a/tools/php_api_ref/phpdoc.sh b/tools/php_api_ref/phpdoc.sh
index eb079f84c1..ad91ee853e 100755
--- a/tools/php_api_ref/phpdoc.sh
+++ b/tools/php_api_ref/phpdoc.sh
@@ -7,6 +7,7 @@ OUTPUT_DIR=${2:-./docs/api/php_api/php_api_reference}; # Path to the directory w
 
 DXP_EDITION='commerce'; # Edition from and for which the Reference is built
 DXP_VERSION='4.6.*'; # Version from and for which the Reference is built
+DXP_ADD_ONS=(connector-ai connector-openai); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa"
 DXP_EDITIONS=(oss headless experience commerce); # Available editions ordered by ascending capabilities
 PHPDOC_VERSION='3.5.3'; # Version of phpDocumentor used to build the Reference
 PHPDOC_CONF="$(pwd)/tools/php_api_ref/phpdoc.dist.xml"; # Absolute path to phpDocumentor configuration file
@@ -63,6 +64,12 @@ fi;
 
 export COMPOSER_ROOT_VERSION=$DXP_VERSION;
 
+if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
+  for additional_package in "${DXP_ADD_ONS[@]}"; do
+    composer require --no-interaction --ignore-platform-reqs --no-scripts ibexa/$additional_package:$DXP_VERSION
+  done;
+fi;
+
 #if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
 #  MY_PACKAGE='';
 #  MY_BRANCH='';