Referer attribute

---

1Presentation

This attribute is used to protect access to a controller or action based on the value of the HTTP REFERER header.

---

2Parameters

The attribute offers several parameters:

• $domain: (bool|string|array) Indicates the referer's domain (if true, the domain must be identical to the current domain), or a list of domains (the referer must be equal to one of them).
• $domainSuffix: (string|array) Referrer's domain suffix, or list of suffixes.
• $domainRegex: (string) Regular expression to be validated by the referer's domain.
• $domainVar: (string) Name of the template variable containing the domain to which the referer's domain must correspond.
• $domainConfig: (bool) Set to true to use the refererDomain key from the x-security extended configuration (in the etc/temma.php file).
• $https: (bool|string) The effect of this parameter depends on its value:
  • null: (default value) The referer can be in HTTP or HTTPS.
  • true: The referer must be HTTPS.
  • false: The referer must be HTTP.
  • 'same': The referer must use the same protocol (HTTP/HTTPS) as the current site.
• $path: (string|array) Path or path list of the referer.
• $pathPrefix: (string|array) Path prefix of the referer, or list of prefixes.
• $pathSuffix: (string|array) Path suffix of the referer, or list of suffixes.
• $pathRegex: (string) Regular expression that the referer's path must validate.
• $pathVar: (string) Name of the template variable containing the referer's path.
• $pathConfig: (bool) Set to true to use the refererPath key from the x-security extended configuration (in the etc/temma.php file).
• $url: (string|array) URL or list of URLs of the referer.
• $urlRegex: (string) Regular expression to be validated by the referer's URL.
• $urlVar: (string) Name of template variable containing referrer URL.
• $urlConfig: (bool) Set to true to use the refererUrl key from the x-security extended configuration (in the etc/temma.php file).
• $redirect: (string) URL to redirect users to if they don't have the right to access the controller or action (instead of displaying an error page).
• $redirectVar: (string) Name of template variable containing URL to redirect user to.

---

3Redirection priority

If access is denied, the user can be redirected. To determine the redirection URL, the attribute applies the following order of priority:

1. If the $redirect parameter is set, it is used.
2. If the $redirectVar parameter is defined, and it contains the name of an existing, non-empty template variable, its content is used.
3. If the etc/temma.php file contains an x-security extended configuration, and this contains a refererRedirect key, its content is used.
4. If the etc/temma.php file contains an x-security extended configuration, and this contains a redirect key, its content is used.

---

4Configuration

To ensure that all Referer attributes redirect to the same URL, simply set the refererRedirect key in the x-security extended configuration of the etc/temma.php file:

<?php

return [
    'x-security' => [
        'refererRedirect' => '/failure'
    ]
];

To ensure that the redirect URL is the same for the Auth, Method, Referer and Redirect attributes, simply define the redirect key in the x-security extended configuration in the etc/temma.php file:

<?php

return [
    'x-security' => [
        'redirect' => '/login'
    ]
];

---

5Examples

use \Temma\Attributes\Referer as TµReferer;

class Admin extends \Temma\Web\Controller {
    // access forbidden for requests without referer
    #[TµReferer]
    public function action1() { }

    // authorized for requests from the same domain only
    #[TµReferer(true)]
    public function action2() { }

    // allowed for 'fubar.com' domain
    #[TµReferer('fubar.com')]
    public function action3() { }

    // same as previous
    #[TµReferer(domain: 'fubar.com')]
    public function action3bis() { }

    // allowed for 'fubar.com' and 'www.fubar.com' domains
    #[TµReferer(['fubar.com', 'www.fubar.com'])]
    public function action4() { }

    // same as previous
    #[TµReferer(domain: ['fubar.com', 'www.fubar.com'])]
    public function action4bis() { }

    // allowed for domains ending in '.fubar.com'.
    #[TµReferer(domainSuffix: '.fubar.com')]
    public function action5() { }

    // allowed for domains ending in '.fubar.com' or '.foobar.com'.
    #[TµReferer(domainSuffix: ['.fubar.com', '.foobar.com'])]
    public function action6() { }

    // allowed for domains that validate the provided regular expression
    #[TµReferer(domainRegex: '/^test\d?.fubar.(com|net)$/')]
    public function action7() { }

    // authorized for the domain whose name is stored in
    // the 'okDomain' template variable
    #[TµReferer(domainVar: 'okDomain')]
    public function action8() { }

    // authorized for the domain defined in the 'refererDomain' key of
    // the 'x-security' extended configuration (in the 'etc/temma.php' file)
    #[TµReferer(domainConfig: true)]
    public function action9() { }

    // authorized for an HTTP referer
    #[TµReferer(https: false)]
    public function action10() { }

    // authorized for an HTTPS referer
    #[TµReferer(https: true)]
    public function action11() { }

    // authorized for a referer whose protocol (HTTP/HTTPS)
    // is the same as that of the current site
    #[TµReferer(https: 'same')]
    public function action12() { }

    // authorized for a referer with path '/fu/bar.html'.
    #[TµReferer(path: '/fu/bar.html')]
    public function action13() { }

    // allowed for a referer with path '/fu.html' or '/bar.html'
    #[TµReferer(path: ['/fu.html', '/bar.html'])]
    public function action14() { }

    // allowed for a referer whose path starts with '/fu/'
    #[TµReferer(pathPrefix: '/fu/')]
    public function action15() { }

    // authorized for a referer whose path starts with '/fu/' or '/bar/'
    #[TµReferer(pathPrefix: ['/fu/', '/bar/'])]
    public function action16() { }

    // allowed for a referer whose path ends with '/api.xml'
    #[TµReferer(pathSuffix: '/api.xml')]
    public function action17() { }

    // authorized for a referer whose path ends with '/api.xml' or '/api.json'
    #[TµReferer(pathSuffix: ['/api.xml', '/api.json'])]
    public function action18() { }

    // authorized for a referer whose path validates the provided regular expression
    #[TµReferer(pathRegex: '/^\/.*testApi.*\.xml$/')]
    public function action19() { }

    // authorized for a referer whose path corresponds to that stored
    // in the 'okPath' template variable
    #[TµReferer(pathVar: 'okPath')]
    public function action20() { }

    // authorized for a referer whose path corresponds to that stored
    // in the 'refererPath' key of the 'x-security' extended configuration
    // (in the 'etc/temma.php' file)
    #[TµReferer(pathConfig: true)]
    public function action21() { }

    // authorized for a referer whose URL is 'https://www.fubar.com/some/page.html'
    #[TµReferer(url: 'https://www.fubar.com/some/page.html')]
    public function action22() { }

    // allowed for a referer whose URL is 'https://fu.com/bar'
    // or 'https://bar.com/fu'
    #[TµReferer(url: ['https://fu.com/bar', 'https://bar.com/fu'])]
    public function action23() { }

    // authorized for a referer whose URL validates the provided regular expression
    #[TµReferer(urlRegex: '/^.*$/')]
    public function action24() { }

    // authorized for a referer whose URL matches that stored in
    // the 'okURL' template variable
    #[TµReferer(urlVar: 'okURL')]
    public function action25() { }

    // authorized for a referer whose URL matches that stored in the
    // 'refererUrl' key of the 'x-security' extended configuration
    // (in the 'etc/temma.php' file)
    #[TµReferer(urlConfig: true)]
    public function action26() { }

    // redirect to the defined URL if there is no referer
    #[TµReferer(redirect: '/login')]
    public function action27() { }

    // redirect to URL defined in 'redirRef' template variable
    #[TµReferer(redirectVar: 'redirRef')]
    public function action28() { }

    // redirect to the URL stored in the 'refererRedirect' key of
    // the 'x-security' extended configuration (in the 'etc/temma.php' file)
    #[TµReferer]
    public function action29() { }
}