Documentation

AbstractDataBaseRepository extends DBObject
in package
implements DataRepository, Configurable

AbstractYes

An abstract implementation of the DataBaseRepository interface Extending this provides CRUD interaction with the configured database table

Tags
todo

Provide another layer to allow for non MySQL flavors of SQL

author

Jason Savell jsavell@library.tamu.edu

Table of Contents

Interfaces

DataRepository
An interface defining a DataRepository DataRepositories are utilized to perform CRUD actions on data stores
Configurable
An interface defining a Configurable class

Properties

$db  : DBInstance
$defaultOrderBy  : string|null
$gettableColumns  : array<string|int, string>|null
$primaryKey  : string
$primaryTable  : string
$searchableColumns  : array<string|int, string>|null
$site  : Site

Methods

add()  : string|false
Insert a row into the DB using $data
configure()  : void
Allows instantiators of a Configurable class to trigger instance configuration *after* the __constructor() is callled
get()  : array<string|int, mixed>|false
Get all rows from the $primaryTable, optionally ordered by $defaultOrderBy, with selected columns optionally limited to $gettableColumns
getAppConfiguration()  : array<string|int, mixed>
Provides a single instance of the global app configuration to all extenders of CoreObject
getById()  : mixed|false
Get the row whose 'id' matches the passed $id
getLogger()  : Logger
Provides a single instance of a configured Logger to all extenders of CoreObject
removeById()  : bool
Remove a row from the DB with an 'id' matching the passed $id
search()  : array<string|int, mixed>|false
Get all rows from the $primaryTable matching the search %$term% against a 'name' field
searchAdvanced()  : array<string|int, mixed>|false
Get all rows from the $primaryTable matching the provided field/value pairs search %$term% against a 'name' field
setSite()  : void
Set the Site context
update()  : bool
Update the row having ID of $id with the key/value pairs in $data
__construct()  : mixed
Extending classes configure themselves using this constructor.
buildIn()  : string
Returns a parametrized IN clause for use in a prepared statement
buildInsertStatement()  : string|false
Builds and executes an insert statement
buildMultiRowInsertStatement()  : bool
Builds and executes a single insert statement that inserts multiple new records
buildUpdateStatement()  : bool
Builds and executes an update statement
dbFormatDate()  : string
Returns an appropriate date format function for the SQL language
dbNow()  : string
Returns an appropriate CURRENT TIME function for the SQL language
dbTextMatch()  : string
Returns an appropriate text search function for the SQL language
executeQuery()  : array<string, array<string, string>>|false
Execute a query and return the results as an array
executeUpdate()  : bool
Execute an update query
getBaseQuery()  : string
Provides the base query for the extending repository
getBaseSearchQuery()  : array{'sql': string, 'bindparams': array}
Provides the default search query base for the extending repository
getGetQuery()  : string
Provides the default get query for the extending repository
getLastInsertId()  : string|false
Returns the id of the most recent insert query
getPrimaryTable()  : mixed
Provides the name of the primary table associated with the instance
getSearchableColumns()  : array<string|int, string>|null
Returns an array of column names that should be used to perform searches on records in a repository
getSearchQuery()  : array{'sql': string, 'bindparams': array}
Provides the default search query for the extending repository
getSite()  : Site
Get the Site context
logStatementError()  : void
Logs SQL errors to the logger
processResult()  : array<string|int, mixed>|Entity
Apply any needed processing to a single db result array
processResults()  : array<string|int, mixed>
Apply any needed processing to a db results array
queryWithIndex()  : array<string|int, mixed>|false
Query the DB and return the rows as a 1 or 2 dimensional indexed array
quote()  : string
quoteArray()  : array<string|int, string>

Properties

$db

protected DBInstance $db

An instance of the db class, providing the connection to the DB

$defaultOrderBy

protected string|null $defaultOrderBy

If provided, AbstractDataBaseRepository::get()) will ORDER BY this property.

$gettableColumns

protected array<string|int, string>|null $gettableColumns

If provided, AbstractDataBaseRepository::get()) will only SELECT the columns present in this array.

$primaryKey

protected string $primaryKey = 'id'

This is the name of the Primary Key for the $primaryTable managed by DatabaseRepositories extending this class

$primaryTable

protected string $primaryTable

This is the name of the DB table managed by DatabaseRepositories extending this class

$searchableColumns

protected array<string|int, string>|null $searchableColumns

If provided, AbstractDataBaseRepository::search()) will carry out its search on these columns

Methods

add()

Insert a row into the DB using $data

public add(array<string|int, mixed> $data) : string|false
Parameters
$data : array<string|int, mixed>

The data to be inserted into the $primaryTable

Return values
string|false —

The id of the inserted row on success, false on failure

configure()

Allows instantiators of a Configurable class to trigger instance configuration *after* the __constructor() is callled

public configure(Site $site) : void
Parameters
$site : Site

An implementation of the \Pipit\Interfaces\Site interface

get()

Get all rows from the $primaryTable, optionally ordered by $defaultOrderBy, with selected columns optionally limited to $gettableColumns

public get() : array<string|int, mixed>|false
Return values
array<string|int, mixed>|false —

$results A two dimensional array representing the resulting rows: array(array("id"=>1,"field"=>"value1"),array("id"=>2","field"=>"value2")), false on failure

getAppConfiguration()

Provides a single instance of the global app configuration to all extenders of CoreObject

public getAppConfiguration() : array<string|int, mixed>
Return values
array<string|int, mixed>

getById()

Get the row whose 'id' matches the passed $id

public getById(mixed $id) : mixed|false
Parameters
$id : mixed

The unique identifier for the row

Return values
mixed|false —

$results An array representing the resulting DB row, empty array if no match, false if the request failed

getLogger()

Provides a single instance of a configured Logger to all extenders of CoreObject

public getLogger() : Logger
Return values
Logger

removeById()

Remove a row from the DB with an 'id' matching the passed $id

public removeById(mixed $id) : bool
Parameters
$id : mixed

The unique identifier for the row to be removed

Return values
bool —

$result true on removal, false on failure

search()

Get all rows from the $primaryTable matching the search %$term% against a 'name' field

public search(string $term) : array<string|int, mixed>|false
Parameters
$term : string

The search criteria

Return values
array<string|int, mixed>|false —

$results A two dimensional array representing the resulting rows: array(array("id"=>1,"field"=>"value1"),array("id"=>2","field"=>"value2")), false on failure

searchAdvanced()

Get all rows from the $primaryTable matching the provided field/value pairs search %$term% against a 'name' field

public searchAdvanced(array<string, string> $data) : array<string|int, mixed>|false
Parameters
$data : array<string, string>

The search criteria field/value pair(s)

Return values
array<string|int, mixed>|false —

$results A two dimensional array representing the resulting rows: array(array("id"=>1,"field"=>"value1"),array("id"=>2","field"=>"value2")), false on failure

update()

Update the row having ID of $id with the key/value pairs in $data

public update(string $id, array<string|int, mixed> $data) : bool
Parameters
$id : string

The unique identifier for the row to be updated

$data : array<string|int, mixed>

The data with which to update the row

Return values
bool —

True on success, false on failure

__construct()

Extending classes configure themselves using this constructor.

protected __construct(string $primaryTable, string $primaryKey[, string|null $defaultOrderBy = null ][, array<string|int, string>|null $gettableColumns = null ][, array<string|int, string>|null $searchableColumns = null ]) : mixed
Parameters
$primaryTable : string

Required. This specializes an instance of an extending class to the given DB table name

$primaryKey : string

Required. Extending classes define the Primary Key of the table they manage

$defaultOrderBy : string|null = null

Optional. Explicitly define a column to order query results by

$gettableColumns : array<string|int, string>|null = null

Optional. AbstractDataBaseRepository::get()) will SELECT only these fields, when passed

$searchableColumns : array<string|int, string>|null = null

Optional. AbstractDataBaseRepository::search()) will search these columns

buildIn()

Returns a parametrized IN clause for use in a prepared statement

protected buildIn(array<string|int, mixed> $ar, array<string|int, mixed> &$bindparams[, string $varprefix = 'v' ]) : string
Parameters
$ar : array<string|int, mixed>

An array of values representing the contents of the IN clause

$bindparams : array<string|int, mixed>

A reference to the caller's array of binded parameters

$varprefix : string = 'v'

Can be used to avoid bind parameter naming collisions when calling multiple times within 1 statement

Return values
string —

The resulting IN clause

buildInsertStatement()

Builds and executes an insert statement

protected buildInsertStatement(array<string|int, mixed> $data[, string $table = null ]) : string|false
Parameters
$data : array<string|int, mixed>

An associative array (ColumnName->Value) of data representing the new DB record

$table : string = null

Optional - The table to insert the new record into. Defaults to $primaryTable

Return values
string|false —

Returns the ID of the new record on success, false on failure

buildMultiRowInsertStatement()

Builds and executes a single insert statement that inserts multiple new records

protected buildMultiRowInsertStatement(array<string|int, array<string, string>> $rows[, string $table = null ]) : bool
Parameters
$rows : array<string|int, array<string, string>>

An array of associative arrays (ColumnName->Value) of data representing the new DB records

$table : string = null

Optional - The table to insert the new records into. Defaults to $primaryTable

Return values
bool —

True on success, false on failure

buildUpdateStatement()

Builds and executes an update statement

protected buildUpdateStatement(string $id, array<string|int, mixed> $data[, string $table = null ]) : bool
Parameters
$id : string

The id of the record to be updated

$data : array<string|int, mixed>

An associative array (ColumnName->Value) of data representing the updated data

$table : string = null

Optional - The table to insert the new record into. Defaults to $primaryTable

Return values
bool —

True on success, false on failure

dbFormatDate()

Returns an appropriate date format function for the SQL language

protected dbFormatDate(string $field) : string
Parameters
$field : string

The name of the field to format

Return values
string

dbNow()

Returns an appropriate CURRENT TIME function for the SQL language

protected dbNow() : string
Return values
string

dbTextMatch()

Returns an appropriate text search function for the SQL language

protected dbTextMatch(string $fields, string $value) : string
Parameters
$fields : string

The fields to use for the search (field1,field2,..)

$value : string

The search criteria

Return values
string

executeQuery()

Execute a query and return the results as an array

protected executeQuery(mixed $sql[, array<string|int, mixed> $bindparams = NULL ]) : array<string, array<string, string>>|false 
@param string $sql the SQL query
Parameters
$sql : mixed
$bindparams : array<string|int, mixed> = NULL

: an array of values to be binded by PDO to any query parameters

Return values
array<string, array<string, string>>|false —

A two dimensional array representing the resulting rows: array(array("id"=>1,"field"=>"value1"),array("id"=>2","field"=>"value2")), false on failure

executeUpdate()

Execute an update query

protected executeUpdate(mixed $sql[, array<string|int, mixed> $bindparams = NULL ]) : bool 
@param string $sql The SQL query
Parameters
$sql : mixed
$bindparams : array<string|int, mixed> = NULL

An array of values to be binded by PDO to any query parameters

Return values
bool —

True on success, false on anything else

getBaseQuery()

Provides the base query for the extending repository

protected getBaseQuery() : string
Return values
string

getBaseSearchQuery()

Provides the default search query base for the extending repository

protected getBaseSearchQuery(string $term) : array{'sql': string, 'bindparams': array}
Parameters
$term : string

The search term

Return values
array{'sql': string, 'bindparams': array}

getGetQuery()

Provides the default get query for the extending repository

protected getGetQuery() : string
Return values
string

getLastInsertId()

Returns the id of the most recent insert query

protected getLastInsertId() : string|false
Return values
string|false —

The id of the last inserted record

getPrimaryTable()

Provides the name of the primary table associated with the instance

protected getPrimaryTable() : mixed

@return string

getSearchableColumns()

Returns an array of column names that should be used to perform searches on records in a repository

protected getSearchableColumns() : array<string|int, string>|null
Return values
array<string|int, string>|null —

$searchableColumns An array of string containing the searchable columns

getSearchQuery()

Provides the default search query for the extending repository

protected getSearchQuery(string $term) : array{'sql': string, 'bindparams': array}
Parameters
$term : string

The search term

Return values
array{'sql': string, 'bindparams': array}

logStatementError()

Logs SQL errors to the logger

protected logStatementError(array<string|int, string> $error[, string $sql = null ]) : void
Parameters
$error : array<string|int, string>

A PDO::errorInfo() error or similar structure

$sql : string = null

The SQL query that triggered the error

processResult()

Apply any needed processing to a single db result array

protected processResult(array<string|int, mixed> $result) : array<string|int, mixed>|Entity
Parameters
$result : array<string|int, mixed>
Return values
array<string|int, mixed>|Entity

processResults()

Apply any needed processing to a db results array

protected processResults(array<string|int, mixed> $results) : array<string|int, mixed>
Parameters
$results : array<string|int, mixed>
Return values
array<string|int, mixed>

queryWithIndex()

Query the DB and return the rows as a 1 or 2 dimensional indexed array

protected queryWithIndex(string $sql, mixed $index[, string $findex = NULL ][, mixed $bindparams = NULL ]) : array<string|int, mixed>|false
Parameters
$sql : string

The query string @param string $index The table's primary key

$index : mixed
$findex : string = NULL

An optional foreign key from the table (when used, returns a 2 dimensional array, indexed first by $index, second by $findex) @param mixed[] $bindparams An array of values to be binded by PDO to any query parameters

$bindparams : mixed = NULL
Return values
array<string|int, mixed>|false —

$results A two (or three) dimensional array representing the resulting rows: array(array("id"=>1,"field"=>"value1"),array("id"=>2","field"=>"value2")), false on failure

quote()

protected quote(string $value) : string
Parameters
$value : string

The value to escape

Tags
Deprecated

Use bind parameters option provided by sql execution methods instead Escape a @value to prep for use in a DB query

Return values
string —

The escaped $value

quoteArray()

protected quoteArray(array<string|int, string> $ar) : array<string|int, string>
Parameters
$ar : array<string|int, string>

An array of string values to escape

Tags
Deprecated

Use bind parameters option provided by sql execution methods instead Escapes the contents of an array and returns the result

Return values
array<string|int, string> —

The escaped array


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results