IBX-9902: PHP API Ref: Support new PHP features

tools/php_api_ref/.phpdoc/template/base.html.twig

@@ -1,6 +1,6 @@
 {% extends 'layout.html.twig' %}
 
-{% set symfony_version = '5.4' %}
+{% set symfony_version = 'SF_VERSION' %}
 
 {% block javascripts %}
     {{ parent() }}

tools/php_api_ref/.phpdoc/template/components/class-title.html.twig

@@ -8,6 +8,12 @@
     add_edition: true,
 } %}
     {% block subheader %}
+        {% if node.isReadOnly %}
+            <div class="content-header__subheader">Read Only</div>
+        {% endif %}
+        {% if node.isFinal %}
+            <div class="content-header__subheader">Final</div>
+        {% endif %}
         {% if node.isAbstract %}
             <div class="content-header__subheader">Abstract</div>
         {% endif %}

tools/php_api_ref/.phpdoc/template/components/constant.html.twig

@@ -9,3 +9,4 @@
 {% include 'components/description.html.twig' with { node: constant } %}
 {% include 'components/description.html.twig' with { node: constant.var[0] } %}
 {% include 'components/tags.html.twig' with {node: constant } %}
+{% include 'components/attributes.html.twig' with { node: constant } %}

tools/php_api_ref/.phpdoc/template/components/enum-case-signature.html.twig

@@ -0,0 +1,8 @@
+{% set code %}{% apply spaceless %}
+    {% if node.parent.backedType %}
+        <span class="phpdocumentor-signature__type">{{ node.parent.backedType }} </span>
+    {% endif %}
+    <span class="phpdocumentor-signature__name">{{ node.name }}</span> = <span class="phpdocumentor-signature__default-value">{{ node.value | default('""') }}</span>
+{% endapply %}{% endset %}
+
+{% include 'components/signature.html.twig' with { code } %}

tools/php_api_ref/.phpdoc/template/components/enum-case.html.twig

@@ -0,0 +1,11 @@
+<article class="phpdocumentor-element-enum-case">
+    {% embed 'components/content-header.html.twig' with { node: case, anchor: 'enumcase_' ~ case.name, anchor_link: link(case), header_tag: 'h3' } %}
+    {% endembed %}
+    {% include 'components/summary.html.twig' with { node: case } %}
+    {% if case.value %}{% include 'components/enum-case-signature.html.twig' with { node: case } %}{% endif %}
+    {% include 'components/deprecation.html.twig' with { node: case } %}
+    {% include 'components/description.html.twig' with { node: case } %}
+    {% include 'components/description.html.twig' with { node: case.var[0] } %}
+    {% include 'components/tags.html.twig' with { node: case } %}
+    {% include 'components/attributes.html.twig' with { node: case } %}
+</article>

tools/php_api_ref/.phpdoc/template/components/enum-title.html.twig

@@ -0,0 +1,21 @@
+{% 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 name %}
+        {{ node.name }}
+    {% endblock %}
+    {% block subheader %}
+        <div class="content-header__subheader">
+            Enum
+            {%- if node.backedType -%}
+                : {{ node.backedType }}
+            {% endif %}
+        </div>
+    {% endblock %}
+{% endembed %}

tools/php_api_ref/.phpdoc/template/components/menu-entry.html.twig

@@ -1,4 +1,4 @@
-{% set is_nested = entry.children.count or entry.interfaces[0] is defined or entry.classes[0] is defined or entry.traits[0] is defined %}
+{% set is_nested = entry.children.count or entry.interfaces[0] is defined or entry.classes[0] is defined or entry.traits[0] is defined or entry.enums[0] is defined %}
 {% set url = entry|route("url")|raw %}
 {% set type = type|default('') %}
 

tools/php_api_ref/.phpdoc/template/components/menu.html.twig

@@ -35,10 +35,10 @@
         </ul>
     {% endif %}
 
-    {% if entry.interfaces[0] is defined or entry.classes[0] is defined or entry.traits[0] is defined %}
+    {% if entry.interfaces[0] is defined or entry.classes[0] is defined or entry.traits[0] is defined or entry.enums[0] is defined %}
         {% if depth > 1 %}
             <label class="md-nav__list-title">
-                Interfaces, classes, and traits
+                Interfaces, classes, traits, and enums
             </label>
         {% endif %}
         <ul class="md-nav__list">
@@ -78,6 +78,19 @@
                         icon: 'file.svg',
                     } %}
 
+                    {% set index = index + 1 %}
+                {% endfor %}
+            {% endif %}
+            {% if entry.enums[0] is defined %}
+                {% for element in entry.enums|sort_asc %}
+                    {% include 'components/menu-entry.html.twig' with {
+                        title: element.name|shortFQSEN,
+                        nav_id: nav_id ~ '-' ~ index,
+                        entry: element,
+                        expanded: false,
+                        icon: 'file.svg',
+                    } %}
+
                     {% set index = index + 1 %}
                 {% endfor %}
             {% endif %}

tools/php_api_ref/.phpdoc/template/components/method.html.twig

@@ -15,3 +15,4 @@
 {% include 'components/method-arguments.html.twig' with { node: method } %}
 {% include 'components/method-response.html.twig' with { node: method } %}
 {% include 'components/tags.html.twig' with { node: method } %}
+{% include 'components/attributes.html.twig' with { node: method } %}

tools/php_api_ref/.phpdoc/template/components/property.html.twig

@@ -13,3 +13,4 @@
 {% include 'components/description.html.twig' with { node: property } %}
 {% include 'components/description.html.twig' with { node: property.var[0] } %}
 {% include 'components/tags.html.twig' with {node: property } %}
+{% include 'components/attributes.html.twig' with { node: property } %}

tools/php_api_ref/.phpdoc/template/components/table-of-contents.html.twig

@@ -52,14 +52,17 @@
 {% if node.traits[0] is defined %}
     {% set joined_data = joined_data|merge(node.traits) %}
 {% endif %}
+{% if node.enums[0] is defined %}
+    {% set joined_data = joined_data|merge(node.enums) %}
+{% endif %}
 
 {% if joined_data is not empty %}
     <h2 id="interfaces">
-        Interfaces, classes, and traits
+        Interfaces, classes, traits, and enums
         {%- include 'components/anchor.html.twig' with { anchor_link: link(node) ~ '#interfaces' } -%}
     </h2>
     <ul class="namespace-list">
-        {% for entry in joined_data %}
+        {% for entry in joined_data|sort((entry1, entry2) => entry1.name <=> entry2.name) %}
             <li>
                 <span>
                     <img src="./images/arrow-right.svg" class="arrow" />

tools/php_api_ref/.phpdoc/template/css/base.css.twig

@@ -585,6 +585,6 @@ ul.breadcrumbs li.breadcrumb-item-current span {
 
 }
 
-.phpdocumentor-admonition article {
+.phpdocumentor-admonition article, .phpdocumentor-cases article {
     padding-bottom: 0;
 }

tools/php_api_ref/.phpdoc/template/enum.html.twig

@@ -0,0 +1,65 @@
+{% 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/enum-title.html.twig' %}
+    {% include 'components/element-header.html.twig' %}
+    {% include 'components/enum-cases.html.twig' %}
+    {% include 'components/methods.html.twig' %}
+{% endblock %}
+
+{% block on_this_page %}
+    {% set cases = cases(node) %}
+    {% set methods = methods(node) %}
+
+    {% if cases 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 cases is not empty %}
+            <li class="md-nav__item level-1 with-children">
+                <a href="{{ node|route("url")|raw }}#cases" title="Cases" class="md-nav__link">
+                    Cases
+                </a>
+                <nav class="md-nav">
+                    <ul class="md-nav__list">
+                        {% for case in cases %}
+                            <li class="md-nav__item level-2">
+                                <a href="{{ link(case) }}" title="{{ case.name }}" class="md-nav__link">
+                                    {{ case.name }}
+                                </a>
+                            </li>
+                        {% 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 %}

tools/php_api_ref/phpdoc.sh

@@ -9,6 +9,7 @@ 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 automated-translation product-catalog-date-time-attribute); # 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
+SF_VERSION='5.4'; # Symfony version used by Ibexa DXP
 PHPDOC_VERSION='3.7.1'; # Version of phpDocumentor used to build the Reference
 PHPDOC_CONF="$(pwd)/tools/php_api_ref/phpdoc.dist.xml"; # Absolute path to phpDocumentor configuration file
 #PHPDOC_CONF="$(pwd)/tools/php_api_ref/phpdoc.dev.xml"; # Absolute path to phpDocumentor configuration file
@@ -89,10 +90,6 @@ fi
 
 if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
   echo -n 'Building package→edition map… ';
-  map=$PHPDOC_DIR/template/package-edition-map.twig;
-  if [[ -f $map ]]; then
-    rm $map;
-  fi;
   PACKAGE_MAP=''
   NAMESPACE_MAP=''
   for edition in ${DXP_EDITIONS[@]}; do
@@ -110,14 +107,22 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
       break;
     fi;
   done;
+  echo 'OK';
 
+  echo -n 'Building namespace→edition map… ';
   for package in "${DXP_ADD_ONS[@]}"; do
     NAMESPACES=$(composer show "ibexa/$package" --available --format=json | \
       jq -r --arg PACKAGE "ibexa/$package" '"'\''\(.autoload | ."psr-4" | try to_entries[] catch empty | .key[:-1] | sub("\\\\";"\\\\\\";"g"))'\'': '\''\($PACKAGE)'\'',"')
     NAMESPACE_MAP="$NAMESPACE_MAP\n$NAMESPACES"
     PACKAGE_MAP="$PACKAGE_MAP\n'ibexa/$package': 'optional',"
   done;
+  echo 'OK';
 
+  echo -n "Store package→edition and namespace→edition maps into $map… ";
+  map=$PHPDOC_DIR/template/package-edition-map.twig;
+  if [[ -f $map ]]; then
+    rm $map;
+  fi;
   PACKAGE_MAP="{% set package_edition_map = {\n$PACKAGE_MAP\n} %}"
   NAMESPACE_MAP="{% set namespace_package_map = {\n$NAMESPACE_MAP\n} %}"
   {
@@ -154,6 +159,9 @@ mv ./.phpdoc/template/fonts ./php_api_reference/;
 mv ./.phpdoc/template/images ./php_api_reference/;
 mv ./.phpdoc/template/js/*.js ./php_api_reference/js/;
 
+echo 'Set Symfony version…';
+sed "s/symfony_version = '.*'/symfony_version = '$SF_VERSION'/" $PHPDOC_DIR/template/base.html.twig > ./.phpdoc/template/base.html.twig;
+
 echo 'Run phpDocumentor…';
 curl -LO "https://github.com/phpDocumentor/phpDocumentor/releases/download/v$PHPDOC_VERSION/phpDocumentor.phar";
 PHPDOC_BIN='phpDocumentor.phar';