Documentation

SQLRepository extends SaveableMappingObjectFactory implements ISQLRepository

A repository for a MySQL database table.

This is meant for SIMPLE database operations on single tables. If you are joining tables, doing fancy things, etc then please create a new repository and write some beautifully hand-crafted sql.

Tags

Table of Contents

$table Table name string
$dbc Database connection IDBConnection
$locked If the table is locked bool
$hasMutexLock If a lock has been obtained via GET_LOCK() bool
$mapper Data mapper IModelMapper
$properties Properties IPropertySet
$pNames Property names string[]
__construct() Create a new SQLRepository instance mixed
getTable() Retrieve the database table name backing this repository. string
lockTable() Lock the table via "lock tables". void
unlockTable() Unlock the tables obtained by lockTable() This also commits. void
getLock() Attempts to obtain a lock for this table via GET_LOCK(). void
releaseLock() Release the lock obtained by getLock() void
isTableLocked() If the table is locked via lock tables. bool
isLocked() If there is a lock in effect via GET_LOCK() bool
getDatabaseConnection() Retrieve the database connection IDBConnection
getSaveFunction() Retrieve an IRunnable instance to be used with some ITransaction instance. IRunnable
createUnitOfWork() Create a unit of work against the repo. IRunnable
stream() Stream the data one record at a time from the data source. This may not always be implemented. Generator
query() Query the data source. \buffalokiwi\magicgraph\IModel[]
get() Load some record by primary key IModel
getIdsForProperty() Retrieve a list of id's for some property. array
findByProperty() Perform a simple search by property name. array
getForProperty() Retrieve a list of models where some property name matches some value. array
exists() Tests to see if some value exists by primary key bool
getAll() Retrieve a list of models by a list of primary key values. \buffalokiwi\magicgraph\IModel[]
saveModel() Save some record. void
saveAll() Saves a batch of records. void
removeById() Remove an entry by id. This does not work for compound keys. void
remove() Removes a model. void
count() Retrieve the estimated record count. int
getPage() Retrieve user records by page. array
getStatement() string
isSafe() Detect if a string is only [a-zA-Z0-9_] bool
doesRecordExistByCompoundPrimaryKey() Execute a query to locate rows by primary key. bool
saveModel() What to do when saving the model. mixed
save() Save some record. void
saveAll() Saves a batch of records. void
beforeSave() Called before the repo save call is made. void
afterSave() Called after the repo save call is made void
beforeValidate() Called before the validate call is made void
getSaveClosure() Retrieve an IRunnable instance to be used with some ITransaction instance. Closure
runBeforeSave() void
runAfterSave() void
__construct() mixed
addPropertyConfig() Adds an additional property config to this repo. mixed
create() Create a new Model instance using the internal data mapper. IModel
createPropertySet() Clones and returns the internal property set used to construct objects. IPropertySet
createPropertyNameSet() Retrieves a set containing the property names. IBigSet
test() Test that one or more models is the correct type. void
mapper() IModelMapper
properties() IPropertySet
getInsertProperties() IBigSet
getModifiedProperties() IBigSet
filterPropertyNamesForSave() Removes any properties flagged with SUBCONFIG from the list of property names array

Properties

$hasMutexLock

If a lock has been obtained via GET_LOCK()

private bool $hasMutexLock = false

Methods

getTable()

Retrieve the database table name backing this repository.

public getTable( ) : string
Return values
string —

database table name

lockTable()

Lock the table via "lock tables".

public lockTable( ) : void

Disables autocommit.

unlockTable()

Unlock the tables obtained by lockTable() This also commits.

public unlockTable( ) : void

getLock()

Attempts to obtain a lock for this table via GET_LOCK().

public getLock( ) : void

This blocks until one can be obtained.

releaseLock()

Release the lock obtained by getLock()

public releaseLock( ) : void

isTableLocked()

If the table is locked via lock tables.

public isTableLocked( ) : bool
Return values
bool —

locked

isLocked()

If there is a lock in effect via GET_LOCK()

public isLocked( ) : bool
Return values
bool —

is locked

getSaveFunction()

Retrieve an IRunnable instance to be used with some ITransaction instance.

public getSaveFunction( $beforeSave : Closure , $afterSave : Closure , ...$models : IModel ) : IRunnable

This runnable will execute the supplied function prior to saving the model.

Parameters
$beforeSave : Closure

What to run prior to saving f( IRepository, ...IModel )

$afterSave : Closure

What to run after saving f( IRepository, ...IModel )

$models : IModel

One or more models to save

Return values
IRunnable

createUnitOfWork()

Create a unit of work against the repo.

public createUnitOfWork( $action : Closure ) : IRunnable
Parameters
$action : Closure

f( IRepository $repo ) : void - What to do

Return values
IRunnable —

Runnable

stream()

Stream the data one record at a time from the data source. This may not always be implemented.

public stream( $properties : IPropertySet , $filter : IFilter [, $rows : IRows = null ] ) : Generator
Parameters
$properties : IPropertySet
$filter : IFilter

Filters to use

$rows : IRows = null

Sort order and limit

Tags
throws
DBException

For db errors

Return values
Generator —

yielded results

query()

Query the data source.

public query( $properties : IPropertySet , $filter : IFilter [, $rows : IRows = null ] ) : \buffalokiwi\magicgraph\IModel[]
Parameters
$properties : IPropertySet

Properties to return

$filter : IFilter

Filters to use

$rows : IRows = null

Sort order and limit

Tags
throws
DBException

For db errors

Return values
\buffalokiwi\magicgraph\IModel[] —

model instances

getIdsForProperty()

Retrieve a list of id's for some property.

public getIdsForProperty( $propertyName : string , $value : string ) : array

If primary key is compound, then each returned element will be an array (map) listing each key.

Parameters
$propertyName : string

Property Name

$value : string

value

Tags
todo

Make this work with in and null values.

Return values
array —

ids

findByProperty()

Perform a simple search by property name.

public findByProperty( $propertyName : string , $value : string [, $limit : int = 100 ] ) : array

If the engine supports simple searching, this can be used for that. For example: With SQL databases, this can simply be a wildcard search. Also possible to use full text indexes or whatever else the engine supports.

Depending on the repo, this could connect to any number of things for searching.

Parameters
$propertyName : string

Property name

$value : string

Search value. What this is depends on the engine.

$limit : int = 100
Tags
throws
InvalidArgumentException
Return values
array

getForProperty()

Retrieve a list of models where some property name matches some value.

public getForProperty( $propertyName : string , $value : mixed ) : array

If value is an array, this uses the "in" operator if the value is null, this tests for "is null" All other values use the "=" operator.

As with everything in magic graph, NEVER feed user input into a property name argument. ALWAYS use the whitelisted column names contained within a property set.

Parameters
$propertyName : string

Property name

$value : mixed

value

Tags
throws
Exception
Return values
array

exists()

Tests to see if some value exists by primary key

public exists( ...$id : string ) : bool
Parameters
$id : string
Return values
bool

getAll()

Retrieve a list of models by a list of primary key values.

public getAll( $idList : array ) : \buffalokiwi\magicgraph\IModel[]

If multiple primary key columns are defined, this simply uses the first one that was defined in the list of primary keys. Use query() for compound keys.

Parameters
$idList : array

id list

Tags
throws
DBException

For DB Errors

Return values
\buffalokiwi\magicgraph\IModel[] —

found models

saveModel()

Save some record.

protected saveModel( $model : IModel ) : void

If the primary key value is specified, this is considered to be an update. Otherwise, this is considered to be an insert.

Parameters
$model : IModel

Model to save

Tags
throws
DBException

For DB errors

todo

This contains some system-specific code that should really not be here. Consider moving most of this to some generic location, and passing the columns to insert/update to this method instead of processing them here.

saveAll()

Saves a batch of records.

public saveAll( ...$model : IModel ) : void

All records are first validated, then saved sequentially. Validation exceptions will be thrown prior to any saves happening.

If the primary key value is specified, this is considered to be an update. Otherwise, this is considered to be an insert.

This is split into 3 batches (iterations of supplied models):

1) beforeValidate, validate and beforeSave 2) saveModel 3) afterSave

This will wrap the call to saveAll() with a database transaction. Exceptions will call rollBack().

If merging multiple repositories, DO NOT USE THIS. Use the transaction factory to create a unit of work, which will manage transactions across different storage engines.

Parameters
$model : IModel

Model to save

Tags
throws
DBException

For DB errors

throws
ValidationException

if the model fails to validate

removeById()

Remove an entry by id. This does not work for compound keys.

public removeById( $id : string ) : void
Parameters
$id : string

id

Tags
throws
DBException

count()

Retrieve the estimated record count.

public count( [ $full : bool = false ] ) : int
Parameters
$full : bool = false

Set to true to retrieve count(*), set to false for max(primary key)

Return values
int —

estimated number of records

getPage()

Retrieve user records by page.

public getPage( $page : int [, $size : int = 25 ] [, $orderBy : string = '' ] ) : array
Parameters
$page : int

Page number

$size : int = 25

page size

$orderBy : string = ''
Return values
array —

IModel[] Users

getStatement()

private getStatement( $properties : IBigSet [, $filter : IFilter|null = null ] [, $rows : IRows|null = null ] ) : string
Parameters
$properties : IBigSet
$filter : IFilter|null = null
$rows : IRows|null = null
Return values
string

isSafe()

Detect if a string is only [a-zA-Z0-9_]

private isSafe( $s : string ) : bool
Parameters
$s : string

String to check

Return values
bool —

is letters

doesRecordExistByCompoundPrimaryKey()

Execute a query to locate rows by primary key.

private doesRecordExistByCompoundPrimaryKey( $model : IModel , $priKeys : array ) : bool
Parameters
$model : IModel
$priKeys : array
Return values
bool —

exists

save()

Save some record.

public save( $model : IModel [, $validate : bool = true ] ) : void

If the primary key value is specified, this is considered to be an update. Otherwise, this is considered to be an insert.

Parameters
$model : IModel

Model to save

$validate : bool = true

Validate the model prior to save

Tags
throws
DBException

For DB errors

throws
ValidationException

if the model fails to validate

saveAll()

Saves a batch of records.

public saveAll( ...$model : IModel ) : void

All records are first validated, then saved sequentially. Validation exceptions will be thrown prior to any saves happening.

If the primary key value is specified, this is considered to be an update. Otherwise, this is considered to be an insert.

This is split into 3 batches (iterations of supplied models):

1) beforeValidate, validate and beforeSave 2) saveModel 3) afterSave

Parameters
$model : IModel

Model to save

Tags
throws
DBException

For DB errors

throws
ValidationException

if the model fails to validate

getSaveClosure()

Retrieve an IRunnable instance to be used with some ITransaction instance.

protected final getSaveClosure( $beforeSave : Closure , $afterSave : Closure , ...$models : IModel ) : Closure

This runnable will execute the supplied function prior to saving the model.

Parameters
$beforeSave : Closure

What to run prior to saving f( IRepository, ...IModel )

$afterSave : Closure

What to run after saving f( IRepository, ...IModel )

$models : IModel

One or more models to save

Return values
Closure —

Function

addPropertyConfig()

Adds an additional property config to this repo.

public addPropertyConfig( ...$config : type ) : mixed

When models reference themselves, sometimes it's necessary for a property config to reference the repository (circular).

Feels a bit like cheating to me...

Warning: This method should only be caled from composition root. This can obviously have some unintended side effects when used in other locations.

Parameters
$config : type
Return values
mixed

create()

Create a new Model instance using the internal data mapper.

public create( $data : array [, $readOnly : bool = false ] ) : IModel
Parameters
$data : array

Raw data to use

$readOnly : bool = false

Set the produced model to read only

Tags
throws
DBException

For db errors

todo

Create some code that can disable or remove properties that are not fetched when the model is built. Think about this a bit...

Return values
IModel —

model instance

createPropertyNameSet()

Retrieves a set containing the property names.

public createPropertyNameSet( ) : IBigSet
Return values
IBigSet —

set

filterPropertyNamesForSave()

Removes any properties flagged with SUBCONFIG from the list of property names

private filterPropertyNamesForSave( $names : string[] , $model : IModel ) : array
Parameters
$names : string[]

Property names

$model : IModel
Tags
throws
Exception

if model is an incorrect type.

Return values
array —

filtered names

Search results