spunQ_HttpEntryPoint Class Reference

An entry point to the application for HTTP connections. More...

List of all members.

Public Member Functions

 getUrlTemplates ()
 getName ()
 getTitle ()
 Getter for the title of this entry point.
 getModule ()
 Getter for the module of this entry point.
 getUrlManager ()
 checkAuthorization (spunQ_IHttpRequest $request, $variables)
 getAllowedUsers ()
 Provides usernames of users that are allowed to acces this entry point.
 getAllowedGroups ()
 Provides names of groups that are allowed to acces this entry point.
 getCacheOptions ()
 Returns a mapping of cache options to their values.
 isCallableByCurrentUser ()
 Checks whether the current user is allowed to call the entry point.
 invoke (array $variables)
 invokeCallback (array $variables, $captureOutput=true)
 Callback function for the cache used by invoke().
 getVariableDefaults ()
 Returns default variables for this entry point.
 getVariableDefaultDeclarations ()
 Returns default declarations of this entry point.
 createHtmlLink ($locale, array $variables)
 getVariables ()
 getRequiredRequestMethod ()
 Possible request methods for this entry point A combination of the spunQ_IHttpRequest::REQUEST_* constants, combined using binary AND.
 getLastModificationTime ()

Static Public Member Functions

static getAll ()
 Gets all known entry points, mapped by their alias.
static getMaxLastModificationTime ()
static getOneCallback ($module, $pageFiles)
 Gets spunQ_HttpEntryPoint objects for a single module.
static getByName ($name)
 Will find the entry point with given name.
static getForRequest (spunQ_IHttpRequest $request, &$statusCode)
 Will find the spunQ_HttpEntryPoint that can respond to given request.
static createPublicHttpLink ($dirAlias, $file)
 Will create a link to an object in a public folder alias.
static getPublicFolder ($dirAlias, $publicFolder=NULL)
 Gets the folder in a public directory alias.
static getPublicFile ($dirAlias, $file)
 Gets the file in a public directory alias.
static parseTimeSpan ($string)
 Parses a time value.

Protected Member Functions

 __construct (spunQ_File $file, $module, $name)
 Constructor.
 initFromDocComments (spunQ_File $file)
 Will initialize this instance using the doc comments in a file See class description for an explanation of the expected doc format.
 callPageFile ($variables)
 Helper function for calling the page file with a clean scope.
 setTitleFromDocComment ($doc)
 Sets $title from the parsed doc comment block of the page file.
 addTemplatesFromDocComment ($doc)
 Adds $templates from the parsed doc comment block of the page file.
 addVariableDeclarationsFromDocComment ($doc, $file)
 Adds $requiredVariables $title from the parsed doc comment block of the page file.
 addRequestMethodsFromDocComment ($doc)
 Generates $requiredRequestMethod from the parsed doc comment block of the page file.
 addAllowedUsersFromDocComment ($doc)
 Adds $allowedUsers from the parsed doc comment block of the page file.
 addAllowedGroupsFromDocComment ($doc)
 Adds $allowedGroups from the parsed doc comment block of the page file.
 setCacheTimeoutFromDocComment ($doc)
 Sets cache timeout from the parsed doc comment block of the page file.
 addVariableDefaultsFromDocComment ($doc)
 Adds $variableDefaultDeclarations from the parsed doc comment block.
 addCacheOptionsFromDocComment ($doc)
 addUrlTemplatesFromDocComment ($doc)
 Adds $urlTemplates from the parsed doc comment block of the page file.
 addUrlManagerFromDocComment ($doc)
 Replaces the $urlManager with the one provided in the doc comment.

Static Protected Member Functions

static getCache ()
 Initializes and returns the spunQ_ModificationBasedCacheInterface.

Protected Attributes

 $pageFile
 The page file this entry point definition was extracted from.
 $name
 Name of this entry point.
 $title
 Title of this entry point.
 $urlTemplates = array()
 The url templates matching this entry point.
 $templates = array()
 Templates to be included when answering a request.
 $requiredVariables = array()
 Variables required by the url templates.
 $requiredRequestMethod = 0
 Possible request methods for this entry point A combination of the spunQ_IHttpRequest::REQUEST_* constants, combined using binary AND.
 $variableDefaults = NULL
 Default values for variables.
 $variableDefaultDeclarations = array()
 Default value declarations for variables.
 $allowedUsers = array()
 Name of users allowed to view the page.
 $allowedGroups = array()
 Name of groups allowed to view the page.
 $secondsToCache = 0
 Number of seconds to cache the result of this page.
 $urlManager = 'spunQ.default'
 The name of the spunQ_UrlVariableConverter to use.
 $cacheOptions = array()
 Mapping cache options to their values.

Static Protected Attributes

static $all = NULL
 Array containing all entry points that were found in the configuration.
static $maxLastModificationTime = NULL
static $cache = NULL
 Cache for expensive operations.


Detailed Description

An entry point to the application for HTTP connections.

An entry point is defined as certain conditions which a request must meet in order to be fulfilled and the definition of steps involved in the fulfillment thereof.
The most obvious property of an entry point is the url that is served. The entry point may be defined to be serving the url www.example.com/users, for example. Other conditions might involve the type of the request (get/post/put/head...), the user that is currently logged in or the groups that user is a member of.
Another responsibility of this class is the storage of actions to take in order to fulfill the request. All code that is evaluated during the resolution of the request will print the results as if it was sending the result back normally. That output can be captured through output buffering which must start before calling invoke().
One important definition is that of a url template: In order to allow passing dynamic values in urls, we need a way to describe the format of the url without giving concrete values. This is where the url template comes into play: it is a pseudo-url containing variable definitions in curly braces at some points. An example is /user/{user}. The type of the variables need to be defined too, for the class to be able to create a url for this entry point with distinct values for its variables. An entry point can possess multiple url templates. These templates are further broken down into variants with distinct names, each variant containing multiple templates. The same page for displaying a user profile above could have a variant called german, consisting of the templates /benutzer/{user} and /mitglied/{user}.
More details on variables in templates: One might have noticed that the above template has the variable called user. The type of this variable is possibly spunQ.User or a sub-class thereof. If the method createHtmlLink() is called on that entry point, an object of type spunQ_User needs to be converted to a string value. Only storable objects can be converted this way and the string representation of such objects is merely their id. To allow more user-friendly urls, multiple members of the storable object may be specified in the url template: /user/{user=id|username}. Now both the id and the username may be used to address a user in the url. Note that only members with the @unique option should be used, since detection of multiple values (i.e. if multiple users have the same user name) will lead to a runtime exception.
All information to create an entry point can be extracted from so-called page-files. These are simple php pages starting with a doc comment block and an optional code block. The required tags in the doc comments are the following:

See also:
spunQ_Template For more information on templates.

Definition at line 179 of file HttpEntryPoint.class.php.


Constructor & Destructor Documentation

spunQ_HttpEntryPoint::__construct ( spunQ_File file,
module,
name 
) [protected]

Constructor.

Parameters:
$file The page file to extract information from.
$name Alias of this entry point

Definition at line 481 of file HttpEntryPoint.class.php.


Member Function Documentation

spunQ_HttpEntryPoint::addAllowedGroupsFromDocComment ( doc  )  [protected]

Adds $allowedGroups from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 813 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::addAllowedUsersFromDocComment ( doc  )  [protected]

Adds $allowedUsers from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 801 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::addRequestMethodsFromDocComment ( doc  )  [protected]

Generates $requiredRequestMethod from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 774 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::addTemplatesFromDocComment ( doc  )  [protected]

Adds $templates from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 746 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::addUrlManagerFromDocComment ( doc  )  [protected]

Replaces the $urlManager with the one provided in the doc comment.

This will set $urlManager to the string extracted. It will be converted to the proper spunQ_IUrlManager object on demand.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 887 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::addUrlTemplatesFromDocComment ( doc  )  [protected]

Adds $urlTemplates from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 862 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::addVariableDeclarationsFromDocComment ( doc,
file 
) [protected]

Adds $requiredVariables $title from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
$file The file containing the doc comment.
Returns:
void

Definition at line 759 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::addVariableDefaultsFromDocComment ( doc  )  [protected]

Adds $variableDefaultDeclarations from the parsed doc comment block.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 837 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::callPageFile ( variables  )  [protected]

Helper function for calling the page file with a clean scope.

Parameters:
$variables The variables received through the url
Returns:
map<string,any> Mapping of variable names to values that have been defined in the page file.

Definition at line 718 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::createPublicHttpLink ( dirAlias,
file 
) [static]

Will create a link to an object in a public folder alias.

The public folder needs to be configured as "spunQ.html.static.$dirAlias".

Parameters:
$dirAlias The alias of the directory as defined in the spunQ configuraiton.
$file The actual file name.
Returns:
string

Definition at line 319 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::getAll (  )  [static]

Gets all known entry points, mapped by their alias.

Returns:
array<string,spunQ_HttpEntryPoint>

Definition at line 216 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::getAllowedGroups (  ) 

Provides names of groups that are allowed to acces this entry point.

If this and getAllowedUsers() return an empty array, it means that everyone is allowed to use this entry point.

Returns:
array<string>

Definition at line 582 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::getAllowedUsers (  ) 

Provides usernames of users that are allowed to acces this entry point.

See also:
getAllowedGroups()
Returns:
array<string>

Definition at line 572 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::getByName ( name  )  [static]

Will find the entry point with given name.

Parameters:
$name The name of the spunQ_HttpEntryPoint to find.
Returns:
spunQ_HttpEntryPoint

Definition at line 261 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::getCache (  )  [static, protected]

Initializes and returns the spunQ_ModificationBasedCacheInterface.

Returns:
spunQ_ModificationBasedCacheInterface

Definition at line 199 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::getCacheOptions (  ) 

Returns a mapping of cache options to their values.

Returns:
array

Definition at line 590 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::getForRequest ( spunQ_IHttpRequest request,
&$  statusCode 
) [static]

Will find the spunQ_HttpEntryPoint that can respond to given request.

Parameters:
$request The request to find entry point for.
Returns:
spunQ_HttpEntryPoint Or NULL if no entry point was matched.

Definition at line 274 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::getOneCallback ( module,
pageFiles 
) [static]

Gets spunQ_HttpEntryPoint objects for a single module.

Parameters:
$module The module to get entry points for.
$pageFiles Return value of spunQ_Module::getPageFiles()
Returns:
array Array of spunQ_HttpEntryPoint objects, mapped by their name.

Definition at line 247 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::getPublicFile ( dirAlias,
file 
) [static]

Gets the file in a public directory alias.

See also:
spunQ_Folder::getByAlias()
Parameters:
$dirAlias The directory alias.
$file The name of the file to retrieve.
Returns:
spunQ_File
Exceptions:
spunQ_IOException If no folder was configured for given alias.

Definition at line 353 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::getPublicFolder ( dirAlias,
publicFolder = NULL 
) [static]

Gets the folder in a public directory alias.

See also:
spunQ_Folder::getByAlias()
Parameters:
$dirAlias The directory alias.
$folder The name of the folder to retrieve.
Returns:
spunQ_Folder
Exceptions:
spunQ_IOException If no folder was configured for given alias.

Definition at line 337 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::getRequiredRequestMethod (  ) 

Possible request methods for this entry point A combination of the spunQ_IHttpRequest::REQUEST_* constants, combined using binary AND.

Returns:
integer

Definition at line 704 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::getTitle (  ) 

Getter for the title of this entry point.

Returns:
string

Definition at line 536 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::getVariableDefaultDeclarations (  ) 

Returns default declarations of this entry point.

This merely returns the strings as parsed out of the entry points doc comment. To get the concrete values, use getVariableDefaults().

Returns:
array<string> Mapping opf variable names to their default declarations.

Definition at line 680 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::getVariableDefaults (  ) 

Returns default variables for this entry point.

Returns:
array Mapping of variable names to default values.

Definition at line 663 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::initFromDocComments ( spunQ_File file  )  [protected]

Will initialize this instance using the doc comments in a file See class description for an explanation of the expected doc format.

Parameters:
$file The file to read doc comments from.
Returns:
void
Exceptions:
spunQ_DocumentationError 

Definition at line 499 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::invokeCallback ( array $  variables,
captureOutput = true 
)

Callback function for the cache used by invoke().

Parameters:
$variables The variables required to show the templates.
$captureOutput Whether the output of the template should be captured and returned. This is necessary if the result is going to be cached, unnecessary otherwise.
Returns:
string? void if $captureOutput is false.

Definition at line 640 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::isCallableByCurrentUser (  ) 

Checks whether the current user is allowed to call the entry point.

Will consult getAllowedGroups() and getAllowedUsers().

Returns:
boolean

Definition at line 599 of file HttpEntryPoint.class.php.

static spunQ_HttpEntryPoint::parseTimeSpan ( string  )  [static]

Parses a time value.

A time span should be a number, optionally followed by 's', 'm', 'h' or 'd' for seconds, minutes, hours and days respectively. The unit defaults to seconds.

Parameters:
$string The string to parse.
Returns:
integer The amount of seconds represented by the string.

Definition at line 365 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::setCacheTimeoutFromDocComment ( doc  )  [protected]

Sets cache timeout from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 825 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::setTitleFromDocComment ( doc  )  [protected]

Sets $title from the parsed doc comment block of the page file.

Parameters:
$doc The value returned by spunQ_Module::parseDocComment().
Returns:
void

Definition at line 734 of file HttpEntryPoint.class.php.


Member Data Documentation

spunQ_HttpEntryPoint::$all = NULL [static, protected]

Array containing all entry points that were found in the configuration.

Type:
array<spunQ_HttpEntryPoint>

Definition at line 185 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$allowedGroups = array() [protected]

Name of groups allowed to view the page.

Type:
array<string>

Definition at line 456 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$allowedUsers = array() [protected]

Name of users allowed to view the page.

Type:
array<string>

Definition at line 450 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$cache = NULL [static, protected]

Cache for expensive operations.

Type:
spunQ_ModificationBasedCacheInterface

Definition at line 193 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$cacheOptions = array() [protected]

Mapping cache options to their values.

Type:
array

Definition at line 474 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$name [protected]

Name of this entry point.

Type:
string

Definition at line 395 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$pageFile [protected]

The page file this entry point definition was extracted from.

Type:
spunQ_File

Definition at line 389 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$requiredRequestMethod = 0 [protected]

Possible request methods for this entry point A combination of the spunQ_IHttpRequest::REQUEST_* constants, combined using binary AND.

Type:
integer

Definition at line 428 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$requiredVariables = array() [protected]

Variables required by the url templates.

Type:
map<string,string> Mapping of variable names to their type description.

Definition at line 420 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$secondsToCache = 0 [protected]

Number of seconds to cache the result of this page.

Type:
integer

Definition at line 462 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$templates = array() [protected]

Templates to be included when answering a request.

Parameters:
arary<string> Array of template aliases.

Definition at line 413 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$title [protected]

Title of this entry point.

Type:
string

Definition at line 401 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$urlManager = 'spunQ.default' [protected]

The name of the spunQ_UrlVariableConverter to use.

Type:
string

Definition at line 468 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$urlTemplates = array() [protected]

The url templates matching this entry point.

Type:
array<string>

Definition at line 407 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$variableDefaultDeclarations = array() [protected]

Default value declarations for variables.

Default values as declared in the doc comment of the enttry point.

Type:
array Mapping of variable names to their default value declarations. The real default values are obtained by calling spunQ_IUrlManager::processDefaultValue().

Definition at line 444 of file HttpEntryPoint.class.php.

spunQ_HttpEntryPoint::$variableDefaults = NULL [protected]

Default values for variables.

If a url template omits a variable, this default value will be assumed.

Type:
array<any> Mapping of variable names to their default value.

Definition at line 435 of file HttpEntryPoint.class.php.


The documentation for this class was generated from the following file:

Generated on Fri Jul 1 11:12:40 2011 for spunQ3 by  doxygen 1.5.9