1. class
  2. Andromeda
  3. \
  4. Core
  5. \
  6. Database
  7. \
  8. ObjectDatabase

ObjectDatabase

class ObjectDatabase extends Database

Provides the basic interfaces between BaseObject and the underlying PDO database

Basic functions include loading (caching), updating, creating, and deleting objects. This class should only be used internally for BaseObjects.

Constants

private CONFIG_PATHS

the default path for storing the config file
DRIVER_MYSQL

DRIVER_SQLITE

DRIVER_POSTGRESQL

private DRIVERS

QUERY_READ

QUERY_WRITE

Properties

private $connection

the PDO database connection

 from  Database
protected array<string,mixed> $config from  Database
protected $driver

The enum value of the driver being used

 from  Database
private $read_only

if true, don't allow writes

 from  Database
private DBStats[] $stats_stack from  Database
private $queries

global history of SQL queries sent to the DB (not a stack)

 from  Database
private T>> $objects
private array $loaded

Methods

int
getDriver()

No description

from  Database
__construct(string|null $config = null)

Constructs the database and initializes the PDO connection

from  Database
static string
GetInstallUsage()

Returns a string with the primary CLI usage for Install()

from  Database
static array
GetInstallUsages()

Returns the CLI usages specific to each driver

from  Database
static string|null
Install(Input $input)

Creates and tests a new database config from the given user input

from  Database
array
GetClientObject()

returns the array of config that was loaded from the config file

from  Database
array
getInfo()

returns an array with some PDO attributes for debugging

from  Database
Database
setReadOnly(bool $ro = true)

Sets the database as writeable or readonly

from  Database
bool
isReadOnly()

Returns true if the database is read-only

from  Database
Database
importTemplate(string $path)

Imports the appropriate SQL template file for an app

from  Database
Database
importFile(string $path)

Parses and imports an SQL file into the database

from  Database
bool
SupportsRETURNING()

Whether or not the DB supports the RETURNING keyword

from  Database
bool
RequiresSAVEPOINT()

Whether or not the DB aborts transactions after an error and requires use of SAVEPOINTs

from  Database
bool
BinaryAsStreams()

Whether or not the DB fetches binary/blob fields as streams rather than scalars

from  Database
bool
BinaryEscapeInput()

Whether or not the DB requires binary input to be escaped

from  Database
bool
UsePublicSchema()

Whether or not the DB expects using public. as a prefix for table names

from  Database
string
SQLConcat(string ...$args)

Returns the given arguments concatenated in SQL

from  Database
string
SQLUpsert(string $query)

Returns the driver-specific SQL UPSERT DO NOTHING query

from  Database
bool
inTransaction()

Returns true if the DB is currently in a transaction

from  Database
array|int|null
query(string $sql, int $type, array|null $data = null)

Sends an SQL query down to the database, possibly beginning a transaction

from  Database
string
logQuery(string $sql, array|null $data)

Logs a query to the internal query history, logging the actual data values if debug allows

from  Database
void
fetchStreams(array $rows)

Loops through an array of row results and replaces streams with their values

from  Database
void
beginTransaction()

Begins a new database transaction

from  Database
rollback()

Rolls back the current database transaction

from  Database
commit()

Commits the current database transaction

from  Database
void
startTimingQuery()

Begins timing a query (performance metrics)

from  Database
void
stopTimingQuery(string $sql, int $type, bool $count = true)

Ends timing a query (performance metrics)

from  Database
Database
pushStatsContext()

Add a new performance metrics context on to the stack

from  Database
DBStats|null
popStatsContext()

Pop the current performance metrics context off of the stack

from  Database
array
getAllQueries()

Returns the array of query history

from  Database
array
getLoadedObjectIDs()

No description

ObjectDatabase
saveObjects(bool $onlyMandatory = false)

Loops through every objects and saves them to the DB

string
GetClassTableName(string $class)

Return the database table name for a class

array
Rows2Objects(array $rows, string $class)

Converts database rows into objects

BaseObject|null
TryPreloadObjectByID(string $class, string $id)

Attempt to fetch an object from the cache by its ID

BaseObject|null
TryLoadObjectByUniqueKey(string $class, string $field, string $value)

Attempt to load a unique object by the value of a field

int
CountObjectsByQuery(string $class, QueryBuilder $query)

Counts objects using the given query

array
LoadObjectsByQuery(string $class, QueryBuilder $query)

Loads an array of objects using the given query

void
UnsetObject(BaseObject $object)

No description

int
DeleteObjectsByQuery(string $class, QueryBuilder $query)

Delete objects matching the given query

ObjectDatabase
DeleteObject(BaseObject $object)

Deletes a single object from the database (only to be called by the object itself)

ObjectDatabase
SaveObject(BaseObject $object, array $values, array $counters)

UPDATEs an object in the database with the given data

ObjectDatabase
InsertObject(BaseObject $object, array $values)

INSERTs a new object into the database with the given data

BaseObject
GenerateObject(string $class)

Generates a new blank object of the given class

Details

in Database at line 90
int getDriver()

No description

Return Value

int

See also

Database::$driver

in Database at line 98
__construct(string|null $config = null)

Constructs the database and initializes the PDO connection

Parameters

string|null $config

the path to the config file to use, generated by Install()

Exceptions

DatabaseConfigException

if the given path does not exist
InvalidDriverException

if the driver in the config is invalid

in Database at line 155
static string GetInstallUsage()

Returns a string with the primary CLI usage for Install()

Return Value

string

in Database at line 161
static array GetInstallUsages()

Returns the CLI usages specific to each driver

Return Value

array

in Database at line 177
static string|null Install(Input $input)

Creates and tests a new database config from the given user input

Parameters

Input $input

input parameters

Return Value

string|null

the database config file contents

Exceptions

Throwable

if the database config is not valid and PDO fails

See also

Database::GetInstallUsage

in Database at line 237
array GetClientObject()

returns the array of config that was loaded from the config file

Return Value

array

{driver:string, connect:string, ?username:string, ?password:true, ?persistent:bool}

in Database at line 250
array getInfo()

returns an array with some PDO attributes for debugging

Return Value

array

{driver:string, cversion:string, sversion:string, info:string}

in Database at line 265
Database setReadOnly(bool $ro = true)

Sets the database as writeable or readonly

Parameters

bool $ro

if true, set as readonly

Return Value

Database

in Database at line 268
bool isReadOnly()

Returns true if the database is read-only

Return Value

bool

in Database at line 274
Database importTemplate(string $path)

Imports the appropriate SQL template file for an app

Parameters

string $path

the base path containing the templates

Return Value

Database

in Database at line 280
Database importFile(string $path)

Parses and imports an SQL file into the database

Parameters

string $path

the path of the SQL file

Return Value

Database

in Database at line 288
protected bool SupportsRETURNING()

Whether or not the DB supports the RETURNING keyword

Return Value

bool

in Database at line 295
protected bool RequiresSAVEPOINT()

Whether or not the DB aborts transactions after an error and requires use of SAVEPOINTs

Return Value

bool

in Database at line 298
protected bool BinaryAsStreams()

Whether or not the DB fetches binary/blob fields as streams rather than scalars

Return Value

bool

in Database at line 301
protected bool BinaryEscapeInput()

Whether or not the DB requires binary input to be escaped

Return Value

bool

in Database at line 304
protected bool UsePublicSchema()

Whether or not the DB expects using public. as a prefix for table names

Return Value

bool

in Database at line 307
string SQLConcat(string ...$args)

Returns the given arguments concatenated in SQL

Parameters

string ...$args

Return Value

string

in Database at line 321
string SQLUpsert(string $query)

Returns the driver-specific SQL UPSERT DO NOTHING query

Parameters

string $query

the query after INSERT INTO (e.g. table (columns) VALUES (vals)

Return Value

string

compiled query

in Database at line 331
bool inTransaction()

Returns true if the DB is currently in a transaction

Return Value

bool

in Database at line 343
array|int|null query(string $sql, int $type, array|null $data = null)

Sends an SQL query down to the database, possibly beginning a transaction

Parameters

string $sql

the SQL query string, with placeholder data values
int $type

whether the query is a read, a write, or both (bitset)
array|null $data

associative array of data replacements for the prepared statement

Return Value

array|int|null

an associative array of the query results for reads, row count for writes

Exceptions

DatabaseReadOnlyException

if the query is a write and the DB is read-only

in Database at line 411
private string logQuery(string $sql, array|null $data)

Logs a query to the internal query history, logging the actual data values if debug allows

Parameters

string $sql
array|null $data

Return Value

string

in Database at line 433
private void fetchStreams(array $rows)

Loops through an array of row results and replaces streams with their values

Parameters

array $rows

reference to an array of rows from the DB

Return Value

void

in Database at line 446
void beginTransaction()

Begins a new database transaction

Return Value

void

in Database at line 459
rollback()

Rolls back the current database transaction

in Database at line 472
commit()

Commits the current database transaction

in Database at line 485
private void startTimingQuery()

Begins timing a query (performance metrics)

Return Value

void

in Database at line 492
private void stopTimingQuery(string $sql, int $type, bool $count = true)

Ends timing a query (performance metrics)

Parameters

string $sql
int $type
bool $count

Return Value

void

in Database at line 499
Database pushStatsContext()

Add a new performance metrics context on to the stack

Return Value

Database

in Database at line 505
DBStats|null popStatsContext()

Pop the current performance metrics context off of the stack

Return Value

DBStats|null

in Database at line 514
array getAllQueries()

Returns the array of query history

Return Value

array

string array

at line 40
array getLoadedObjectIDs()

No description

Return Value

array

<string, string[]> list of ID arrays indexed by class of loaded objects

at line 46
ObjectDatabase saveObjects(bool $onlyMandatory = false)

Loops through every objects and saves them to the DB

Parameters

bool $onlyMandatory

Return Value

ObjectDatabase

at line 59
string GetClassTableName(string $class)

Return the database table name for a class

Parameters

string $class

the class name

Return Value

string

at line 74
private array Rows2Objects(array $rows, string $class)

Converts database rows into objects

Parameters

array $rows

rows from the DB, each becoming an object
string $class

the class of object represented by the rows

Return Value

array

array of objects indexed by their IDs

at line 114
private BaseObject|null TryPreloadObjectByID(string $class, string $id)

Attempt to fetch an object from the cache by its ID

Parameters

string $class

the class of the desired object
string $id

the ID of the object to load

Return Value

BaseObject|null

the object from the cache

Exceptions

ObjectTypeException

if the object exists but is a different class

at line 141
BaseObject|null TryLoadObjectByUniqueKey(string $class, string $field, string $value)

Attempt to load a unique object by the value of a field

Will try to fetch the object from the cache if loading by ID

Parameters

string $class

the desired class of the object
string $field

the field to check
string $value

the value of the field to match

Return Value

BaseObject|null

the object returned by the database

Exceptions

DuplicateUniqueKeyException

if this returns > 1 object

at line 162
int CountObjectsByQuery(string $class, QueryBuilder $query)

Counts objects using the given query

Parameters

string $class

the class of the objects
QueryBuilder $query

the query used to match objects

Return Value

int

count of objects

at line 178
array LoadObjectsByQuery(string $class, QueryBuilder $query)

Loads an array of objects using the given query

Parameters

string $class

the class of the objects
QueryBuilder $query

the query used to match objects

Return Value

array

array of objects indexed by their IDs

at line 191
private void UnsetObject(BaseObject $object)

No description

Parameters

BaseObject $object

Return Value

void

at line 205
int DeleteObjectsByQuery(string $class, QueryBuilder $query)

Delete objects matching the given query

The objects will be loaded when deleted and their Delete() will run

Parameters

string $class

the class of the objects to delete
QueryBuilder $query

the query used to match objects

Return Value

int

number of deleted objects

at line 244
ObjectDatabase DeleteObject(BaseObject $object)

Deletes a single object from the database (only to be called by the object itself)

The delete query happens immediately, not waiting for the object to be saved.

Parameters

BaseObject $object

the object to delete

Return Value

ObjectDatabase

Exceptions

RowDeleteFailedException

if nothing is deleted

at line 264
ObjectDatabase SaveObject(BaseObject $object, array $values, array $counters)

UPDATEs an object in the database with the given data

Parameters

BaseObject $object

the object to update
array $values

columns to be overwritten using =
array $counters

columns to be incremented using +=

Return Value

ObjectDatabase

at line 297
ObjectDatabase InsertObject(BaseObject $object, array $values)

INSERTs a new object into the database with the given data

Parameters

BaseObject $object

the created object to be saved
array $values

the values of each column

Return Value

ObjectDatabase

Exceptions

RowInsertFailedException

if nothing is inserted

at line 332
BaseObject GenerateObject(string $class)

Generates a new blank object of the given class

The object will not actually exist in the DB until Save() is called, and its fields will have only the defaults given in its field template

Parameters

string $class

the desired class of the new object

Return Value

BaseObject

the newly created object