Alpha Framework 3.1.0 API Documentation

ActiveRecordProviderInterface

An interface that defines all of the active record methods that should be included in a provider that implements this interface.

Tags
since
1.1
author

John Collins dev@alphaframework.org

license

http://www.opensource.org/licenses/bsd-license.php The BSD License

copyright

Copyright (c) 2018, John Collins (founder of Alpha Framework). All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

* Redistributions of source code must retain the above
  copyright notice, this list of conditions and the
  following disclaimer.
* Redistributions in binary form must reproduce the above
  copyright notice, this list of conditions and the
  following disclaimer in the documentation and/or other
  materials provided with the distribution.
* Neither the name of the Alpha Framework nor the names
  of its contributors may be used to endorse or promote
  products derived from this software without specific
  prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents

addProperty()  : void
Adds in a new class property without loosing existing data (does an ALTER TABLE query on the database).
begin()  : void
Starts a new database transaction.
checkDatabaseExists()  : bool
Check to see if the configured database exists.
checkRecordExists()  : bool
Checks that a record exists for the Record in the database.
checkRecordTableExists()  : bool
Static method to check the database and see if the table for the indicated Record class name exists (assumes table name will be $RecordClassName less "Object").
checkTableExists()  : bool
Checks to see if the table exists in the database for the current business class.
checkTableNeedsUpdate()  : bool
Checks to see if the table in the database matches (for fields) the business class definition, i.e. if the database table is in sync with the class definition.
commit()  : void
Commits the current database transaction.
createDatabase()  : void
Creates the configured database.
createForeignIndex()  : void
Creates a foreign key constraint (index) in the database on the given attribute.
createUniqueIndex()  : void
Creates a unique index in the database on the given attribute(s).
delete()  : void
Deletes the current object from the database.
disconnect()  : void
Disconnects the current database connection if one exists (self::$connection is set).
dropDatabase()  : void
Drops the configured database.
dropTable()  : void
Drops the table if the model requirements have changed. All data is lost!
findMissingFields()  : array<string|int, mixed>
Returns an array containing any properties on the class which have not been created on the database table yet.
getConnection()  : mixed
Gets the current connection singleton, or creates a new one if none exists.
getCount()  : int
Gets the count from the database for the amount of objects of this class.
getHistoryCount()  : int
Gets the count from the database for the amount of entries in the [tableName]_history table for this business object. Only call this method on classes where maintainHistory = true, otherwise an exception will be thrown.
getIndexes()  : array<string|int, mixed>
Gets an array of all of the names of the active database indexes for this class.
getLastDatabaseError()  : string
Returns the last database error string for the current connection.
getMAX()  : int
Gets the maximum ID value from the database for this class type.
getVersion()  : int
Gets the version_num of the object from the database (returns 0 if the Record is not saved yet).
isTableOverloaded()  : bool
Checks to see if the table name matches the classname, and if not if the table name matches the classname name of another record, i.e. the table is used to store multiple types of records.
load()  : void
Populates the record object with the properties retrived from the database for the record $ID.
loadAll()  : array<string|int, mixed>
Loads all of the record objects of this class into an array which is returned.
loadAllByAttribute()  : array<string|int, mixed>
Loads all of the objects of this class by the specified attribute into an array which is returned.
loadAllByAttributes()  : array<string|int, mixed>
Loads all of the record objects of this class by the specified attributes into an array which is returned.
loadAllByDayUpdated()  : array<string|int, mixed>
Loads all of the record objects of this class that where updated (updated_ts value) on the date indicated.
loadAllFieldValuesByAttribute()  : array<string|int, mixed>
Loads all of the specified attribute values of this class by the specified attribute into an array which is returned.
loadAllOldVersions()  : array<string|int, mixed>
Load all old versions (if any) of this record from the [tablename]_history table.
loadByAttribute()  : void
Populates the record object from the database table by the given attribute value.
makeHistoryTable()  : void
Builds a new database table for the Record class to store it's history.
makeTable()  : void
Builds a new database table for the Record class.
query()  : array<string|int, mixed>
Returns a 2d array, where each element in the array is another array representing a database row.
rebuildTable()  : void
Re-builds the table if the model requirements have changed. All data is lost!
reload()  : void
Reloads the object from the database, overwritting any attribute values in memory.
rollback()  : void
Aborts the current database transaction.
save()  : void
Saves the record. If $this->ID is empty or null it will INSERT, otherwise UPDATE.
saveAttribute()  : void
Saves the field specified with the value supplied. Only works for persistent records. Note that no Alpha type validation is performed with this method!
saveHistory()  : void
Saves the object history to the [tablename]_history table. It always does an INSERT.
setEnumOptions()  : void
Populate all of the enum options for this object from the database.
setRecord()  : void
Provide the Record that we are going to map the data to from this provider.

Methods

addProperty()

Adds in a new class property without loosing existing data (does an ALTER TABLE query on the database).

public addProperty(string $propName) : void
Parameters
$propName : string

The name of the new field to add to the database table.

Tags
since
1.1
throws
AlphaException
Return values
void —

checkDatabaseExists()

Check to see if the configured database exists.

public static checkDatabaseExists() : bool
Tags
since
2.0
Return values
bool —

checkRecordExists()

Checks that a record exists for the Record in the database.

public checkRecordExists(int $ID) : bool
Parameters
$ID : int

The Object ID of the object we want to see whether it exists or not.

Tags
since
1.1
throws
AlphaException
Return values
bool —

checkRecordTableExists()

Static method to check the database and see if the table for the indicated Record class name exists (assumes table name will be $RecordClassName less "Object").

public static checkRecordTableExists(string $RecordClassName[, bool $checkHistoryTable = false ]) : bool
Parameters
$RecordClassName : string

The name of the business object class we are checking.

$checkHistoryTable : bool = false

Set to true if you want to check for the existance of the _history table for this DAO.

Tags
since
1.1
throws
AlphaException
throws
IllegalArguementException
Return values
bool —

checkTableExists()

Checks to see if the table exists in the database for the current business class.

public checkTableExists([bool $checkHistoryTable = false ]) : bool
Parameters
$checkHistoryTable : bool = false

Set to true if you want to check for the existance of the _history table for this DAO.

Tags
since
1.1
throws
AlphaException
Return values
bool —

checkTableNeedsUpdate()

Checks to see if the table in the database matches (for fields) the business class definition, i.e. if the database table is in sync with the class definition.

public checkTableNeedsUpdate() : bool
Tags
since
1.1
throws
AlphaException
Return values
bool —

createForeignIndex()

Creates a foreign key constraint (index) in the database on the given attribute.

public createForeignIndex(string $attributeName, string $relatedClass, string $relatedClassAttribute[, string $indexName = null ]) : void
Parameters
$attributeName : string

The name of the attribute to apply the index on.

$relatedClass : string

The fully-qualified name of the related class.

$relatedClassAttribute : string

The name of the field to relate to on the related class.

$indexName : string = null

The optional name for the index, will calculate if not provided.

Tags
since
1.1
throws
FailedIndexCreateException
Return values
void —

createUniqueIndex()

Creates a unique index in the database on the given attribute(s).

public createUniqueIndex(string $attribute1Name[, string $attribute2Name = '' ][, string $attribute3Name = '' ]) : void
Parameters
$attribute1Name : string

The first attribute to mark unique in the database.

$attribute2Name : string = ''

The second attribute to mark unique in the databse (optional, use only for composite keys).

$attribute3Name : string = ''

The third attribute to mark unique in the databse (optional, use only for composite keys).

Tags
since
1.1
throws
FailedIndexCreateException
Return values
void —

disconnect()

Disconnects the current database connection if one exists (self::$connection is set).

public static disconnect() : void
Tags
since
1.1
Return values
void —

dropTable()

Drops the table if the model requirements have changed. All data is lost!

public dropTable([string $tableName = null ]) : void
Parameters
$tableName : string = null

Optional table name, leave blank for the defined table for this class to be dropped

Tags
since
1.1
throws
AlphaException
Return values
void —

findMissingFields()

Returns an array containing any properties on the class which have not been created on the database table yet.

public findMissingFields() : array<string|int, mixed>
Tags
since
1.1
throws
AlphaException
Return values
array<string|int, mixed> —

An array of missing fields in the database table.

getConnection()

Gets the current connection singleton, or creates a new one if none exists.

public static getConnection() : mixed
Tags
since
1.1
Return values
mixed —

getCount()

Gets the count from the database for the amount of objects of this class.

public getCount([array<string|int, mixed> $attributes = array() ][, array<string|int, mixed> $values = array() ]) : int
Parameters
$attributes : array<string|int, mixed> = array()

The attributes to count the objects by (optional).

$values : array<string|int, mixed> = array()

The values of the attributes to count the objects by (optional).

Tags
since
1.1
throws
AlphaException
Return values
int —

getHistoryCount()

Gets the count from the database for the amount of entries in the [tableName]_history table for this business object. Only call this method on classes where maintainHistory = true, otherwise an exception will be thrown.

public getHistoryCount() : int
Tags
since
1.2
throws
AlphaException
Return values
int —

getIndexes()

Gets an array of all of the names of the active database indexes for this class.

public getIndexes() : array<string|int, mixed>
Tags
since
1.1
throws
AlphaException
Return values
array<string|int, mixed> —

An array of database indexes on this table.

getLastDatabaseError()

Returns the last database error string for the current connection.

public static getLastDatabaseError() : string
Tags
since
1.1
Return values
string —

getMAX()

Gets the maximum ID value from the database for this class type.

public getMAX() : int
Tags
since
1.1
throws
AlphaException
Return values
int —

The maximum ID value in the class table.

getVersion()

Gets the version_num of the object from the database (returns 0 if the Record is not saved yet).

public getVersion() : int
Tags
since
1.1
throws
RecordFoundException
Return values
int —

isTableOverloaded()

Checks to see if the table name matches the classname, and if not if the table name matches the classname name of another record, i.e. the table is used to store multiple types of records.

public isTableOverloaded() : bool
Tags
since
1.1
throws
BadTableNameException
Return values
bool —

load()

Populates the record object with the properties retrived from the database for the record $ID.

public load(int $ID, int $version) : void
Parameters
$ID : int

The object ID of the record to load.

$version : int

Optionaly, provide the version to load that version from the [tablename]_history table.

Tags
since
1.1
throws
RecordFoundException
Return values
void —

loadAll()

Loads all of the record objects of this class into an array which is returned.

public loadAll(int $start, int $limit[, string $orderBy = 'ID' ][, string $order = 'ASC' ][, bool $ignoreClassType = false ]) : array<string|int, mixed>
Parameters
$start : int

The start of the SQL LIMIT clause, useful for pagination.

$limit : int

The amount (limit) of records to load, useful for pagination.

$orderBy : string = 'ID'

The name of the field to sort the records by.

$order : string = 'ASC'

The order to sort the records by.

$ignoreClassType : bool = false

Default is false, set to true if you want to load from overloaded tables and ignore the class type

Tags
since
1.1
throws
RecordFoundException
Return values
array<string|int, mixed> —

An array containing objects of this type of record object.

loadAllByAttribute()

Loads all of the objects of this class by the specified attribute into an array which is returned.

public loadAllByAttribute(string $attribute, string $value, int $start, int $limit[, string $orderBy = 'ID' ][, string $order = 'ASC' ][, bool $ignoreClassType = false ][, array<string|int, string> $constructorArgs = array() ]) : array<string|int, mixed>
Parameters
$attribute : string

The attribute to load the objects by.

$value : string

The value of the attribute to load the objects by.

$start : int

The start of the SQL LIMIT clause, useful for pagination.

$limit : int

The amount (limit) of objects to load, useful for pagination.

$orderBy : string = 'ID'

The name of the field to sort the objects by.

$order : string = 'ASC'

The order to sort the objects by.

$ignoreClassType : bool = false

Default is false, set to true if you want to load from overloaded tables and ignore the class type.

$constructorArgs : array<string|int, string> = array()

An optional array of contructor arguements to pass to the records that will be generated and returned. Supports a maximum of 5 arguements.

Tags
since
1.1
throws
RecordFoundException
throws
IllegalArguementException
Return values
array<string|int, mixed> —

An array containing objects of this type of business object.

loadAllByAttributes()

Loads all of the record objects of this class by the specified attributes into an array which is returned.

public loadAllByAttributes([array<string|int, mixed> $attributes = array() ][, array<string|int, mixed> $values = array() ], int $start, int $limit[, string $orderBy = 'ID' ][, string $order = 'ASC' ][, bool $ignoreClassType = false ][, array<string|int, string> $constructorArgs = array() ]) : array<string|int, mixed>
Parameters
$attributes : array<string|int, mixed> = array()

The attributes to load the records by.

$values : array<string|int, mixed> = array()

The values of the attributes to load the records by.

$start : int

The start of the SQL LIMIT clause, useful for pagination.

$limit : int

The amount (limit) of records to load, useful for pagination.

$orderBy : string = 'ID'

The name of the field to sort the records by.

$order : string = 'ASC'

The order to sort the records by.

$ignoreClassType : bool = false

Default is false, set to true if you want to load from overloaded tables and ignore the class type

$constructorArgs : array<string|int, string> = array()

An optional array of contructor arguements to pass to the records that will be generated and returned. Supports a maximum of 5 arguements.

Tags
since
1.1
throws
RecordFoundException
throws
IllegalArguementException
Return values
array<string|int, mixed> —

An array containing objects of this type of record object.

loadAllByDayUpdated()

Loads all of the record objects of this class that where updated (updated_ts value) on the date indicated.

public loadAllByDayUpdated(string $date, int $start, int $limit[, string $orderBy = 'ID' ][, string $order = 'ASC' ][, bool $ignoreClassType = false ]) : array<string|int, mixed>
Parameters
$date : string

The date for which to load the records updated on, in the format 'YYYY-MM-DD'.

$start : int

The start of the SQL LIMIT clause, useful for pagination.

$limit : int

The amount (limit) of records to load, useful for pagination.

$orderBy : string = 'ID'

The name of the field to sort the records by.

$order : string = 'ASC'

The order to sort the records by.

$ignoreClassType : bool = false

Default is false, set to true if you want to load from overloaded tables and ignore the class type

Tags
since
1.1
throws
RecordFoundException
Return values
array<string|int, mixed> —

An array containing objects of this type of record object.

loadAllFieldValuesByAttribute()

Loads all of the specified attribute values of this class by the specified attribute into an array which is returned.

public loadAllFieldValuesByAttribute(string $attribute, string $value, string $returnAttribute[, string $order = 'ASC' ][, bool $ignoreClassType = false ]) : array<string|int, mixed>
Parameters
$attribute : string

The attribute name to load the field values by.

$value : string

The value of the attribute to load the field values by.

$returnAttribute : string

The name of the attribute to return.

$order : string = 'ASC'

The order to sort the records by.

$ignoreClassType : bool = false

Default is false, set to true if you want to load from overloaded tables and ignore the class type.

Tags
since
1.1
throws
RecordFoundException
Return values
array<string|int, mixed> —

An array of field values.

loadAllOldVersions()

Load all old versions (if any) of this record from the [tablename]_history table.

public loadAllOldVersions(int $ID) : array<string|int, mixed>
Parameters
$ID : int

The object ID of the record to load.

Tags
since
2.0
throws
RecordFoundException
Return values
array<string|int, mixed> —

An array containing objects of this type of record object, order by version.

loadByAttribute()

Populates the record object from the database table by the given attribute value.

public loadByAttribute(string $attribute, string $value[, bool $ignoreClassType = false ][, array<string|int, mixed> $loadAttributes = array() ]) : void
Parameters
$attribute : string

The name of the attribute to load the record by.

$value : string

The value of the attribute to load the record by.

$ignoreClassType : bool = false

Default is false, set to true if you want to load from overloaded tables and ignore the class type

$loadAttributes : array<string|int, mixed> = array()

The attributes to load from the database to this object (leave blank to load all attributes)

Tags
since
1.1
throws
RecordFoundException
Return values
void —

makeHistoryTable()

Builds a new database table for the Record class to store it's history.

public makeHistoryTable() : void
Tags
since
1.2
throws
AlphaException
Return values
void —

makeTable()

Builds a new database table for the Record class.

public makeTable([bool $checkIndexes = true ]) : void
Parameters
$checkIndexes : bool = true

Set to false if you do not want to check for any additional required indexes while creating the table (default is true).

Tags
since
1.1
throws
AlphaException
Return values
void —

query()

Returns a 2d array, where each element in the array is another array representing a database row.

public query(string $sqlQuery) : array<string|int, mixed>
Parameters
$sqlQuery : string
Tags
throws
CustomQueryException
since
1.1
Return values
array<string|int, mixed> —

saveAttribute()

Saves the field specified with the value supplied. Only works for persistent records. Note that no Alpha type validation is performed with this method!

public saveAttribute(string $attribute, mixed $value) : void
Parameters
$attribute : string

The name of the attribute to save.

$value : mixed

The value of the attribute to save.

Tags
since
1.1
throws
IllegalArguementException
throws
FailedSaveException
throws
LockingException
Return values
void —

Search results