Class: RecordsetManager

Uses

Properties
$dbworker protected	Internal variable for storing the dbworker.
$fields protected	Internal array for storing the target fields.
$key_fields protected	Internal array for storing the key fields. These are the fields that are used to uniquely identify a record.
$table protected	Internal variable for storing the target table name.

Methods
checkWhereClause() protected	This is internal auxiliary function for converting an array to a where clause.
commit_transaction() public	Commits the translation.
countRecords() public	Counts records based on the where clause.
countRecordsQuery() public	Counts records based on the query.
deleteRecords() public	Deletes records by a given where clause.
deleteRecordsQuery() public	Deletes records by a given query.
describeTableFields() public	Defines the field mappings for working with record sets based on a table.
describeTableFieldsQuery() public	Defines the field mappings for working with record sets based on a query.
escape() public	Escapes the string so that it can be used in the query without causing an error.
format_date() public	Formats the date to a string compatible for the corresponding database.
format_datetime() public	Formats the date/time to a string compatible for the corresponding database.
getDBWorker() public	Returns the dbworker to be used for working with the database.
loadRecord() public	Loads a record into an array in the form "field_name" => "value" based on a table.
loadRecordQuery() public	Loads a record into an array in the form "field_name" => "value".
loadRecordSet() public	Loads records into an array in the form
loadRecordSetQuery() public	Loads records into an array in the form
number_or_null() public	Checks that the value is a number and returns it, or returns the string NULL if the value is empty.
processSubarray() protected	This is internal auxiliary function for saving a record set from an array with key field values as array dimensions.
quotes_or_null() public	Escapes the string so that it can be used in the query without causing an error or returns the sstring NULL if the string is empty.
rollback_transaction() public	Rolls back the translation.
saveRecord() public	Saves a record from an array in the form "field_name" => "value" into the table.
saveRecordSet() public	Saves records from an array in the form $records["key_field1"]["key_field2"]["key_fieldN"]["field_name"] = "value" into the table.
setDBWorker() public	Sets the dbworker to be used for working with the database.
start_transaction() public	Starts the translation.
validateParameters() protected	This is internal auxiliary function for checking that the recordset manager is initialized correctly.

Property: RecordsetManager::$dbworker

protected ?\DatabaseWorkers\DBWorker $dbworker = null;

Internal variable for storing the dbworker.

Type

?\DatabaseWorkers\DBWorker

Authors

Oleg Schildt

Source code

Property: RecordsetManager::$fields

protected array $fields = [];

Internal array for storing the target fields.

Type

array

Authors

Oleg Schildt

Source code

Property: RecordsetManager::$key_fields

protected array $key_fields = [];

Internal array for storing the key fields. These are the fields that are used to uniquely identify a record.

Type

array

Authors

Oleg Schildt

Source code

Property: RecordsetManager::$table

protected ?string $table = null;

Internal variable for storing the target table name.

Type

?string

Authors

Oleg Schildt

Source code

Method: RecordsetManager::checkWhereClause()

protected function checkWhereClause(array|string &$where_clause): void;

This is internal auxiliary function for converting an array to a where clause.

Parameters

Name	Pass type	Value type	Default value	Description
$where_clause	by reference	array\|string		The where clause that should be checked. If an array of keys is passed, the where clause is build based on it.

Returns

void

Throws

\Exception

It might throw an exception in the case if a field for the clause wad not described by the initialization.

Authors

Oleg Schildt

Source code

Method: RecordsetManager::commit_transaction()

public function commit_transaction(): void;

Commits the translation.

Returns

void

Throws

\SmartFactory\Interfaces\IRecordsetManager::commit_transaction()

It might throw an exception in the case of any errors.

Overrides

Authors

Oleg Schildt

Source code

\SmartFactory\Interfaces\IRecordsetManager::countRecords()

Method: RecordsetManager::countRecords()

public function countRecords(array|string $where_clause): int;

Counts records based on the where clause.

Parameters

Name	Pass type	Value type	Default value	Description
$where_clause	by value	array\|string		The where clause that should restrict the result. If an array of keys is passed, the where clause is build automatically based on it.

Returns

int

Returns the number of records.

Throws

\Exception

It might throw exceptions in the case of any errors.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::countRecordsQuery()

Method: RecordsetManager::countRecordsQuery()

public function countRecordsQuery(string $query): int;

Counts records based on the query.

Parameters

Name	Pass type	Value type	Default value	Description
$query	by value	string		The query to be used.

Returns

int

Returns the number of records.

Throws

\Exception

It might throw exceptions in the case of any errors.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::deleteRecords()

Method: RecordsetManager::deleteRecords()

public function deleteRecords(array|string $where_clause): void;

Deletes records by a given where clause.

Parameters

Name	Pass type	Value type	Default value	Description
$where_clause	by value	array\|string		The where clause that should restrict the result. If an array of keys is passed, the where clause is build automatically based on it.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::deleteRecordsQuery()

Method: RecordsetManager::deleteRecordsQuery()

public function deleteRecordsQuery(string $query): void;

Deletes records by a given query.

Parameters

Name	Pass type	Value type	Default value	Description
$query	by value	string		The query to be used.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::describeTableFields()

Method: RecordsetManager::describeTableFields()

public function describeTableFields(string $table, array $fields, array $key_fields): void;

Defines the field mappings for working with record sets based on a table.

Parameters

Name	Pass type	Value type	Description
$table	by value	string	The name of the table.
$fields	by value	array	The array of fields in the form "field name" => "field type".
$key_fields	by value	array	The array of key fields. These are the fields that are used to uniquely identify a record.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

\SmartFactory\Interfaces\IRecordsetManager::describeTableFieldsQuery()

Method: RecordsetManager::describeTableFieldsQuery()

public function describeTableFieldsQuery(array $fields, array $key_fields): void;

Defines the field mappings for working with record sets based on a query.

Parameters

Name	Pass type	Value type	Default value	Description
$fields	by value	array		The array of fields in the form "field name" => "field type".
$key_fields	by value	array		The array of key fields. These are the fields that are used to uniquely identify a record.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Method: RecordsetManager::escape()

public function escape(string $str): string;

Escapes the string so that it can be used in the query without causing an error.

Parameters

Name	Pass type	Value type	Default value	Description
$str	by value	string		The string to be escaped.

Returns

string

Returns the escaped string.

Overrides

\SmartFactory\Interfaces\IRecordsetManager::escape()

Authors

Oleg Schildt

Source code

\SmartFactory\Interfaces\IRecordsetManager::format_date()

Method: RecordsetManager::format_date()

public function format_date(int $date): string;

Formats the date to a string compatible for the corresponding database.

Parameters

Name	Pass type	Value type	Default value	Description
$date	by value	int		The date value as timestamp.

Returns

string

Returns the string representation of the date compatible for the corresponding database.

Overrides

Authors

Oleg Schildt

Source code

\SmartFactory\Interfaces\IRecordsetManager::format_datetime()

Method: RecordsetManager::format_datetime()

public function format_datetime(int $datetime): string;

Formats the date/time to a string compatible for the corresponding database.

Parameters

Name	Pass type	Value type	Default value	Description
$datetime	by value	int		The date/time value as timestamp.

Returns

string

Returns the string representation of the date/time compatible for the corresponding database.

Overrides

Authors

Oleg Schildt

Source code

Method: RecordsetManager::getDBWorker()

public function getDBWorker(): ?\SmartFactory\DatabaseWorkers\DBWorker;

Returns the dbworker to be used for working with the database.

Returns

?\SmartFactory\DatabaseWorkers\DBWorker

Returns the dbworker to be used for working with the database.

Throws

\SmartFactory\Interfaces\IRecordsetManager::getDBWorker()

It might throw exceptions in the case of any errors.

Overrides

Authors

Oleg Schildt

Source code

\SmartFactory\Interfaces\IRecordsetManager::loadRecord()

Method: RecordsetManager::loadRecord()

public function loadRecord(array &$record, array|string $where_clause): void;

Loads a record into an array in the form "field_name" => "value" based on a table.

Parameters

Name	Pass type	Value type	Default value	Description
$record	by reference	array		The target array where the data should be loaded.
$where_clause	by value	array\|string		The where clause that should restrict the result to one record. If an array of keys is passed, the where clause is build automatically based on it.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::loadRecordQuery()

Method: RecordsetManager::loadRecordQuery()

public function loadRecordQuery(array &$record, string $query): void;

Loads a record into an array in the form "field_name" => "value".

Parameters

Name	Pass type	Value type	Default value	Description
$record	by reference	array		The target array where the data should be loaded.
$query	by value	string		The query to be used.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::loadRecordSet()

Method: RecordsetManager::loadRecordSet()

public function loadRecordSet(array &$records, array|string $where_clause, string $order_clause = "", int $limit = 0 ) : void;

Loads records into an array in the form

Details

$records["key_field1"]["key_field2"]["key_fieldN"]["field_name"] = "value".

baed on a table.

Parameters

Name	Pass type	Value type	Default value	Description
$records	by reference	array		The target array where the data should be loaded.
$where_clause	by value	array\|string		The where clause that should restrict the result. If an array of keys is passed, the where clause is build automatically based on it.
$order_clause	by value	string	""	The order clause to sort the results.
$limit	by value	int	0	The limit how many records should be loaded. 0 for unlimited.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::loadRecordSetQuery()

Method: RecordsetManager::loadRecordSetQuery()

public function loadRecordSetQuery(array &$records, string $query): void;

Loads records into an array in the form

Details

$records["key_field1"]["key_field2"]["key_fieldN"]["field_name"] = "value".

baed on a query.

Parameters

Name	Pass type	Value type	Default value	Description
$records	by reference	array		The target array where the data should be loaded.
$query	by value	string		The query to be used.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

Method: RecordsetManager::number_or_null()

function number_or_null(string $str): string;

Checks that the value is a number and returns it, or returns the string NULL if the value is empty.

Parameters

Name	Pass type	Value type	Default value	Description
$str	by value	string		The string to be escaped.

Returns

string

Returns the escaped string.

Throws

It might throw an exception in the case of any errors.

Authors

Oleg Schildt

Source code

Method: RecordsetManager::processSubarray()

protected function processSubarray(array $subarray, array $key_fields, array &$parent_values, array &$record, string $identity_field ) : void;

This is internal auxiliary function for saving a record set from an array with key field values as array dimensions.

Details

It expands this multidimensional array into the set of flat records suitable for call \SmartFactory\RecordsetManager::saveRecord().

Parameters

Name	Pass type	Value type	Description
$subarray	by value	array	The current subarray ro be processed.
$key_fields	by value	array	The array of the key fields. These are the fields that are used to uniquely identify a record.
$parent_values	by reference	array	The array of the values of the foreign keys in the form "field_name" => "value".
$record	by reference	array	The array where the resulting flat record is built.
$identity_field	by value	string	The name of the identity field if exists. If the identity field is specified and the record does not exist yet in the table, the source array is extended with a pair "identity field" => "identity value" issued by the database by this insert operation.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Authors

Oleg Schildt

Source code

Method: RecordsetManager::quotes_or_null()

function quotes_or_null(string $str): string;

Escapes the string so that it can be used in the query without causing an error or returns the sstring NULL if the string is empty.

Parameters

Name	Pass type	Value type	Default value	Description
$str	by value	string		The string to be escaped.

Returns

string

Returns the escaped string.

Authors

Oleg Schildt

Source code

Method: RecordsetManager::rollback_transaction()

public function rollback_transaction(): void;

Rolls back the translation.

Returns

void

Throws

\SmartFactory\Interfaces\IRecordsetManager::rollback_transaction()

It might throw an exception in the case of any errors.

Overrides

Authors

Oleg Schildt

Source code

\SmartFactory\Interfaces\IRecordsetManager::saveRecord()

Method: RecordsetManager::saveRecord()

public function saveRecord(array &$record, array|string $where_clause, string $identity_field = ""): void;

Saves a record from an array in the form "field_name" => "value" into the table.

Parameters

Name	Pass type	Value type	Default value	Description
$record	by reference	array		The source array with the data to be saved.
$where_clause	by value	array\|string		The where clause that should be used to define whether a record should be inserted or updated. If an array of keys is passed, the where clause is build automatically based on it.
$identity_field	by value	string	""	The name of the identity field if exists. If the identity field is specified and the record does not exist yet in the table, the source array is extended with a pair "identity field" => "identity value" issued by the database by this insert operation.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::saveRecordSet()

Method: RecordsetManager::saveRecordSet()

public function saveRecordSet(array $records, array $parent_values = [], string $identity_field = ""): void;

Saves records from an array in the form $records["key_field1"]["key_field2"]["key_fieldN"]["field_name"] = "value" into the table.

Parameters

Name	Pass type	Value type	Default value	Description
$records	by value	array		The source array with the data to be saved.
$parent_values	by value	array	[]	If this recordset is a child subset of data to be saved, you can set the values of the foreign keys in the form "field_name" => "value".
$identity_field	by value	string	""	The name of the identity field if exists. If the identity field is specified and the record does not exist yet in the table, the source array is extended with a pair "identity field" => "identity value" issued by the database by this insert operation.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.
if the query fails or if some object names are invalid.

Overrides

Authors

Oleg Schildt

Source code

Uses

\SmartFactory\Interfaces\IRecordsetManager::setDBWorker()

Method: RecordsetManager::setDBWorker()

public function setDBWorker(\SmartFactory\DatabaseWorkers\DBWorker $dbworker): void;

Sets the dbworker to be used for working with the database.

Parameters

Name	Pass type	Value type	Default value	Description
$dbworker	by value	\SmartFactory\DatabaseWorkers\DBWorker		The dbworker to be used for working with the database.

Returns

void

Overrides

Authors

Oleg Schildt

Source code

Method: RecordsetManager::start_transaction()

public function start_transaction(): void;

Starts the translation.

Returns

void

Throws

\SmartFactory\Interfaces\IRecordsetManager::start_transaction()

It might throw an exception in the case of any errors.

Overrides

Authors

Oleg Schildt

Source code

Method: RecordsetManager::validateParameters()

protected function validateParameters(string $type): void;

This is internal auxiliary function for checking that the recordset manager is initialized correctly.

Parameters

Name	Pass type	Value type	Default value	Description
$type	by value	string		The type of validation - table or query.

Returns

void

Throws

\Exception

It might throw an exception in the case of any errors:

if some parameters are missing.
if dbworker does not extend \SmartFactory\DatabaseWorkers\DBWorker.
if some parameters are not of the proper type.

Authors

Oleg Schildt

Source code