Using Retour

Retour Statistics

Retour keeps track of every 404 your site receives. You can view them by clicking on Retour->Dashboard.

Screenshot

If you’re using Craft to host multiple sites you can view the statistics for All Sites or an individual site using the Sites menu at the top of the page.

You can sort by any column by clicking on the column name, and you can filter the results by typing in the Search for: field.

Only one record is saved per URL Pattern, so the database won’t get clogged with a ton of records.

The charts show you how many directs happened during the last month, week, and day, including how many were handled by Retour.

The Handled column will display an if the last 404 hit to this URL was handled by Retour, and an x if it was not.

Clicking on the + next to an unhandled 404 will create a new Static Redirect with the 404’s URL set as the source.

Screenshot

Hovering over the 404 File Not Found URL will give you more detailed information on the 404 that occurred.

Exporting Statistics to a CSV File

The Export CSV File button on the Retour->Statistics page allows you to export all of your statistics to a CSV file for external processing or archival purposes.

Retour Widget

If you’d like to see an overview of the Retour Statistics in your dashboard, you can add a Retour widget to your Dashboard:

Screenshot

It displays the total number of handled and not handled 404s, and the 5 most recent 404 URLs in each category right in your dashboard.

GraphQL Query support

Resolving Redirects

To retrieve Retour redirect data through the native GraphQL in Craft CMS 3.3 or the CraftQL plugin, use the retourResolveRedirect field in your GraphQL query.

This is useful if your site is a SPA, and Craft is running "headless", but you still want to give your content authors a way to deal with 404s.

You must at least pass in the URI you want metadata for:

{
    retourResolveRedirect(uri: "/stuff") {
    redirectDestUrl
  }
}

...and you can also pass in an optional siteId:

{
    retourResolveRedirect(uri: "/stuff", siteId: 1) {
    redirectDestUrl
  }
}

Whenever you query Retour via GraphQL, it assumes a 404 has already taken place, and records the statistics for it.

If no redirect can be found to handle the 404, null is returned:

{
  "data": {
    "retourResolveRedirect": null
  }
}

Otherwise, the requested data will be returned:

{
  "data": {
    "retourResolveRedirect": {
      "redirectDestUrl": "/c3"
    }
  }
}

Screenshot

Most of the time, the only thing you’ll care about is the redirectDestUrl, which is the route that the user should be redirected to. However, you can query for everything:

{
    retourResolveRedirect(uri: "/stuff") {
    id
    siteId
    associatedElementId
    enabled
    redirectSrcUrl
    redirectSrcUrlParsed
    redirectSrcMatch
    redirectMatchType
    redirectDestUrl
    redirectHttpCode
    hitCount
    hitLastTime
  }
}

...which results in something like this:

{
  "data": {
    "retourResolveRedirect": {
      "id": 1,
      "siteId": 1,
      "associatedElementId": 0,
      "enabled": true,
      "redirectSrcUrl": "/stuff",
      "redirectSrcUrlParsed": "/stuff",
      "redirectSrcMatch": "pathonly",
      "redirectMatchType": "exactmatch",
      "redirectDestUrl": "/c3",
      "redirectHttpCode": 301,
      "hitCount": 12,
      "hitLastTime": "2019-06-12 03:26:42"
    }
  }
}

Arguments:

retourResolveRedirect(uri: '/', siteId: 1)

uri: String - The URI to resolve a redirect for.

siteId: Int - Optional - The siteId to resolve a redirect for.

Getting All Redirects

To retrieve all of the redirects that have been entered into Retour, you can to that with the retourRedirects query:

{
  retourRedirects(siteId: 1) {
    redirectMatchType
    redirectSrcUrl
    redirectDestUrl
  }
}

This will return all of the redirects for the passed in siteId:

{
  "data": {
    "retourRedirects": [
      {
        "redirectMatchType": "exactmatch",
        "redirectSrcUrl": "/woof",
        "redirectDestUrl": "/"
      },
      {
        "redirectMatchType": "regexmatch",
        "redirectSrcUrl": "^/branches/(.{4})$",
        "redirectDestUrl": "/locations/$1"
      }
    ]
  }
}

If you omit the siteId argument, it will retrieve all redirects for all sites.

Arguments:

retourRedirects(siteId: 1)

siteId: Int - Optional - The siteId to resolve a redirect for.

API Endpoint

N.B.: Anonymous access to the Retour API endpoint is disabled by default; you’ll need to enable it in Retour → Plugin Settings

Retour has an API endpoint that allows you to get a JSON array of all of the redirects.

This is useful if you have an SPA, which you want to have handle the redirects, but you want to give your content authors a GUI for managing them.

To get all of the Retour Redirects, the controller action is:

/actions/retour/api/get-redirects

This will return to you an array of redirects as JSON data, for example:

[
  {
    "id": "1",
    "dateCreated": "2020-03-03 23:50:05",
    "dateUpdated": "2020-03-03 23:50:05",
    "uid": "0a530fb3-30fe-49a6-ab6b-363cdac8515e",
    "siteId": "2",
    "associatedElementId": "0",
    "enabled": "1",
    "redirectSrcUrl": "/blog/stuffer",
    "redirectSrcUrlParsed": "/blog/stuffer",
    "redirectSrcMatch": "pathonly",
    "redirectMatchType": "exactmatch",
    "redirectDestUrl": "/blog/stuffer-es",
    "redirectHttpCode": "301",
    "hitCount": "0",
    "hitLastTime": null
  },
  {
    "id": "2",
    "dateCreated": "2020-03-03 23:50:19",
    "dateUpdated": "2020-03-03 23:50:19",
    "uid": "f81b4752-398c-4e6d-942b-a33f19f06421",
    "siteId": "4",
    "associatedElementId": "0",
    "enabled": "1",
    "redirectSrcUrl": "/blog/stuffer",
    "redirectSrcUrlParsed": "/blog/stuffer",
    "redirectSrcMatch": "pathonly",
    "redirectMatchType": "exactmatch",
    "redirectDestUrl": "/blog/stuffer-to-to",
    "redirectHttpCode": "301",
    "hitCount": "0",
    "hitLastTime": null
  }
]

If you want only the redirects for a particular siteId, you can pass that in as a parameter as well:

/actions/retour/api/get-redirects?siteId=1

Brought to you by nystudio107