linkhandler para TYPO3

linkhandler evita links quebrados quando URLs mudam

No TYPO3, uma indicação Typolink se refere diretamente a uma página, um arquivo ou uma URL, não a um registro. Assim que uma redação quer linkar no texto corrido para eventos, artigos de news, produtos ou endereços, ou precisa inserir a URL fixa, ou ligar uma extensão intermediária que gera uma URL estável a partir de um ID de registro. Essa é exatamente a tarefa do linkhandler. A extensão da Cobwebsters registra novos tipos de link no RTE do TYPO3 e no Link Browser e os conecta a quaisquer tabelas de banco. Em um projeto editorial com mais de cem referências internas, essa é a diferença entre uma arquitetura de conteúdo funcional e uma página cemitério cheia de links 404.

Cenários típicos ocorrem em toda redação com mais de um domínio de conteúdo

Assim que news, eventos e produtos coexistem em um mesmo projeto, os redatores precisam de um sistema de linking limpo. Uma universidade brasileira linka no artigo da revista para o evento em sf_event_mgt, no texto do evento para o autor envolvido de md_news_author e, no perfil do autor, de volta para todos os seus artigos em GeorgRinger/news. Três extensões, três tipos de registro, e sem linkhandler cada uma dessas referências seria uma URL fixa que quebraria no próximo refactoring de slug. No cotidiano, isso significa: um único refactoring de URL pode gerar dezenas ou centenas de broken links, que só aparecem semanas depois no relatório do Google Search Console.

Um segundo cenário são textos de e-commerce: descrições de produto que apontam para acessórios, ou artigos de blog que linkam para produtos do aimeos. O linkhandler gera os URLs automaticamente a partir da configuração de routing do produto, e em um refactoring de categoria todos os links migram junto.

Em terceiro, a necessidade aparece em listagens de localizações. Quem mantém uma estrutura de filiais ou diretórios de contatos com tt_address ou um model próprio quer, a partir de artigos, linkar para a página de detalhe correspondente. O link linkhandler permanece estável mesmo quando a localização é renomeada.

Arquitetura técnica registra link types via YAML e classe handler

O linkhandler usa o mecanismo LinkHandler do core TYPO3, disponível desde a v8. Cada link type é registrado via arquivo YAML no diretório de configuração. O YAML define o identificador do handler, a tabela, o model Extbase e a configuração de routing. No RTE e no Link Browser, o link type aparece como nova aba: “News”, “Evento”, “Produto”, “Endereço”. Cada aba mostra uma lista dos registros disponíveis com função de busca e filtro, para que redatores, mesmo com milhares de entradas de news, encontrem o registro desejado de forma direcionada.

O resolver propriamente dito é uma classe PHP que herda de AbstractLinkHandler e implementa os métodos modifyLinkField e generateRelativeUrl. Os métodos geram a partir do ID do registro uma URL amigável, via site config e router da extensão correspondente. No frontend, o Typolink é chamado com o parâmetro t3://record e resolvido pelo page rendering para a URL final. Isso significa: mesmo que dezenas de milhares de artigos linkem para o mesmo registro de news, em uma mudança de slug basta atualizar o próprio registro do artigo, todos os links se resolvem automaticamente para a nova URL.

A configuração penetra fundo no sistema de linking do TYPO3, mas permanece declarativa: após o registro YAML e o clear cache, o novo link type fica disponível no projeto inteiro, inclusive templates Fluid e componentes de menu. Quem não usa o linkhandler explicitamente também obtém o mecanismo via core linking do TYPO3, mas sem a camada de abstração YAML e sem o UI confortável de picker de registro no backend da extensão.

Problemas frequentes envolvem cache, variantes de idioma e file handlers

O tema de suporte mais frequente são inconsistências de cache após o update de um registro. Quando o slug de um artigo news é ajustado, o page cache do artigo de origem, no qual está o link linkhandler, também precisa ser limpo, caso contrário a URL antiga permanece na saída. A solução é uma cache tag definida junto com o rendering do Typolink. Muitas instalações não ativam isso e depois lutam contra links supostamente quebrados.

O segundo problema são variantes de idioma. Um artigo news em BR aponta via linkhandler para um evento. A tradução em inglês do artigo precisa apontar para o mesmo ID de evento, mas gerar a URL no idioma inglês. O linkhandler oferece essa resolução via Language Aspect, mas a configuração YAML precisa apontar explicitamente para as variantes de routing das páginas-alvo. Quem usa fallback de idioma precisa verificar adicionalmente como o handler se comporta em traduções ausentes, ele deve resolver no idioma de fallback, não cair de volta no idioma principal.

Em terceiro, o file handler é um caso especial. Quem, além de links de registro, também quer linkar para arquivos FAL do TYPO3, precisa configurar o linkhandler file handler separadamente ou recorrer ao File Linker nativo do TYPO3. A combinação é possível, mas a ordem dos handlers no YAML decide qual aba aparece primeiro.

TYPO3 v12 e v13 usam o LinkHandler do core, migração vale a pena

A partir do TYPO3 v11, o LinkHandler do core está pronto para produção e pode assumir muitas tarefas do linkhandler. Ainda assim, a extensão da Cobwebsters continua sendo mantida, porque traz recursos extras de conforto como o editor YAML, o picker de registro aprimorado e saída compatível com schema. Para TYPO3 v12 e v13, existe uma versão atual no TER e no Packagist.

Na revisão de migração, a Gosign verifica quantas chamadas linkhandler estão nos conteúdos do RTE. Com menos de 50 ocorrências, frequentemente vale a pena migrar para o LinkHandler do core; com mais de 100 ocorrências ou handlers muito customizados, o linkhandler continua sendo a escolha mais pragmática. A migração para uma nova major version costuma rodar sem alterações de conteúdo, porque a sintaxe t3://record no conteúdo permanece estável. Para a análise, usamos um scan sobre os campos tt_content que discrimina todos os tipos de link e gera uma recomendação por instalação.