Director
class Director implements TemplateGlobalProvider
Director is responsible for processing URLs, and providing environment information.
The most important part of director is {@link 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 {@link Director::$environment_type}.
Config options
| alternate_base_folder | string | ||
| dev_servers | array | ||
| test_servers | array | ||
| alternate_protocol | string | Setting this explicitly specifies the protocol (http or https) used, overriding the normal behaviour of Director::is_https introspecting it from the request | |
| alternate_base_url | string | ||
| environment_type | string |
Methods
Test a URL request, returning a response object.
Set url parameters (should only be called internally by RequestHandler->handleRequest()).
Return the {@link SiteTree} object that is currently being viewed. If there is no SiteTree object to return, then this will return the current controller.
Set the currently active {@link SiteTree} object that is being used to respond to the request.
Turns the given URL into an absolute URL.
Returns the part of the URL, 'http://www.mysite.com'.
Return the current protocol that the site is running under.
Return whether the site is running as under HTTPS.
Returns the root URL for the site.
Returns the root filesystem folder for the site.
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.
Returns true if a given path is absolute. Works under both *nix and windows systems
Checks if a given URL is absolute (e.g. starts with 'http://' etc.).
Checks if a given URL is relative by checking {@link is_absolute_url()}.
Checks if the given URL is belonging to this "site" (not an external link).
Takes a $_SERVER data array and extracts HTTP request headers.
Given a filesystem reference relative to the site root, return the full file-system path.
Returns true if the given file exists.
Returns the Absolute URL of the site root.
Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL.
Force the site to run on SSL.
Force a redirect to a domain starting with "www."
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.
Returns true if this script is being run from the command line rather than the webserver.
Can also be checked with {@link Director::isDev()}, {@link Director::isTest()}, and {@link Director::isLive()}.
No description
This function will return true if the site is in a development environment.
This function will return true if the site is in a test environment.
No description
Details
at line 77
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.
at line 102
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.
at line 217
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.
at line 413
static
setUrlParams($params)
Set url parameters (should only be called internally by RequestHandler->handleRequest()).
at line 423
static SiteTree
get_current_page()
Return the {@link SiteTree} object that is currently being viewed. If there is no SiteTree object to return, then this will return the current controller.
at line 432
static
set_current_page(SiteTree $page)
Set the currently active {@link SiteTree} object that is being used to respond to the request.
at line 445
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.
at line 476
static boolean|string
protocolAndHost()
Returns the part of the URL, 'http://www.mysite.com'.
at line 506
static string
protocol()
Return the current protocol that the site is running under.
at line 515
static boolean
is_https()
Return whether the site is running as under HTTPS.
at line 559
static string
baseURL()
Returns the root URL for the site.
It will be automatically calculated unless it is overridden with {@link setBaseURL()}.
at line 587
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.
at line 596
static
baseFolder()
Returns the root filesystem folder for the site.
It will be automatically calculated unless it is overridden with {@link setBaseFolder()}.
at line 607
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.
at line 621
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.
at line 676
static bool
is_absolute(string $path)
Returns true if a given path is absolute. Works under both *nix and windows systems
at line 696
static boolean
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.
at line 728
static boolean
is_relative_url(string $url)
Checks if a given URL is relative by checking {@link is_absolute_url()}.
at line 744
static boolean
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 {@link is_relative_url()}, or if the host matches {@link 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.
at line 760
static array
extract_request_headers(array $server)
Takes a $_SERVER data array and extracts HTTP request headers.
at line 784
static string
getAbsFile(string $file)
Given a filesystem reference relative to the site root, return the full file-system path.
at line 792
static
fileExists($file)
Returns true if the given file exists.
at line 801
static
absoluteBaseURL()
Returns the Absolute URL of the site root.
at line 808
static
absoluteBaseURLWithAuth()
Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL.
at line 867
static boolean|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.
at line 907
static
forceWWW()
Force a redirect to a domain starting with "www."
at line 926
static boolean
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.
at line 942
static boolean
is_cli()
Returns true if this script is being run from the command line rather than the webserver.
at line 983
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 {@link 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 {@link Director::isDev()}, {@link Director::isTest()}, and {@link Director::isLive()}.
at line 998
static string
get_environment_type()
Can also be checked with {@link Director::isDev()}, {@link Director::isTest()}, and {@link Director::isLive()}.
at line 1014
static
isLive()
at line 1022
static
isDev()
This function will return true if the site is in a development environment.
For information about environment types, see {@link Director::set_environment_type()}.
at line 1042
static
isTest()
This function will return true if the site is in a test environment.
For information about environment types, see {@link Director::set_environment_type()}.