IBX-12664: Added siteaccess-aware headless mode configuration

src/bundle/DependencyInjection/Configuration/Parser/Headless.php

@@ -0,0 +1,136 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace Ibexa\Bundle\AdminUi\DependencyInjection\Configuration\Parser;
+
+use Ibexa\Bundle\Core\DependencyInjection\Configuration\AbstractParser;
+use Ibexa\Bundle\Core\DependencyInjection\Configuration\SiteAccessAware\ContextualizerInterface;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
+
+/**
+ * Configuration parser for the headless mode, where the site is rendered by an external front-end application.
+ *
+ * Example configuration:
+ * ```yaml
+ * ibexa:
+ *   system:
+ *      admin_group: # configuration per siteaccess or siteaccess group
+ *          headless:
+ *              enabled: true
+ *              page_builder:
+ *                  preview_url: 'https://frontend.example.com/page-builder'
+ *              content:
+ *                  preview_url: 'https://frontend.example.com/preview'
+ *              configuration_url: 'https://admin.example.com/frontend'
+ * ```
+ *
+ * The node intentionally declares no default values (they live in ezplatform_default_settings.yaml):
+ * a key omitted on a siteaccess inherits the value of its group. An explicit `~` on a URL key sets it
+ * to null; note that Symfony normalizes `enabled: ~` to `true`, so omit the key to inherit the flag.
+ *
+ * `content.preview_url` is reserved for the content previews outside of Page Builder and has no consumer yet.
+ */
+final class Headless extends AbstractParser
+{
+    private const string NODE = 'headless';
+
+    private const array PARAMETERS = [
+        'headless.enabled' => ['enabled'],
+        'headless.page_builder.preview_url' => ['page_builder', 'preview_url'],
+        'headless.content.preview_url' => ['content', 'preview_url'],
+        'headless.configuration_url' => ['configuration_url'],
+    ];
+
+    /**
+     * @param array<string, mixed> $scopeSettings
+     */
+    public function mapConfig(
+        array &$scopeSettings,
+        mixed $currentScope,
+        ContextualizerInterface $contextualizer
+    ): void {
+        if (!isset($scopeSettings[self::NODE]) || !is_array($scopeSettings[self::NODE])) {
+            return;
+        }
+
+        $settings = $scopeSettings[self::NODE];
+
+        foreach (self::PARAMETERS as $parameterName => $path) {
+            if (!$this->hasPath($settings, $path)) {
+                continue;
+            }
+
+            $contextualizer->setContextualParameter(
+                $parameterName,
+                $currentScope,
+                $this->getPath($settings, $path)
+            );
+        }
+    }
+
+    public function addSemanticConfig(NodeBuilder $nodeBuilder): void
+    {
+        $nodeBuilder
+            ->arrayNode(self::NODE)
+                ->info('Headless mode configuration.')
+                ->children()
+                    ->booleanNode('enabled')
+                        ->info('Enables the headless mode for the siteaccess.')
+                    ->end()
+                    ->arrayNode('page_builder')
+                        ->children()
+                            ->scalarNode('preview_url')
+                                ->info('Front-end application URL loaded into the Page Builder preview iframe.')
+                            ->end()
+                        ->end()
+                    ->end()
+                    ->arrayNode('content')
+                        ->children()
+                            ->scalarNode('preview_url')
+                                ->info('Front-end application URL used for content preview.')
+                            ->end()
+                        ->end()
+                    ->end()
+                    ->scalarNode('configuration_url')
+                        ->info('URL of the front-end application configuration page.')
+                    ->end()
+                ->end()
+            ->end();
+    }
+
+    /**
+     * @param array<string, mixed> $settings
+     * @param string[] $path
+     */
+    private function hasPath(array $settings, array $path): bool
+    {
+        foreach ($path as $key) {
+            if (!is_array($settings) || !array_key_exists($key, $settings)) {
+                return false;
+            }
+
+            $settings = $settings[$key];
+        }
+
+        return true;
+    }
+
+    /**
+     * @param array<string, mixed> $settings
+     * @param string[] $path
+     */
+    private function getPath(array $settings, array $path): mixed
+    {
+        $value = $settings;
+        foreach ($path as $key) {
+            $value = $value[$key];
+        }
+
+        return $value;
+    }
+}

src/bundle/DependencyInjection/IbexaAdminUiExtension.php

@@ -14,6 +14,7 @@
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Extension\Extension;
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
+use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
 use Symfony\Component\Yaml\Yaml;
 
@@ -51,15 +52,16 @@ final class IbexaAdminUiExtension extends Extension implements PrependExtensionI
      */
     public function load(array $configs, ContainerBuilder $container): void
     {
-        $loader = new YamlFileLoader(
-            $container,
-            new FileLocator(__DIR__ . '/../Resources/config')
-        );
+        $configLocator = new FileLocator(__DIR__ . '/../Resources/config');
+        $loader = new YamlFileLoader($container, $configLocator);
 
         $loader->load('default_parameters.yaml');
         $loader->load('services.yaml');
         $loader->load('role.yaml');
 
+        $phpLoader = new PhpFileLoader($container, $configLocator);
+        $phpLoader->load('services.php');
+
         $shouldLoadTestServices = $this->shouldLoadTestServices($container);
         if ($shouldLoadTestServices) {
             $loader->load('services/test/feature_contexts.yaml');

src/bundle/IbexaAdminUiBundle.php

@@ -73,6 +73,7 @@ private function getConfigParsers(): array
             new Parser\Assets(),
             new Parser\AdminUiParser(),
             new Parser\UserProfile(),
+            new Parser\Headless(),
         ];
     }
 }

src/bundle/Resources/config/ezplatform_default_settings.yaml

@@ -92,3 +92,9 @@ parameters:
     ibexa.site_access.config.default.user_profile.enabled: false
     ibexa.site_access.config.default.user_profile.content_types: []
     ibexa.site_access.config.default.user_profile.field_groups: []
+
+    # Headless mode (external front-end application)
+    ibexa.site_access.config.default.headless.enabled: false
+    ibexa.site_access.config.default.headless.page_builder.preview_url: ~
+    ibexa.site_access.config.default.headless.content.preview_url: ~
+    ibexa.site_access.config.default.headless.configuration_url: ~

src/bundle/Resources/config/services.php

@@ -0,0 +1,13 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (ContainerConfigurator $container): void {
+    $container->import('services/**/*.php');
+};

src/bundle/Resources/config/services/headless.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+use Ibexa\AdminUi\Headless\HeadlessConfiguration;
+use Ibexa\AdminUi\Headless\HeadlessConfigurationInterface;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (ContainerConfigurator $container): void {
+    $services = $container->services();
+
+    $services
+        ->defaults()
+        ->autowire()
+        ->autoconfigure()
+        ->private();
+
+    $services->set(HeadlessConfiguration::class);
+
+    $services->alias(HeadlessConfigurationInterface::class, HeadlessConfiguration::class);
+};

src/lib/Headless/HeadlessConfiguration.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace Ibexa\AdminUi\Headless;
+
+use Ibexa\Contracts\Core\SiteAccess\ConfigResolverInterface;
+
+final readonly class HeadlessConfiguration implements HeadlessConfigurationInterface
+{
+    public function __construct(private ConfigResolverInterface $configResolver)
+    {
+    }
+
+    public function isEnabled(?string $scope = null): bool
+    {
+        return (bool)$this->configResolver->getParameter('headless.enabled', null, $scope);
+    }
+
+    public function getPageBuilderPreviewUrl(?string $scope = null): ?string
+    {
+        return $this->getUrl('headless.page_builder.preview_url', $scope);
+    }
+
+    public function getContentPreviewUrl(?string $scope = null): ?string
+    {
+        return $this->getUrl('headless.content.preview_url', $scope);
+    }
+
+    public function getConfigurationUrl(?string $scope = null): ?string
+    {
+        return $this->getUrl('headless.configuration_url', $scope);
+    }
+
+    private function getUrl(string $parameterName, ?string $scope): ?string
+    {
+        $value = $this->configResolver->getParameter($parameterName, null, $scope);
+
+        return is_string($value) && $value !== '' ? $value : null;
+    }
+}

src/lib/Headless/HeadlessConfigurationInterface.php

@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace Ibexa\AdminUi\Headless;
+
+/**
+ * Siteaccess-aware configuration of the headless mode, where the site is rendered by an external
+ * front-end application (`ibexa.system.<scope>.headless`).
+ *
+ * All methods resolve the configuration for the current siteaccess unless `$scope` is given.
+ *
+ * `isEnabled()` only reflects the flag: consumers must also check that the URL they need is configured
+ * (for example `getPageBuilderPreviewUrl() !== null`) before switching to the headless behaviour.
+ *
+ * @internal
+ */
+interface HeadlessConfigurationInterface
+{
+    public function isEnabled(?string $scope = null): bool;
+
+    /**
+     * URL of the front-end application loaded into the Page Builder preview iframe.
+     */
+    public function getPageBuilderPreviewUrl(?string $scope = null): ?string;
+
+    /**
+     * URL of the front-end application used to preview content items outside of Page Builder.
+     */
+    public function getContentPreviewUrl(?string $scope = null): ?string;
+
+    /**
+     * URL of the page where the front-end application can be configured, if the installation provides one.
+     */
+    public function getConfigurationUrl(?string $scope = null): ?string;
+}