asconsulting/contao-zyppy-redirect

Back end crafted URL redirects for Contao 5.3+, with per-rule control over when in the request lifecycle a rule is allowed to fire.

Replaces asconsulting/redirect_manager, whose rules could only ever run on the 404 page. Existing rules import automatically — see Migration from legacy version below.

Requirements

Installation

composer require asconsulting/contao-zyppy-redirect:^5.0

Then run the database migration. Contao Manager does this on install and on update; on the command line it is vendor/bin/contao-console contao:migrate. It creates the tl_zyppy_redirect table and, if the old redirect_manager table is present, imports its rules.

Usage

Creating a rule

Open Design > Redirects and add a rule. Only back end administrators see the module — see Permissions below.

Field Meaning
Category An arbitrary label for grouping. Searchable and filterable.
Precedence Lower numbers are checked first when more than one rule matches the same URL.
Execution tier Passive or First order — see The two execution tiers.
Match mode How the incoming URL is compared with the source — see Match modes.
Source The path to match, e.g. /old-page. In domain mode, the hostname to match. Include a query string only if the rule should match that query string alone.
Restrict to host Apply the rule on this domain only. Empty applies it on every domain.
Target type URL, Contao page, File, or Another host, same path.
Target URL / page / file / host The destination, according to the target type. In regex mode, $1 … $n in a target URL insert the captured groups.
HTTP status code 301, 302, 303, 307 or 308.
Publish rule, Show from, Show until Enable the rule, optionally for a date range.

The two execution tiers

Every rule carries a tier, and this is the feature the old module did not have.

Tier Fires Use it when
Passive (default) Only after every Contao page, route and file has failed to resolve — i.e. at the 404 The URL is genuinely gone. This is the safe default and what you want almost every time
First order Before Contao routes the request You need to override a page that still exists — retiring a live section, forcing a canonical domain, moving a URL whose old page has not been deleted yet

A first-order rule wins against a real Contao page. That is the point of it, and also the reason the default is passive: a rule created without thinking cannot take a live page offline.

Out of scope: anything above Contao at the host level. A physical index.html in the document root is served by the web server before PHP runs, and nothing in this bundle can override it.

Paths no rule can redirect

Both tiers refuse to act on a short list of prefixes, matched on a path segment boundary — so /contaoshop is redirectable while /contao/… is not. A rule pointed at one of these is stored and shown in the back end but will never fire, which is the one case where a rule can look correct and do nothing.

Prefix Why
/contao, /_contao The back end, and Contao's front end controller routes. A first-order rule here would lock you out of the site that defines the rule
/_wdt, /_profiler, /_fragment Symfony's profiler, toolbar and fragment handler
/assets contao_images generates images on the fly at /assets/images/{path}
/bundles, /files, /system Asset namespaces. A redirect aimed into one is far more likely to be a mistake than an intent, so they are excluded deliberately

/share is not on this list, despite Contao's installer creating a public/share directory. The real share route is /_contao/share, already covered above, so a page at /share is ordinary site space and stays redirectable.

Match modes

Mode Matches Notes
Exact path /old-page One indexed lookup. Stays fast on a table with hundreds of thousands of rows
Path prefix /old and everything under /old/ Does not match /older. The unmatched tail is appended to a URL or host target
Regular expression Whatever the pattern matches Include delimiters: #^/news/(\d+)$#. $1 … $n insert captured groups into the target URL
Domain The whole hostname source holds the host to match. The incoming path is carried across unchanged

Query strings

A rule stored as /old-page matches whatever the query string is, and the incoming query is forwarded onto the target.

Note that Contao itself strips tracking parameters — utm_*, gclid, fbclid, msclkid and similar — at its HTTP cache layer, before any application code runs. Those never reach a redirect rule and so are not forwarded. That is core behaviour, not something this bundle does. A rule stored as /old-page?id=7 matches only that exact query, and does not forward it again. If the target already carries its own query string, the target's wins.

Performance

The bundle is built for installations with very large redirect tables.

The HTTP cache caveat — read this one

Contao's HTTP cache serves a page without running PHP. Neither listener fires for a URL that is already in the cache, so a first order rule added for an existing page does not take effect until that cache entry is invalidated.

This looks fine on a development site, where the cache is usually cold, and does not work in production. After adding a first-order rule for a URL that already resolves, invalidate the cache.

Redirect responses themselves are sent with no-store, so the redirect never becomes a cached page in its own right.

Permissions

tl_zyppy_redirect is restricted to back end administrators by a data container voter.

This is deliberate rather than conservative: a user who can create a redirect can point any URL on the site — its home page included, at the first-order tier — at an arbitrary external target. That is a site-defacement capability, so it is not grantable through tl_user_group.

Migration from legacy version

This bundle replaces asconsulting/redirect_manager. Install this bundle and run contao:migrate. Rules in tl_asc_redirect are copied into tl_zyppy_redirect automatically.

After importing, the redirect_404 front end module can be removed from your 404 page and the old bundle uninstalled.

Development

composer install
vendor/bin/phpunit --no-coverage

TODO.md records the test matrix run and what remains open.

Licence

Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE. Copyright Andrew Stevens.

Downloads

VersionReleasedFile
5.0.1contao-zyppy-redirect-5.0.1.zip 93 KB
5.0.0contao-zyppy-redirect-5.0.0.zip 92 KB