---
name: "Mason::Manual::RequestDispatch"
section: "3pm"
platform: "linux"
package: "libmason-perl"
version: "2.24-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Mason::Manual::RequestDispatch"
---

# Mason::Manual::RequestDispatch(3pm)

How request paths get mapped to page components

## NAME

Mason::Manual::RequestDispatch - How request paths get mapped to page components

## DESCRIPTION

Given the request path

```
    /news/sports/hockey
```

Mason searches for the following components in order, setting `$m`-\>path\_info as noted.

```
    /news/sports/hockey.{mp,mc}
    /news/sports/hockey/index.{mp,mc}
    /news/sports/hockey/dhandler.{mp,mc}
    /news/sports/dhandler.{mp,mc}  # $m->path_info = hockey
    /news/sports.{mp,mc}           # $m->path_info = hockey (but see next section)
    /news/dhandler.{mp,mc}         # $m->path_info = sports/hockey
    /news.{mp,mc}                  # $m->path_info = sports/hockey (but see next section)
    /dhandler.{mp,mc}              # $m->path_info = news/sports/hockey
```

where `".{mp,mc}"` means either `".mp"` (indicating a *pure-perl* component). or `".mc"` (indicating a *top-level* component).

The following sections describe these elements in more detail.

### Autoextended path

The request path is suffixed with ".mp" and ".mc" to translate it to a component path.

```
    /news/sports/hockey.{mp,mc}
```

### Index

An index matches its exact directory, nothing underneath.

```
    /news/sports/hockey/index.{mp,mc}
```

### Dhandlers

A dhandler matches its directory as well as anything underneath, setting `"$m->path_info"` to the remainder.

```
    /news/sports/hockey/dhandler.{mp,mc}
    /news/sports/dhandler.{mp,mc}  # $m->path_info = hockey
    /news/dhandler.{mp,mc}         # $m->path_info = sports/hockey
    /dhandler.{mp,mc}              # $m->path_info = news/sports/hockey
```

### Partial paths

A component can match an initial part of the URL, setting `"$m->path_info"` to the remainder:

```
    /news/sports.{mp,mc}           # $m->path_info = hockey
    /news.{mp,mc}                  # $m->path_info = sports/hockey
```

Since this isn't always desirable behavior, it must be explicitly enabled for the component. Mason will call method `"allow_path_info"` on the component class, and will only allow the match if it returns true:

```
    <%class>
    method allow_path_info { 1 }
    </%class>
```

The default `"allow_path_info"` returns false.

`"allow_path_info"` is not checked on dhandlers, since the whole point of dhandlers is to match partial paths.

### Trailing slash

If the request URL has a trailing slash (ends with `"/"`), we remove it before the match process begins and add it to the `"$m->path_info"`. Components that should match must have `"allow_path_info"` return true.

For example:

```
    ## request URL /news/
    /news/index.{mp,mc}     # $m->path_info = / if index.{mp,mc} has
                            # allow_path_info => true
    /news/dhandler.{mp,mc}  # $m->path_info = /
    /news.{mp,mc}           # $m->path_info = / if news.{mp,mc} has
                            # allow_path_info => true
    ## request URL /news/sports/
    /news/sports/index.{mp,mc}     # $m->path_info = / if index.{mp,mc} has
                                   # allow_path_info => true
    /news/sports/dhandler.{mp,mc}  # $m->path_info = /
    /news/sports.{mp,mc}           # $m->path_info = / if sports.{mp,mc}
                                   # has allow_path_info => true
    /news/dhandler.{mp,mc}         # $m->path_info = sports/
    /news.{mp,mc}                  # $m->path_info = /sports/ if news.{mp,mc}
                                   # has allow_path_info => true
```

### Routes

It is possible to use route syntax to more elegantly parse `"$m->path_info"` for dhandlers and partial paths, e.g.

```
    <%class>
    route "{year:[0-9]+}/{month:[0-9]{2}}";
    </%class>
```

See Mason::Plugin::RouterSimple.

## SEE ALSO

Mason

## AUTHOR

Jonathan Swartz \<swartz@pobox.com\>

## COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jonathan Swartz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.