vendor/contao/core-bundle/src/Image/Studio/FigureBuilder.php line 624

Open in your IDE?
  1. <?php
  3. declare(strict_types=1);
  5. /*
  6.  * This file is part of Contao.
  7.  *
  8.  * (c) Leo Feyer
  9.  *
  10.  * @license LGPL-3.0-or-later
  11.  */
  13. namespace Contao\CoreBundle\Image\Studio;
  15. use Contao\CoreBundle\Event\FileMetadataEvent;
  16. use Contao\CoreBundle\Exception\InvalidResourceException;
  17. use Contao\CoreBundle\File\Metadata;
  18. use Contao\CoreBundle\Framework\Adapter;
  19. use Contao\CoreBundle\Util\LocaleUtil;
  20. use Contao\FilesModel;
  21. use Contao\Image\ImageInterface;
  22. use Contao\Image\PictureConfiguration;
  23. use Contao\Image\ResizeOptions;
  24. use Contao\PageModel;
  25. use Contao\StringUtil;
  26. use Contao\Validator;
  27. use Nyholm\Psr7\Uri;
  28. use Psr\Container\ContainerInterface;
  29. use Symfony\Component\Filesystem\Filesystem;
  30. use Symfony\Component\Filesystem\Path;
  32. /**
  33.  * Use the FigureBuilder class to create Figure result objects. The class
  34.  * has a fluent interface to configure the desired output. When you are ready,
  35.  * call build() to get a Figure. If you need another instance with similar
  36.  * settings, you can alter values and call build() again - it will not affect
  37.  * your first instance.
  38.  */
  39. class FigureBuilder
  40. {
  41.     private ContainerInterface $locator;
  42.     private string $projectDir;
  43.     private string $uploadPath;
  44.     private string $webDir;
  45.     private Filesystem $filesystem;
  46.     private ?InvalidResourceException $lastException = null;
  48.     /**
  49.      * @var array<string>
  50.      */
  51.     private array $validExtensions;
  53.     /**
  54.      * The resource's absolute file path.
  55.      */
  56.     private ?string $filePath = null;
  58.     /**
  59.      * The resource's file model if applicable.
  60.      */
  61.     private ?FilesModel $filesModel = null;
  63.     /**
  64.      * User defined size configuration.
  65.      *
  66.      * @phpcsSuppress SlevomatCodingStandard.Classes.UnusedPrivateElements
  67.      *
  68.      * @var int|string|array|PictureConfiguration|null
  69.      */
  70.     private $sizeConfiguration;
  72.     /**
  73.      * User defined resize options.
  74.      *
  75.      * @phpcsSuppress SlevomatCodingStandard.Classes.UnusedPrivateElements
  76.      */
  77.     private ?ResizeOptions $resizeOptions = null;
  79.     /**
  80.      * User defined custom locale. This will overwrite the default if set.
  81.      */
  82.     private ?string $locale = null;
  84.     /**
  85.      * User defined metadata. This will overwrite the default if set.
  86.      */
  87.     private ?Metadata $metadata = null;
  89.     /**
  90.      * User defined metadata. This will be added to the default if set.
  91.      */
  92.     private ?Metadata $overwriteMetadata = null;
  94.     /**
  95.      * Determines if a metadata should never be present in the output.
  96.      */
  97.     private ?bool $disableMetadata = null;
  99.     /**
  100.      * User defined link attributes. These will add to or overwrite the default values.
  101.      *
  102.      * @var array<string, string|null>
  103.      */
  104.     private array $additionalLinkAttributes = [];
  106.     /**
  107.      * User defined lightbox resource or url. This will overwrite the default if set.
  108.      *
  109.      * @var string|ImageInterface|null
  110.      */
  111.     private $lightboxResourceOrUrl;
  113.     /**
  114.      * User defined lightbox size configuration. This will overwrite the default if set.
  115.      *
  116.      * @var int|string|array|PictureConfiguration|null
  117.      */
  118.     private $lightboxSizeConfiguration;
  120.     /**
  121.      * User defined lightbox resize options.
  122.      */
  123.     private ?ResizeOptions $lightboxResizeOptions = null;
  125.     /**
  126.      * User defined lightbox group identifier. This will overwrite the default if set.
  127.      */
  128.     private ?string $lightboxGroupIdentifier = null;
  130.     /**
  131.      * Determines if a lightbox (or "fullsize") image should be created.
  132.      */
  133.     private ?bool $enableLightbox = null;
  135.     /**
  136.      * User defined template options.
  137.      *
  138.      * @phpcsSuppress SlevomatCodingStandard.Classes.UnusedPrivateElements
  139.      *
  140.      * @var array<string, mixed>
  141.      */
  142.     private array $options = [];
  144.     /**
  145.      * @internal Use the Contao\CoreBundle\Image\Studio\Studio factory to get an instance of this class
  146.      */
  147.     public function __construct(ContainerInterface $locator, string $projectDir, string $uploadPath, string $webDir, array $validExtensions)
  148.     {
  149.         $this->locator = $locator;
  150.         $this->projectDir = $projectDir;
  151.         $this->uploadPath = $uploadPath;
  152.         $this->webDir = $webDir;
  153.         $this->validExtensions = $validExtensions;
  155.         $this->filesystem = new Filesystem();
  156.     }
  158.     /**
  159.      * Sets the image resource from a FilesModel.
  160.      */
  161.     public function fromFilesModel(FilesModel $filesModel): self
  162.     {
  163.         $this->lastException = null;
  165.         if ('file' !== $filesModel->type) {
  166.             $this->lastException = new InvalidResourceException(sprintf('DBAFS item "%s" is not a file.', $filesModel->path));
  168.             return $this;
  169.         }
  171.         $this->filePath = Path::makeAbsolute($filesModel->path, $this->projectDir);
  172.         $this->filesModel = $filesModel;
  174.         if (!$this->filesystem->exists($this->filePath)) {
  175.             $this->lastException = new InvalidResourceException(sprintf('No resource could be located at path "%s".', $this->filePath));
  176.         }
  178.         return $this;
  179.     }
  181.     /**
  182.      * Sets the image resource from a tl_files UUID.
  183.      */
  184.     public function fromUuid(string $uuid): self
  185.     {
  186.         $this->lastException = null;
  188.         $filesModel = $this->getFilesModelAdapter()->findByUuid($uuid);
  190.         if (null === $filesModel) {
  191.             $this->lastException = new InvalidResourceException(sprintf('DBAFS item with UUID "%s" could not be found.', $uuid));
  193.             return $this;
  194.         }
  196.         return $this->fromFilesModel($filesModel);
  197.     }
  199.     /**
  200.      * Sets the image resource from a tl_files ID.
  201.      */
  202.     public function fromId(int $id): self
  203.     {
  204.         $this->lastException = null;
  206.         /** @var FilesModel|null $filesModel */
  207.         $filesModel = $this->getFilesModelAdapter()->findByPk($id);
  209.         if (null === $filesModel) {
  210.             $this->lastException = new InvalidResourceException(sprintf('DBAFS item with ID "%s" could not be found.', $id));
  212.             return $this;
  213.         }
  215.         return $this->fromFilesModel($filesModel);
  216.     }
  218.     /**
  219.      * Sets the image resource from an absolute or relative path.
  220.      *
  221.      * @param bool $autoDetectDbafsPaths Set to false to skip searching for a FilesModel
  222.      */
  223.     public function fromPath(string $path, bool $autoDetectDbafsPaths = true): self
  224.     {
  225.         $this->lastException = null;
  227.         // Make sure path is absolute and in a canonical form
  228.         $path = Path::isAbsolute($path) ? Path::canonicalize($path) : Path::makeAbsolute($path, $this->projectDir);
  230.         // Only check for a FilesModel if the resource is inside the upload path
  231.         $getDbafsPath = function (string $path): ?string {
  232.             if (Path::isBasePath(Path::join($this->webDir, $this->uploadPath), $path)) {
  233.                 return Path::makeRelative($path, $this->webDir);
  234.             }
  236.             if (Path::isBasePath(Path::join($this->projectDir, $this->uploadPath), $path)) {
  237.                 return $path;
  238.             }
  240.             return null;
  241.         };
  243.         if ($autoDetectDbafsPaths && null !== ($dbafsPath = $getDbafsPath($path))) {
  244.             $filesModel = $this->getFilesModelAdapter()->findByPath($dbafsPath);
  246.             if (null !== $filesModel) {
  247.                 return $this->fromFilesModel($filesModel);
  248.             }
  249.         }
  251.         $this->filePath = $path;
  252.         $this->filesModel = null;
  254.         if (!$this->filesystem->exists($this->filePath)) {
  255.             $this->lastException = new InvalidResourceException(sprintf('No resource could be located at path "%s".', $this->filePath));
  256.         }
  258.         return $this;
  259.     }
  261.     /**
  262.      * Sets the image resource from an absolute or relative URL.
  263.      *
  264.      * @param list<string> $baseUrls a list of allowed base URLs, the first match gets stripped from the resource URL
  265.      */
  266.     public function fromUrl(string $url, array $baseUrls = []): self
  267.     {
  268.         $this->lastException = null;
  270.         $uri = new Uri($url);
  271.         $path = null;
  273.         foreach ($baseUrls as $baseUrl) {
  274.             $baseUri = new Uri($baseUrl);
  276.             if ($baseUri->getHost() === $uri->getHost() && Path::isBasePath($baseUri->getPath(), $uri->getPath())) {
  277.                 $path = Path::makeRelative($uri->getPath(), $baseUri->getPath().'/');
  278.                 break;
  279.             }
  280.         }
  282.         if (null === $path) {
  283.             if ('' !== $uri->getHost()) {
  284.                 $this->lastException = new InvalidResourceException(sprintf('Resource URL "%s" outside of base URLs "%s".', $url, implode('", "', $baseUrls)));
  286.                 return $this;
  287.             }
  289.             $path = $uri->getPath();
  290.         }
  292.         if (preg_match('/%2f|%5c/i', $path)) {
  293.             $this->lastException = new InvalidResourceException(sprintf('Resource URL path "%s" contains invalid percent encoding.', $path));
  295.             return $this;
  296.         }
  298.         // Prepend the web_dir (see #6123)
  299.         return $this->fromPath(Path::join($this->webDir, urldecode($path)));
  300.     }
  302.     /**
  303.      * Sets the image resource from an ImageInterface.
  304.      */
  305.     public function fromImage(ImageInterface $image): self
  306.     {
  307.         return $this->fromPath($image->getPath());
  308.     }
  310.     /**
  311.      * Sets the image resource by guessing the identifier type.
  312.      *
  313.      * @param int|string|FilesModel|ImageInterface|null $identifier Can be a FilesModel, an ImageInterface, a tl_files UUID/ID/path or a file system path
  314.      */
  315.     public function from($identifier): self
  316.     {
  317.         if (null === $identifier) {
  318.             $this->lastException = new InvalidResourceException('The defined resource is "null".');
  320.             return $this;
  321.         }
  323.         if ($identifier instanceof FilesModel) {
  324.             return $this->fromFilesModel($identifier);
  325.         }
  327.         if ($identifier instanceof ImageInterface) {
  328.             return $this->fromImage($identifier);
  329.         }
  331.         $isString = \is_string($identifier);
  333.         if ($isString && $this->getValidatorAdapter()->isUuid($identifier)) {
  334.             return $this->fromUuid($identifier);
  335.         }
  337.         if (is_numeric($identifier)) {
  338.             return $this->fromId((int) $identifier);
  339.         }
  341.         if ($isString) {
  342.             return $this->fromPath($identifier);
  343.         }
  345.         $type = \is_object($identifier) ? \get_class($identifier) : \gettype($identifier);
  347.         throw new \TypeError(sprintf('%s(): Argument #1 ($identifier) must be of type FilesModel|ImageInterface|string|int|null, %s given', __METHOD__, $type));
  348.     }
  350.     /**
  351.      * Sets a size configuration that will be applied to the resource.
  352.      *
  353.      * @param int|string|array|PictureConfiguration|null $size A picture size configuration or reference
  354.      */
  355.     public function setSize($size): self
  356.     {
  357.         $this->sizeConfiguration = $size;
  359.         return $this;
  360.     }
  362.     /**
  363.      * Sets resize options.
  364.      *
  365.      * By default, or if the argument is set to null, resize options are derived
  366.      * from predefined image sizes.
  367.      */
  368.     public function setResizeOptions(?ResizeOptions $resizeOptions): self
  369.     {
  370.         $this->resizeOptions = $resizeOptions;
  372.         return $this;
  373.     }
  375.     /**
  376.      * Sets custom metadata.
  377.      *
  378.      * By default, or if the argument is set to null, metadata is trying to be
  379.      * pulled from the FilesModel.
  380.      */
  381.     public function setMetadata(?Metadata $metadata): self
  382.     {
  383.         $this->metadata = $metadata;
  385.         return $this;
  386.     }
  388.     /**
  389.      * Sets custom overwrite metadata.
  390.      *
  391.      * The metadata will be merged with the default metadata from the FilesModel.
  392.      */
  393.     public function setOverwriteMetadata(?Metadata $metadata): self
  394.     {
  395.         $this->overwriteMetadata = $metadata;
  397.         return $this;
  398.     }
  400.     /**
  401.      * Disables creating/using metadata in the output even if it is present.
  402.      */
  403.     public function disableMetadata(bool $disable = true): self
  404.     {
  405.         $this->disableMetadata = $disable;
  407.         return $this;
  408.     }
  410.     /**
  411.      * Sets a custom locale.
  412.      *
  413.      * By default, or if the argument is set to null, the locale is determined
  414.      * from the request context and/or system settings.
  415.      */
  416.     public function setLocale(?string $locale): self
  417.     {
  418.         $this->locale = $locale;
  420.         return $this;
  421.     }
  423.     /**
  424.      * Adds a custom link attribute.
  425.      *
  426.      * Set the value to null to remove it. If you want to explicitly remove an
  427.      * auto-generated value from the results, set the $forceRemove flag to true.
  428.      */
  429.     public function setLinkAttribute(string $attribute, ?string $value, bool $forceRemove = false): self
  430.     {
  431.         if (null !== $value || $forceRemove) {
  432.             $this->additionalLinkAttributes[$attribute] = $value;
  433.         } else {
  434.             unset($this->additionalLinkAttributes[$attribute]);
  435.         }
  437.         return $this;
  438.     }
  440.     /**
  441.      * Sets all custom link attributes as an associative array.
  442.      *
  443.      * This will overwrite previously set attributes. If you want to explicitly
  444.      * remove an auto-generated value from the results, set the respective
  445.      * attribute to null.
  446.      */
  447.     public function setLinkAttributes(array $attributes): self
  448.     {
  449.         foreach ($attributes as $key => $value) {
  450.             if (!\is_string($key) || !\is_string($value)) {
  451.                 throw new \InvalidArgumentException('Link attributes must be an array of type <string, string>.');
  452.             }
  453.         }
  455.         $this->additionalLinkAttributes = $attributes;
  457.         return $this;
  458.     }
  460.     /**
  461.      * Sets the link href attribute.
  462.      *
  463.      * Set the value to null to use the auto-generated default.
  464.      */
  465.     public function setLinkHref(?string $url): self
  466.     {
  467.         $this->setLinkAttribute('href', $url);
  469.         return $this;
  470.     }
  472.     /**
  473.      * Sets a custom lightbox resource (file path or ImageInterface) or URL.
  474.      *
  475.      * By default, or if the argument is set to null, the image/target will be
  476.      * automatically determined from the metadata or base resource. For this
  477.      * setting to take effect, make sure you have enabled the creation of a
  478.      * lightbox by calling enableLightbox().
  479.      *
  480.      * @param string|ImageInterface|null $resourceOrUrl
  481.      */
  482.     public function setLightboxResourceOrUrl($resourceOrUrl): self
  483.     {
  484.         $this->lightboxResourceOrUrl = $resourceOrUrl;
  486.         return $this;
  487.     }
  489.     /**
  490.      * Sets a size configuration that will be applied to the lightbox image.
  491.      *
  492.      * For this setting to take effect, make sure you have enabled the creation
  493.      * of a lightbox by calling enableLightbox().
  494.      *
  495.      * @param int|string|array|PictureConfiguration|null $size A picture size configuration or reference
  496.      */
  497.     public function setLightboxSize($size): self
  498.     {
  499.         $this->lightboxSizeConfiguration = $size;
  501.         return $this;
  502.     }
  504.     /**
  505.      * Sets resize options for the lightbox image.
  506.      *
  507.      * By default, or if the argument is set to null, resize options are derived
  508.      * from predefined image sizes.
  509.      */
  510.     public function setLightboxResizeOptions(?ResizeOptions $resizeOptions): self
  511.     {
  512.         $this->lightboxResizeOptions = $resizeOptions;
  514.         return $this;
  515.     }
  517.     /**
  518.      * Sets a custom lightbox group ID.
  519.      *
  520.      * By default, or if the argument is set to null, the ID will be empty. For
  521.      * this setting to take effect, make sure you have enabled the creation of
  522.      * a lightbox by calling enableLightbox().
  523.      */
  524.     public function setLightboxGroupIdentifier(?string $identifier): self
  525.     {
  526.         $this->lightboxGroupIdentifier = $identifier;
  528.         return $this;
  529.     }
  531.     /**
  532.      * Enables the creation of a lightbox image (if possible) and/or
  533.      * outputting the respective link attributes.
  534.      *
  535.      * This setting is disabled by default.
  536.      */
  537.     public function enableLightbox(bool $enable = true): self
  538.     {
  539.         $this->enableLightbox = $enable;
  541.         return $this;
  542.     }
  544.     /**
  545.      * Sets all template options as an associative array.
  546.      */
  547.     public function setOptions(array $options): self
  548.     {
  549.         $this->options = $options;
  551.         return $this;
  552.     }
  554.     /**
  555.      * Returns the last InvalidResourceException that was captured when setting
  556.      * resources or null if there was none.
  557.      */
  558.     public function getLastException(): ?InvalidResourceException
  559.     {
  560.         return $this->lastException;
  561.     }
  563.     /**
  564.      * Creates a result object with the current settings, throws an exception
  565.      * if the currently defined resource is invalid.
  566.      *
  567.      * @throws InvalidResourceException
  568.      */
  569.     public function build(): Figure
  570.     {
  571.         if (null !== $this->lastException) {
  572.             throw $this->lastException;
  573.         }
  575.         return $this->doBuild();
  576.     }
  578.     /**
  579.      * Creates a result object with the current settings, returns null if the
  580.      * currently defined resource is invalid.
  581.      */
  582.     public function buildIfResourceExists(): ?Figure
  583.     {
  584.         if (null !== $this->lastException) {
  585.             return null;
  586.         }
  588.         $figure = $this->doBuild();
  590.         try {
  591.             // Make sure the resource can be processed
  592.             $figure->getImage()->getOriginalDimensions();
  593.         } catch (\Throwable $e) {
  594.             $this->lastException = new InvalidResourceException(sprintf('The file "%s" could not be opened as an image.', $this->filePath), 0, $e);
  596.             return null;
  597.         }
  599.         return $figure;
  600.     }
  602.     /**
  603.      * Creates a result object with the current settings.
  604.      */
  605.     private function doBuild(): Figure
  606.     {
  607.         if (null === $this->filePath) {
  608.             throw new \LogicException('You need to set a resource before building the result.');
  609.         }
  611.         // Freeze settings to allow reusing this builder object
  612.         $settings = clone $this;
  614.         $imageResult = $this->locator
  615.             ->get('contao.image.studio')
  616.             ->createImage($settings->filePath, $settings->sizeConfiguration, $settings->resizeOptions)
  617.         ;
  619.         // Define the values via closure to make their evaluation lazy
  620.         return new Figure(
  621.             $imageResult,
  622.             \Closure::bind(
  623.                 function (Figure $figure): ?Metadata {
  624.                     $event = new FileMetadataEvent($this->onDefineMetadata());
  626.                     $this->locator->get('event_dispatcher')->dispatch($event);
  628.                     return $event->getMetadata();
  629.                 },
  630.                 $settings
  631.             ),
  632.             \Closure::bind(
  633.                 fn (Figure $figure): array => $this->onDefineLinkAttributes($figure),
  634.                 $settings
  635.             ),
  636.             \Closure::bind(
  637.                 fn (Figure $figure): ?LightboxResult => $this->onDefineLightboxResult($figure),
  638.                 $settings
  639.             ),
  640.             $settings->options
  641.         );
  642.     }
  644.     /**
  645.      * Defines metadata on demand.
  646.      */
  647.     private function onDefineMetadata(): ?Metadata
  648.     {
  649.         if ($this->disableMetadata) {
  650.             return null;
  651.         }
  653.         $getUuid = static function (?FilesModel $filesModel): ?string {
  654.             if (null === $filesModel || null === $filesModel->uuid) {
  655.                 return null;
  656.             }
  658.             // Normalize UUID to ASCII format
  659.             return Validator::isBinaryUuid($filesModel->uuid)
  660.                 ? StringUtil::binToUuid($filesModel->uuid)
  661.                 : $filesModel->uuid;
  662.         };
  664.         $fileReferenceData = array_filter([Metadata::VALUE_UUID => $getUuid($this->filesModel)]);
  666.         if (null !== $this->metadata) {
  667.             return $this->metadata->with($fileReferenceData);
  668.         }
  670.         if (null === $this->filesModel) {
  671.             return null;
  672.         }
  674.         // Get fallback locale list or use without fallbacks if explicitly set
  675.         $locales = null !== $this->locale ? [$this->locale] : $this->getFallbackLocaleList();
  676.         $metadata = $this->filesModel->getMetadata(...$locales);
  677.         $overwriteMetadata = $this->overwriteMetadata ? $this->overwriteMetadata->all() : [];
  679.         if (null !== $metadata) {
  680.             return $metadata
  681.                 ->with($fileReferenceData)
  682.                 ->with($overwriteMetadata)
  683.             ;
  684.         }
  686.         // If no metadata can be obtained from the model, we create a container
  687.         // from the default meta fields with empty values instead
  688.         $metaFields = $this->getFilesModelAdapter()->getMetaFields();
  690.         $data = array_merge(
  691.             array_combine($metaFields, array_fill(0, \count($metaFields), '')),
  692.             $fileReferenceData
  693.         );
  695.         return (new Metadata($data))->with($overwriteMetadata);
  696.     }
  698.     /**
  699.      * Defines link attributes on demand.
  700.      */
  701.     private function onDefineLinkAttributes(Figure $result): array
  702.     {
  703.         $linkAttributes = [];
  705.         // Open in a new window if lightbox was requested but is invalid (fullsize)
  706.         if ($this->enableLightbox && !$result->hasLightbox()) {
  707.             $linkAttributes['target'] = '_blank';
  708.         }
  710.         return array_merge($linkAttributes, $this->additionalLinkAttributes);
  711.     }
  713.     /**
  714.      * Defines the lightbox result (if enabled) on demand.
  715.      */
  716.     private function onDefineLightboxResult(Figure $result): ?LightboxResult
  717.     {
  718.         if (!$this->enableLightbox) {
  719.             return null;
  720.         }
  722.         $getMetadataUrl = static function () use ($result): ?string {
  723.             if (!$result->hasMetadata()) {
  724.                 return null;
  725.             }
  727.             return $result->getMetadata()->getUrl() ?: null;
  728.         };
  730.         /**
  731.          * @param ImageInterface|string $target Image object, URL or absolute file path
  732.          */
  733.         $getResourceOrUrl = function ($target): array {
  734.             if ($target instanceof ImageInterface) {
  735.                 return [$target, null];
  736.             }
  738.             $validExtension = \in_array(Path::getExtension($target, true), $this->validExtensions, true);
  739.             $externalUrl = 1 === preg_match('#^https?://#', $target);
  741.             if (!$validExtension) {
  742.                 return [null, null];
  743.             }
  745.             if ($externalUrl) {
  746.                 return [null, $target];
  747.             }
  749.             if (Path::isAbsolute($target)) {
  750.                 $filePath = Path::canonicalize($target);
  751.             } else {
  752.                 // URL relative to the project directory
  753.                 $filePath = Path::makeAbsolute(urldecode($target), $this->projectDir);
  754.             }
  756.             if (!is_file($filePath)) {
  757.                 $filePath = null;
  758.             }
  760.             return [$filePath, null];
  761.         };
  763.         // Use explicitly set data (1), fall back to using metadata (2) or use the base resource (3) if empty
  764.         $lightboxResourceOrUrl = $this->lightboxResourceOrUrl ?? $getMetadataUrl() ?? $this->filePath;
  766.         [$filePathOrImage, $url] = $getResourceOrUrl($lightboxResourceOrUrl);
  768.         if (null === $filePathOrImage && null === $url) {
  769.             return null;
  770.         }
  772.         return $this->locator
  773.             ->get('contao.image.studio')
  774.             ->createLightboxImage(
  775.                 $filePathOrImage,
  776.                 $url,
  777.                 $this->lightboxSizeConfiguration,
  778.                 $this->lightboxGroupIdentifier,
  779.                 $this->lightboxResizeOptions
  780.             )
  781.         ;
  782.     }
  784.     /**
  785.      * @return FilesModel
  786.      *
  787.      * @phpstan-return Adapter<FilesModel>
  788.      */
  789.     private function getFilesModelAdapter(): Adapter
  790.     {
  791.         $framework = $this->locator->get('contao.framework');
  792.         $framework->initialize();
  794.         return $framework->getAdapter(FilesModel::class);
  795.     }
  797.     /**
  798.      * @return Validator
  799.      *
  800.      * @phpstan-return Adapter<Validator>
  801.      */
  802.     private function getValidatorAdapter(): Adapter
  803.     {
  804.         $framework = $this->locator->get('contao.framework');
  805.         $framework->initialize();
  807.         return $framework->getAdapter(Validator::class);
  808.     }
  810.     /**
  811.      * Returns a list of locales (if available) in the following order:
  812.      *  1. language of current page,
  813.      *  2. root page fallback language.
  814.      */
  815.     private function getFallbackLocaleList(): array
  816.     {
  817.         $page = $GLOBALS['objPage'] ?? null;
  819.         if (!$page instanceof PageModel) {
  820.             return [];
  821.         }
  823.         $locales = [LocaleUtil::formatAsLocale($page->language)];
  825.         if (null !== $page->rootFallbackLanguage) {
  826.             $locales[] = LocaleUtil::formatAsLocale($page->rootFallbackLanguage);
  827.         }
  829.         return array_unique(array_filter($locales));
  830.     }
  831. }