Site:Interfaces

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 BackendQuery.

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.

getItem()

@return the item data that should be passed along to the query callee.

getContinueUrl()

@return the URL that should be visited if isSuccessful() is true.

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.

BackgroundContext

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

getLicenseContext()

@return a LicenseContext.

getDatabaseContext()

@return a DatabaseContext.

BackgroundTask

The BackgroundTask provides a framework for how to run your background tasks.

getServerOption()

@return the option that controls whether or not this task can be run on the active server.

getMaxSimultaneousTasks()

@return the number of simultaneous tasks that can be run on the active server.

getTaskStartTime()

@return the start time that must be passed before this task can be run. This is useful for having tasks only run at certain times... such as a database backup late at night.

getIdleTimeout()

@return the amount of time that must pass before the task manager attempts to run this task again.

isActive()

@return whether or not this task can be run.

run()

run the background task.

getContext()

@return the BackgroundContext.

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

The Backend Context is responsible for passing the approrpriate information to the Backend Query. This usually consists of URL parameters on the actual page being viewed, along with some defaults that are specified while creating the site page.

getUrlArgs()

@return the URL parameters for the current page.

hasContextArg(key)

@return whether or not a context argument exists.

getContextArg(key)

@return the context argument stored with the param:key.

getConfigParam(key)

@return the configuration param stored with the param:key. These params are used while processing a backend query result into an BackendOutput object. These params are usually specified in the METADATA CONTROLS panel of the site page. An example of one of these params would be to use a HTML filter on all content descriptions to escape bad HTML.

BackendQuery

getInternalName()

@return the internal name of this query.

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 result of 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 BackendOutput via param:key.

merge(prefixKey, BackendOutput)

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

getHashMap()

@return an associative Array of all of the key/value pairs stored within this BackendOutput 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.