How do you enable URL segments?

URL segments are not enabled by default. They have to be enabled for each template you want them in: Setup > Templates > [your template] > URLs > Enable URL segments. By default, ProcessWire allows up to 4 stacked URL segments before it'll start throwing 404s. You may modify this setting in your /site/config.php file via the $config->maxUrlSegments directive:

$config->maxUrlSegments = 4;

Where can you use URL segments?

You can use URL segments on any page where your template settings allow, regardless of whether it has children or not. Should there be a child page that has the same name as a URL segment that the parent page's template is looking for, the pages in the tree always have precedence. Meaning, URL segments only apply if the requested URL did not resolve to an actual page. As a result, you should avoid using URL segments where you think the page names and URL segments could collide.

How does a template file identify URL segments?

URL segments can be accessed from the $input API variable:

$input->urlSegment($n); // Retrieve the $n'th URL segment (1–3*)
$input->urlSegment1; // Retrieve the first: /path/to/page/aaa/
$input->urlSegment2; // Retrieve the second: /path/to/page/aaa/bbb/
$input->urlSegment3; // Retrieve the third: /path/to/page/aaa/bbb/ccc/


if($input->urlSegment1 == 'photos') {
  // display photo gallery
} else if($input->urlSegment1 == 'map') {
  // display map
} else {
  // display main content

Next: Best practices »

  1. What are URL segments?
  2. How and where to use them
  3. Best practices
  4. Page numbers and URL segments


  • Chris

    Chris 4 years ago 32

    These url segments, although cleaner, seem just like a query string. how do they differ?

    • ryan

      ryan 4 years ago 182

      Some reasons to use URL segments rather than query strings:

      1. Pages rendered from URL segments can be cached, whereas pages rendered as the result of a query string cannot.

      2. URL segments are search engine friendly, whereas query strings are not necessarily.

      3. URL segments are sanitized automatically, since they have to follow PW page name format, whereas query strings are not.

      4. URL segments are nicer to look at, easier to read, and easier to type.

      But should you replace your use of query strings with URL segments? Nope. I would always still use query strings in these situations:

      1. The potential values you accept are unlimited. You would not want such values to benefit from caching (per item 1 above) since a cache with no limits can fill up a drive.

      2. You are in an environment where things like search friendliness and readability aren't really a factor. For instance web applications with a logged in user is likely to derive more benefit from using query strings.

      3. You need true "key=value" relationships with variables. Keep in mind URL segments are just the 'value' part. You might translate /key1/value1/key2/value2, etc., but that's more work and things to keep track of than a nice simple key=value query string.

      4. One of the biggest: if you need to allow values outside PW page name format. Keep in mind PW page names are limited to this set of characters: -_.a-z0-9. So you aren't going to want to use URL segments for a text search engine for example.

      5. The quantity of variables in the URL is unknown. URL segments are naturally limited to just a few. Whereas you could have any number of variables present in a query string.

      • Chris Falkenstein

        Chris Falkenstein 4 years ago 63

        Ryan, thanks for the informative response. and thank you for your generous offering here, pw. The more I use it the more I like it. Keep up the excellent work.

  • Alan

    Alan 3 years ago 11

    Coming from WordPress it seems to me this Would be an optimal way to use category/tags. But what can be a better use for this? =)

  • Joseph D Regan

    Joseph D Regan 3 months ago 00

    Can you use both at the same time? Query string and URL segment?

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.