Documentation

SafetyDataStructureVariable
in package

FinalYes

SafetyDataStructureVariable

High performance static repository for database tables.

Features:

  • static memory storage
  • optional external cache support
  • automatic is_active filtering
  • dynamic searching
  • multi-column filtering
  • sorting
  • pagination
  • value extraction
  • existence checks
  • distinct values
  • preload support

Data source priority:

  1. Static memory
  2. External cache
  3. Database

Example:

$repo = new SafetyDataStructureVariable( $pdo, $cache );

$users = $repo->search( 'users', [ 'role'=>'admin' ], 'created_at', 'desc' );

Table of Contents

Properties

$cache  : CacheWrapper|null
$cachePrefix  : string
$cacheTtl  : int
$connectionKey  : string
$database  : Database
$memoryStore  : array<string|int, mixed>
Static data store: [connectionKey][tableName] => array<array<string,mixed>>

Methods

__construct()  : mixed
all()  : array<int, array<string, mixed>>
Returns all active rows matching the given table_name value.
clearCache()  : void
Clears static memory and external cache.
columns()  : array<int, string>
Returns the list of available columns from the first matching table_name group.
count()  : int
Counts matching active rows.
distinct()  : array<int, mixed>
Returns values from a selected column with unique results.
exists()  : bool
Checks whether at least one matching active row exists.
first()  : array<string, mixed>|null
Returns the first matching active row.
firstByTableAndColumnName()  : array<string, mixed>|null
Returns the first matching row by table_name and column_name.
firstWhere()  : array<string, mixed>|null
Returns the first matching row by a single column filter.
preload()  : void
Preloads the full active dataset into static memory.
refresh()  : void
Reloads the full dataset from the database.
search()  : array<int, array<string, mixed>>
Searches dynamically inside one logical table group.
searchAcrossColumns()  : array<int, array<string, mixed>>
Searches for a value across all columns inside one logical table group.
searchStatic()  : array<int, array<string, mixed>>
Searches dynamically across all loaded rows, regardless of table_name value.
tables()  : array<int, string>
Returns the list of unique table_name values currently loaded in memory.
value()  : mixed
Returns a single column value from the first matching row.
values()  : array<int, mixed>
Returns a list of values from a selected column.
where()  : array<int, array<string, mixed>>
Returns rows filtered by a single column.
whereTableAndColumnName()  : array<int, array<string, mixed>>
Returns rows filtered by table_name and column_name.
whereTableName()  : array<int, array<string, mixed>>
Alias for all().
whereValueKey()  : array<int, array<string, mixed>>
Returns rows filtered by table_name and value_key.
betweenCompare()  : bool
Performs a BETWEEN comparison.
cacheKey()  : string
Creates a cache key.
compare()  : bool
Compares two values using a selected operator.
compareValues()  : int
Performs a loose comparison useful for sorting.
getAllRows()  : array<int, array<string, mixed>>
Returns all active rows from the database, memory store, or external cache.
getRowsByTableNameValue()  : array<int, array<string, mixed>>
Returns rows filtered by table_name value.
likeCompare()  : bool
Performs a LIKE-style comparison.
loadAllRowsFromDatabase()  : array<int, array<string, mixed>>
Loads all active rows from the database.
normalizeSortOrder()  : string
Normalizes the sort direction.
sortRows()  : array<int, array<string, mixed>>
Sorts rows by a selected column and direction.

Properties

$memoryStore

Static data store: [connectionKey][tableName] => array<array<string,mixed>>

private static array<string|int, mixed> $memoryStore = []

Methods

all()

Returns all active rows matching the given table_name value.

public all(string $tableNameValue[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, array<string, mixed>>
Parameters
$tableNameValue : string

Value from the table_name column.

Example: 'users'

$sortBy : string = 'sort_order'

Column used for sorting.

Example: 'sort_order' 'id' 'column_name'

$sortOrder : string = 'asc'

Sort direction.

Allowed values:

  • asc
  • desc
Return values
array<int, array<string, mixed>>

clearCache()

Clears static memory and external cache.

public clearCache([string|null $tableNameValue = null ]) : void

If $tableNameValue is null, the full connection scope is cleared.

Parameters
$tableNameValue : string|null = null

Optional value from the table_name column.

columns()

Returns the list of available columns from the first matching table_name group.

public columns(string $tableNameValue) : array<int, string>
Parameters
$tableNameValue : string

Value from the table_name column.

Return values
array<int, string>

count()

Counts matching active rows.

public count(string $tableNameValue[, array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : int
Parameters
$tableNameValue : string

Value from the table_name column.

$filters : array<string, mixed> = []

Search filters.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
int

distinct()

Returns values from a selected column with unique results.

public distinct(string $tableNameValue, string $columnName[, array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, mixed>
Parameters
$tableNameValue : string

Value from the table_name column.

$columnName : string

Column to extract.

$filters : array<string, mixed> = []

Search filters.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<int, mixed>

exists()

Checks whether at least one matching active row exists.

public exists(string $tableNameValue[, array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : bool
Parameters
$tableNameValue : string

Value from the table_name column.

$filters : array<string, mixed> = []

Search filters.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
bool

first()

Returns the first matching active row.

public first(string $tableNameValue[, array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<string, mixed>|null
Parameters
$tableNameValue : string

Value from the table_name column.

$filters : array<string, mixed> = []

Filter structure.

Supported formats:

[ 'column_name' => 'email', 'value_key' => 'primary_email', 'sort_order' => 10, 'id' => 1 ]

Advanced format:

[ 'sort_order' => [ 'operator' => '>=', 'value' => 10 ], 'column_name' => [ 'operator' => 'LIKE', 'value' => '%email%' ] ]

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<string, mixed>|null

firstByTableAndColumnName()

Returns the first matching row by table_name and column_name.

public firstByTableAndColumnName(string $tableNameValue, string $columnName, mixed $value[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<string, mixed>|null
Parameters
$tableNameValue : string

Value from the table_name column.

$columnName : string

Value from the column_name column.

$value : mixed

Expected value.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<string, mixed>|null

firstWhere()

Returns the first matching row by a single column filter.

public firstWhere(string $tableNameValue, string $columnName, mixed $value[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<string, mixed>|null
Parameters
$tableNameValue : string

Value from the table_name column.

$columnName : string

Column name used for filtering.

$value : mixed

Expected value.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<string, mixed>|null

preload()

Preloads the full active dataset into static memory.

public preload([array<int, string>|null $tableNames = null ]) : void

Optionally warms up selected logical table groups by table_name.

Parameters
$tableNames : array<int, string>|null = null

Optional list of values from the table_name column.

Example: [ 'users', 'products', 'categories' ]

search()

Searches dynamically inside one logical table group.

public search(string $tableNameValue[, array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ][, int|null $limit = null ][, int $offset = 0 ]) : array<int, array<string, mixed>>

Supported operators:

  • =
  • !=

  • =

  • <
  • <=
  • LIKE
  • NOT LIKE
  • IN
  • NOT IN
  • BETWEEN
  • IS NULL
  • IS NOT NULL

Filter structure examples:

Simple: [ 'column_name' => 'email', 'value_key' => 'primary_email' ]

Advanced: [ 'sort_order' => [ 'operator' => '>=', 'value' => 10 ], 'column_name' => [ 'operator' => 'LIKE', 'value' => '%email%' ], 'value_key' => [ 'operator' => 'IN', 'value' => ['a', 'b', 'c'] ] ]

Special rule: The repository always enforces is_active = 1.

Parameters
$tableNameValue : string

Value from the table_name column.

$filters : array<string, mixed> = []

Filtering conditions.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

$limit : int|null = null

Maximum number of rows returned.

$offset : int = 0

Offset for pagination.

Return values
array<int, array<string, mixed>>

searchAcrossColumns()

Searches for a value across all columns inside one logical table group.

public searchAcrossColumns(string $tableNameValue, mixed $needle[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, array<string, mixed>>
Parameters
$tableNameValue : string

Value from the table_name column.

$needle : mixed

Value to search for.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<int, array<string, mixed>>

searchStatic()

Searches dynamically across all loaded rows, regardless of table_name value.

public searchStatic([array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ][, int|null $limit = null ][, int $offset = 0 ]) : array<int, array<string, mixed>>
Parameters
$filters : array<string, mixed> = []

Filtering conditions in the same format as search().

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

$limit : int|null = null

Maximum number of rows returned.

$offset : int = 0

Offset for pagination.

Return values
array<int, array<string, mixed>>

tables()

Returns the list of unique table_name values currently loaded in memory.

public tables() : array<int, string>
Return values
array<int, string>

value()

Returns a single column value from the first matching row.

public value(string $tableNameValue, string $valueKey[, array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : mixed
Parameters
$tableNameValue : string

Value from the table_name column.

$valueKey : string

Column name to extract.

Example: 'column_name' 'value_key' 'sort_order'

$filters : array<string, mixed> = []

Search filters.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

values()

Returns a list of values from a selected column.

public values(string $tableNameValue, string $columnName[, array<string, mixed> $filters = [] ][, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, mixed>
Parameters
$tableNameValue : string

Value from the table_name column.

$columnName : string

Column to extract.

$filters : array<string, mixed> = []

Search filters.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<int, mixed>

where()

Returns rows filtered by a single column.

public where(string $tableNameValue, string $columnName, mixed $value[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, array<string, mixed>>
Parameters
$tableNameValue : string

Value from the table_name column.

$columnName : string

Column name used for filtering.

$value : mixed

Expected value.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<int, array<string, mixed>>

whereTableAndColumnName()

Returns rows filtered by table_name and column_name.

public whereTableAndColumnName(string $tableNameValue, string $columnName, mixed $value[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, array<string, mixed>>
Parameters
$tableNameValue : string

Value from the table_name column.

$columnName : string

Value from the column_name column.

Example: 'email'

$value : mixed

Value to match against a chosen field.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<int, array<string, mixed>>

whereTableName()

Alias for all().

public whereTableName(string $tableNameValue[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, array<string, mixed>>
Parameters
$tableNameValue : string
$sortBy : string = 'sort_order'
$sortOrder : string = 'asc'
Return values
array<int, array<string, mixed>>

whereValueKey()

Returns rows filtered by table_name and value_key.

public whereValueKey(string $tableNameValue, mixed $valueKey[, string $sortBy = 'sort_order' ][, string $sortOrder = 'asc' ]) : array<int, array<string, mixed>>
Parameters
$tableNameValue : string

Value from the table_name column.

$valueKey : mixed

Value to match against the value_key column.

$sortBy : string = 'sort_order'

Column used for sorting.

$sortOrder : string = 'asc'

Sort direction.

Return values
array<int, array<string, mixed>>

betweenCompare()

Performs a BETWEEN comparison.

private betweenCompare(mixed $left, mixed $right) : bool
Parameters
$left : mixed
$right : mixed
Return values
bool

cacheKey()

Creates a cache key.

private cacheKey(string $scope) : string
Parameters
$scope : string

Cache scope name.

Return values
string

compare()

Compares two values using a selected operator.

private compare(mixed $left, string $operator, mixed $right) : bool
Parameters
$left : mixed
$operator : string
$right : mixed
Return values
bool

compareValues()

Performs a loose comparison useful for sorting.

private compareValues(mixed $left, mixed $right) : int
Parameters
$left : mixed
$right : mixed
Return values
int

getAllRows()

Returns all active rows from the database, memory store, or external cache.

private getAllRows() : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>

getRowsByTableNameValue()

Returns rows filtered by table_name value.

private getRowsByTableNameValue(string $tableNameValue) : array<int, array<string, mixed>>
Parameters
$tableNameValue : string

Value from the table_name column.

Return values
array<int, array<string, mixed>>

likeCompare()

Performs a LIKE-style comparison.

private likeCompare(mixed $left, mixed $right) : bool
Parameters
$left : mixed
$right : mixed
Return values
bool

loadAllRowsFromDatabase()

Loads all active rows from the database.

private loadAllRowsFromDatabase() : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>

normalizeSortOrder()

Normalizes the sort direction.

private normalizeSortOrder(string $sortOrder) : string
Parameters
$sortOrder : string

Sort direction.

Return values
string

sortRows()

Sorts rows by a selected column and direction.

private sortRows(array<int, array<string, mixed>> $rows, string $sortBy, string $sortOrder) : array<int, array<string, mixed>>
Parameters
$rows : array<int, array<string, mixed>>

Rows to sort.

$sortBy : string

Column used for sorting.

$sortOrder : string

Sort direction.

Return values
array<int, array<string, mixed>>
On this page

Search results