class Preference

Holds Tuskfish site configuration (preference) data.

Traits

Provides common access to system languages.
Provides an array of time zones.
Provides methods for validating UTF-8 character encoding and string composition.

Methods

array
listLanguages()

Returns a list of languages in use by the system.

from Language
array
listTimezones()

Provide a list of timezone offsets.

from Timezones
string
encodeEscapeUrl(string $url)

URL-encode and escape a query string for use in a URL.

bool
isAlnum(string $alnum)

Check that a string is comprised solely of alphanumeric characters.

bool
isAlnumUnderscore(string $alnumUnderscore)

Check that a string is comprised solely of alphanumeric characters and underscores.

bool
isAlpha(string $alpha)

Check that a string is comprised solely of alphabetical characters.

bool
isUtf8(string $text)

Check if the character encoding of text is UTF-8.

string
trimString(mixed $text)

Cast to string, check UTF-8 encoding and strip trailing whitespace and control characters.

__construct(Database $database)

Constructor.

array
getPreferencesAsArray()

Converts the preference object to an array suitable for insert/update calls to the database.

load(array $input)

Update the preference object from an external data source (eg. form submission).

array
readPreferences()

Read out the site preferences into an array.

int
adminPagination()

No description

setAdminPagination(int $value)

Set the number of objects to display in a single admin page view.

string
siteAuthor()

Return site author

setSiteAuthor(string $value)

Set the name of the site author. Used to population page meta author tag.

int
cacheLife()

Return cache life.

setCacheLife(int $value)

Set life of items in cache (seconds).

int
closeSite()

Return the value of the site closed preference.

setCloseSite(int $value)

Open our close the site.

string
dateFormat()

Return date format.

setDateFormat(string $value)

Set the date format, used to convert timestamps to human readable form.

string
defaultLanguage()

Return default language.

setDefaultLanguage(string $value)

Set the default language for this Tuskfish installation.

string
siteDescription()

Return site description.

setSiteDescription(string $value)

Set the site description. Used in meta description tag.

string
siteEmail()

Return site email.

setSiteEmail(string $value)

Set the admin email address for the site.

int
enableCache()

Return enableCache.

setEnableCache(int $value)

Enable or disable the cache.

int
galleryPagination()

Return gallery pagination.

setGalleryPagination(int $value)

Set number of objects to display on the gallery page.

string
mapsApiKey()

No description

setMapsApiKey(string $value)

No description

int
minSearchLength()

Return minimum search length.

setMinSearchLength(int $value)

Set the minimum length of search terms (characters).

int
paginationElements()

Return number of elements in a pagination control.

setPaginationElements(int $value)

Set the default number of page slots to display in pagination elements.

int
rssPosts()

Return the number of items to include in a RSS feed.

setRssPosts(int $value)

Set number of items to display in RSS feeds.

int
searchPagination()

Number of items to include in a search page view.

setSearchPagination(int $value)

Set number of results to display on a search page view.

int
serverTimezone()

Return server timezone.

setServerTimezone(int $value)

Set the server timezone.

int
sessionLife()

Return session life (minutes).

setSessionLife(int $value)

Set the life of an idle session.

string
sessionName()

Return session name.

setSessionName(string $value)

Set the name (prefix) used to identify Tuskfish sessions.

string
siteCopyright()

Return site copyright.

setSiteCopyright(string $value)

Set the site meta copyright.

string
siteName()

Return site name.

setSiteName(string $value)

Set the title of the page.

int
siteTimezone()

Return site timezone.

setSiteTimezone(int $value)

Set the site timezone.

int
userPagination()

Number of items to display on a single user-side page.

setUserPagination(int $value)

Set the number of objects to display in a single page view on the public facing side of the site.

Details

in Language at line 42
array listLanguages()

Returns a list of languages in use by the system.

In the interests of brevity and sanity a full list is not provided. Add entries that you want to use to the array using ISO 639-1 two-letter language codes, which you can find at: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes. Be aware that deleting entries that are in use by your content objects will cause errors.

Return Value

array Array of languages in ISO 639-1 code => name format.

in Timezones at line 36
array listTimezones()

Provide a list of timezone offsets.

Return Value

array Array of timezone offsets.

in ValidateString at line 41
string encodeEscapeUrl(string $url)

URL-encode and escape a query string for use in a URL.

Trims, checks for UTF-8 compliance, rawurlencodes and then escapes with htmlspecialchars(). If you wish to use the data on a landing page you must decode it with htmlspecialchars_decode() followed by rawurldecode() in that order. But really, if you are using any characters that need to be encoded in the first place you should probably just stop.

Parameters

string $url Unescaped input URL.

Return Value

string Encoded and escaped URL.

in ValidateString at line 59
bool isAlnum(string $alnum)

Check that a string is comprised solely of alphanumeric characters.

Accented regional characters are rejected. This method is designed to be used to check database identifiers or object property names.

Parameters

string $alnum Input to be tested.

Return Value

bool True if valid alphanumerical string, false otherwise.

in ValidateString at line 77
bool isAlnumUnderscore(string $alnumUnderscore)

Check that a string is comprised solely of alphanumeric characters and underscores.

Accented regional characters are rejected. This method is designed to be used to check database identifiers or object property names.

Parameters

string $alnumUnderscore Input to be tested.

Return Value

bool True if valid alphanumerical or underscore string, false otherwise.

in ValidateString at line 95
bool isAlpha(string $alpha)

Check that a string is comprised solely of alphabetical characters.

Tolerates vanilla ASCII only. Accented regional characters are rejected. This method is designed to be used to check database identifiers or object property names.

Parameters

string $alpha Input to be tested.

Return Value

bool True if valid alphabetical string, false otherwise.

in ValidateString at line 113
bool isUtf8(string $text)

Check if the character encoding of text is UTF-8.

All strings received from external sources must be passed through this function, particularly prior to storage in the database.

Parameters

string $text Input string to check.

Return Value

bool True if string is UTF-8 encoded otherwise false.

in ValidateString at line 131
string trimString(mixed $text)

Cast to string, check UTF-8 encoding and strip trailing whitespace and control characters.

Removes trailing whitespace and control characters (ASCII <= 32 / UTF-8 points 0-32 inclusive), checks for UTF-8 character set and casts input to a string. Note that the data returned by this function still requires escaping at the point of use; it is not database or XSS safe.

As the input is cast to a string do NOT apply this function to non-string types (int, float, bool, object, resource, null, array, etc).

Parameters

mixed $text Input to be trimmed.

Return Value

string Trimmed and UTF-8 validated string.

at line 90
__construct(Database $database)

Constructor.

Parameters

Database $database Instance of the Tuskfish database class.

at line 104
array getPreferencesAsArray()

Converts the preference object to an array suitable for insert/update calls to the database.

Note that the output is not XSS escaped and should not be sent to display.

Return Value

array Array of object property/values.

at line 124
load(array $input)

Update the preference object from an external data source (eg. form submission).

The preference object will conduct its own internal data type validation and range checks.

Parameters

array $input Usually $_REQUEST data.

at line 155
array readPreferences()

Read out the site preferences into an array.

Return Value

array Array of site preferences.

at line 167
int adminPagination()

Return Value

int

at line 177
setAdminPagination(int $value)

Set the number of objects to display in a single admin page view.

Parameters

int $value Number of objects to view on a single page.

at line 189
string siteAuthor()

Return site author

Return Value

string Name of the site author.

at line 199
setSiteAuthor(string $value)

Set the name of the site author. Used to population page meta author tag.

Parameters

string $value Name of the site author.

at line 209
int cacheLife()

Return cache life.

Return Value

int Cache life in seconds.

at line 222
setCacheLife(int $value)

Set life of items in cache (seconds).

Items that expire will be rebuilt and re-written to the cache the next time the page is requested.

Parameters

int $value Expiry timer on cached items (seconds).

at line 234
int closeSite()

Return the value of the site closed preference.

Return Value

int Open (0) or closed (1).

at line 244
setCloseSite(int $value)

Open our close the site.

Parameters

int $value Site open (0) or closed (1).

at line 258
string dateFormat()

Return date format.

Return Value

string Ttemplate as per the PHP date() function.

at line 270
setDateFormat(string $value)

Set the date format, used to convert timestamps to human readable form.

See the PHP manual for date formatting templates: http://php.net/manual/en/function.date.php

Parameters

string $value Template for formatting dates.

at line 280
string defaultLanguage()

Return default language.

Return Value

string Two-letter ISO language code.

at line 290
setDefaultLanguage(string $value)

Set the default language for this Tuskfish installation.

Parameters

string $value ISO 639-1 two-letter language codes.

at line 312
string siteDescription()

Return site description.

Return Value

string

at line 322
setSiteDescription(string $value)

Set the site description. Used in meta description tag.

Parameters

string $value Site description.

at line 332
string siteEmail()

Return site email.

Return Value

string

at line 344
setSiteEmail(string $value)

Set the admin email address for the site.

Used in RSS feeds to populate the managingEditor and webmaster tags.

Parameters

string $value Email address.

at line 374
int enableCache()

Return enableCache.

Return Value

int Enabled (1) or disabled (0).

at line 384
setEnableCache(int $value)

Enable or disable the cache.

Parameters

int $value Enabled (1) or disabled (0).

at line 398
int galleryPagination()

Return gallery pagination.

Return Value

int Number of objects to display on a single page view.

at line 408
setGalleryPagination(int $value)

Set number of objects to display on the gallery page.

Parameters

int $value Number of objects to display on a single page view.

at line 417
string mapsApiKey()

Return Value

string

at line 422
setMapsApiKey(string $value)

Parameters

string $value

at line 434
int minSearchLength()

Return minimum search length.

Return Value

int Number of characters in a search term.

at line 448
setMinSearchLength(int $value)

Set the minimum length of search terms (characters).

Search terms less than this number of characters will be discarded. It is usually best to allow a minimum length of 3 characters; this allows searching for common acronyms without returning massive numbers of hits.

Parameters

int $value Minimum number of characters.

at line 462
int paginationElements()

Return number of elements in a pagination control.

Return Value

int

at line 474
setPaginationElements(int $value)

Set the default number of page slots to display in pagination elements.

Can be overridden manually in PaginationControl.

Parameters

int $value Number of page slots to display in pagination control.

at line 488
int rssPosts()

Return the number of items to include in a RSS feed.

Return Value

int

at line 498
setRssPosts(int $value)

Set number of items to display in RSS feeds.

Parameters

int $value Number of items to include in feed.

at line 512
int searchPagination()

Number of items to include in a search page view.

Return Value

int

at line 522
setSearchPagination(int $value)

Set number of results to display on a search page view.

Parameters

int $value Number of objects to display in a single page view.

at line 536
int serverTimezone()

Return server timezone.

Return Value

int

at line 546
setServerTimezone(int $value)

Set the server timezone.

Parameters

int $value Timezone.

at line 556
int sessionLife()

Return session life (minutes).

Return Value

int

at line 568
setSessionLife(int $value)

Set the life of an idle session.

User will be logged out after being idle for this many minutes.

Parameters

int $value Session life (minutes).

at line 582
string sessionName()

Return session name.

Return Value

string

at line 594
setSessionName(string $value)

Set the name (prefix) used to identify Tuskfish sessions.

If you change it, use something unpredictable.

Parameters

string $value Session name.

Return site copyright.

Return Value

string

at line 623
setSiteCopyright(string $value)

Set the site meta copyright.

Used to populate the dcterms.rights meta tag in the theme. Can be overridden in the theme.html file.

Parameters

string $value Copyright statement.

at line 633
string siteName()

Return site name.

Return Value

string

at line 648
setSiteName(string $value)

Set the title of the page.

Used to populate the meta title tag. Usually each page / object will specify a title, but if none is set this value will be used as the default. The title can be manually overriden on each page using the Metadata object (see comments at the bottom of controller scripts).

Parameters

string $value

at line 658
int siteTimezone()

Return site timezone.

Return Value

int

at line 670
setSiteTimezone(int $value)

Set the site timezone.

This is normally the timezone for your principal target audience.

Parameters

int $value Timezone.

at line 680
int userPagination()

Number of items to display on a single user-side page.

Return Value

int

at line 691
setUserPagination(int $value)

Set the number of objects to display in a single page view on the public facing side of the site.

Parameters

int $value Number of objects to display.