Module.php

<?php declare(strict_types=1);

/*
 * Copyright 2015-2026 Daniel Berthereau
 * Copyright 2016-2017 BibLibre
 *
 * This software is governed by the CeCILL license under French law and abiding
 * by the rules of distribution of free software. You can use, modify and/or
 * redistribute the software under the terms of the CeCILL license as circulated
 * by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".
 *
 * As a counterpart to the access to the source code and rights to copy, modify
 * and redistribute granted by the license, users are provided only with a
 * limited warranty and the software’s author, the holder of the economic
 * rights, and the successive licensors have only limited liability.
 *
 * In this respect, the user’s attention is drawn to the risks associated with
 * loading, using, modifying and/or developing or reproducing the software by
 * the user in light of its specific status of free software, that may mean that
 * it is complicated to manipulate, and that also therefore means that it is
 * reserved for developers and experienced professionals having in-depth
 * computer knowledge. Users are therefore encouraged to load and test the
 * software’s suitability as regards their requirements in conditions enabling
 * the security of their systems and/or data to be ensured and, more generally,
 * to use and operate it in the same conditions as regards security.
 *
 * The fact that you are presently reading this means that you have had
 * knowledge of the CeCILL license and that you accept its terms.
 */

namespace IiifServer;

if (!class_exists('Common\TraitModule', false)) {
    require_once file_exists(dirname(__DIR__) . '/Common/src/TraitModule.php')
        ? dirname(__DIR__) . '/Common/src/TraitModule.php'
        : dirname(__DIR__) . '/Common/TraitModule.php';
}

use Common\Stdlib\PsrMessage;
use Common\TraitModule;
use IiifServer\Form\ConfigForm;
use Laminas\EventManager\Event;
use Laminas\EventManager\SharedEventManagerInterface;
use Laminas\ModuleManager\ModuleManager;
use Laminas\Mvc\Controller\AbstractController;
use Laminas\Mvc\MvcEvent;
use Laminas\View\Renderer\PhpRenderer;
use Omeka\Entity\Item;
use Omeka\Module\AbstractModule;

class Module extends AbstractModule
{
    use TraitModule;

    const NAMESPACE = __NAMESPACE__;

    public function init(ModuleManager $moduleManager): void
    {
        // The autoload doesn’t work with GetId3.
        // @see \IiifServer\Service\ControllerPlugin\MediaDimensionFactory
        require_once __DIR__ . '/vendor/autoload.php';
    }

    public function onBootstrap(MvcEvent $event): void
    {
        parent::onBootstrap($event);

        /** @var \Omeka\Permissions\Acl $acl */
        $acl = $this->getServiceLocator()->get('Omeka\Acl');
        $acl
            ->allow(
                null,
                [
                    \IiifServer\Controller\MediaController::class,
                    \IiifServer\Controller\NoopServerController::class,
                    \IiifServer\Controller\PresentationController::class,
                ]
            );

        // Re-encode decoded slashes in identifiers so Segment routes match.
        $event->getApplication()->getEventManager()
            ->attach(MvcEvent::EVENT_ROUTE, [$this, 'reencodeIdentifierSlashes'], 1000);
    }

    /**
     * Re-encode decoded slashes in iiif url identifiers.
     *
     * When apache or a reverse proxy does not preserve encoded slashes
     * (%2F), they get decoded to "/" in the path, breaking segment routes
     * that expect the identifier as a single path segment. This listener
     * detects where the identifier ends by looking for known iiif keywords
     * (manifest, canvas, info.json, etc.) from the right of the path, then
     * re-encodes all "/" within the identifier portion.
     *
     * This is a no-op when identifiers contain no decoded slashes (e.g.
     * simple numeric ids or already-encoded identifiers).
     *
     * @see https://iiif.io/api/presentation/3.0/
     * @see https://iiif.io/api/presentation/2.1/
     * @see https://iiif.io/api/image/3.0/
     */
    public function reencodeIdentifierSlashes(MvcEvent $event): void
    {
        $request = $event->getRequest();
        if (!$request instanceof \Laminas\Http\PhpEnvironment\Request) {
            return;
        }

        $path = $request->getUri()->getPath();

        // Quick check: only process iiif presentation/image/media paths.
        if (strpos($path, '/iiif/') === false) {
            return;
        }

        // Skip fixed literal routes (e.g. ixif placeholder).
        if (strpos($path, 'ixif-message') !== false) {
            return;
        }

        $matches = [];

        // Parse: /iiif[/version][/collection|set]/{identifier}[/suffix]
        // Version is any single digit to be future-proof (v2, v3, v4…).
        if (!preg_match('#^(/iiif(?:/\d+)?)(?:(/collection|/set))?(/[^?]*)$#', $path, $matches)) {
            return;
        }

        $iiifBase = $matches[1];
        $routePrefix = $matches[2] ?? '';
        $remainder = $matches[3] ?? '';

        if ($remainder === '' || $remainder === '/') {
            return;
        }

        // Remove leading slash.
        $remainder = substr($remainder, 1);
        $segments = explode('/', $remainder);
        $count = count($segments);

        // A single segment means no slashes in the identifier.
        if ($count <= 1) {
            return;
        }

        // Known iiif presentation types and keywords that appear after the
        // identifier in the URL path. Used as anchors to detect where the
        // identifier portion ends.
        // @see IiifServer config: route "uri" type constraint.
        static $iiifKeywords = [
            'manifest' => true,
            'info.json' => true,
            'annotation-page' => true,
            'annotation-collection' => true,
            'annotation-list' => true,
            'annotation' => true,
            'canvas-segment' => true,
            'canvas' => true,
            'collection' => true,
            'content-resource' => true,
            'range' => true,
            // Iiif presentation 2.1 types.
            'sequence' => true,
            'layer' => true,
            'list' => true,
            'res' => true,
        ];

        // Scan from the right to find the first iiif keyword.
        // Start at index 1 (the identifier needs at least one segment).
        $suffixCount = 0;
        for ($i = $count - 1; $i >= 1; $i--) {
            if (isset($iiifKeywords[$segments[$i]])) {
                $suffixCount = $count - $i;
                break;
            }
        }

        // If no keyword found, check for Image API request pattern:
        // {id}/{region}/{size}/{rotation}/{quality}.{format}
        // where quality is one of: default, color, gray, bitonal.
        if ($suffixCount === 0 && $count >= 5) {
            if (preg_match('/^(?:default|color|gray|bitonal)\.\w+$/', $segments[$count - 1])) {
                $suffixCount = 4;
            }
        }

        $identifierCount = $count - $suffixCount;
        if ($identifierCount <= 1) {
            return;
        }

        // Re-encode slashes within the identifier portion.
        $identifierParts = array_slice($segments, 0, $identifierCount);
        $encodedIdentifier = implode('%2F', $identifierParts);

        $suffixParts = array_slice($segments, $identifierCount);
        $newRemainder = $suffixParts
            ? $encodedIdentifier . '/' . implode('/', $suffixParts)
            : $encodedIdentifier;

        $newPath = $iiifBase . $routePrefix . '/' . $newRemainder;

        if ($newPath !== $path) {
            $request->getUri()->setPath($newPath);
        }
    }

    protected function preInstall(): void
    {
        $services = $this->getServiceLocator();
        $translator = $services->get('MvcTranslator');

        if (!method_exists($this, 'checkModuleActiveVersion') || !$this->checkModuleActiveVersion('Common', '3.4.82')) {
            $message = new \Omeka\Stdlib\Message(
                $translator->translate('The module %1$s should be upgraded to version %2$s or later.'), // @translate
                'Common', '3.4.82'
            );
            throw new \Omeka\Module\Exception\ModuleCannotInstallException((string) $message);
        }

        $errors = [];

        // Check the optional module Derivative Media for incompatibility.
        if ($this->isModuleActive('DerivativeMedia') && !$this->isModuleVersionAtLeast('DerivativeMedia', '3.4.10')) {
            $errors[] = (string) (new PsrMessage(
                'The module {module} should be upgraded to version {version} or later.', // @translate
                ['module' => 'Derivative Media', 'version' => '3.4.10']
            ))->setTranslator($translator);
        }

        $config = $services->get('Config');
        $basePath = $config['file_store']['local']['base_path'] ?: (OMEKA_PATH . '/files');

        if (!$this->checkDestinationDir($basePath . '/iiif/2')) {
            $errors[] = (string) (new PsrMessage(
                'The directory "{directory}" is not writeable.', // @translate
                ['directory' => $basePath . '/iiif']
            ))->setTranslator($translator);
        }

        if (!$this->checkDestinationDir($basePath . '/iiif/3')) {
            $errors[] = (string) (new PsrMessage(
                'The directory "{directory}" is not writeable.', // @translate
                ['directory' => $basePath . '/iiif']
            ))->setTranslator($translator);
        }

        if ($errors) {
            throw new \Omeka\Module\Exception\ModuleCannotInstallException(implode("\n", $errors));
        }
    }

    protected function postInstall(): void
    {
        $this->updateWhitelist();

        /** @var \Omeka\Settings\Settings $settings */
        $settings = $this->getServiceLocator()->get('Omeka\Settings');

        // Set default setting for cors according to the config of the server.
        $corsHeaders = $this->checkCorsHeaders();
        $settings->set('iiifserver_append_cors_headers', !$corsHeaders);
        if ($corsHeaders > 1) {
            $this->messageCors();
        }

        $this->messageEncodedSlashes();
        $this->messageExternalImageServer();
    }

    protected function postUpgrade(?string $oldVersion, ?string $newVersion): void
    {
        $this->postUpgradeAuto($oldVersion, $newVersion);

        // Auto-configure CORS setting according to the current server config.
        $corsHeaders = $this->checkCorsHeaders();
        if ($corsHeaders) {
            $settings = $this->getServiceLocator()->get('Omeka\Settings');
            $settings->set('iiifserver_append_cors_headers', false);
        }
        $this->messageCors();

        $this->messageEncodedSlashes();
        $this->messageExternalImageServer();
    }

    protected function postUninstall(): void
    {
        $services = $this->getServiceLocator();
        $config = $services->get('Config');
        $basePath = $config['file_store']['local']['base_path'] ?: (OMEKA_PATH . '/files');
        $dirPath = $basePath . '/iiif';
        $this->rmDir($dirPath);
    }

    public function attachListeners(SharedEventManagerInterface $sharedEventManager): void
    {
        // Update dimensions of medias on item save.
        $sharedEventManager->attach(
            \Omeka\Api\Adapter\ItemAdapter::class,
            'api.hydrate.post',
            [$this, 'handleBeforeSaveItem']
        );

        // TODO Update manifests on media update.
        $sharedEventManager->attach(
            \Omeka\Api\Adapter\ItemAdapter::class,
            'api.create.post',
            [$this, 'handleAfterSaveItem']
        );
        $sharedEventManager->attach(
            \Omeka\Api\Adapter\ItemAdapter::class,
            'api.update.post',
            [$this, 'handleAfterSaveItem']
        );
        $sharedEventManager->attach(
            \Omeka\Api\Adapter\ItemAdapter::class,
            'api.delete.post',
            [$this, 'handleAfterDeleteItem']
        );

        // Add a job to upgrade structures once from v3.
        $sharedEventManager->attach(
            \EasyAdmin\Form\CheckAndFixForm::class,
            'form.add_elements',
            [$this, 'handleEasyAdminJobsForm']
        );
        $sharedEventManager->attach(
            \EasyAdmin\Controller\Admin\CheckAndFixController::class,
            'easyadmin.job',
            [$this, 'handleEasyAdminJobs']
        );
    }

    public function getConfigForm(PhpRenderer $renderer)
    {
        $services = $this->getServiceLocator();
        $plugins = $services->get('ControllerPluginManager');
        $messenger = $plugins->get('messenger');

        // Clear previous, run diagnostics, collect for audit tab.
        $messenger->clear();
        $this->runIiifDiagnostics();
        $diagnostics = $messenger->get();
        $messenger->clear();

        // Also run existing checks (they may add messages too).
        $this->messageCors();
        $this->messageEncodedSlashes();
        $this->messageExternalImageServer();
        $diagExtra = $messenger->get();
        $messenger->clear();

        // Merge all diagnostics.
        foreach ($diagExtra as $type => $msgs) {
            foreach ($msgs as $msg) {
                $diagnostics[$type][] = $msg;
            }
        }

        $escape = $renderer->plugin('escapeHtml');
        $translate = $renderer->plugin('translate');

        // Render audit HTML.
        $levelClasses = [
            \Omeka\Mvc\Controller\Plugin\Messenger::ERROR => 'error',
            \Omeka\Mvc\Controller\Plugin\Messenger::SUCCESS => 'success',
            \Omeka\Mvc\Controller\Plugin\Messenger::WARNING => 'warning',
        ];
        $auditHtml = '';
        foreach ($diagnostics as $type => $messages) {
            $class = $levelClasses[$type] ?? 'notice';
            foreach ($messages as $msg) {
                $text = ($msg instanceof PsrMessage && $msg->escapeHtml() === false)
                    ? (string) $msg
                    : $escape((string) $msg);
                $auditHtml .= '<p class="' . $class . '">' . $text . '</p>';
            }
        }
        if (!$auditHtml) {
            $auditHtml = '<p class="success">'
                . $escape($translate('All checks passed.')) // @translate
                . '</p>';
        }

        // Build the form.
        $settings = $services->get('Omeka\Settings');
        $formManager = $services->get('FormElementManager');
        $renderer->ckEditor();

        $this->initDataToPopulate($settings, 'config');
        $data = $this->prepareDataToPopulate($settings, 'config');
        if ($data === null) {
            return null;
        }

        $form = $formManager->get(\IiifServer\Form\ConfigForm::class);
        $form->init();
        $form->setData($data);
        $form->prepare();

        $view = $renderer;

        // Dispatch elements to tabs using element_groups.
        // Fieldsets are rendered as sub-sections within their group.
        $elementGroups = $form->getOption('element_groups') ?: [];
        $tabs = array_fill_keys(array_keys($elementGroups), '');
        $ungrouped = '';

        foreach ($form as $element) {
            if ($element instanceof \Laminas\Form\FieldsetInterface) {
                $group = $element->getOption('element_group');
                if ($group && isset($tabs[$group])) {
                    $tabs[$group] .= $view->formCollection($element);
                }
                continue;
            }
            $group = $element->getOption('element_group');
            if ($group && isset($tabs[$group])) {
                $tabs[$group] .= $view->formRow($element);
            } else {
                $ungrouped .= $view->formRow($element);
            }
        }

        // Prepend intro text to first tab.
        $configNote = '<p>'
            . $translate('The module creates manifests with the properties from each resource (item set, item and media).') // @translate
            . ' ' . $translate('The properties below are used when some metadata are missing.') // @translate
            . ' ' . $translate('In all cases, empty properties are not set.') // @translate
            . '</p>';
        $firstGroup = array_key_first($elementGroups);
        if ($firstGroup) {
            $tabs[$firstGroup] = $configNote . $ungrouped
                . $tabs[$firstGroup];
        }

        // Build tab navigation and content.
        $iiifModules = [
            'IiifServer',
            'ImageServer',
            'IiifSearch',
        ];
        $moduleNav = $view->moduleConfigNav($iiifModules, 'IiifServer');

        $tabNav = '<li class="active"><a href="#iiifserver-audit">'
            . $escape($translate('Audit')) . '</a></li>';
        $tabContent = '<div id="iiifserver-audit" class="section active">'
            . $auditHtml . '</div>';

        foreach ($elementGroups as $groupName => $groupLabel) {
            if (empty($tabs[$groupName])) {
                continue;
            }
            $tabNav .= '<li><a href="#iiifserver-' . $groupName . '">'
                . $escape($translate($groupLabel)) . '</a></li>';
            $tabContent .= '<div id="iiifserver-' . $groupName
                . '" class="section">'
                . $tabs[$groupName] . '</div>';
        }

        return $moduleNav
            . '<ul class="section-nav" style="list-style:none;padding:0;">'
            . $tabNav
            . '</ul>'
            . $tabContent;
    }

    public function handleConfigForm(AbstractController $controller)
    {
        // Auto-configure CORS setting according to the current server config.
        $corsHeaders = $this->checkCorsHeaders();
        if ($corsHeaders) {
            $settings = $this->getServiceLocator()->get('Omeka\Settings');
            $settings->set('iiifserver_append_cors_headers', false);
        }
        $this->messageCors();

        $this->messageCache();
        $this->messageEncodedSlashes();
        $this->messageExternalImageServer();

        /**
         * @var \Laminas\ServiceManager\ServiceLocatorInterface $services
         * @var \IiifServer\Form\ConfigForm $configForm
         */
        $services = $this->getServiceLocator();
        $settings = $services->get('Omeka\Settings');
        $form = $services->get('FormElementManager')->get(ConfigForm::class);
        $params = $controller->getRequest()->getPost();

        if (!$this->handleConfigFormAuto($controller)) {
            return false;
        }

        // Form is already validated in parent.
        $form->init();
        $form->setData($params);
        $form->isValid();
        $params = $form->getData();

        // Specific options.
        foreach (['iiifserver_manifest_collection_properties', 'iiifserver_manifest_item_properties', 'iiifserver_manifest_media_properties'] as $key) {
            $value = empty($params[$key]) || in_array('', $params[$key])
                ? []
                : (in_array('none', $params[$key]) ? ['none'] : $params[$key]);
            $settings->set($key, $value);
        }

        $this->normalizeMediaApiSettings($params);

        if (empty($params['fieldset_cache']['process_cache'])
            && empty($params['fieldset_dimensions']['process_dimensions'])
        ) {
            return true;
        }

        $dispatcher = $services->get(\Omeka\Job\Dispatcher::class);

        if (!empty($params['fieldset_cache']['process_cache'])) {
            $query = [];
            parse_str($params['fieldset_cache']['query_cache'] ?? '', $query);
            $args = ['query' => $query ?: []];
            $job = $dispatcher->dispatch(\IiifServer\Job\CacheManifests::class, $args);
            $message = 'Caching manifests ({link}job #{job_id}{link_end}, {link_log}logs{link_end})'; // @translate
        } elseif (!empty($params['fieldset_dimensions']['process_dimensions'])) {
            $query = [];
            parse_str($params['fieldset_dimensions']['query'] ?? '', $query);
            $args = ['query' => $query ?: []];
            $job = $dispatcher->dispatch(\IiifServer\Job\MediaDimensions::class, $args);
            $message = 'Storing dimensions of images, audio and video ({link}job #{job_id}{link_end}, {link_log}logs{link_end})'; // @translate
        }

        $urlPlugin = $controller->url();
        $message = new PsrMessage(
            $message,
            [
                'link' => sprintf('<a href="%s">',
                    htmlspecialchars($controller->url()->fromRoute('admin/id', ['controller' => 'job', 'id' => $job->getId()]))
                ),
                'job_id' => $job->getId(),
                'link_end' => '</a>',
                'link_log' => class_exists('Log\Module', false)
                    ? sprintf('<a href="%1$s">', $urlPlugin->fromRoute('admin/default', ['controller' => 'log'], ['query' => ['job_id' => $job->getId()]]))
                    : sprintf('<a href="%1$s" target="_blank">', $urlPlugin->fromRoute('admin/id', ['controller' => 'job', 'action' => 'log', 'id' => $job->getId()])),
            ]
        );
        $message->setEscapeHtml(false);
        $controller->messenger()->addSuccess($message);
        return true;
    }

    public function handleBeforeSaveItem(Event $event): void
    {
        /** @var \Omeka\Api\Request $request */
        $request = $event->getParam('request');

        // Don't run sizing during a batch edit of items, because it runs one
        // job by item and it is slow. A batch process is always partial.
        if ($request->getOption('isPartial')) {
            return;
        }

        /** @var \Omeka\Api\Adapter\ItemAdapter $itemAdapter */
        $itemAdapter = $event->getTarget();
        if (!$itemAdapter->shouldHydrate($request, 'o:media')) {
            return;
        }

        /** @var \Omeka\Entity\Item $item */
        $item = $event->getParam('entity');
        $this->prepareSizeItem($item);
    }

    public function handleAfterSaveItem(Event $event): void
    {
        /** @var \Omeka\Api\Request $request */
        $request = $event->getParam('request');
        if ($request->getOption('isPartial')) {
            return;
        }

        $services = $this->getServiceLocator();
        if (!$services->get('Omeka\Settings')
            ->get('iiifserver_manifest_cache')
        ) {
            return;
        }

        /** @var \Omeka\Entity\Item $item */
        $item = $event->getParam('response')->getContent();

        if ($services->has('Common\DeferredJobDispatch')) {
            $services->get('Common\DeferredJobDispatch')->defer(
                \IiifServer\Job\CacheManifests::class,
                'iiifserver_cache_manifests',
                ['item_ids' => $item->getId()],
                function (string $key, array $allParams): array {
                    $ids = [];
                    foreach ($allParams as $p) {
                        $ids[] = $p['item_ids'];
                    }
                    return [
                        'query' => ['id' => array_unique($ids)],
                    ];
                }
            );
        } else {
            $dispatcher = $services->get(\Omeka\Job\Dispatcher::class);
            $dispatcher->dispatch(
                \IiifServer\Job\CacheManifests::class,
                ['query' => ['id' => $item->getId()]]
            );
        }
    }

    public function handleAfterDeleteItem(Event $event): void
    {
        /** @var \Omeka\Api\Request $request */
        $request = $event->getParam('request');
        $itemId = $request->getId();
        if (!$itemId) {
            return;
        }

        $services = $this->getServiceLocator();
        $config = $services->get('Config');
        $basePath = $config['file_store']['local']['base_path'] ?: (OMEKA_PATH . '/files');

        foreach ([2, 3] as $version) {
            $filepath = "$basePath/iiif/$version/$itemId.manifest.json";
            if (file_exists($filepath) && is_writeable($filepath)) {
                @unlink($filepath);
            }
        }
    }

    public function handleEasyAdminJobsForm(Event $event): void
    {
        /**
         * @var \EasyAdmin\Form\CheckAndFixForm $form
         * @var \Laminas\Form\Element\Radio $process
         */
        $form = $event->getTarget();
        $fieldset = $form->get('module_tasks');
        $process = $fieldset->get('process');
        $valueOptions = $process->getValueOptions();
        $valueOptions['iiifserver_cache_manifests'] = 'Iiif Server: Cache manifests'; // @translate
        $valueOptions['iiifserver_store_dimensions'] = 'Iiif Server: Store dimensions of medias'; // @translate
        $valueOptions['iiifserver_upgrade_structure'] = 'Iiif Server: Upgrade old tables of contents to new format with four columns (to do only one time for old external manifests)'; // @translate
        $process->setValueOptions($valueOptions);
        $fieldset
            ->add([
                'type' => \Laminas\Form\Fieldset::class,
                'name' => 'iiifserver_cache_manifests',
                'options' => [
                    'label' => 'Options to cache manifests', // @translate
                ],
                'attributes' => [
                    'class' => 'iiifserver_cache_manifests',
                ],
            ])
            ->get('iiifserver_cache_manifests')
            ->add([
                'name' => 'query',
                'type' => \Omeka\Form\Element\Query::class,
                'options' => [
                    'label' => 'Limit cache of manifests to specific items', // @translate
                ],
                'attributes' => [
                    'id' => 'iiifserver_cache_manifests-query',
                ],
            ]);
        $fieldset
            ->add([
                'type' => \Laminas\Form\Fieldset::class,
                'name' => 'iiifserver_store_dimensions',
                'options' => [
                    'label' => 'Options to store dimensions', // @translate
                ],
                'attributes' => [
                    'class' => 'iiifserver_store_dimensions',
                ],
            ])
            ->get('iiifserver_store_dimensions')
            ->add([
                'name' => 'query',
                'type' => \Omeka\Form\Element\Query::class,
                'options' => [
                    'label' => 'Limit storage of dimensions to specific items', // @translate
                ],
                'attributes' => [
                    'id' => 'iiifserver_store_dimensions-query',
                ],
            ]);
        $fieldset
            ->add([
                'type' => \Laminas\Form\Fieldset::class,
                'name' => 'iiifserver_upgrade_structure',
                'options' => [
                    'label' => 'Options to upgrade table of contents', // @translate
                ],
                'attributes' => [
                    'class' => 'iiifserver_upgrade_structure',
                ],
            ])
            ->get('iiifserver_upgrade_structure')
            ->add([
                'name' => 'query',
                'type' => \Omeka\Form\Element\Query::class,
                'options' => [
                    'label' => 'Limit upgrade of tables of contents to specific items', // @translate
                ],
                'attributes' => [
                    'id' => 'iiifserver_upgrade_structure-query',
                ],
            ]);
    }

    public function handleEasyAdminJobs(Event $event): void
    {
        $process = $event->getParam('process');
        if ($process === 'iiifserver_cache_manifests') {
            $params = $event->getParam('params');
            $event->setParam('job', \IiifServer\Job\CacheManifests::class);
            $event->setParam('args', $params['module_tasks']['iiifserver_cache_manifests'] ?? []);
        } elseif ($process === 'iiifserver_store_dimensions') {
            $params = $event->getParam('params');
            $event->setParam('job', \IiifServer\Job\MediaDimensions::class);
            $event->setParam('args', $params['module_tasks']['iiifserver_store_dimensions'] ?? []);
        } elseif ($process === 'iiifserver_upgrade_structure') {
            $params = $event->getParam('params');
            $event->setParam('job', \IiifServer\Job\UpgradeStructures::class);
            $event->setParam('args', $params['module_tasks']['iiifserver_upgrade_structure'] ?? []);
        }
    }

    /**
     * Same in Iiif server and Image server.
     *
     * @see \IiifServer\Module::normalizeMediaApiSettings()
     * @see \ImageServer\Module::normalizeMediaApiSettings()
     */
    protected function normalizeMediaApiSettings(array $params): void
    {
        $services = $this->getServiceLocator();
        $settings = $services->get('Omeka\Settings');

        // Check and normalize image api versions.
        $defaultVersion = $params['iiifserver_media_api_default_version'] ?: '0';
        $has = ['1' => null, '2' => null, '3' => null];
        foreach ($params['iiifserver_media_api_supported_versions'] ?? [] as $supportedVersion) {
            $service = strtok($supportedVersion, '/');
            $level = strtok('/') ?: '0';
            $has[$service] = isset($has[$service]) && $has[$service] > $level
                ? $has[$service]
                : $level;
        }
        $has = array_filter($has);
        if ($defaultVersion && !isset($has[$defaultVersion])) {
            $has[$defaultVersion] = '0';
        }
        ksort($has);
        $supportedVersions = [];
        foreach ($has as $service => $level) {
            $supportedVersions[] = $service . '/' . $level;
        }
        $settings->set('iiifserver_media_api_default_version', $defaultVersion);
        $settings->set('iiifserver_media_api_supported_versions', $supportedVersions);

        // Avoid to do the computation each time for manifest v2, that supports
        // only one service.
        $defaultSupportedVersion = ['service' => '0', 'level' => '0'];
        foreach ($supportedVersions as $supportedVersion) {
            $service = strtok($supportedVersion, '/');
            if ($service === $defaultVersion) {
                $level = strtok('/') ?: '0';
                $defaultSupportedVersion = [
                    'service' => $service,
                    'level' => $level,
                ];
                break;
            }
        }
        $settings->set('iiifserver_media_api_default_supported_version', $defaultSupportedVersion);
    }

    protected function updateWhitelist(): void
    {
        $settings = $this->getServiceLocator()->get('Omeka\Settings');

        $whitelist = $settings->get('media_type_whitelist', []);
        $whitelist = array_values(array_unique(array_merge(array_values($whitelist), [
            'image/ktx2',
            'model/gltf-binary',
            'model/gltf+json',
            'model/vnd.threejs+json',
            'application/octet-stream',
        ])));
        $settings->set('media_type_whitelist', $whitelist);

        $whitelist = $settings->get('extension_whitelist', []);
        $whitelist = array_values(array_unique(array_merge(array_values($whitelist), [
            'bin',
            'glb',
            'gltf',
            'json',
            'ktx2',
        ])));
        $settings->set('extension_whitelist', $whitelist);
    }

    /**
     * Check how many times the cors header is returned (zero or one).
     *
     * Returning the cors header "Access-Control-Allow-Origin" multiple times
     * disable it.
     */
    protected function checkCorsHeaders(): int
    {
        // Check cors on a default file, because there may not be any media file.
        $services = $this->getServiceLocator();
        $assetUrl = $services->get('ViewHelperManager')->get('assetUrl');
        $checkServerUrl = $assetUrl('css/style.css', 'Omeka', false, true, true);

        // Remove warning, related to proxy or specific domain issue.
        $headers = @get_headers($checkServerUrl, version_compare(PHP_VERSION, '8.0.0', '<') ? 1 : true);
        if (!$headers) {
            return 0;
        }

        return array_key_exists('Access-Control-Allow-Origin', $headers)
            ? count((array) $headers['Access-Control-Allow-Origin'])
            : 0;
    }

    /**
     * Run IIIF Server diagnostics.
     */
    protected function runIiifDiagnostics(): void
    {
        $this->checkIiifPresentationVersion();
        $this->checkManifestCache();
        $this->checkMediaDimensions();
        $this->checkManifestRoute();
    }

    /**
     * Recommend IIIF Presentation v3.
     */
    protected function checkIiifPresentationVersion(): void
    {
        $services = $this->getServiceLocator();
        $settings = $services->get('Omeka\Settings');
        $messenger = $services->get('ControllerPluginManager')
            ->get('messenger');

        $version = $settings->get('iiifserver_manifest_default_version', '2');
        if ($version !== '3') {
            $messenger->addWarning(new PsrMessage(
                'The default IIIF Presentation version is {version}. Version 3 is the current standard and is recommended.', // @translate
                ['version' => $version]
            ));
        }
    }

    /**
     * Check manifest cache status and recommend it for large
     * collections.
     */
    protected function checkManifestCache(): void
    {
        $services = $this->getServiceLocator();
        $settings = $services->get('Omeka\Settings');
        $connection = $services->get('Omeka\Connection');
        $messenger = $services->get('ControllerPluginManager')
            ->get('messenger');

        $cacheEnabled = (bool) $settings->get('iiifserver_manifest_cache', false);

        // Count items with many images.
        $threshold = 10;
        $largeItems = (int) $connection->fetchOne(<<<SQL
            SELECT COUNT(*) FROM (
                SELECT item_id, COUNT(*) as cnt FROM media
                WHERE media_type LIKE 'image/%'
                GROUP BY item_id
                HAVING cnt > $threshold
            ) t
            SQL
        );

        if ($largeItems && !$cacheEnabled) {
            $messenger->addWarning(new PsrMessage(
                '{count} items have more than {threshold} images. Enabling manifest cache is recommended to avoid slow page loads.', // @translate
                ['count' => $largeItems, 'threshold' => $threshold]
            ));
        } elseif ($cacheEnabled) {
            $config = $services->get('Config');
            $basePath = $config['file_store']['local']['base_path']
                ?: (OMEKA_PATH . '/files');
            $cachePath = $basePath . '/iiif';
            if (!is_dir($cachePath)) {
                @mkdir($cachePath, 0775, true);
            }
            if (!is_dir($cachePath) || !is_writable($cachePath)) {
                $messenger->addError(new PsrMessage(
                    'Manifest cache is enabled but directory "{dir}" is not writable.', // @translate
                    ['dir' => 'files/iiif']
                ));
            } else {
                $messenger->addSuccess(new PsrMessage(
                    'Manifest cache is enabled.' // @translate
                ));
            }
        }
    }

    /**
     * Check how many audio/video/image media lack dimensions.
     */
    protected function checkMediaDimensions(): void
    {
        $services = $this->getServiceLocator();
        $connection = $services->get('Omeka\Connection');
        $messenger = $services->get('ControllerPluginManager')
            ->get('messenger');

        $total = (int) $connection->fetchOne(<<<'SQL'
            SELECT COUNT(*) FROM media
            WHERE (media_type LIKE 'image/%'
                OR media_type LIKE 'audio/%'
                OR media_type LIKE 'video/%')
                AND media_type != 'image/svg+xml'
            SQL
        );
        if (!$total) {
            return;
        }

        $unsized = (int) $connection->fetchOne(<<<'SQL'
            SELECT COUNT(*) FROM media
            WHERE (media_type LIKE 'image/%'
                OR media_type LIKE 'audio/%'
                OR media_type LIKE 'video/%')
                AND media_type != 'image/svg+xml'
                AND (data IS NULL
                    OR JSON_EXTRACT(data, '$.dimensions') IS NULL)
            SQL
        );

        if ($unsized === 0) {
            $messenger->addSuccess(new PsrMessage(
                'All {total} media (images, audio, video) have stored dimensions.', // @translate
                ['total' => $total]
            ));
        } else {
            $messenger->addWarning(new PsrMessage(
                '{unsized} of {total} media (images, audio, video) have no stored dimensions. Run "Media Dimensions" job to speed up manifest generation.', // @translate
                ['unsized' => $unsized, 'total' => $total]
            ));
        }
    }

    /**
     * Quick self-test of the manifest route.
     */
    protected function checkManifestRoute(): void
    {
        $services = $this->getServiceLocator();
        $connection = $services->get('Omeka\Connection');
        $messenger = $services->get('ControllerPluginManager')
            ->get('messenger');

        // Find any public item to test.
        $itemId = $connection->fetchOne(<<<'SQL'
            SELECT r.id FROM resource r
            JOIN item i ON r.id = i.id
            WHERE r.is_public = 1
            LIMIT 1
            SQL
        );
        if (!$itemId) {
            return;
        }

        $urlHelper = $services->get('ViewHelperManager')->get('url');
        $settings = $services->get('Omeka\Settings');
        $baseUrl = $settings->get('imageserver_base_url')
            ?: $settings->get('iiifserver_url')
            ?: rtrim($urlHelper('top', [], ['force_canonical' => true]), '/') . '/';
        $version = $settings->get('iiifserver_manifest_default_version', '2');
        $manifestUrl = $baseUrl . 'iiif/' . $version . '/' . $itemId . '/manifest';

        $context = stream_context_create([
            'http' => ['timeout' => 5, 'ignore_errors' => true],
            'ssl' => ['verify_peer' => false, 'verify_peer_name' => false],
        ]);
        $result = @file_get_contents($manifestUrl, false, $context);
        if ($result === false) {
            $messenger->addWarning(new PsrMessage(
                'Could not reach manifest URL: {url}. Check server configuration.', // @translate
                ['url' => $manifestUrl]
            ));
        } else {
            $json = json_decode($result, true);
            if (empty($json)) {
                $messenger->addWarning(new PsrMessage(
                    'Manifest URL {url} returned invalid JSON.', // @translate
                    ['url' => $manifestUrl]
                ));
            } else {
                $messenger->addSuccess(new PsrMessage(
                    'Manifest route is working (tested item #{id}).', // @translate
                    ['id' => $itemId]
                ));
            }
        }
    }

    protected function messageCors(): void
    {
        $services = $this->getServiceLocator();

        /** @var \Omeka\Settings\Settings $settings */
        $settings = $services->get('Omeka\Settings');
        $appendCorsHeaders = (bool) $settings->get('iiifserver_append_cors_headers');

        $plugins = $services->get('ControllerPluginManager');
        $messenger = $plugins->get('messenger');

        $checkCorsHeaders = $this->checkCorsHeaders();
        if (!$checkCorsHeaders && !$appendCorsHeaders) {
            $message = new PsrMessage(
                'The cors headers are disabled. You shall enable them to allow other libraries to access to your manifests.' // @translate
            );
            $messenger->addWarning($message);
        } elseif ($checkCorsHeaders > 1
            || ($checkCorsHeaders === 1 && $appendCorsHeaders)
        ) {
            $message = new PsrMessage(
                'The cors headers are enabled multiple times in the config of the module and in the config of Apache or in the file .htaccess. Duplicating the cors headers makes them disabled. You should disable the option in the config of the module, in the Apache config or in the file .htaccess.' // @translate
            );
            $messenger->addError($message);
        }
    }

    protected function messageCache(): void
    {
        $services = $this->getServiceLocator();
        $plugins = $services->get('ControllerPluginManager');
        $settings = $services->get('Omeka\Settings');
        $messenger = $plugins->get('messenger');

        $isCacheEnabled = $settings->get('iiifserver_manifest_cache');
        if ($isCacheEnabled) {
            $message = new PsrMessage(
                'When cache is enabled, you should recreate it each time the config is updated.' // @translate
            );
            $messenger->addWarning($message);
        }
    }

    /**
     * Check if the server supports encoded slashes (%2F) in URLs.
     *
     * Uses the same self-request pattern as checkCorsHeaders().
     *
     * @return int 0 = test impossible, 1 = %2F accepted, 2 = %2F rejected.
     */
    protected function checkEncodedSlashes(): int
    {
        $services = $this->getServiceLocator();
        $helpers = $services->get('ViewHelperManager');
        $serverUrl = $helpers->get('ServerUrl')->__invoke();
        $basePath = $helpers->get('BasePath')->__invoke();

        // Request a URL with %2F in the path. Use the Omeka API endpoint
        // which always returns JSON. If Apache rejects %2F with a 400,
        // we know AllowEncodedSlashes is Off (default).
        $testUrl = $serverUrl . $basePath . '/api/items%2F0';

        $context = @stream_context_create([
            'http' => [
                'method' => 'GET',
                'timeout' => 5,
                'follow_location' => 0,
            ],
        ]);
        $response = @file_get_contents($testUrl, false, $context);

        // Check the HTTP response code from $http_response_header.
        if (!isset($http_response_header) || !is_array($http_response_header)) {
            return 0;
        }

        $statusLine = $http_response_header[0] ?? '';
        if (!preg_match('/\s(\d{3})\s/', $statusLine, $m)) {
            return 0;
        }

        $statusCode = (int) $m[1];
        // Apache returns 400 (or 404 with "not found") when %2F is rejected.
        // When accepted, Omeka processes the request and returns JSON
        // (typically 404 with a JSON error body for a non-existent item).
        if ($statusCode === 400) {
            return 2;
        }

        // Any Omeka-processed response (200, 404 with JSON, etc.) means
        // the %2F was accepted by the server.
        return 1;
    }

    /**
     * Display a message about encoded slashes support and auto-update the
     * setting iiifserver_identifier_encode_slash.
     */
    protected function messageEncodedSlashes(): void
    {
        $services = $this->getServiceLocator();
        $settings = $services->get('Omeka\Settings');
        $plugins = $services->get('ControllerPluginManager');
        $messenger = $plugins->get('messenger');

        // Check if there are identifiers with "/" (ARK-style).
        $hasSlashIdentifiers = $this->hasIdentifiersWithSlash();
        if (!$hasSlashIdentifiers) {
            return;
        }

        $check = $this->checkEncodedSlashes();

        if ($check === 1) {
            // Server supports %2F: enable spec-compliant encoding.
            $settings->set('iiifserver_identifier_encode_slash', true);
            $message = new PsrMessage(
                'The server supports encoded slashes (AllowEncodedSlashes). IIIF URLs will use spec-compliant %%2F encoding for identifiers with "/". The option can be changed in the config form.' // @translate
            );
            $messenger->addSuccess($message);
        } elseif ($check === 2) {
            // Server rejects %2F: disable encoding, use literal slashes.
            $settings->set('iiifserver_identifier_encode_slash', false);
            $message = new PsrMessage(
                'The server rejects encoded slashes (%%2F) in URLs (Apache default). IIIF URLs will use literal slashes in identifiers, which is functional but not fully IIIF-spec-compliant. To enable compliant URLs, add "AllowEncodedSlashes NoDecode" to your Apache VirtualHost config, or use a prefix, or use numeric identifiers.' // @translate
            );
            $messenger->addWarning($message);
        }
        // check === 0: test impossible, don't change the setting.
    }

    /**
     * Check if any resources use identifiers containing "/".
     */
    protected function hasIdentifiersWithSlash(): bool
    {
        $services = $this->getServiceLocator();

        // Check via CleanUrl module if available.
        $moduleManager = $services->get('Omeka\ModuleManager');
        $cleanUrlModule = $moduleManager->getModule('CleanUrl');
        $hasCleanUrl = $cleanUrlModule
            && $cleanUrlModule->getState() === \Omeka\Module\Manager::STATE_ACTIVE;

        if ($hasCleanUrl) {
            /** @var \Doctrine\DBAL\Connection $connection */
            $connection = $services->get('Omeka\Connection');
            try {
                $result = $connection->executeQuery(
                    "SELECT 1 FROM clean_url WHERE identifier LIKE '%/%' LIMIT 1"
                )->fetchOne();
                return (bool) $result;
            } catch (\Throwable $e) {
                // Table may not exist; fall through.
            }
        }

        // Fallback: check if the prefix setting contains "/".
        $settings = $services->get('Omeka\Settings');
        $prefix = $settings->get('iiifserver_identifier_prefix', '');
        return strpos($prefix, '/') !== false;
    }

    /**
     * Check if an external IIIF image server handles image requests.
     *
     * Uses a self-request to a IIIF image info endpoint and analyzes
     * response headers and content. Detection works regardless of which
     * proxy (Apache, nginx, Traefik) sits in front of the image server.
     *
     * Known servers detected by name: Cantaloupe, IIPImage.
     * Any other external server (Loris, serverless-iiif, RAIS, Digilib,
     * SIPI, Go IIIF, Riiif, etc.) is detected generically via header and
     * content analysis.
     *
     * @see https://iiif.io/get-started/image-servers/
     *
     * @return array With keys "external" (bool) and "server" (string|null:
     * "cantaloupe", "iipimage", "unknown", or null).
     */
    protected function checkExternalImageServer(): array
    {
        $result = ['external' => false, 'server' => null];

        $services = $this->getServiceLocator();
        $helpers = $services->get('ViewHelperManager');
        $serverUrl = $helpers->get('ServerUrl')->__invoke();
        $basePath = $helpers->get('BasePath')->__invoke();

        // Request a non-existent media info.json. If an external server
        // intercepts /iiif/ requests, the response will differ from the
        // Omeka IiifServer module response.
        $testUrl = $serverUrl . $basePath . '/iiif/3/0/info.json';

        $context = @stream_context_create([
            'http' => [
                'method' => 'GET',
                'timeout' => 5,
                'follow_location' => 0,
                'ignore_errors' => true,
            ],
        ]);
        $response = @file_get_contents($testUrl, false, $context);

        if (!isset($http_response_header) || !is_array($http_response_header)) {
            // Self-request failed. Fallback: check the media api url setting.
            $settings = $services->get('Omeka\Settings');
            $mediaApiUrl = $settings->get('iiifserver_media_api_url', '');
            if ($mediaApiUrl) {
                $result['external'] = true;
                $result['server'] = 'unknown';
            }
            return $result;
        }

        $headers = implode("\n", $http_response_header);

        // 1. Try to identify the server by name from headers.
        if (stripos($headers, 'Cantaloupe') !== false
            || preg_match('/Server:\s*Jetty/i', $headers)
        ) {
            return ['external' => true, 'server' => 'cantaloupe'];
        }

        if (stripos($headers, 'IIPImage') !== false
            || stripos($headers, 'iipsrv') !== false
        ) {
            return ['external' => true, 'server' => 'iipimage'];
        }

        // 2. Check for non-Apache/PHP server headers (covers nginx,
        // Caddy, Traefik, CloudFront, gunicorn, Puma, etc.).
        if (!preg_match('/Server:\s*Apache/i', $headers)
            && !preg_match('/X-Powered-By:\s*PHP/i', $headers)
            && preg_match('/^Server:\s*\S/im', $headers)
        ) {
            return ['external' => true, 'server' => 'unknown'];
        }

        // 3. Headers look like Apache/PHP (e.g. external server behind
        // an Apache reverse proxy). Fall back to content analysis:
        // IiifServer always returns JSON for errors (Omeka error format
        // with "errors" key). External servers return plain text, HTML,
        // or a different JSON structure.
        if ($response !== false && $response !== '') {
            $json = @json_decode($response, true);
            if ($json === null) {
                // Non-JSON response on a .json endpoint -> external.
                return ['external' => true, 'server' => 'unknown'];
            }
            if (is_array($json) && !isset($json['errors'])) {
                // JSON but not Omeka error format. Check for IIIF Image
                // API keys that IiifServer would not return for a
                // non-existent media.
                if (isset($json['protocol']) || isset($json['tiles'])
                    || isset($json['extraQualities'])
                ) {
                    return ['external' => true, 'server' => 'unknown'];
                }
            }
        }

        return $result;
    }

    /**
     * Display a message about external image server detection and auto-update
     * the setting iiifserver_media_api_identifier when needed.
     */
    protected function messageExternalImageServer(): void
    {
        $services = $this->getServiceLocator();
        $settings = $services->get('Omeka\Settings');
        $plugins = $services->get('ControllerPluginManager');
        $messenger = $plugins->get('messenger');

        $check = $this->checkExternalImageServer();

        $identifier = $settings->get('iiifserver_media_api_identifier', 'media_id');

        if ($check['external']) {
            $serverLabel = $check['server'] === 'cantaloupe'
                ? 'Cantaloupe'
                : ($check['server'] === 'iipimage' ? 'IIPImage' : 'unknown');

            if (in_array($identifier, ['media_id', 'default'])) {
                // Auto-configure: external server with filesystem source
                // needs the filename, not the numeric media id.
                $settings->set('iiifserver_media_api_identifier', 'filename_image');
                $message = new PsrMessage(
                    'An external IIIF image server was detected ({server_label}). The media identifier has been set to "filename with extension (image only)" for compatibility. The option can be changed in the config form.', // @translate
                    ['server_label' => $serverLabel]
                );
                $messenger->addSuccess($message);
            } else {
                $message = new PsrMessage(
                    'An external IIIF image server was detected ({server_label}). The current media identifier setting "{identifier}" is already set and likely compatible. If images don’t display, check the config form.', // @translate
                    ['server_label' => $serverLabel, 'identifier' => $identifier]
                );
                $messenger->addNotice($message);
            }
        }
    }

    /**
     * Only unsized medias are dimensionned.
     *
     * @todo Get size for external media iiif?
     *
     * @see \IiifServer\Module::prepareSizeItem()
     * @see \IiifServer\Job\MediaDimensions::prepareSize()
     */
    protected function prepareSizeItem(Item $item): void
    {
        $medias = $item->getMedia();
        if (!$medias->count()) {
            return;
        }

        /** @var \IiifServer\Mvc\Controller\Plugin\MediaDimension $mediaDimension */
        $services = $this->getServiceLocator();
        $imageTypes = array_keys($services->get('Config')['thumbnails']['types']);
        $mediaDimension = $services->get('ControllerPluginManager')->get('mediaDimension');

        /** @var \Omeka\Entity\Media $media */
        foreach ($medias as $media) {
            $mainMediaType = strtok((string) $media->getMediaType(), '/');
            if (!in_array($mainMediaType, ['image', 'audio', 'video'])) {
                continue;
            }

            // Keep possible data added by another module.
            $mediaData = $media->getData() ?: [];

            // Don't redo sizing here.
            if (($mainMediaType === 'image' && !empty($mediaData['dimensions']['large']['width']))
                || ($mainMediaType === 'audio' && !empty($mediaData['dimensions']['original']['duration']))
                || ($mainMediaType === 'video' && !empty($mediaData['dimensions']['original']['duration']))
            ) {
                continue;
            }

            // Reset dimensions to make the sizer working.
            // TODO In rare cases, the original file is removed once the thumbnails are built.
            $mediaData['dimensions'] = [];
            $media->setData($mediaData);

            $failedTypes = [];
            foreach ($mainMediaType === 'image' ? $imageTypes : ['original'] as $imageType) {
                $result = $mediaDimension->__invoke($media, $imageType);
                $result = array_filter($result);
                if (!$result) {
                    $failedTypes[] = $imageType;
                }
                // Store the dimensions in all cases (empty array), to know that
                // the dimensions were processed.
                $mediaData['dimensions'][$imageType] = $result;
            }

            if (count($failedTypes)) {
                $this->getServiceLocator()->get('Omeka\Logger')->err(
                    'Item #{item_id} / media #{media_id}: Error getting dimensions for types "{types}".', // @translate
                    [
                        'item_id' => $item->getId(),
                        'media_id' => $media->getId(),
                        'types' => implode('", "', $failedTypes),
                    ]
                );
            }

            $media->setData($mediaData);
        }

        // No flush.
    }
}