TYPO3 Extbase模型中FileReference始终为Null的问题排查

问题描述 #

按照TYPO3官方文档实现文件上传功能后，在视图或PHP代码中访问模型的singleFile属性始终为Null，multipleFiles为空集合。但后端能正常显示这两个字段的FileReference，数据库存储的数据也无异常。

环境信息 #

• PHP版本：8.2.26
• TYPO3版本：13.4.2

相关代码 #

Model #

class Blog extends AbstractEntity
{
    // A single file
    protected ?FileReference $singleFile = null;

    /**
     * A collection of files.
     * @var ObjectStorage<FileReference>
     */
    protected ObjectStorage $multipleFiles;

    // When using ObjectStorages, it is vital to initialize these.
    public function __construct()
    {
        $this->multipleFiles = new ObjectStorage();
    }

    /**
     * Called again with initialize object, as fetching an entity from the DB does not use the constructor
     */
    public function initializeObject(): void
    {
        $this->multipleFiles = $this->multipleFiles ?? new ObjectStorage();
    }

    // Typical getters
    public function getSingleFile(): ?FileReference
    {
        return $this->singleFile;
    }

    /**
     * @return ObjectStorage|FileReference[]
     */
    public function getMultipleFiles(): ObjectStorage
    {
        return $this->multipleFiles;
    }

    // For later examples, the setters:
    public function setSingleFile(?FileReference $singleFile): void
    {
        $this->singleFile = $singleFile;
    }

    public function setMultipleFiles(ObjectStorage $files): void
    {
        $this->multipleFiles = $files;
    }
}

TCA #

<?php

return [
    'ctrl' => [
      'title' => 'Blog',
      'label' => 'uid',
      'iconfile' => 'EXT:myext/Resources/Public/Icons/bx-book-alt.svg',
    ],
    'types' => [
      0 => [
        'showitem' => '
          singleFile,multipleFiles
        ',
      ],
    ],
    'columns' => [
        'singleFile' => [
            'exclude' => true,
            'label' => 'Single file',
            'config' => [
                'type' => 'file',
                'maxitems' => 1,
                'allowed' => 'common-image-types',
            ],
        ],
        'multipleFiles' => [
            'exclude' => true,
            'label' => 'Multiple files',
            'config' => [
                'type' => 'file',
                'allowed' => 'common-image-types',
            ],
        ],
    ],
];

ext_localconf.php #

ExtensionUtility::configurePlugin(
    // extension name, matching the PHP namespaces (but without the vendor)
    'MyExt',
    // arbitrary, but unique plugin name (not visible in the backend)
    'Blog',
    // all actions
    [BlogController::class => 'show'],
    // non-cacheable actions
    [BlogController::class => 'show'],
    ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT,
);

Controller #

class BlogController extends ActionController
{
    public function __construct(protected readonly BlogRepository $blogRepository)
    {
      // Note: The repository is a standard extbase repository, nothing specific
      //       to this example.
    }

    public function showAction(): ResponseInterface
    {
      $blog = $this->blogRepository->findAll()[0];
      $this->view->assign('blog', $blog);

      return $this->htmlResponse();
    }
}

解决方案 #

1. 添加Extbase属性映射配置 #

在你的扩展的ext_typoscript_setup.typoscript文件中添加以下配置，明确字段与模型属性的映射关系：

config.tx_extbase.persistence.classes {
    Vendor\MyExt\Domain\Model\Blog {
        mapping {
            columns {
                singleFile.mapOnProperty = singleFile
                multipleFiles.mapOnProperty = multipleFiles
            }
        }
    }
}

注意：将Vendor\MyExt替换为你实际的命名空间。

2. 修正TCA文件字段配置 #

TYPO3 13中使用type='file'字段时，必须指定关联的系统表和匹配条件。修改TCA的columns部分：

'singleFile' => [
    'exclude' => true,
    'label' => 'Single file',
    'config' => [
        'type' => 'file',
        'maxitems' => 1,
        'allowed' => 'common-image-types',
        'foreign_table' => 'sys_file_reference',
        'foreign_match_fields' => [
            'fieldname' => 'singleFile',
            'tablenames' => 'tx_myext_domain_model_blog', // 替换为你的实际表名
            'table_local' => 'sys_file',
        ],
    ],
],
'multipleFiles' => [
    'exclude' => true,
    'label' => 'Multiple files',
    'config' => [
        'type' => 'file',
        'allowed' => 'common-image-types',
        'foreign_table' => 'sys_file_reference',
        'foreign_match_fields' => [
            'fieldname' => 'multipleFiles',
            'tablenames' => 'tx_myext_domain_model_blog', // 替换为你的实际表名
            'table_local' => 'sys_file',
        ],
    ],
],

注意：tablenames必须与Blog模型对应的数据库表名一致（格式通常为tx_扩展名_domain_model_模型名）。

3. 确认模型命名空间引入 #

确保模型文件顶部正确引入了所需的类：

use TYPO3\CMS\Core\Resource\FileReference;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;

4. 清除所有缓存 #

修改配置后，必须通过TYPO3后端的"清除全部缓存"按钮清除所有缓存，包括配置缓存和Extbase相关缓存，确保新配置生效。

内容的提问来源于stack exchange，提问作者Doku