README

License: GNU GPL, Version 2

Repository: https://gitlab.sgalinski.de/typo3/sg_routes

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_routes

Overview

With this extension you can simply create and manage URL redirects for your page and generate redirect rules for your .htaccess file.

Requirements

• TYPO3 ^13.4
• PHP 8.3 or 8.4

Installation

Install the extension via Composer:

composer require sgalinski/sg-routes

Then install/activate the extension in TYPO3 and run database migrations in the Install Tool.

Configuration

Domain setup (required)

sg_routes is a multi-domain extension so before you use the configuration module, make sure that all the domains in your installation have correctly configured domain records for their site-root page.

You can find more information here.

Scheduler setup

Depending on traffic, route hit/log data can grow quickly. Configure TYPO3 Scheduler cleanup tasks and run them periodically.

The Backend Module

After a successful installation, you have a new module in the WEB section of your TYPO3 backend.

Clicking on it loads the administration panel. Using the drop-down above you can switch between the Redirect Management and Redirect Log views.

The Redirect Management view

Here, all your custom URL routes are listed. The list can be filtered by Categories and search words. You can also create, update and delete your routes and categories.

For multi-domain TYPO3 sites, the backend module also supports site/domain scoping:

• This site
• This site + global redirects
• Only global redirects
• All redirects

The optional domain dropdown narrows the result to one concrete configured host of the selected TYPO3 site. Configured environment variants are treated as part of the same site by default.

Note: To create a route/category, you need to first select a page in the page tree.

The Redirect Log view

In this view, you can find logs of when your route records were used to redirect the users of your website, and also the time it took for each redirect to execute (in seconds).

The log view supports the same site/domain scoping as the redirect management view:

• This site
• This site + global redirects
• Only global redirects
• All redirects

Note: Depending on how often redirects are triggered, route hit/log tables can get large. Configure scheduler cleanup tasks and make sure they are executed periodically. You can find setup details for TYPO3 scheduler cron jobs in the official documentation.

For large tx_sgroutes_domain_model_log tables, make sure the latest database schema is applied so the backend log module can use the composite pid, crdate and pid, source_host, crdate indexes for its paginated newest-first listing. The backend log list keeps the familiar pagination UI, but the exact total count is cached per storage page and active scope/domain filter combination so large installations do not pay a full-table count penalty on every request. The log rows themselves are still fetched live from the database on every request, so newly written entries show up in realtime. Only the informational pagination values (total items and derived last page) can lag behind for up to five minutes.

Usage

Creating a redirect rule

In your backend module, click on the "Create" button. Now enter from which url(Source URL) you want to redirect to (Destination URL) and whether you want it to be a permanent (301) or a temporary redirect (302).

Example: You want to redirect temporarily from your starting page to the contact page

Source URL : /

Destination : /contact

Redirect Code: 302

Description: Here you can add a custom description for your rule, visible in the backend overview

When creating/editing a rule, you have also the option to Use regular expression. By checking this, the Source URL is evaluated as a regular expression and is matched against the request url. If a match is found and, the rule is applied with a rewrite based on the Destination URL.

Example: You want to redirect permanently from your /news/... pages to /blog/...

Source URL : ^/news/(.+?)$

Destination : /blog/$1

Redirect Code: 301

Note: The rules are evaluated in the order you see them in the BE module list. Take this into account when creating new rules, and that you can adust the order of the rules by using the , , buttons

Options for your redirect rule

After you created one or more redirect rules, you get a list overview in your backend module of all rules.

You can click on a rule to edit it or use the menu buttons:

Edit
Disable/Enable
Delete
.... Expand/Collapse the options menu
Show further information
Show history
Versioning
Create new
Move up
Move down
Copy
Cut
Paste after

Export your redirect rule(s) to your .htaccess file

It is a good practice to insert your redirect routes into your .htaccess file for better performance.

Simply click the " Export .htaccess" button and copy & paste the textarea content into your .htaccess file.

If all works, you can now delete your routes with the " Delete all" Button.

Note: Be aware that the "Export .htaccess" and "Delete all" actions respect the current filter options. Only the rules visible in the paginated list are taken into account.

Import redirects (CSV / .htaccess)

The redirect list includes an Import Redirects button (right before Export Redirects (CSV)).

Current implementation validates redirect payloads before persistence and imports them with predictable behavior:

• Supported inputs:
  • CSV file upload
  • CSV text paste
  • .htaccess file upload
  • .htaccess text paste
• Input priority is top-to-bottom in the form (higher input wins, lower inputs are ignored).
• CSV supports:
  • advanced header-based format (source_path, target, optional fields)
  • simple 2/3-column customer CSV variants (with or without header)
• .htaccess supports common Redirect and redirecting RewriteRule lines.
• Validation runs before persistence and shows detailed line-level errors in the backend.
• Default behavior remains atomic (no import if errors exist), but the error result offers Ignore Errors and Import Valid Rows to skip invalid lines and import only valid rows.
• Every import run uses an automatic daily category:
  • title format: Import YYYY-MM-DD
  • existing category for today is reused, otherwise created automatically
  • the import category is assigned to every imported redirect
• CSV categories tokens are merged into the assignment:
  • numeric tokens are treated as category UIDs and must already exist
  • existing category titles are reused
  • unknown category titles are created automatically
• Input must be UTF-8 encoded (UTF-8 BOM is tolerated). Other encodings are rejected.

Testing

Run checks from the project root:

composer ecs vendor/sgalinski/sg-routes
composer phpstan vendor/sgalinski/sg-routes
composer phpunit vendor/sgalinski/sg-routes

You can also run PHPUnit directly with the extension config:

vendor/bin/phpunit -c vendor/sgalinski/sg-routes/phpunit.xml.dist

Changelog and Upgrade Notes

Breaking changes are documented in UPGRADE.md.

Developer Guide

TYPO3 Bootstrap Hook

To have the best Performance, this extension hooks into the TYPO3 bootstrap mechanism as early as possible, after the domain root-page is identified.

This is done inside the ext_localconf.php with a configuration array by supplying a path to the desired hook function SGalinski\SgRoutes\Service\RoutingService->hook. By extending or replacing this function, it is possible to implement more complex redirect / rewrite rules.

You can find more information on hooks in the TYPO3 Documentation.

FAQ

Why should I put my redirect rules into the .htaccess file?

You get a slightly better performance for your website by doing this.

I get the error "Too many redirects" when trying to open my website

You are most likely stuck in a redirect loop. Backup your routes by copying up your .htaccess entries and reset all your changes. Try to determine if you have created an endless loop with your routes, for instance:

/home redirects to /contact
/contact redirects to /support
/support redirects to /home