Virtual filesystem

class Example {
    public function __construct(private VirtualFilesystemInterface $documentsStorage) {}
}

<?php
// src/App/Controller/FilesListController.php
namespace App\Controller;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\File\Metadata;
use Contao\CoreBundle\Filesystem\VirtualFilesystemInterface;
use Contao\CoreBundle\ServiceAnnotation\ContentElement;
use Contao\Template;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

/**
 * @ContentElement(category="files")
 */
class FilesListController extends AbstractContentElementController
{
    private VirtualFilesystemInterface $filesStorage;
    
    // We inject the 'files' virtual filesystem instance, that is scoped to the
    // 'files' directory.
    public function __construct(VirtualFilesystemInterface $filesStorage) 
    {
        $this->filesStorage = $filesStorage; 
    }

    protected function getResponse(Template $template, ContentModel $model, Request $request): Response
    {
        $template->elements = $this->describeDirectory('images');

        return $template->getResponse();
    }

    /** 
     * @return array<string> 
     */
    private function describeDirectory(string $directory): array {
        // Check if the directory exists
        if(!$this->filesStorage->directoryExists($directory)) {
            return [];
        }

        $files = [];

        // Read the contents of the directory. As we're only interested in
        // files, we add the "->files()" filter.
        foreach($this->filesStorage->listContents($directory)->files() as $item) {
            // The full path and filesize in kB
            $name = $item->getPath();
            $size = $item->getFileSize() / 1000;

            // Read the "extra metadata" - let's use the title as the
            // name instead if one one was defined in the metadata array.
            $fileMetadata = $item->getExtraMetadata()['metadata']['en'] ?? null;

            if($fileMetadata instanceof Metadata && ($title = $fileMetadata->getTitle()) !== '') {
                $name = "'$title' ($name)";
            }

            $files[] = "$name has a size of {$size}kB.";
        }

        return $files;
    }
}

<?php
// src/App/Controller/FilesListController.php
namespace App\Controller;

use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsContentElement;
use Contao\CoreBundle\File\Metadata;
use Contao\CoreBundle\Filesystem\VirtualFilesystemInterface;
use Contao\Template;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsContentElement(category: 'files')]
class FilesListController extends AbstractContentElementController
{
    // We inject the 'files' virtual filesystem instance, that is scoped to the
    // 'files' directory.
    public function __construct(private VirtualFilesystemInterface $filesStorage) {}

    protected function getResponse(Template $template, ContentModel $model, Request $request): Response
    {
        $template->elements = $this->describeDirectory('images');

        return $template->getResponse();
    }

    /** 
     * @return array<string> 
     */
    private function describeDirectory(string $directory): array {
        // Check if the directory exists
        if(!$this->filesStorage->directoryExists($directory)) {
            return [];
        }

        $files = [];

        // Read the contents of the directory. As we're only interested in
        // files, we add the "->files()" filter.
        foreach($this->filesStorage->listContents($directory)->files() as $item) {
            // The full path and filesize in kB
            $name = $item->getPath();
            $size = $item->getFileSize() / 1000;

            // Read the "extra metadata" - let's use the title as the
            // name instead if one one was defined in the metadata array.
            $fileMetadata = $item->getExtraMetadata()['metadata']['en'] ?? null;

            if($fileMetadata instanceof Metadata && ($title = $fileMetadata->getTitle()) !== '') {
                $name = "'$title' ($name)";
            }

            $files[] = "$name has a size of {$size}kB.";
        }

        return $files;
    }
}

{# templates/ce_files_list.html.twig #}

<ul>
  {% for element in elements %}<li>{{ element }}</li>
</ul>

use Symfony\Component\Uid\Uuid;

// by path
$fooStorage->read('my/file.txt');

// by UUID
$fooStorage->read(new Uuid('94cc007c-8cc0-11ec-a8a3-0242ac120002'));