{"id":76,"date":"2026-10-21T17:00:00","date_gmt":"2026-10-21T15:00:00","guid":{"rendered":"https:\/\/hoja.in\/blog\/replacing-realurl-with-site-configuration-slugs-and-redirects\/"},"modified":"2026-10-16T14:00:12","modified_gmt":"2026-10-16T12:00:12","slug":"replacing-realurl-with-site-configuration-slugs-and-redirects","status":"publish","type":"post","link":"https:\/\/hoja.in\/blog\/replacing-realurl-with-site-configuration-slugs-and-redirects\/","title":{"rendered":"Replacing realurl with site configuration, slugs and redirects"},"content":{"rendered":"

Hi folks,<\/p>\n

When I moved my own site hoja.in from TYPO3 7.6 to a fresh TYPO3 14.3 project this year, one extension worried me more than the others: realurl. For years it built every speaking URL of the site. In TYPO3 14 it simply does not exist, and since 9.5 the core has its own routing with site configuration and page slugs. The code part of the move is easy. The scary part is the URLs that Google, old emails and other people’s bookmarks still point to. They must not break.<\/p>\n

In this post I show what I did: read what realurl really produced, let the core generate slugs, keep the old paths alive with redirects, and check the status codes with curl instead of trusting my eyes.<\/p>\n

Problems I faced<\/h2>\n

realurl had a habit of hiding its decisions. Mine used realurl_autoconf.php<\/code>, the file realurl writes itself, so nobody had looked at it for years. Before deleting anything I opened it from the legacy copy:<\/p>\n

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['realurl'] = [\n    'hoja.in' => [\n        'init' => [\n            'appendMissingSlash' => 'ifNotFile,redirect',\n            'emptyUrlReturnValue' => '\/',\n        ],\n        'pagePath' => ['rootpage_id' => '6'],\n        'fileName' => [\n            'defaultToHTMLsuffixOnPrev' => 0,\n            'acceptHTMLsuffix' => 1,\n        ],\n    ],\n];<\/code><\/pre>\n
Three facts came out of it. The root page was uid 6. URLs ended with a slash, like \/about\/<\/code>. And realurl also accepted<\/em> \/about.html<\/code>, even if it never generated it. So the new site has to answer for three shapes of the same page.<\/p>\n
Step 1: the site configuration<\/h2>\n
In TYPO3 14 the site lives in config\/sites\/main\/config.yaml<\/code>. For hoja.in it is short, because the site is one language and has no plugins with URL parameters:<\/p>\n
rootPageId: 6\nbase: 'https:\/\/hoja.in\/'\nbaseVariants:\n  -\n    base: 'https:\/\/myport.ddev.site\/'\n    condition: 'applicationContext == \"Development\/Ddev\"'\nwebsiteTitle: 'hoja.in'\ndependencies:\n  - harvisoft\/sitepackage\nlanguages:\n  -\n    title: English\n    enabled: true\n    languageId: 0\n    base: \/\n    locale: en_US.UTF-8\n    hreflang: en-US<\/code><\/pre>\n
The baseVariants<\/code> entry is what lets the same file work in DDEV and on the server. No route enhancers are needed here. If your old realurl config appended .html<\/code> to every page and you want to keep that, the core has the PageType<\/code> decorator for it:<\/p>\n
routeEnhancers:\n  PageTypeSuffix:\n    type: PageType\n    default: '.html'\n    map:\n      '.html': 0<\/code><\/pre>\n
I did not use it. Keeping a suffix forever only to match an old extension felt wrong when the old site itself did not generate it.<\/p>\n
Step 2: generate the slugs like the backend does<\/h2>\n
The content came over with an import script, not with the seven-hop upgrade chain, so the pages.slug<\/code> field started empty. I did not want to invent slugs by hand. TYPO3 has SlugHelper<\/code>, which is the same class the backend uses when an editor saves a page. The import script calls it for every page and then makes the result unique inside the site:<\/p>\n
$slugHelper = GeneralUtility::makeInstance(\n    SlugHelper::class,\n    'pages',\n    'slug',\n    $GLOBALS['TCA']['pages']['columns']['slug']['config']\n);\nforeach ($pageUids as $uid) {\n    $record = BackendUtility::getRecord('pages', $uid);\n    $slug = $uid === ROOT_PAGE ? '\/' : $slugHelper->generate($record, (int)$record['pid']);\n    $state = RecordStateFactory::forName('pages')\n        ->fromArray($record, (int)$record['pid'], $uid);\n    $slug = $slugHelper->buildSlugForUniqueInSite($slug, $state);\n    $connection->update('pages', ['slug' => $slug], ['uid' => $uid]);\n}<\/code><\/pre>\n
The real script fetches the record with a QueryBuilder without restrictions, because hidden pages need slugs too, but the idea is the same. Because the slug config uses the page title, “About” became \/about<\/code>, which is exactly the old path without the slash. Lucky me.<\/p>\n
Step 3: redirects for everything else<\/h2>\n
EXT:redirects stores redirects in the table sys_redirect<\/code>, and its middleware runs before the page is resolved. That means a redirect wins even if a page with the same path exists. For a handful of URLs you can use the Redirects backend module. For a list from an old sitemap or a log file, I prefer a small command, so the mapping lives in a CSV file in git and can be reviewed.<\/p>\n
<?php\n\ndeclare(strict_types=1);\n\nnamespace HarvisoftSitepackageCommand;\n\nuse SymfonyComponentConsoleAttributeAsCommand;\nuse SymfonyComponentConsoleCommandCommand;\nuse SymfonyComponentConsoleInputInputArgument;\nuse SymfonyComponentConsoleInputInputInterface;\nuse SymfonyComponentConsoleOutputOutputInterface;\nuse TYPO3CMSCoreDatabaseConnectionPool;\nuse TYPO3CMSRedirectsServiceRedirectCacheService;\n\n#[AsCommand('sitepackage:redirects:import', 'Creates 301 redirects from a CSV file: old path, page uid')]\nfinal class ImportRedirectsCommand extends Command\n{\n    public function __construct(\n        private readonly ConnectionPool $connectionPool,\n        private readonly RedirectCacheService $redirectCacheService,\n    ) {\n        parent::__construct();\n    }\n\n    protected function configure(): void\n    {\n        $this->addArgument('file', InputArgument::REQUIRED, 'CSV file');\n        $this->addArgument('host', InputArgument::OPTIONAL, 'Source host', '*');\n    }\n\n    protected function execute(InputInterface $input, OutputInterface $output): int\n    {\n        $connection = $this->connectionPool->getConnectionForTable('sys_redirect');\n        $host = (string)$input->getArgument('host');\n        $created = 0;\n\n        $file = new SplFileObject((string)$input->getArgument('file'));\n        $file->setFlags(SplFileObject::READ_CSV | SplFileObject::SKIP_EMPTY | SplFileObject::READ_AHEAD);\n        $file->setCsvControl(',', '\"', '');\n\n        foreach ($file as $row) {\n            [$path, $pageUid] = array_map('trim', $row) + [1 => ''];\n            if ($path === '' || str_starts_with($path, '#') || (int)$pageUid === 0) {\n                continue;\n            }\n            $exists = $connection->count('uid', 'sys_redirect', [\n                'source_host' => $host,\n                'source_path' => $path,\n                'deleted' => 0,\n            ]);\n            if ($exists > 0) {\n                continue;\n            }\n            $connection->insert('sys_redirect', [\n                'pid' => 0,\n                'createdon' => time(),\n                'updatedon' => time(),\n                'source_host' => $host,\n                'source_path' => $path,\n                'target' => 't3:\/\/page?uid=' . (int)$pageUid,\n                'target_statuscode' => 301,\n                'force_https' => 1,\n            ]);\n            $created++;\n        }\n\n        \/\/ Redirects are cached per host; rows inserted by SQL are not seen until the cache is rebuilt\n        $this->redirectCacheService->rebuildForHost($host);\n        $output->writeln(sprintf('%d redirects created.', $created));\n\n        return Command::SUCCESS;\n    }\n}<\/code><\/pre>\n
Two details matter. The target is a t3:\/\/page<\/code> link, so the redirect still works when somebody renames the page later. And the redirect cache must be rebuilt, otherwise you insert rows and wonder why nothing happens. The command is registered by its #[AsCommand]<\/code> attribute as long as the extension has the usual Configuration\/Services.yaml<\/code> with autowire<\/code> and autoconfigure<\/code> enabled.<\/p>\n
The CSV is boring on purpose:<\/p>\n
# old path, page uid\n\/about.html,7\n\/resume.html,10\n\/contact.html,13<\/code><\/pre>\n
ddev exec vendor\/bin\/typo3 sitepackage:redirects:import redirects.csv<\/code><\/pre>\n
Run it against a copy with a fresh dump first. Writing to the database is the one step git cannot undo.<\/p>\n
Step 4: check status codes, not screenshots<\/h2>\n
A page that “looks fine” in the browser can still be a 404 with a nice error page, or a 302 where you wanted a 301. So I ask curl:<\/p>\n
for path in \/about \/about\/ \/about.html \/contact\/ '\/index.php?id=7'; do\n  printf '%-18s ' \"$path\"\n  curl -sk -o \/dev\/null -w '%{http_code} %{redirect_url}n' \"https:\/\/myport.ddev.site$path\"\ndone<\/code><\/pre>\n
Before the redirects, my local copy answered like this: \/about<\/code>, \/about\/<\/code>, \/contact\/<\/code> and \/index.php?id=7<\/code> with 200, and \/about.html<\/code> with 404. The trailing slash version still resolves, so the old realurl links keep working, and the canonical tag tells search engines which URL counts (on hoja.in the section pages even point to the one-page root, because that is where their content is shown). The .html<\/code> variant is honestly still open on my list: realurl accepted it, but I have no proof anybody ever linked to it. The CSV above is ready for the day the server log shows those requests.<\/p>\n
The bigger check was the smoke test. Before touching anything, I captured status code, size and title of the old 7.6 site’s URLs as a baseline, and after the move the same URLs were compared against it. All of them answered 200 with the expected titles. That baseline gave me more peace of mind than any amount of clicking.<\/p>\n
What I would do again<\/h2>\n