Expanded PHP API Reference

Author: mnocon

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 %}

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

@@ -252,6 +252,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;

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);
 }

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='';