Class: GalleryUrlGenerator

Source Location: /modules/core/classes/GalleryUrlGenerator.class

Class GalleryUrlGenerator

Class Overview

This class generates all URLs for Gallery based on the auto-detected protocol, hostname, URL

path and the given GALLERY_MAIN_PHP. Handles normal standalone as well as embedded and multisite operation when some URLs need to go to the Gallery codebase directly. Also handles the navigation (history) together with GallerySession. All auto-detected URL parts can be overrided with the init() parameters (originating either from the optional config.php parameter 'baseUri' or from GalleryEmbed).

Located in /modules/core/classes/GalleryUrlGenerator.class [line 53]

Properties

Methods

[ Top ]

Direct descendents

Child Class	Description
RewriteUrlGenerator	Generic rewrite URL generator.
PrintPhotoControllerTestUrlGenerator	Mock url generator for this test
SnapGalaxyPrintPhotosControllerTestUrlGenerator	Mock url generator for this test

[ Top ]

Property Summary

array	$_currentBaseHost	The base host (protocol + host name) of all URLs generated with function makeUrl.
array	$_currentUrl	The complete URL (protocol + host name + path + file + query string) of the current request eg. 'http://example.com/gallery2/main.php?g2_view=core.ShowItem&g2_itemId=15'.
array	$_currentUrlBaseDir	The complete URL dir (protocol + host name + path) of all URLs to be generated eg.
string	$_embedSessionString	The session key=value for the CMS application in which Gallery is embedded. Should only be non-empty when cookieless browsing is supported by CMS, eg. 'session=3838562834573' which is then added to all URLs generated by Gallery.
array	$_file	URL base filename of Gallery, defaults to 'main.php'. Can also include some parameters, eg.
array	$_host	The host string of generated URLs (including optional port) eg. 'www.example.com'.
boolean	$_isCookiePathConfigured	Whether the cookie path was configured by the admin.
array	$_path	URL path to Gallery, eg. '/gallery2/' of http://example.com/gallery2/main.php.
array	$_protocol	The protocol of generated URLs, 'http' or 'https'.

[ Top ]

Method Summary

static string	appendParamsToUrl()	Append parameters to a URL using the Gallery prefix and URL encoding keys and values.
static string	getCurrentRequestUri()	Return the current request URI.
static void	getGalleryId()	Old multisite system used a galleryId based on the current URL. Return a value here so sites won't break before they can upgrade.
static void	_flattenParamsArray()	Convert a structure of nested URL parameters into a flat array of parameters.
static array	_parseUri()	Split a URI string into file, path, host and protocol substrings and normalize them.
static void	_saveLocalUrlMap()	Save changes to the local URL map.
GalleryStatus	assertIsInternalUrl()	Assert that the given URL is internal to the application
boolean	embedForceSessionId()	Decide whether to include session id in the URL.
string	generateUrl()	Generate a Gallery URL.
string	getCacheableUrl()	Return a URL that is stripped of all parameters that don't directly affect the output of the page, like navigation parameters. This URL can be used as the cache key for this page.
array	getCookiePath()	Get the cookie path that will encompass Gallery (and CMS app if embedded).
string	getCurrentUrl()	Return the complete URL of the current request.
string	getCurrentUrlDir()	Return the base directory of all generated URLs. Eg, if the URL is:
string	getHostName()	Return the host name for the current request.
string	getNavigationId()	Get the current navigation id.
array	getNavigationLinks()	Get a list of navigation links to go back to where we came from.
string	getNavigationReturnUrl()	Get an URL to return to the currently loaded view, stripping all parameters that are of navigational nature.
GalleryStatus	init()	Configure the GalleryUrlGenerator with all the data it needs.
GalleryStatus	initNavigation()	Initialize the navigation.
boolean	isNavigationBackPossible()	Check if we currently have a back link to where we came from.
string	makeAbsoluteUrl()	Make a given URL an absolute Gallery URL. The specified URL can be relative (e.g. main.php), server-relative (e.g. /gallery2/main.php) or already absolute.
string	makeRelativeUrl()	Translate the given absolute URL to a relative URL.
string	makeUrl()	Add given path to current protocol/server/port to create full URL.
string	_getLocalPath()	Check for a local override of an href path (to override a css or js file, for example).
void	_saveLocalUrlMapPhp5()	Compatibility function for PHP 5.3. See comment in GalleryUrlGenerator::_getLocalPath.

[ Top ]

Properties

array $_currentBaseHost [line 113]

The base host (protocol + host name) of all URLs generated with function makeUrl.

Index of array = $forceDirect (true/false), eg. 'http://example.com/' array (0 => string base host, 1 => string forceDirect base host)

API Tags:

Access:

private

[ Top ]

array $_currentUrl [line 124]

The complete URL (protocol + host name + path + file + query string) of the current request eg. 'http://example.com/gallery2/main.php?g2_view=core.ShowItem&g2_itemId=15'.

Index of array = $forceDirect (true/false) only relevant for embedded Gallery array (0 => string base URL, 1 => string forceDirect base URL)

API Tags:

Access:

private

[ Top ]

array $_currentUrlBaseDir [line 135]

The complete URL dir (protocol + host name + path) of all URLs to be generated eg.

'http://example.com/gallery2/.

Index of array = $forceDirect (true/false) only relevant for embedded Gallery array (0 => string base URL dir, 1 => string forceDirect base URL dir)

API Tags:

Access:

private

[ Top ]

string $_embedSessionString [line 103]

The session key=value for the CMS application in which Gallery is embedded. Should only be non-empty when cookieless browsing is supported by CMS, eg. 'session=3838562834573' which is then added to all URLs generated by Gallery.

API Tags:

Access:

private

[ Top ]

array $_file [line 64]

URL base filename of Gallery, defaults to 'main.php'. Can also include some parameters, eg.

main.php?foo=bar.

Index of array = $forceDirect (true/false) only relevant for embedded Gallery array (0 => string file, 1 => string forceDirect file)

API Tags:

Access:

private

[ Top ]

array $_host [line 84]

The host string of generated URLs (including optional port) eg. 'www.example.com'.

Index of array = $forceDirect (true/false) only relevant for embedded Gallery array (0 => string host, 1 => string forceDirect host)

API Tags:

Access:

private

[ Top ]

boolean $_isCookiePathConfigured [line 142]

Whether the cookie path was configured by the admin.

API Tags:

Access:

private

[ Top ]

array $_path [line 74]

URL path to Gallery, eg. '/gallery2/' of http://example.com/gallery2/main.php.

Index of array = $forceDirect (true/false) only relevant for embedded Gallery array (0 => string path, 1 => string forceDirect path)

API Tags:

Access:

private

[ Top ]

array $_protocol [line 94]

The protocol of generated URLs, 'http' or 'https'.

Index of array = $forceDirect (true/false) only relevant for embedded Gallery array (0 => string protocol, 1 => string forceDirect protocol)

API Tags:

Access:

private

[ Top ]

Methods

static method appendParamsToUrl [line 196]

static string appendParamsToUrl(
string
$url, array
$params, [boolean
$addPrefix = true], [boolean
$htmlEntities = true], [boolean
$urlEncode = true] 
)

Append parameters to a URL using the Gallery prefix and URL encoding keys and values.

Parameters:

string	$url:	the original URL
array	$params:	key/value pairs to be appended; may contain nested arrays
boolean	$addPrefix:	(optional) false to not add prefix to parameter names
boolean	$htmlEntities:	(optional) false to not convert ampersands to HTML entities
boolean	$urlEncode:	(optional) false to not URL encode parameter names and values

API Tags:

Return:

the new URL (& separates added params)

[ Top ]

static method getCurrentRequestUri [line 157]

static string getCurrentRequestUri(
)

Return the current request URI.

Example: for http://domain.com/gallery2/main.php?g2_view=core.ShowItem it returns /gallery2/main.php?g2_view=core.ShowItem

API Tags:

Return:

the current URL path component plus query parameters

[ Top ]

static method getGalleryId [line 253]

static void getGalleryId(
)

Old multisite system used a galleryId based on the current URL. Return a value here so sites won't break before they can upgrade.

API Tags:

Deprecated:

Information Tags:

Todo:

Remove on next major bump of core api

[ Top ]

static method _flattenParamsArray [line 234]

static void _flattenParamsArray(
array
$nestedParams, 
&$flatParams, [string
$keyBase = null], array
$flatParams 
)

Convert a structure of nested URL parameters into a flat array of parameters.

Preserves the order of the parameters and does not encode them yet. Example: Input array('a' => '1', 'b' => array('c' => 2), 'd' = 3) Result array('a' => '1', 'b[c]' => 2, 'd' = 3)

Parameters:

array	$nestedParams:	array of URL parameters, can have nested arrays
array	$flatParams:	flat array of URL parameters
string	$keyBase:	(optional) base of the key for nested array parameters
	&$flatParams:

API Tags:

Access:

private

[ Top ]

static method _parseUri [line 268]

static array _parseUri(
string
$uri 
)

Split a URI string into file, path, host and protocol substrings and normalize them.

Used to allow overriding auto-detected protocol, host, path and default base file. Also used to accept various embedUri formats

Parameters:

string

$uri:

URI

API Tags:

Return:	$host, $path, $file (incl. query string)
Access:	private

[ Top ]

static method _saveLocalUrlMap [line 989]

static void _saveLocalUrlMap(

&$urlGenerator 
)

Save changes to the local URL map.

Parameters:

&$urlGenerator:

API Tags:

Access:

private

[ Top ]

assertIsInternalUrl [line 819]

GalleryStatus assertIsInternalUrl(
string
$url 
)

Assert that the given URL is internal to the application

Parameters:

string

$url:

URL to check

API Tags:

Return:

a status code

[ Top ]

embedForceSessionId [line 929]

boolean embedForceSessionId(
array
$params 
)

Decide whether to include session id in the URL.

Force the session id in the URL for embedded DownloadItem URLs if the cookie.path plugin parameter is not set. See GallerySession::init for details

Parameters:

array

$params:

(string param)

API Tags:

Return:	forceSessionId
Access:	protected

[ Top ]

generateUrl [line 575]

string generateUrl(
[array
$params = array()], [array
$options = array()] 
)

Generate a Gallery URL.

Parameters:

array	$params:	(optional) key=value pairs to be included in the URL special 'href' key specifies path to append to Gallery base URL instead of a query param %CURRENT_URL% token in a parameter value will be replaced with current URL
array	$options:	(optional) additional URL generation options: 'baseUrl' => string; to override the default baseUrl 'forceDirect' => true; to generate from Gallery site URL even if embedded or multisite 'forceFullUrl' => true; to generate absolute URL instead of relative path URL 'forceSessionId' => boolean; to force session id to be included or excluded; by default it is included when cookies are not in use (by default it is excluded from href URLs) 'htmlEntities' => false; to use '&' parameter separator instead of '&' 'urlEncode' => false; to not URL encode parameter names and values 'forceServerRelativeUrl' => true; to generate server-relative URLs if possible but no relative URLs (e.g. /gallery2/main.php instead of http://example.com/gallery2/main.php but never just main.php (without path)) 'useAuthToken' => boolean; to force auth token to be included or excluded; by default it is included in controller URLs 'protocol' => string; to override the URL scheme

API Tags:

Return:

URL

Redefined in descendants as:

[ Top ]

getCacheableUrl [line 481]

string getCacheableUrl(
)

Return a URL that is stripped of all parameters that don't directly affect the output of the page, like navigation parameters. This URL can be used as the cache key for this page.

[ Top ]

getCookiePath [line 770]

array getCookiePath(
[boolean
$forceDirect = false] 
)

Get the cookie path that will encompass Gallery (and CMS app if embedded).

The forceDirect parameter forces the function to return the path to Gallery and not to the current dir of the URL. This is only relevant when Gallery is embedded. forceDirect is only used for applets because they talk to Gallery directly and not through the embedding application. If the cookie path wouldn't be set to the Gallery base in this case, the applet wouldn't select the cookie for requests, because it wasn't allowed to (according to the cookie specs)

Examples: Current URL forceDirect cookie path http://example.com/gallery2/main.php false /gallery2/ http://example.com/gallery2/main.php true /gallery2/ http://example.com/applicationXy/index.php false /applicationXy/ http://example.com/applicationXy/index.php true /gallery2/

In the last example we assumed that Gallery is installed at that location.

Parameters:

boolean

$forceDirect:

(optional) if true, ensure Gallery path of base URL is returned (different when embedded)

API Tags:

Return:

(object Gallery status, string path)

[ Top ]

getCurrentUrl [line 465]

string getCurrentUrl(
[boolean
$forceDirect = false] 
)

Return the complete URL of the current request.

The returned URL may differ from the actual request URL since we allow for overriding the discovered protocol/host/host/path/file

Parameters:

boolean

$forceDirect:

(optional) if true, ensure Gallery base protocol/host is used

API Tags:

Return:

the current URL

Redefined in descendants as:

ModRewriteUrlGenerator::getCurrentUrl()

[ Top ]

getCurrentUrlDir [line 517]

string getCurrentUrlDir(
[boolean
$forceDirect = false] 
)

Return the base directory of all generated URLs. Eg, if the URL is:

http://example.com/gallery2/main.php Then we return: http://example.com/gallery2/

Usually, it's the same as the URL directory of the current request URL, unless we're using short URLs. Also, the base URL can be overridden

Parameters:

boolean

$forceDirect:

(optional) if true, ensure Gallery base URL is returned (different when embedded)

API Tags:

Return:

the base URL directory

Redefined in descendants as:

IsapiRewriteUrlGenerator::getCurrentUrlDir()
PathInfoUrlGenerator::getCurrentUrlDir() : Return the base directory of all generated URLs, e.g. if the URL is:

[ Top ]

getHostName [line 414]

string getHostName(
[boolean
$forceDirect = false] 
)

Return the host name for the current request.

Parameters:

boolean

$forceDirect:

(optional) if true, ensure Gallery base protocol/host is used

API Tags:

Return:

the host name

[ Top ]

getNavigationId [line 866]

string getNavigationId(
)

Get the current navigation id.

API Tags:

Return:	the navigation id
Deprecated:

Information Tags:

Todo:

will be removed in the next API branch

[ Top ]

getNavigationLinks [line 915]

array getNavigationLinks(
[int
$depth = null] 
)

Get a list of navigation links to go back to where we came from.

Parameters:

int

$depth:

set this to get links back to a certain depth

API Tags:

Return:	( GalleryStatus a status code, array of navigational links: array('url' => ..., 'name' => 'Back to ...'))
Deprecated:

Information Tags:

Todo:

will be removed in the next API branch

[ Top ]

getNavigationReturnUrl [line 876]

string getNavigationReturnUrl(
)

Get an URL to return to the currently loaded view, stripping all parameters that are of navigational nature.

API Tags:

Return:

the URL

[ Top ]

init [line 330]

GalleryStatus init(
[string
$baseUri = null], [string
$g2Uri = null], [string
$embedSessionString = null] 
)

Configure the GalleryUrlGenerator with all the data it needs.

Parameters:

string	$baseUri:	the base URL (optional), eg. index.php?mod=gallery will override main.php, /index.php or /gallery/index.php will override the path and file, /gallery/ overrides the path only, example.com/, overrides the host and the path and http://example.com/gallery/index.php?page=gallery overrides all parts All non-specified parts fall back to auto-detected values
string	$g2Uri:	(optional) when embedded, base URL to Gallery standalone. Same format as baseUri
string	$embedSessionString:	(optional) when embedded in CMS app that supports cookieless browsing, key=value string for CMS session key and id

API Tags:

Return:

a status code

Redefined in descendants as:

[ Top ]

initNavigation [line 803]

GalleryStatus initNavigation(
)

Initialize the navigation.

If we came here with a 'return' set, validate the given return URL.

Note: This should be called as soon as we have access to our session and the requestVariables, but before we start generating URLs with generateUrl(). Currently it's called from GalleryInitSecondPass

API Tags:

Return:

a status code

Redefined in descendants as:

[ Top ]

isNavigationBackPossible [line 901]

boolean isNavigationBackPossible(
)

Check if we currently have a back link to where we came from.

API Tags:

Return:	true if we can go back
Deprecated:

Information Tags:

Todo:

will be removed in the next API branch

[ Top ]

makeAbsoluteUrl [line 444]

string makeAbsoluteUrl(
mixed
$url, [boolean
$forceDirect = false] 
)

Make a given URL an absolute Gallery URL. The specified URL can be relative (e.g. main.php), server-relative (e.g. /gallery2/main.php) or already absolute.

Parameters:

boolean

$forceDirect:

(optional) if true, Gallery base protocol/host is used in case the URL isn't absolute already

API Tags:

Return:

the absolute URL

[ Top ]

makeRelativeUrl [line 727]

string makeRelativeUrl(
string
$url, [
$forceServerRelativeUrl = false] 
)

Translate the given absolute URL to a relative URL.

The result will be either a server relative URL /..., a URL relative to the current URL directory or an unchanged absolute URL (some URLs in multisite go to the codebase, embedded Gallery could be on a different subdomain, ..)

Note: don't be fooled if $this->_file shows up in the query string!

Parameters:

string	$url:	absolute URL
	$forceServerRelativeUrl:

API Tags:

Return:

relative URL (or unchanged absolute URL)

[ Top ]

makeUrl [line 425]

string makeUrl(
string
$path, [boolean
$forceDirect = false] 
)

Add given path to current protocol/server/port to create full URL.

Parameters:

string	$path:	the URL path; leading slash will be added if missing
boolean	$forceDirect:	(optional) if true, ensure Gallery base protocol/host is used

API Tags:

Return:

the URL

[ Top ]

_getLocalPath [line 948]

string _getLocalPath(
string
$href 
)

Check for a local override of an href path (to override a css or js file, for example).

Parameters:

string

$href:

relative path

API Tags:

Return:	path to local override, or given path if override not found
Access:	private

[ Top ]

_saveLocalUrlMapPhp5 [line 1000]

void _saveLocalUrlMapPhp5(
)

Compatibility function for PHP 5.3. See comment in GalleryUrlGenerator::_getLocalPath.

[ Top ]

Documentation generated on Fri, 08 Oct 2010 05:06:36 -0700 by phpDocumentor 1.3.0RC6

	GalleryCore Classes

[ class tree: GalleryCore ] [ index: GalleryCore ] [ all elements ]