1. class
  2. Tfish
  3. \
  4. Criteria

Criteria

class Criteria

Sets conditions on database queries, used to compose a query.

Use this class to set parameters on database-related actions. Individual conditions are held within the item property, as CriteriaItem objects. Criteria holds the basic query parameters and controls how CriteriaItem are chained together (eg. with "AND", "OR").

See the Tuskfish Developer Guide for a full explanation and examples.

Traits

IntegerCheck
Validate and range check integers.
TraversalCheck
Validates that a filename or path does NOT contain directory traversals in any form.
ValidateString
Provides methods for validating UTF-8 character encoding and string composition.

Properties

$item
$condition
$groupBy
$limit
$offset
$order
$orderType
$secondaryOrder
$secondaryOrderType
$tag

Methods

bool
isInt(int $int, int $min = null, int $max = null)

Validate integer, optionally include range check.

from IntegerCheck
bool
hasTraversalorNullByte(string $path)

Check if a file path contains traversals (including encoded traversals) or null bytes.

from TraversalCheck
string
encodeEscapeUrl(string $url)

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

from ValidateString
bool
isAlnum(string $alnum)

Check that a string is comprised solely of alphanumeric characters.

from ValidateString
bool
isAlnumUnderscore(string $alnumUnderscore)

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

from ValidateString
bool
isAlpha(string $alpha)

Check that a string is comprised solely of alphabetical characters.

from ValidateString
bool
isUtf8(string $text)

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

from ValidateString
string
trimString(mixed $text)

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

from ValidateString
__construct()

Constructor.

add(CriteriaItem $criteriaItem, string $condition = "AND")

Add conditions (CriteriaItem) to a query.

setGroupBy(string $groupBy)

Set a GROUP BY condition on a query.

setLimit(int $limit)

Sets a limit on the number of database records to retrieve in a database query.

setOffset(int $offset)

Sets an offset (starting point) for retrieving records in a database query.

setOrder(string $column)

Sets the primary column to order query results by.

setOrderType(string $sort)

Sets the sort type (ascending or descending) for the primary order column of a result set.

setSecondaryOrder(string $column)

Sets the secondary column to order query results by.

setSecondaryOrderType(string $sort)

Sets the sort type (ascending or descending) for the secondary order column of a result set.

setTag(array $tags)

Set tag(s) to filter query results by.

unsetType(int $key)

Unset existing type criteria.

Details

in IntegerCheck at line 39
bool isInt(int $int, int $min = null, int $max = null)

Validate integer, optionally include range check.

Parameters

int $int Input to be tested.
int $min Minimum acceptable value.
int $max Maximum acceptable value.

Return Value

bool True if valid int and within optional range check, false otherwise.

in TraversalCheck at line 46
bool hasTraversalorNullByte(string $path)

Check if a file path contains traversals (including encoded traversals) or null bytes.

Directory traversals are not permitted in Tuskfish method parameters. If a path is found to contain a traversal it is presumed to be an attack. Encoded traversals are a clear sign of attempted abuse.

In general untrusted data should never be used to construct a file path. This method exists as a second line safety measure.

Parameters

string $path

Return Value

bool True if a traversal or null byte is found, otherwise false.

See also

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 67
__construct()

Constructor.

at line 75
add(CriteriaItem $criteriaItem, string $condition = "AND")

Add conditions (CriteriaItem) to a query.

Parameters

CriteriaItem $criteriaItem CriteriaItem object.
string $condition Condition used to chain CriteriaItems, "AND" or "OR" only.

at line 102
setGroupBy(string $groupBy)

Set a GROUP BY condition on a query.

Parameters

string $groupBy Column to group results by.

at line 128
setLimit(int $limit)

Sets a limit on the number of database records to retrieve in a database query.

Parameters

int $limit The number of records to retrieve.

at line 142
setOffset(int $offset)

Sets an offset (starting point) for retrieving records in a database query.

Parameters

int $offset The record to start retrieving results from, from a result set.

at line 156
setOrder(string $column)

Sets the primary column to order query results by.

Parameters

string $column Name of the primary column to order the query results by.

at line 172
setOrderType(string $sort)

Sets the sort type (ascending or descending) for the primary order column of a result set.

Parameters

string $sort Ascending (ASC) or descending (DESC) order.

at line 188
setSecondaryOrder(string $column)

Sets the secondary column to order query results by.

Parameters

string $column Name of the secondary column to order the query results by.

at line 204
setSecondaryOrderType(string $sort)

Sets the sort type (ascending or descending) for the secondary order column of a result set.

Parameters

string $sort Ascending (ASC) or descending (DESC) order.

at line 220
setTag(array $tags)

Set tag(s) to filter query results by.

Parameters

array $tags Array of tag IDs to be used to filter a query.

at line 248
unsetType(int $key)

Unset existing type criteria.

Used by content object handler subclasses to remove any existing type filter when they may need to set or reset it to a specific type.

Parameters

int $key Key of the item array containing the type filter.