TYPO3 v12：URL参数触发控制器动作及URL缩短问题

问题背景 #

正在将一个展示已发送新闻通讯列表的旧插件适配到TYPO3 v12，列表视图正常，但详情页无法触发showAction。新闻通讯内容存储在tt_content表中，UID为内容ID。

当前链接格式 #

/detail?tx_newsletter%5Baction%5D=show&tx_newsletter%5Bcontroller%5D=NewsletterArchive&tx_newsletter%5Buid%5D=2195&cHash=5094bebe868a51e8e17afb0b9629ddc2

生成链接的代码 #

public function buildUrlByUidAction($uid) {
    $url = $this->uriBuilder
        ->reset()
        ->setTargetPageUid($this->settings['singlePid'])
        ->setCreateAbsoluteUri(true)
        ->uriFor(
            'show',
            [
                'uid' => $uid,
            ],
            'NewsletterArchive',
            'NL',
            'NewsletterArchiveList'
        );
    return $url;
}

详情页处理代码 #

public function showAction($uid): ResponseInterface {
    $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
    ->getQueryBuilderForTable('tt_content');
    $rows = $queryBuilder
        ->select('*')
        ->from('tt_content')
        ->where($queryBuilder->expr()
            ->eq('uid', $queryBuilder->createNamedParameter($uid, \PDO::PARAM_INT)))
        ->executeQuery()
        ->fetchAll();
    $row = NULL;
    if (count($rows)) {
        $row = $rows[0];

        $content = $row['bodytext'];

        $content = $this->cleanHtml($content);
        libxml_use_internal_errors(true);
        $x = new \DOMDocument;
        $x->loadHTML(mb_convert_encoding($content, 'HTML-ENTITIES', 'UTF-8'));
        $element = $x->getElementsByTagName('body')->item(0);
        $newdoc = new \DOMDocument();
        $cloned = $element->cloneNode(TRUE);
        $newdoc->appendChild($newdoc->importNode($cloned, TRUE));
        $content = $newdoc->saveHTML();
        $content = $this->cleanHtml($content);

        $row['bodytext'] = $content;
    }
    $this->view->assign('row', $row);
    return $this->htmlResponse();
}

Typoscript配置 #

lib.newsletterDetail >
lib.newsletterDetail = USER
lib.newsletterDetail {
  userFunc = TYPO3\CMS\Extbase\Core\Bootstrap->run
  extensionName = NL
  pluginName = NewsletterArchiveList
  vendorName = Cawd
  controller = NewsletterArchive
  action = show
  switchableControllerActions {
    NewsletterArchive {
      1 = show
    }
  }
  view < plugin.tx_tmpl.view
  persistence < plugin.tx_tmpl.persistence
  settings < plugin.tx_tmpl.settings
}

问题排查尝试 #

已尝试修改函数名称、在showAction开头输出内容，但均无法触发该函数，同时希望缩短当前URL。

解决方案 #

一、修复showAction不触发的问题 #

1. 参数前缀不匹配：
   当前链接中的参数前缀是tx_newsletter，但根据Typoscript配置的extensionName=NL和pluginName=NewsletterArchiveList，正确的参数前缀应为tx_nl_newsletterarchivelist，这是路由无法匹配控制器动作的核心原因。

   • 检查插件注册代码（ext_localconf.php或ext_tables.php），确保插件注册的key与Typoscript一致：

     \TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerPlugin(
         'NL',
         'NewsletterArchiveList',
         'Newsletter Archive List'
     );
     

   • 若注册正确，uriBuilder生成的链接参数前缀会自动匹配，若仍异常可清除TYPO3缓存。

2. 页面配置检查：
   确保singlePid对应的详情页中，已正确包含lib.newsletterDetail对象，或直接使用插件内容元素渲染详情页，Extbase路由会更稳定。

3. 调试路由匹配：
   开启TYPO3调试模式，查看系统日志中的路由匹配信息，确认请求是否被正确路由到目标控制器动作。

二、缩短URL的方法 #

使用TYPO3的路由增强（Route Enhancers），在站点配置文件（config.yaml）中添加规则，将参数化URL转换为友好URL：

routeEnhancers:
  NewsletterArchivePlugin:
    type: Extbase
    limitToPages: [123] # 替换为你的详情页PID
    extension: NL
    plugin: NewsletterArchiveList
    routes:
      - routePath: '/detail/{uid}'
        _controller: 'NewsletterArchive::show'
        _arguments:
          uid: uid
    defaultController: 'NewsletterArchive::show'
    requirements:
      uid: '\d+'

配置完成后，uriBuilder会自动生成类似/detail/2195的短URL，同时请求可正确路由到showAction。

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