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

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.      * @internal
  565.      */
  566.     public function setLastException(InvalidResourceException $exception): self
  567.     {
  568.         $this->lastException = $exception;
  570.         return $this;
  571.     }
  573.     /**
  574.      * Creates a result object with the current settings, throws an exception
  575.      * if the currently defined resource is invalid.
  576.      *
  577.      * @throws InvalidResourceException
  578.      */
  579.     public function build(): Figure
  580.     {
  581.         if (null !== $this->lastException) {
  582.             throw $this->lastException;
  583.         }
  585.         return $this->doBuild();
  586.     }
  588.     /**
  589.      * Creates a result object with the current settings, returns null if the
  590.      * currently defined resource is invalid.
  591.      */
  592.     public function buildIfResourceExists(): ?Figure
  593.     {
  594.         if (null !== $this->lastException) {
  595.             return null;
  596.         }
  598.         $figure = $this->doBuild();
  600.         try {
  601.             // Make sure the resource can be processed
  602.             $figure->getImage()->getOriginalDimensions();
  603.         } catch (\Throwable $e) {
  604.             $this->lastException = new InvalidResourceException(sprintf('The file "%s" could not be opened as an image.', $this->filePath), 0, $e);
  606.             return null;
  607.         }
  609.         return $figure;
  610.     }
  612.     /**
  613.      * Creates a result object with the current settings.
  614.      */
  615.     private function doBuild(): Figure
  616.     {
  617.         if (null === $this->filePath) {
  618.             throw new \LogicException('You need to set a resource before building the result.');
  619.         }
  621.         // Freeze settings to allow reusing this builder object
  622.         $settings = clone $this;
  624.         $imageResult = $this->locator
  625.             ->get('contao.image.studio')
  626.             ->createImage($settings->filePath, $settings->sizeConfiguration, $settings->resizeOptions)
  627.         ;
  629.         // Define the values via closure to make their evaluation lazy
  630.         return new Figure(
  631.             $imageResult,
  632.             \Closure::bind(
  633.                 function (Figure $figure): ?Metadata {
  634.                     $event = new FileMetadataEvent($this->onDefineMetadata());
  636.                     $this->locator->get('event_dispatcher')->dispatch($event);
  638.                     return $event->getMetadata();
  639.                 },
  640.                 $settings
  641.             ),
  642.             \Closure::bind(
  643.                 fn (Figure $figure): array => $this->onDefineLinkAttributes($figure),
  644.                 $settings
  645.             ),
  646.             \Closure::bind(
  647.                 fn (Figure $figure): ?LightboxResult => $this->onDefineLightboxResult($figure),
  648.                 $settings
  649.             ),
  650.             $settings->options
  651.         );
  652.     }
  654.     /**
  655.      * Defines metadata on demand.
  656.      */
  657.     private function onDefineMetadata(): ?Metadata
  658.     {
  659.         if ($this->disableMetadata) {
  660.             return null;
  661.         }
  663.         $getUuid = static function (?FilesModel $filesModel): ?string {
  664.             if (null === $filesModel || null === $filesModel->uuid) {
  665.                 return null;
  666.             }
  668.             // Normalize UUID to ASCII format
  669.             return Validator::isBinaryUuid($filesModel->uuid)
  670.                 ? StringUtil::binToUuid($filesModel->uuid)
  671.                 : $filesModel->uuid;
  672.         };
  674.         $fileReferenceData = array_filter([Metadata::VALUE_UUID => $getUuid($this->filesModel)]);
  676.         if (null !== $this->metadata) {
  677.             return $this->metadata->with($fileReferenceData);
  678.         }
  680.         if (null === $this->filesModel) {
  681.             return null;
  682.         }
  684.         // Get fallback locale list or use without fallbacks if explicitly set
  685.         $locales = null !== $this->locale ? [$this->locale] : $this->getFallbackLocaleList();
  686.         $metadata = $this->filesModel->getMetadata(...$locales);
  687.         $overwriteMetadata = $this->overwriteMetadata ? $this->overwriteMetadata->all() : [];
  689.         if (null !== $metadata) {
  690.             return $metadata
  691.                 ->with($fileReferenceData)
  692.                 ->with($overwriteMetadata)
  693.             ;
  694.         }
  696.         // If no metadata can be obtained from the model, we create a container
  697.         // from the default meta fields with empty values instead
  698.         $metaFields = $this->getFilesModelAdapter()->getMetaFields();
  700.         $data = array_merge(
  701.             array_combine($metaFields, array_fill(0, \count($metaFields), '')),
  702.             $fileReferenceData
  703.         );
  705.         return (new Metadata($data))->with($overwriteMetadata);
  706.     }
  708.     /**
  709.      * Defines link attributes on demand.
  710.      */
  711.     private function onDefineLinkAttributes(Figure $result): array
  712.     {
  713.         $linkAttributes = [];
  715.         // Open in a new window if lightbox was requested but is invalid (fullsize)
  716.         if ($this->enableLightbox && !$result->hasLightbox()) {
  717.             $linkAttributes['target'] = '_blank';
  718.         }
  720.         return array_merge($linkAttributes, $this->additionalLinkAttributes);
  721.     }
  723.     /**
  724.      * Defines the lightbox result (if enabled) on demand.
  725.      */
  726.     private function onDefineLightboxResult(Figure $result): ?LightboxResult
  727.     {
  728.         if (!$this->enableLightbox) {
  729.             return null;
  730.         }
  732.         $getMetadataUrl = static function () use ($result): ?string {
  733.             if (!$result->hasMetadata()) {
  734.                 return null;
  735.             }
  737.             return $result->getMetadata()->getUrl() ?: null;
  738.         };
  740.         /**
  741.          * @param ImageInterface|string $target Image object, URL or absolute file path
  742.          */
  743.         $getResourceOrUrl = function ($target): array {
  744.             if ($target instanceof ImageInterface) {
  745.                 return [$target, null];
  746.             }
  748.             $validExtension = \in_array(Path::getExtension($target, true), $this->validExtensions, true);
  749.             $externalUrl = 1 === preg_match('#^https?://#', $target);
  751.             if (!$validExtension) {
  752.                 return [null, null];
  753.             }
  755.             if ($externalUrl) {
  756.                 return [null, $target];
  757.             }
  759.             if (Path::isAbsolute($target)) {
  760.                 $filePath = Path::canonicalize($target);
  761.             } else {
  762.                 // URL relative to the project directory
  763.                 $filePath = Path::makeAbsolute(urldecode($target), $this->projectDir);
  764.             }
  766.             if (!is_file($filePath)) {
  767.                 $filePath = null;
  768.             }
  770.             return [$filePath, null];
  771.         };
  773.         // Use explicitly set href (1) or lightbox resource (2), fall back to using metadata (3) or use the base resource (4) if empty
  774.         $lightboxResourceOrUrl = $this->additionalLinkAttributes['href'] ?? $this->lightboxResourceOrUrl ?? $getMetadataUrl() ?? $this->filePath;
  776.         [$filePathOrImage, $url] = $getResourceOrUrl($lightboxResourceOrUrl);
  778.         if (null === $filePathOrImage && null === $url) {
  779.             return null;
  780.         }
  782.         return $this->locator
  783.             ->get('contao.image.studio')
  784.             ->createLightboxImage(
  785.                 $filePathOrImage,
  786.                 $url,
  787.                 $this->lightboxSizeConfiguration,
  788.                 $this->lightboxGroupIdentifier,
  789.                 $this->lightboxResizeOptions
  790.             )
  791.         ;
  792.     }
  794.     /**
  795.      * @return FilesModel
  796.      *
  797.      * @phpstan-return Adapter<FilesModel>
  798.      */
  799.     private function getFilesModelAdapter(): Adapter
  800.     {
  801.         $framework = $this->locator->get('contao.framework');
  802.         $framework->initialize();
  804.         return $framework->getAdapter(FilesModel::class);
  805.     }
  807.     /**
  808.      * @return Validator
  809.      *
  810.      * @phpstan-return Adapter<Validator>
  811.      */
  812.     private function getValidatorAdapter(): Adapter
  813.     {
  814.         $framework = $this->locator->get('contao.framework');
  815.         $framework->initialize();
  817.         return $framework->getAdapter(Validator::class);
  818.     }
  820.     /**
  821.      * Returns a list of locales (if available) in the following order:
  822.      *  1. language of current page,
  823.      *  2. root page fallback language.
  824.      */
  825.     private function getFallbackLocaleList(): array
  826.     {
  827.         $page = $GLOBALS['objPage'] ?? null;
  829.         if (!$page instanceof PageModel) {
  830.             return [];
  831.         }
  833.         $locales = [LocaleUtil::formatAsLocale($page->language)];
  835.         if (null !== $page->rootFallbackLanguage) {
  836.             $locales[] = LocaleUtil::formatAsLocale($page->rootFallbackLanguage);
  837.         }
  839.         return array_unique(array_filter($locales));
  840.     }
  841. }