PHP Class SimpleSAML\Utils\HTTP

Show file Open project: simplesamlphp/simplesamlphp Class Usage Examples

Public Methods

Method Description
addURLParameters ( string $url, array $parameters ) : string Add one or more query parameters to the given URL.
checkSessionCookie ( string | null $retryURL = null ) : void Check for session cookie, and show missing-cookie page if it is missing.
checkURLAllowed ( string $url, array $trustedSites = null ) : string Check if a URL is valid and is in our list of allowed URLs.
fetch ( string $url, array $context = [], boolean $getHeaders = false ) : mixed Helper function to retrieve a file or URL with proxy support, also supporting proxy basic authorization.
getAcceptLanguage ( ) : array This function parses the Accept-Language HTTP header and returns an associative array with each language and the score for that language. If a language includes a region, then the result will include both the language with the region and the language without the region.
getBaseURL ( ) : string Retrieve the base URL of the SimpleSAMLphp installation. The URL will always end with a '/'. For example: https://idp.example.org/simplesaml/
getFirstPathElement ( boolean $trailingslash = true ) : string Retrieve the first element of the URL path.
getPOSTRedirectURL ( string $destination, array $data ) : string Create a link which will POST data.
getSelfHost ( ) : string Retrieve our own host.
getSelfHostWithNonStandardPort ( ) : string Retrieve our own host, including the port in case the it is not standard for the protocol in use. That is port 80 for HTTP and port 443 for HTTPS.
getSelfHostWithPath ( ) : string Retrieve our own host together with the URL path. Please note this function will return the base URL for the current SP, as defined in the global configuration.
getSelfURL ( ) : string Retrieve the current URL using the base URL in the configuration, if possible.
getSelfURLHost ( ) : string Retrieve the current URL using the base URL in the configuration, containing the protocol, the host and optionally, the port number.
getSelfURLNoQuery ( ) : string Retrieve the current URL using the base URL in the configuration, without the query parameters.
guessBasePath ( ) : string Try to guess the base SimpleSAMLphp path from the current request.
isHTTPS ( ) : boolean This function checks if we are using HTTPS as protocol.
normalizeURL ( string $url ) : string Normalizes a URL to an absolute URL and validate it. In addition to resolving the URL, this function makes sure that it is a link to an http or https site.
parseQueryString ( string $query_string ) : array Parse a query string into an array.
redirectTrustedURL ( string $url, string[] $parameters = [] ) : void This function redirects to the specified URL without performing any security checks. Please, do NOT use this function with user supplied URLs.
redirectUntrustedURL ( string $url, string[] $parameters = [] ) : void This function redirects to the specified URL after performing the appropriate security checks on it.
resolveURL ( string $url, string $base = null ) : string Resolve a (possibly relative) URL relative to a given base URL.
setCookie ( string $name, string | null $value, array | null $params = null, boolean $throw = true ) Set a cookie.
submitPOSTData ( string $destination, array $data ) Submit a POST form to a specific destination.

Private Methods

Method Description
getSecurePOSTRedirectURL ( string $destination, array $data ) : string Obtain a URL where we can redirect to securely post a form with the given data to a specific destination.
getServerHTTPS ( ) : boolean Retrieve HTTPS status from $_SERVER environment variables.
getServerHost ( ) : string Retrieve Host value from $_SERVER environment variables.
getServerPort ( ) : string Retrieve the port number from $_SERVER environment variables.
redirect ( string $url, string[] $parameters = [] ) : void This function redirects the user to the specified address.
savePOSTData ( SimpleSAML_Session $session, string $destination, array $data ) : string Save the given HTTP POST data and the destination where it should be posted to a given session.

Method Details

addURLParameters() public static method

Add one or more query parameters to the given URL.
Author: Andreas Solberg, UNINETT AS ([email protected])
Author: Olav Morken, UNINETT AS ([email protected])
public static addURLParameters ( string $url, array $parameters ) : string
$url string The URL the query parameters should be added to.
$parameters array The query parameters which should be added to the url. This should be an associative array.
return string The URL with the new query parameters.

checkSessionCookie() public static method

Check for session cookie, and show missing-cookie page if it is missing.
Author: Olav Morken, UNINETT AS ([email protected])
public static checkSessionCookie ( string | null $retryURL = null ) : void
$retryURL string | null The URL the user should access to retry the operation. Defaults to null.
return void If there is a session cookie, nothing will be returned. Otherwise, the user will be redirected to a page telling about the missing cookie.

checkURLAllowed() public static method

Check if a URL is valid and is in our list of allowed URLs.
Author: Jaime Perez, UNINETT AS ([email protected])
public static checkURLAllowed ( string $url, array $trustedSites = null ) : string
$url string The URL to check.
$trustedSites array An optional white list of domains. If none specified, the 'trusted.url.domains' configuration directive will be used.
return string The normalized URL itself if it is allowed. An empty string if the $url parameter is empty as defined by the empty() function.

fetch() public static method

. An exception will be thrown if we are unable to retrieve the data.
Author: Andjelko Horvat
Author: Olav Morken, UNINETT AS ([email protected])
Author: Marco Ferrante, University of Genova ([email protected])
public static fetch ( string $url, array $context = [], boolean $getHeaders = false ) : mixed
$url string The path or URL we should fetch.
$context array Extra context options. This parameter is optional.
$getHeaders boolean Whether to also return response headers. Optional.
return mixed array if $getHeaders is set, string otherwise

getAcceptLanguage() public static method

The returned array will be in the same order as the input.
Author: Olav Morken, UNINETT AS ([email protected])
public static getAcceptLanguage ( ) : array
return array An associative array with each language and the score for that language.

getBaseURL() public static method

Retrieve the base URL of the SimpleSAMLphp installation. The URL will always end with a '/'. For example: https://idp.example.org/simplesaml/
Author: Olav Morken, UNINETT AS ([email protected])
public static getBaseURL ( ) : string
return string The absolute base URL for the SimpleSAMLphp installation.

getFirstPathElement() public static method

Retrieve the first element of the URL path.
Author: Andreas Solberg, UNINETT AS ([email protected])
public static getFirstPathElement ( boolean $trailingslash = true ) : string
$trailingslash boolean Whether to add a trailing slash to the element or not. Defaults to true.
return string The first element of the URL path, with an optional, trailing slash.

getPOSTRedirectURL() public static method

Create a link which will POST data.
Author: Andjelko Horvat
Author: Jaime Perez, UNINETT AS ([email protected])
public static getPOSTRedirectURL ( string $destination, array $data ) : string
$destination string The destination URL.
$data array The name-value pairs which will be posted to the destination.
return string A URL which can be accessed to post the data.

getSelfHost() public static method

E.g. www.example.com
Author: Jaime Perez, UNINETT AS ([email protected])
public static getSelfHost ( ) : string
return string The current host.

getSelfHostWithNonStandardPort() public static method

E.g. www.example.com:8080
Author: Andreas Solberg, UNINETT AS ([email protected])
Author: Olav Morken, UNINETT AS ([email protected])
public static getSelfHostWithNonStandardPort ( ) : string
return string The current host, followed by a colon and the port number, in case the port is not standard for the protocol.

getSelfHostWithPath() public static method

Retrieve our own host together with the URL path. Please note this function will return the base URL for the current SP, as defined in the global configuration.
Author: Andreas Solberg, UNINETT AS ([email protected])
Author: Olav Morken, UNINETT AS ([email protected])
public static getSelfHostWithPath ( ) : string
return string The current host (with non-default ports included) plus the URL path.

getSelfURL() public static method

This method will try to see if the current script is part of SimpleSAMLphp. In that case, it will use the 'baseurlpath' configuration option to rebuild the current URL based on that. If the current script is NOT part of SimpleSAMLphp, it will just return the current URL. Note that this method does NOT make use of the HTTP X-Forwarded-* set of headers.
Author: Andreas Solberg, UNINETT AS ([email protected])
Author: Olav Morken, UNINETT AS ([email protected])
Author: Jaime Perez, UNINETT AS ([email protected])
public static getSelfURL ( ) : string
return string The current URL, including query parameters.

getSelfURLHost() public static method

Retrieve the current URL using the base URL in the configuration, containing the protocol, the host and optionally, the port number.
Author: Andreas Solberg, UNINETT AS ([email protected])
Author: Olav Morken, UNINETT AS ([email protected])
public static getSelfURLHost ( ) : string
return string The current URL without path or query parameters.

getSelfURLNoQuery() public static method

Retrieve the current URL using the base URL in the configuration, without the query parameters.
Author: Andreas Solberg, UNINETT AS ([email protected])
Author: Jaime Perez, UNINETT AS ([email protected])
public static getSelfURLNoQuery ( ) : string
return string The current URL, not including query parameters.

guessBasePath() public static method

This method offers just a guess, so don't rely on it.
public static guessBasePath ( ) : string
return string The guessed base path that should correspond to the root installation of SimpleSAMLphp.

isHTTPS() public static method

This function checks if we are using HTTPS as protocol.
Author: Olav Morken, UNINETT AS ([email protected])
Author: Jaime Perez, UNINETT AS ([email protected])
public static isHTTPS ( ) : boolean
return boolean True if the HTTPS is used, false otherwise.

normalizeURL() public static method

Normalizes a URL to an absolute URL and validate it. In addition to resolving the URL, this function makes sure that it is a link to an http or https site.
Author: Olav Morken, UNINETT AS ([email protected])
Author: Jaime Perez, UNINETT AS ([email protected])
public static normalizeURL ( string $url ) : string
$url string The relative URL.
return string An absolute URL for the given relative URL.

parseQueryString() public static method

This function parses a query string into an array, similar to the way the builtin 'parse_str' works, except it doesn't handle arrays, and it doesn't do "magic quotes". Query parameters without values will be set to an empty string.
Author: Olav Morken, UNINETT AS ([email protected])
public static parseQueryString ( string $query_string ) : array
$query_string string The query string which should be parsed.
return array The query string as an associative array.

redirectTrustedURL() public static method

This function will use the "HTTP 303 See Other" redirection if the current request used the POST method and the HTTP version is 1.1. Otherwise, a "HTTP 302 Found" redirection will be used. The function will also generate a simple web page with a clickable link to the target URL.
Author: Jaime Perez, UNINETT AS ([email protected])
public static redirectTrustedURL ( string $url, string[] $parameters = [] ) : void
$url string The URL we should redirect to. This URL may include query parameters. If this URL is a relative URL (starting with '/'), then it will be turned into an absolute URL by prefixing it with the absolute URL to the root of the website.
$parameters string[] An array with extra query string parameters which should be appended to the URL. The name of the parameter is the array index. The value of the parameter is the value stored in the index. Both the name and the value will be urlencoded. If the value is NULL, then the parameter will be encoded as just the name, without a value.
return void This function never returns.

redirectUntrustedURL() public static method

Particularly, it will make sure that the provided URL is allowed by the 'redirect.trustedsites' directive in the configuration. If the aforementioned option is not set or the URL does correspond to a trusted site, it performs a redirection to it. If the site is not trusted, an exception will be thrown.
Author: Jaime Perez, UNINETT AS ([email protected])
public static redirectUntrustedURL ( string $url, string[] $parameters = [] ) : void
$url string The URL we should redirect to. This URL may include query parameters. If this URL is a relative URL (starting with '/'), then it will be turned into an absolute URL by prefixing it with the absolute URL to the root of the website.
$parameters string[] An array with extra query string parameters which should be appended to the URL. The name of the parameter is the array index. The value of the parameter is the value stored in the index. Both the name and the value will be urlencoded. If the value is NULL, then the parameter will be encoded as just the name, without a value.
return void This function never returns.

resolveURL() public static method

This function supports these forms of relative URLs: - ^\w+: Absolute URL. E.g. "http://www.example.com:port/path?query#fragment". - ^// Same protocol. E.g. "//www.example.com:port/path?query#fragment" - ^/ Same protocol and host. E.g. "/path?query#fragment". - ^? Same protocol, host and path, replace query string & fragment. E.g. "?query#fragment". - ^# Same protocol, host, path and query, replace fragment. E.g. "#fragment". - The rest: Relative to the base path.
Author: Olav Morken, UNINETT AS ([email protected])
Author: Jaime Perez, UNINETT AS ([email protected])
public static resolveURL ( string $url, string $base = null ) : string
$url string The relative URL.
$base string The base URL. Defaults to the base URL of this installation of SimpleSAMLphp.
return string An absolute URL for the given relative URL.

setCookie() public static method

Set a cookie.
Author: Andjelko Horvat
Author: Jaime Perez, UNINETT AS ([email protected])
public static setCookie ( string $name, string | null $value, array | null $params = null, boolean $throw = true )
$name string The name of the cookie.
$value string | null The value of the cookie. Set to NULL to delete the cookie.
$params array | null Cookie parameters.
$throw boolean Whether to throw exception if setcookie() fails.

submitPOSTData() public static method

This function never returns.
Author: Olav Morken, UNINETT AS ([email protected])
Author: Andjelko Horvat
Author: Jaime Perez, UNINETT AS ([email protected])
public static submitPOSTData ( string $destination, array $data )
$destination string The destination URL.
$data array An associative array with the data to be posted to $destination.