Director
class Director implements TemplateGlobalProvider (View source)
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}.
Properties
| static private string | $alternate_base_folder | ||
| static private array | $dev_servers | ||
| static private array | $test_servers | ||
| static private string | $alternate_protocol | Setting this explicitly specifies the protocol (http or https) used, overriding the normal behaviour of Director::is_https introspecting it from the request |
|
| static private string | $alternate_base_url | ||
| static private string | $environment_type |
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
static
addRules($priority, $rules)
deprecated
deprecated
Add URL matching rules to the Director.
The director is responsible for turning URLs into Controller objects.
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.
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.
static
setUrlParams($params)
Set url parameters (should only be called internally by RequestHandler->handleRequest()).
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.
static
set_current_page(SiteTree $page)
Set the currently active {@link SiteTree} object that is being used to respond to the request.
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.
static bool|string
protocolAndHost()
Returns the part of the URL, 'http://www.mysite.com'.
static string
protocol()
Return the current protocol that the site is running under.
static bool
is_https()
Return whether the site is running as under HTTPS.
static string
baseURL()
Returns the root URL for the site.
It will be automatically calculated unless it is overridden with {@link setBaseURL()}.
static
setBaseURL($baseURL)
deprecated
deprecated
Sets the root URL for the website.
If the site isn't accessible from the URL you provide, weird things will happen.
static
baseFolder()
Returns the root filesystem folder for the site.
It will be automatically calculated unless it is overridden with {@link setBaseFolder()}.
static
setBaseFolder($baseFolder)
deprecated
deprecated
Sets the root folder for the website.
If the site isn't accessible from the folder you provide, weird things will happen.
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.
static bool
is_absolute(string $path)
Returns true if a given path is absolute. Works under both *nix and windows systems
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.
static bool
is_relative_url(string $url)
Checks if a given URL is relative by checking {@link is_absolute_url()}.
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 {@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.
static array
extract_request_headers(array $server)
Takes a $_SERVER data array and extracts HTTP request headers.
static string
getAbsFile(string $file)
Given a filesystem reference relative to the site root, return the full file-system path.
static
fileExists($file)
Returns true if the given file exists.
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 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.
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.
static bool
is_cli()
Returns true if this script is being run from the command line rather than the webserver.
static
set_environment_type($et)
deprecated
deprecated
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()}.
static string
get_environment_type()
Can also be checked with {@link Director::isDev()}, {@link Director::isTest()}, and {@link Director::isLive()}.
static
isLive()
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()}.
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()}.