class Director implements TemplateGlobalProvider (View source)

Director is responsible for processing URLs, and providing environment information.

The most important part of director is Director::direct(), which is passed a URL and will execute the appropriate controller.

Director also has a number of static methods that provide information about the environment, such as Director::$environment_type.

Properties

Methods

public static 
addRules($priority, $rules) deprecated

Add URL matching rules to the Director.

public static 
direct($url, DataModel $model)

Process the given URL, creating the appropriate controller and executing it.

public static 
test(string $url, array $postVars = null, Session $session = array(), string $httpMethod = null, string $body = null, array $headers = array(), array|Cookie_Backend $cookies = array(), HTTP_Request $request = null)

Test a URL request, returning a response object.

protected static 
handleRequest(SS_HTTPRequest $request, Session $session, DataModel $model)

Handle an HTTP request, defined with a SS_HTTPRequest object.

public static 
setUrlParams($params)

Set url parameters (should only be called internally by RequestHandler->handleRequest()).

public static 
get_current_page()

Return the SiteTree object that is currently being viewed. If there is no SiteTree object to return, then this will return the current controller.

public static 
set_current_page(SiteTree $page)

Set the currently active SiteTree object that is being used to respond to the request.

public static 
string
absoluteURL(string $url, bool $relativeToSiteBase = false)

Turns the given URL into an absolute URL.

public static 
bool|string
protocolAndHost()

Returns the part of the URL, 'http://www.mysite.com'.

public static 
string
protocol()

Return the current protocol that the site is running under.

public static 
bool
is_https()

Return whether the site is running as under HTTPS.

public static 
string
baseURL()

Returns the root URL for the site.

public static 
setBaseURL($baseURL) deprecated

Sets the root URL for the website.

public static 
baseFolder()

Returns the root filesystem folder for the site.

public static 
setBaseFolder($baseFolder) deprecated

Sets the root folder for the website.

public static 
string
makeRelative(string $url)

Turns an absolute URL or folder into one that's relative to the root of the site. This is useful when turning a URL into a filesystem reference, or vice versa.

public static 
bool
is_absolute(string $path)

Returns true if a given path is absolute. Works under both *nix and windows systems

public static 
bool
is_absolute_url(string $url)

Checks if a given URL is absolute (e.g. starts with 'http://' etc.).

public static 
bool
is_relative_url(string $url)

Checks if a given URL is relative by checking is_absolute_url().

public static 
bool
is_site_url(string $url)

Checks if the given URL is belonging to this "site" (not an external link).

public static 
array
extract_request_headers(array $server)

Takes a $_SERVER data array and extracts HTTP request headers.

public static 
string
getAbsFile(string $file)

Given a filesystem reference relative to the site root, return the full file-system path.

public static 
fileExists($file)

Returns true if the given file exists.

public static 
absoluteBaseURL()

Returns the Absolute URL of the site root.

public static 
absoluteBaseURLWithAuth()

Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL.

protected static 
string
force_redirect(string $destURL)

Skip any further processing and immediately respond with a redirect to the passed URL.

public static 
bool|string
forceSSL(array $patterns = null, string $secureDomain = null)

Force the site to run on SSL.

public static 
forceWWW()

Force a redirect to a domain starting with "www."

public static 
bool
is_ajax()

Checks if the current HTTP-Request is an "Ajax-Request" by checking for a custom header set by jQuery or wether a manually set request-parameter 'ajax' is present.

public static 
bool
is_cli()

Returns true if this script is being run from the command line rather than the webserver.

public static 
set_environment_type($et) deprecated

Set the environment type of the current site.

public static 
isLive()

No description

public static 
isDev()

This function will return true if the site is in a development environment.

public static 
isTest()

This function will return true if the site is in a test environment.

protected static 
string
session_environment()

Check or update any temporary environment specified in the session

public static 
array

Details

static addRules($priority, $rules) deprecated

deprecated 4.0 Use the "Director.rules" config setting instead

Add URL matching rules to the Director.

The director is responsible for turning URLs into Controller objects.

Parameters

$priority

The priority of the rules; higher values will get your rule checked first. We recommend priority 100 for your site's rules. The built-in rules are priority 10, standard modules are priority 50.

$rules

static direct($url, DataModel $model)

Process the given URL, creating the appropriate controller and executing it.

Request processing is handled as follows:

  • Director::direct() creates a new SS_HTTPResponse object and passes this to Director::handleRequest().
  • Director::handleRequest($request) checks each of the Director rules and identifies a controller to handle this request.
  • Controller::handleRequest($request) is then called. This will find a rule to handle the URL, and call the rule handling method.
  • RequestHandler::handleRequest($request) is recursively called whenever a rule handling method returns a RequestHandler object.

In addition to request processing, Director will manage the session, and perform the output of the actual response to the browser.

Parameters

$url

String, the URL the user is visiting, without the querystring.

DataModel $model

static SS_HTTPResponse test(string $url, array $postVars = null, Session $session = array(), string $httpMethod = null, string $body = null, array $headers = array(), array|Cookie_Backend $cookies = array(), HTTP_Request $request = null)

Test a URL request, returning a response object.

This method is the counterpart of Director::direct() that is used in functional testing. It will execute the URL given, and return the result as an SS_HTTPResponse object.

Parameters

string $url

The URL to visit

array $postVars

The $_POST & $_FILES variables

Session $session

The Session object representing the current session. By passing the same object to multiple calls of Director::test(), you can simulate a persisted session.

string $httpMethod

The HTTP method, such as GET or POST. It will default to POST if postVars is set, GET otherwise. Overwritten by $postVars['_method'] if present.

string $body

The HTTP body

array $headers

HTTP headers with key-value pairs

array|Cookie_Backend $cookies

to populate $_COOKIE

HTTP_Request $request

The {\HTTP_Request} object generated as a part of this request

Return Value

SS_HTTPResponse

static protected SS_HTTPResponse|string handleRequest(SS_HTTPRequest $request, Session $session, DataModel $model)

Handle an HTTP request, defined with a SS_HTTPRequest object.

Parameters

SS_HTTPRequest $request
Session $session
DataModel $model

Return Value

SS_HTTPResponse|string

static setUrlParams($params)

Set url parameters (should only be called internally by RequestHandler->handleRequest()).

Parameters

$params array

static SiteTree get_current_page()

Return the SiteTree object that is currently being viewed. If there is no SiteTree object to return, then this will return the current controller.

Return Value

SiteTree

static set_current_page(SiteTree $page)

Set the currently active SiteTree object that is being used to respond to the request.

Parameters

SiteTree $page

static string absoluteURL(string $url, bool $relativeToSiteBase = false)

Turns the given URL into an absolute URL.

By default non-site root relative urls will be evaluated relative to the current request.

Parameters

string $url

URL To transform to absolute

bool $relativeToSiteBase

Flag indicating if non-site root relative urls should be evaluated relative to the site BaseURL instead of the current url.

Return Value

string

The fully qualified URL

static bool|string protocolAndHost()

Returns the part of the URL, 'http://www.mysite.com'.

Return Value

bool|string

The domain from the PHP environment. Returns FALSE is this environment variable isn't set.

static string protocol()

Return the current protocol that the site is running under.

Return Value

string

static bool is_https()

Return whether the site is running as under HTTPS.

Return Value

bool

static string baseURL()

Returns the root URL for the site.

It will be automatically calculated unless it is overridden with setBaseURL().

Return Value

string

static setBaseURL($baseURL) deprecated

deprecated 4.0 Use the "Director.alternate_base_url" config setting instead

Sets the root URL for the website.

If the site isn't accessible from the URL you provide, weird things will happen.

Parameters

$baseURL

static baseFolder()

Returns the root filesystem folder for the site.

It will be automatically calculated unless it is overridden with setBaseFolder().

static setBaseFolder($baseFolder) deprecated

deprecated 4.0 Use the "Director.alternate_base_folder" config setting instead

Sets the root folder for the website.

If the site isn't accessible from the folder you provide, weird things will happen.

Parameters

$baseFolder

static string makeRelative(string $url)

Turns an absolute URL or folder into one that's relative to the root of the site. This is useful when turning a URL into a filesystem reference, or vice versa.

Parameters

string $url

Accepts both a URL or a filesystem path

Return Value

string

Either a relative URL if the checks succeeded, or the original (possibly absolute) URL.

static bool is_absolute(string $path)

Returns true if a given path is absolute. Works under both *nix and windows systems

Parameters

string $path

Return Value

bool

static bool is_absolute_url(string $url)

Checks if a given URL is absolute (e.g. starts with 'http://' etc.).

URLs beginning with "//" are treated as absolute, as browsers take this to mean the same protocol as currently being used.

Useful to check before redirecting based on a URL from user submissions through $_GET or $_POST, and avoid phishing attacks by redirecting to an attackers server.

Note: Can't solely rely on PHP's parse_url() , since it is not intended to work with relative URLs or for security purposes. filter_var($url, FILTER_VALIDATE_URL) has similar problems.

Parameters

string $url

Return Value

bool

static bool is_relative_url(string $url)

Checks if a given URL is relative by checking is_absolute_url().

Parameters

string $url

Return Value

bool

static bool is_site_url(string $url)

Checks if the given URL is belonging to this "site" (not an external link).

That's the case if the URL is relative, as defined by is_relative_url(), or if the host matches protocolAndHost().

Useful to check before redirecting based on a URL from user submissions through $_GET or $_POST, and avoid phishing attacks by redirecting to an attackers server.

Parameters

string $url

Return Value

bool

static array extract_request_headers(array $server)

Takes a $_SERVER data array and extracts HTTP request headers.

Parameters

array $server

Return Value

array

static string getAbsFile(string $file)

Given a filesystem reference relative to the site root, return the full file-system path.

Parameters

string $file

Return Value

string

static fileExists($file)

Returns true if the given file exists.

Parameters

$file

Filename specified relative to the site root

static absoluteBaseURL()

Returns the Absolute URL of the site root.

static absoluteBaseURLWithAuth()

Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL.

static protected string force_redirect(string $destURL)

Skip any further processing and immediately respond with a redirect to the passed URL.

Parameters

string $destURL

The URL to redirect to

Return Value

string

URL redirected to if on CLI

static bool|string forceSSL(array $patterns = null, string $secureDomain = null)

Force the site to run on SSL.

To use, call from _config.php. For example:

if(Director::isLive()) Director::forceSSL();

If you don't want your entire site to be on SSL, you can pass an array of PCRE regular expression patterns for matching relative URLs. For example:

if(Director::isLive()) Director::forceSSL(array('/^admin/', '/^Security/'));

If you want certain parts of your site protected under a different domain, you can specify the domain as an argument:

if(Director::isLive()) Director::forceSSL(array('/^admin/', '/^Security/'), 'secure.mysite.com');

Note that the session data will be lost when moving from HTTP to HTTPS. It is your responsibility to ensure that this won't cause usability problems.

CAUTION: This does not respect the site environment mode. You should check this as per the above examples using Director::isLive() or Director::isTest() for example.

Parameters

array $patterns

Array of regex patterns to match URLs that should be HTTPS

string $secureDomain

Secure domain to redirect to. Defaults to the current domain

Return Value

bool|string

String of URL when unit tests running, boolean FALSE if patterns don't match request URI

static forceWWW()

Force a redirect to a domain starting with "www."

static bool is_ajax()

Checks if the current HTTP-Request is an "Ajax-Request" by checking for a custom header set by jQuery or wether a manually set request-parameter 'ajax' is present.

Note that if you plan to use this to alter your HTTP response on a cached page, you should add X-Requested-With to the Vary header.

Return Value

bool

static bool is_cli()

Returns true if this script is being run from the command line rather than the webserver.

Return Value

bool

static set_environment_type($et) deprecated

deprecated 4.0 Use the "Director.environment_type" config setting instead

Set the environment type of the current site.

Typically, a SilverStripe site have a number of environments:

  • development environments, such a copy on your local machine.
  • test sites, such as the one you show the client before going live.
  • the live site itself.

The behaviour of these environments often varies slightly. For example, development sites may have errors dumped to the screen, and order confirmation emails might be sent to the developer instead of the client.

To help with this, SilverStripe supports the notion of an environment type. The environment type can be dev, test, or live.

You can set it explicitly with Director::set_environment_tpye(). Or you can use Director::$dev_servers} and {@link Director::$test_servers to set it implicitly, based on the value of $_SERVER['HTTP_HOST']. If the HTTP_HOST value is one of the servers listed, then the environment type will be test or dev. Otherwise, the environment type will be live.

Dev mode can also be forced by putting ?isDev=1 in your URL, which will ask you to log in and then push the site into dev mode for the remainder of the session. Putting ?isDev=0 onto the URL can turn it back.

Test mode can also be forced by putting ?isTest=1 in your URL, which will ask you to log in and then push the site into test mode for the remainder of the session. Putting ?isTest=0 onto the URL can turn it back.

Generally speaking, these methods will be called from your _config.php file.

Once the environment type is set, it can be checked with Director::isDev()}, {@link Director::isTest(), and Director::isLive().

Parameters

$et

string The environment type: dev, test, or live.

static string get_environment_type()

Return Value

string

'dev', 'test' or 'live'

static isLive()

No description

static isDev()

This function will return true if the site is in a development environment.

For information about environment types, see Director::set_environment_type().

static isTest()

This function will return true if the site is in a test environment.

For information about environment types, see Director::set_environment_type().

static protected string session_environment()

Check or update any temporary environment specified in the session

Return Value

string

'test', 'dev', or null

static array get_template_global_variables()

No description

Return Value

array

Returns an array of items. Each key => value pair is one of three forms:

  • template name (no key)
  • template name => method name
  • template name => array(), where the array can contain these key => value pairs
    • "method" => method name
    • "casting" => casting class to use (i.e., Varchar, HTMLText, etc)