Version: current

# Class Director

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::set_environment_type()`.

Package: sapphire\control
See: ``Director::direct()``, ``Director::addRules()``, ``Director::set_environment_type()``
Located at sapphire/core/control/Director.php

## Methods summary

`public` | # `__construct( )`
`public static` | # `history( pagesBack $pagesBack = 1 )` Return a URL from this user's navigation history. Return a URL from this user's navigation history. #### Parameters $pagesBack pagesBack The number of pages back to go. The default, 1, returns the previous page.
`public static` | # `addRules( mixed $priority, mixed $rules )` Add URL matching rules to the Director. Add URL matching rules to the Director. The director is responsible for turning URLs into Controller objects. It does thi #### Parameters $priority $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
`public static` | # `direct( mixed $url )` Process the given URL, creating the appropriate controller and executing it. Process the given URL, creating the appropriate controller and executing it. Request processing is handled as folows: - 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 $url String, the URL the user is visiting, without the querystring. #### Uses ``Director::handleRequest()`` rule-lookup logic is handled by this. Controller::run() Controller::run() handles the page logic for a Director::direct() call.
`public static `SS_HTTPResponse`` | # `test( string $url, array $postVars = null, `Session` $session = null, string $httpMethod = null, string $body = null, array $headers = null, array $cookies = null )` Test a URL request, returning a response object. 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, #### Parameters $url string $url The URL to visit $postVars array $postVars The $_POST & $_FILES variables $session Session $session The `Session` object representing the current session. By passing the same object to multiple calls of Director::test(), you can simulate a peristed session. $httpMethod 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. $body string $body The HTTP body $headers array $headers HTTP headers with key-value pairs $cookies array $cookies to populate $_COOKIE #### Returns ``SS_HTTPResponse`` SS_HTTPResponse #### Uses getControllerForURL() The rule-lookup logic is handled by this. Controller::run() Controller::run() handles the page logic for a Director::direct() call. #### Used by ``FunctionalTest::get()`` ``FunctionalTest::post()`` ``TestSession::get()`` ``TestSession::post()``
`protected static `SS_HTTPResponse`|string` | # `handleRequest( `SS_HTTPRequest` $request, `Session` $session )` Handle an HTTP request, defined with a SS_HTTPRequest object. Handle an HTTP request, defined with a SS_HTTPRequest object. #### Returns ``SS_HTTPResponse`|string` SS_HTTPResponse|string #### Used by ``Director::direct()`` rule-lookup logic is handled by this.
`public static` | # `urlParam( mixed $name )` Returns the urlParam with the given name Returns the urlParam with the given name
`public static` | # `urlParams( )` Returns an array of urlParams Returns an array of urlParams
`public 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 the `SiteTree` object that is currently being viewed. If there is no sitetree object to return, then this will return the current controller. #### Returns ``SiteTree`` SiteTree
`public static` | # `set_current_page( `SiteTree` $page )` Set the currently active `SiteTree` object that is being used to respond to the request. Set the currently active `SiteTree` object that is being used to respond to the request. #### Parameters $page SiteTree $page
`public static` | # `currentPage( )` #### Deprecated 2.4 Use `Director::get_current_page()`.
`public static` | # `absoluteURL( mixed $url, mixed $relativeToSiteBase = false )` Turns the given URL into an absolute URL. Turns the given URL into an absolute URL.
`public static boolean|string` | # `protocolAndHost( )` Returns the part of the URL, 'http://www.mysite.com'. Returns the part of the URL, 'http://www.mysite.com'. #### Returns `boolean|string` The domain from the PHP environment. Returns FALSE is this environment variable isn't set.
`public static` | # `redirect( mixed $url, mixed $code = 302 )` Redirect to another page. - $url can be an absolute URL - or it can be a URL relative to the "site base" - if it is just a word without an slashes, then it redirects to another action on the current controller. Redirect to another page. - $url can be an absolute URL - or it can be a URL relative to the "site base" - if it is just a word without an slashes, then it redirects to another action on the current controller.
`public static string` | # `redirected_to( )` Tests whether a redirection has been requested. Tests whether a redirection has been requested. #### Returns `string` If redirect() has been called, it will return the URL redirected to. Otherwise, it will return null;
`public static` | # `set_status_code( mixed $code )` Sets the HTTP status code Sets the HTTP status code
`public static` | # `get_status_code( )` Returns the current HTTP status code Returns the current HTTP status code
`public static` | # `redirectBack( )` #### Deprecated 2.5 Use Controller->redirectBack()
`public static` | # `baseURL( )` Returns the root URL for the site. It will be automatically calculated unless it is overridden with `Director::setBaseURL()`. Returns the root URL for the site. It will be automatically calculated unless it is overridden with `Director::setBaseURL()`. #### Used by ``File::getURL()``
`public static` | # `setBaseURL( mixed $baseURL )` Sets the root URL for the website. If the site isn't accessible from the URL you provide, weird things will happen. Sets the root URL for the website. If the site isn't accessible from the URL you provide, weird things will happen.
`public static` | # `baseFolder( )` Returns the root filesystem folder for the site. It will be automatically calculated unless it is overridden with `Director::setBaseFolder()`. Returns the root filesystem folder for the site. It will be automatically calculated unless it is overridden with `Director::setBaseFolder()`. #### Used by ``Convert::raw2json()`` ``Convert::array2json()`` ``Convert::json2obj()``
`public static` | # `setBaseFolder( mixed $baseFolder )` Sets the root folder for the website. If the site isn't accessible from the folder you provide, weird things will happen. Sets the root folder for the website. If the site isn't accessible from the folder you provide, weird things will happen.
`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. 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 $url string $url Accepts both a URL or a filesystem path #### Returns `string` Either a relative URL if the checks succeeded, or the original (possibly absolute) URL.
`public static boolean` | # `is_absolute( string $path )` Returns true if a given path is absolute. Works under both *nix and windows systems Returns true if a given path is absolute. Works under both *nix and windows systems #### Parameters $path string $path #### Returns `boolean` bool
`public static boolean` | # `is_absolute_url( string $url )` Checks if a given URL is absolute (e.g. starts with 'http://' etc.). Checks if a given URL is absolute (e.g. starts with 'http://' etc.). #### Parameters $url string $url #### Returns `boolean` boolean
`public static boolean` | # `is_relative_url( string $url )` Checks if a given URL is relative by checking `Director::is_absolute_url()`. Checks if a given URL is relative by checking `Director::is_absolute_url()`. #### Parameters $url string $url #### Returns `boolean` boolean
`public static boolean` | # `is_site_url( string $url )` Checks if the given URL is belonging to this "site", as defined by `Director::makeRelative()` and absoluteBaseUrl(). 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. Checks if the given URL is belonging to this "site", as defined by `Director::makeRelative()` and absoluteBaseUrl(). 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 $url string $url #### Returns `boolean` boolean
`public static string` | # `getAbsFile( string $file )` Given a filesystem reference relative to the site root, return the full file-system path. Given a filesystem reference relative to the site root, return the full file-system path. #### Parameters $file string $file #### Returns `string` string
`public static` | # `fileExists( mixed $file )` Returns true if the given file exists. Returns true if the given file exists. #### Parameters $file $file Filename specified relative to the site root
`public static` | # `absoluteBaseURL( )` Returns the Absolute URL of the site root. Returns the Absolute URL of the site root. #### Used by ``File::getAbsoluteURL()``
`public static` | # `absoluteBaseURLWithAuth( )` Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL. Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL.
`public static` | # `forceSSL( )` Force the site to run on SSL. To use, call from _config.php. Force the site to run on SSL. To use, call from _config.php. For example:
    if(Director::isLive()) Director::forceSSL();
`public static` | # `forceWWW( )` Force a redirect to a domain starting with "www." Force a redirect to a domain starting with "www."
`public static boolean` | # `is_ajax( )` Checks if the current HTTP-Request is an "Ajax-Request" by checking for a custom header set by prototype.js or wether a manually set request-parameter 'ajax' is present. Checks if the current HTTP-Request is an "Ajax-Request" by checking for a custom header set by prototype.js or wether a manually set request-parameter 'ajax' is present. #### Returns `boolean` boolean
`public static boolean` | # `is_cli( )` Returns true if this script is being run from the command line rather than the webserver. Returns true if this script is being run from the command line rather than the webserver. #### Returns `boolean` boolean
`public static` | # `set_site_mode( mixed $mode )` #### Deprecated 2.4
`public static` | # `get_site_mode( )` #### Deprecated 2.4
`public static` | # `add_callback( mixed $function, mixed $mode = 'site' )` #### Deprecated 2.4 Use a custom extension on your controller.
`public static` | # `set_environment_type( mixed $et )` Set the environment type of the current site. 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, Sapphire support 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::set_dev_servers()` and `Director::set_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()`, `Director::isTest()`, and `Director::isLive()`. #### Parameters $et $et string The environment type: dev, test, or live.
`public static string` | # `get_environment_type( )` Can also be checked with `Director::isDev()`, `Director::isTest()`, and `Director::isLive()`. Can also be checked with `Director::isDev()`, `Director::isTest()`, and `Director::isLive()`. #### Returns `string` 'dev', 'test' or 'live'
`public static` | # `set_dev_servers( mixed $servers )` Specify HTTP_HOST values that are development environments. For information about environment types, see `Director::set_environment_type()`. Specify HTTP_HOST values that are development environments. For information about environment types, see `Director::set_environment_type()`. #### Parameters $servers $servers array An array of HTTP_HOST values that should be treated as development environments.
`public static` | # `set_test_servers( mixed $servers )` Specify HTTP_HOST values that are test environments. For information about environment types, see `Director::set_environment_type()`. Specify HTTP_HOST values that are test environments. For information about environment types, see `Director::set_environment_type()`. #### Parameters $servers $servers array An array of HTTP_HOST values that should be treated as test environments.
`public static` | # `isLive( )`
`public 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()`. This function will return true if the site is in a development environment. For information about environment types, see `Director::set_environment_type()`.
`public 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()`. This function will return true if the site is in a test environment. For information about environment types, see `Director::set_environment_type()`.

### Magic methods summary

## Properties summary

`public static mixed` | $siteMode | # #### Deprecated 2.4
`public static mixed` | $alternateBaseFolder | #
`public static mixed` | $alternateBaseURL | #
`public static array` | $dev_servers | #
`public static array` | $test_servers | #
`protected static mixed` | $environment_type | #
`protected static mixed` | $callbacks | # #### Deprecated 2.4

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -