Site:Interfaces

Revision as of 09:39, 27 June 2012

Introduction

Context Interfaces encapsulate various functionality available to you during integration.

ApplicationContext

The ApplicationContext is at the heart of it all. It is the gateway to all other contexts that might be necessary for execution of a BackendContext.

getLicenseContext()

@return a LicenseContext.

getDatabaseContext()

@return a DatabaseContext.

getGlobalContext()

@return a GlobalContext.

getAuthContext()

@return a AuthContext.

ApiContext

The ApiContext is responsible for retrieving information necessary to properly execute an ApiQuery.

getSafeLocalStorageString(value)

@return a filtered version of param:value that can be trusted for referencing files on local storage.

getParam(key, default = null)

@return the value for param:key from the request either via GET or POST parameters.

ApiQuery

getInternalName()

@return the internal name of this query. This value must be hard-coded inside this function and must be unique across all other ApiQueries.

execute(ApiContext api, ApiOutputFactory outputFactory)

@return ApiOutput. This function must be overridden by each backend context.

getApplicationContext()

@return ApplicationContext. This dependency is injected into each ApiQuery upon initialization.

ApiOutputFactory

success(item = null, continue = null)

@return an ApiOutput object that indicated successful execution of an ApiQuery.

error(msg)

@return an ApiOutput object that indicated failed execution of an ApiQuery.

ApiOutput

isSuccessful()

@return a boolean indicating whether this ApiOutput represents successful execution of an ApiQuery.

AuthContext

The AuthContext is responsible for providing all necessary functionality for authenticated users and their various access.

isLoggedIn()

@return a boolean on whether or not there is an authenticated user.

hasUser()

@return a boolean on whether or not there is an authenticated user and if that authenticated user is a User object.

getUser()

@return a User object for the authenticated user.

isUser(id)

@return a boolean on whether the param:id represents the current authenticated user (if there is an authenticated user). This is shorthand for doing a check of hasUser() with getUser()->id == id.

hasOwner()

@return a boolean on whether or not there is an authenticated user and if that authenticated user is an Owner object.

getOwner()

@return a Owner object for the authenticated user.

isOwner(id)

@return a boolean on whether the param:id represents the current authenticated owner (if there is an authenticated user). This is shorthand for doing a check of hasOwner() with getOwner()->id == id.

isAdministrator()

@return a boolean on whether or not the authenticated user is an administrator.

isModerator()

@return a boolean on whether or not the authenticated user is a moderator.

DatabaseContext

The DatabaseContext is responsible for providing the necessary functionality to interact with all relevant databases.

getNames()

@return an Array of the available database names.

closeAll()

closes all of the database connections.

getDB(name)

@return a SQLDB object.

getDBOption(name, option)

@return a database option; options include: backups

getBackDB()

@return a SQLDB object for the backend database; this is equivalent to getDB("back")

getBlobDB()

@return a SQLDB object for the blob database; this is equivalent to getDB("blob")

getStatDB()

@return a SQLDB object for the statistics database; this is equivalent to getDB("stat")

GlobalContext

The GlobalContext is responsible for providing access to information that is constant across all backend contexts.

getSite()

@return a Site object that represents the current site.

getNow()

@return an integer representing the current unix timestamp.

getGeo()

@return a Geo object that reprents the current location (countrycode, regioncode, city) of the request.

LicenseContext

The LicenseContext is responsible for providing information stored within the license.

getId()

@return the license id.

getConfigValue(key)

@return the configuration value that is stored for param:key.

getServerConfigValue(key)

@return the server configuration value that is stored for param:key; the server represents the actual server that is executing this function call... meaning the return value may change depending on which server is executing this function.

isEnabled(option)

@return a boolean on whether or not param:option is supported by the license.

getMerchants()

@return an Array of associative arrays representing all the merchants within the license.

getServers()

@return an Array of associative arrays representing all the servers within the license.

BackendContext

TODO: summarize

getUrlArgs()

getContextArgs()

getConfigParam()

BackendQuery

getInternalName()

@return the internal name of this query. This value must be hard-coded inside this function and must be unique across all other BackendQueries.

getDisplayName()

@return the display name of this query.

getLayoutPosition()

@return the layout position of this query so that it can show up higher/lower in a list of all contexts. The default value of this function is 0 and then sorting is alphabetical in ascending order.

isDependantOnScope(scopeKey)

@return a boolean on whether or not this query is dependent upon this scopeKey. This is important to signal whether or not execute(...) function is dependent upon scope produced by other backend contexts.

isCacheable()

@return a boolean on whether or not this query can be cached. Caching is useful for performance optimizations when the query's output doesn't change frequently.

getConsumableParams()

@return Array of param names. This function is necessary to properly handle caching of this context. This function also is used by the helper function getParam().

filterParam(paramName, paramValue, whitelist = Array)

@return the filtered value of paramValue. This function should be overridden by each context that processes input params from the URL.

getParam(BackendContext backend, paramName, default)

@return the proper value for paramName. This is a helper function that properly handles whether or not this value is supported by the context and applies any param whitelisting specified by the BackendContext. This function references the UrlArgs from the BackendContext.

execute(BackendContext backend, ScopeContext scope)

@return an object representing the query execution. This result is later passed into the processResult function. This function must be overridden by each backend context.

processResult(BackendContext backend, BackendOutputFactory outputFactory, result)

@return BackendOutput. This function must be overridden by each backend context.

getApplicationContext()

@return ApplicationContext. This dependency is injected into each BackendQuery upon initialization.

BackendOutputFactory

create()

@return a BackendOutput object.

applyObjectExtras([#BackendOutput|BackendOutput]] output, type)

@return an Array of extra information based on param:output.

BackendOutput

This interface is responsible for manipulating for storing information obtained from a BackendQuery execution.

get(key)

@return the value stored via param:key.

has(key)

@return a boolean on whether or not a value exists for param:key.

set(key, val)

store param:val into the iHDF via param:key.

merge(prefixKey, iHDF)

merge another iHDF into the current iHDF and prefix all keys by the param:prefixKey.

getHashMap()

@return an associative Array of all of the key/value pairs stored within this iHDF object.

getScope()

@return a ScopeContext that has relevant information that should be passed to future BackendQueries.

ScopeContext

The ScopeContext provides relevant scope to consider during various backend processes. At it's core the ScopeContext is a hash-table of objects.

has(key)

@return a boolean on whether or not this key exists.

get(key, default = "")

@return an object for the relevant key.

set(key, value)

stores param: value under param: key

getKeys()

@return an Array of all keys.

SQLDB

getUsername()

@return the username used for authentication to the database.

getPassword()

@return the username used for authentication to the database.

getHost()

@return the hostname used for connecting to the database.

getName()

@return the default database name used once connected to the database.

open(selectDatabase = true)

@return the database resource that just got opened. This function is used automatically inside all other functions that require an active connection. This function mostly serves the purpose of checking if a connection can be made before issuing queries.

param:selectDatabase allows automatic database selection for the default database included in the SQLDB object.

close()

this closes the database connection.

esc(value)

@return the properly escaped version of param:value. This function prevents SQL injection attacks.

query(queryValue)

@return a SQL resource for the particular query or FALSE if there is a problem.

queryOrDie(queryValue)

@return a SQL resource for the particular query or the entire script execution halts with an error message. Technically this should never be used, but is here as a convenience for quick integration with basic queries that should never fail.

queryAssocMulti(queryValue, indexField = null)

@return an Array with each array element representing a table row.

param:indexField allows custom indexing into the Array returned, if non-null. Otherwise, numerical indexing is used for each array element.

getAffectedRowCount()

@return the number of rows that were affected by the previous query.

getTotalResultsCount()

@return the total number of results that would be possible by the previous query. This is only value if SQL_CALC_FOUND_ROWS is used in the previous SELECT statement.

startTransaction()

enables transaction handling for all future queries.

commitTransaction()

completes the transaction and guarantees successful execution for all previous queries issued after the startTransaction() call.

rollbackTransaction()

disables all queries that were issued after the startTransaction() call.

selectDatabase(dbName)

performs a database change for all future queries.

getLastQuery()

@return the last query issued to the database.

getError()

@return a formatted message with all relevant error information for the previous query.

TaskContext

The TaskContext is responsible for providing access to the various requirements of an background task.

getLicenseContext()

@return a LicenseContext.

getDatabaseContext()

@return a DatabaseContext.